aboutsummaryrefslogtreecommitdiffstats
path: root/interimap.md
diff options
context:
space:
mode:
Diffstat (limited to 'interimap.md')
-rw-r--r--interimap.md40
1 files changed, 31 insertions, 9 deletions
diff --git a/interimap.md b/interimap.md
index 4d85eaf..50c1832 100644
--- a/interimap.md
+++ b/interimap.md
@@ -82,10 +82,10 @@ the *list-mailbox*, *list-select-opts* and *ignore-mailbox* options from
the [configuration file](#configuration-file) can be used to shrink that
list and save bandwidth.
However if some extra argument are provided on the command line,
-`interimap` ignores said options and synchronizes the given
+`interimap` ignores these options and synchronizes the given
*MAILBOX*es instead. Note that each *MAILBOX* is taken “as is”; in
particular, it must be [UTF-7 encoded][RFC 2152], unquoted, and the list
-wildcards ‘\*’ and ‘%’ are not expanded.
+wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server.
If the synchronization was interrupted during a previous run while some
messages were being replicated (but before the `UIDNEXT` or
@@ -214,17 +214,38 @@ Valid options are:
(Default: `HOST.db`, where *HOST* is taken from the `[remote]` or
`[local]` sections, in that order.)
+*list-reference*
+
+: An optional “reference name” to use for the initial `LIST` command,
+ indicating the context in which the *MAILBOX*es are interpreted.
+ For instance, by specifying `list-reference=perso/` in the `[local]`
+ section, *MAILBOX* names are interpreted relative to `perso/` on the
+ local server; in other words the remote mailbox hierarchy is mapped
+ to the `perso/` sub-hierarchy on the local server. This is useful
+ for synchronizing multiple remote servers against different
+ namespaces belonging to the same local IMAP server (using a
+ different InterIMAP instance for each local namespace ↔ remote
+ synchronization).
+
+ (Note that if the reference name is not a level of mailbox hierarchy
+ and/or does not end with the hierarchy delimiter, by [RFC 3501] its
+ interpretation by the IMAP server is implementation-dependent.)
+
*list-mailbox*
: A space separated list of mailbox patterns to use when issuing the
initial `LIST` command (overridden by the *MAILBOX*es given as
command-line arguments).
- Note that each pattern containing special characters such as spaces
- or brackets (see [RFC 3501] for the exact syntax) must be quoted.
+ Names containing special characters such as spaces or brackets need
+ to be enclosed in double quotes. Within double quotes C-style
+ backslash escape sequences can be used (‘\\t’ for an horizontal tab,
+ ‘\\n’ for a new line, ‘\\\\’ for a backslash, etc.), as well as
+ hexadecimal escape sequences ‘\\xHH’.
Furthermore, non-ASCII names must be [UTF-7 encoded][RFC 2152].
- Two wildcards are available: a ‘\*’ character matches zero or more
- characters, while a ‘%’ character matches zero or more characters up
- to the mailbox's hierarchy delimiter.
+ Two wildcards are available, and passed verbatim to the IMAP server:
+ a ‘\*’ character matches zero or more characters, while a ‘%’
+ character matches zero or more characters up to the hierarchy
+ delimiter.
This option is only available in the default section.
(The default pattern, `*`, matches all visible mailboxes on the
server.)
@@ -261,8 +282,9 @@ Valid options are:
: One of `imap`, `imaps` or `tunnel`.
`type=imap` and `type=imaps` are respectively used for IMAP and IMAP
over SSL/TLS connections over a INET socket.
- `type=tunnel` causes `interimap` to open a pipe to a *command*
- instead of a raw socket.
+ `type=tunnel` causes `interimap` to create an unnamed pair of
+ connected sockets for interprocess communication with a *command*
+ instead of a opening a network socket.
Note that specifying `type=tunnel` in the `[remote]` section makes
the default *database* to be `localhost.db`.
(Default: `imaps`.)