aboutsummaryrefslogtreecommitdiffstats
path: root/imapsync.1
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2015-07-30 01:40:05 +0200
committerGuilhem Moulin <guilhem@fripost.org>2015-07-30 01:40:05 +0200
commitd1d482c975df0840ed0169f559bdd7c5c8b56191 (patch)
tree202230003310bbd27b0501846a9a1c17d9373903 /imapsync.1
parent651a9a83e34849f51748f87da88d3d3c84470d1d (diff)
parent7a5ef2ffc002e7976fae34d08f296ace993211c8 (diff)
Merge branch 'master' into debian
Diffstat (limited to 'imapsync.1')
-rw-r--r--imapsync.1124
1 files changed, 94 insertions, 30 deletions
diff --git a/imapsync.1 b/imapsync.1
index 8c22222..d794d1a 100644
--- a/imapsync.1
+++ b/imapsync.1
@@ -4,7 +4,7 @@
imapsync \- IMAP-to-IMAP synchronization program for QRESYNC-capable servers
.SH SYNOPSIS
-.B imapsync\fR [\fIOPTION\fR ...] [\fIMAILBOX\fR ...]
+.B imapsync\fR [\fIOPTION\fR ...] [\fICOMMAND\fR] [\fIMAILBOX\fR ...]
.SH DESCRIPTION
@@ -12,12 +12,12 @@ imapsync \- IMAP-to-IMAP synchronization program for QRESYNC-capable servers
.B imapsync\fR performs stateful synchronization between two IMAP4rev1
servers.
Such synchronization is made possible by the QRESYNC extension from
-[RFC7162]; for convenience reasons support for LIST\-EXTENDED [RFC5258],
-LIST\-STATUS [RFC5819] and UIDPLUS [RFC4315] is also required.
-Furthermore, support for LITERAL+ [RFC2088] and MULTIAPPEND [RFC3502]
-is recommended: while they are not needed for \fBimapsync\fR to work,
-these extensions greatly improve performance by reducing the number of
-required round trips.
+[RFC7162]; for convenience reasons servers must also support
+LIST\-EXTENDED [RFC5258], LIST\-STATUS [RFC5819] and UIDPLUS [RFC4315].
+Furthermore, while \fBimapsync\fR can work with servers lacking support
+for LITERAL+ [RFC2088] and MULTIAPPEND [RFC3502], these extensions
+greatly improve performance by reducing the number of required round
+trips hence are recommended.
.PP
Stateful synchronization is only possible for mailboxes supporting
@@ -69,11 +69,18 @@ Go back to step 2 if the server sent some updates in the meantime.
.IP \n+[step].
Go back to step 1 to proceed with the next unsynchronized mailbox.
+.SH COMMANDS
.PP
By default \fBimapsync\fR synchronizes each mailbox listed by the
\(lqLIST "" "*"\(rq IMAP command;
-providing extra arguments limits the synchronization to the given
-\fIMAILBOX\fRes only.
+the \fIlist-mailbox\fR, \fIlist-select-opts\fR and \fIignore-mailbox\fR
+options from the configuration file can be used to shrink that list and
+save bandwidth.
+However if some extra argument are provided on the command line,
+\fBimapsync\fR ignores said options and synchronizes the given
+\fIMAILBOX\fRes instead. Note that each \fIMAILBOX\fR is taken \(lqas
+is\(rq; in particular, it must be UTF-7 encoded, unquoted, and the list
+wildcards \(oq*\(cq and \(oq%\(cq are not interpolated.
.PP
If the synchronization was interrupted during a previous run while some
@@ -86,16 +93,15 @@ their flags have changed in the meantime.
Finally, after propagating the offline changes for these messages,
\fBimapsync\fR resumes the synchronization for the rest of the mailbox.
-.SH OPTIONS
-.TP
-.B \-\-config=\fR\fIFILE\fR
-Specify an alternate configuration file. Relative paths start from
-\fI$XDG_CONFIG_HOME\fR, or \fI~/.config\fR if the XDG_CONFIG_HOME
-environment variable is unset.
+.PP
+Specifying one of the commands below makes \fBimapsync\fR perform an
+action other than the default QRESYNC-based synchronization.
.TP
-.B \-\-repair
+.B \-\-repair \fR[\fIMAILBOX\fR ...]
List the database anomalies and try to repair them.
+(Consider only the given \fIMAILBOX\fRes if non-optional arguments are
+provided.)
This is done by performing a so\-called \(lqfull synchronization\(rq,
namely 1/ download all UIDs along with their flags from both the local
and remote servers, 2/ ensure that each entry in the database corresponds
@@ -107,6 +113,37 @@ Flag conflicts are solved by updating each message to the union of both
lists.
.TP
+.B \-\-delete \fIMAILBOX\fR [...]
+Delete the given \fIMAILBOX\fRes on each target (by default each server
+plus the database, unless \fB\-\-target\fR specifies otherwise) where
+it exists.
+Note that per [RFC3501] deletion is not recursive: \fIMAILBOX\fR's
+children are not deleted.
+
+.TP
+.B \-\-rename \fISOURCE\fR \fIDEST\fR
+Rename the mailbox \fISOURCE\fR to \fIDEST\fR on each target (by default
+each server plus the database, unless \fB\-\-target\fR specifies
+otherwise) where it exists.
+\fBimapsync\fR aborts if \fIDEST\fR already exists on either target.
+Note that per [RFC3501] the renaming is recursive: \fISOURCE\fR's
+children are moved to become \fIDEST\fR's children instead.
+
+
+.SH OPTIONS
+.TP
+.B \-\-config=\fR\fIFILE\fR
+Specify an alternate configuration file. Relative paths start from
+\fI$XDG_CONFIG_HOME\fR, or \fI~/.config\fR if the XDG_CONFIG_HOME
+environment variable is unset.
+
+.TP
+.B \fB\-\-target=\fR{local,remote,database}
+Limit the scope of a \fB\-\-delete\fR or \fB\-\-rename\fR command
+to the given target. Can be repeated to act on multiple targets. By
+default all three targets are considered.
+
+.TP
.B \-q\fR, \fB\-\-quiet\fR
Try to be quiet.
@@ -151,6 +188,42 @@ This option is only available in the default section.
\(lq[remote]\(rq or \(lq[local]\(rq sections, in that order.
.TP
+.I list-mailbox
+A space separated list of mailbox patterns to use when issuing the
+initial LIST command (overridden by the \fIMAILBOX\fRes given as
+command-line arguments).
+Note that each pattern containing special characters such as spaces or
+brackets (see [RFC3501] for the exact syntax) must be quoted.
+Furthermore, non-ASCII names must be UTF\-7 encoded.
+Two wildcards are available: a \(oq*\(cq character matches zero or more
+characters, while a \(oq%\(cq character matches zero or more characters
+up to the mailbox's hierarchy delimiter.
+This option is only available in the default section.
+(The default pattern, \(lq*\(rq, matches all visible mailboxes on the
+server.)
+
+.TP
+.I list-select-opts
+An optional space separated list of selectors for the initial LIST
+command. (Requires a server supporting the LIST-EXTENDED [RFC5258]
+extension.) Useful values are
+\(lqSUBSCRIBED\(rq (to list only subscribed mailboxes),
+\(lqREMOTE\(rq (to also list remote mailboxes on a server supporting
+mailbox referrals), and \(lqRECURSIVEMATCH\(rq (to list parent mailboxes
+with children matching one of the \fIlist-mailbox\fR patterns above).
+This option is only available in the default section.
+
+.TP
+.I ignore-mailbox
+An optional Perl Compatible Regular Expressions (PCRE) covering
+mailboxes to exclude:
+any (UTF-7 encoded, unquoted) mailbox listed in the initial LIST
+responses is ignored if it matches the given expression.
+Note that the \fIMAILBOX\fRes given as command-line arguments bypass the
+check and are always considered for synchronization.
+This option is only available in the default section.
+
+.TP
.I logfile
A file name to use to log debug and informational messages. This option is
only available in the default section.
@@ -231,25 +304,16 @@ Authorities, used for server certificate verification.
.SH KNOWN BUGS AND LIMITATIONS
-.IP \[bu] 2
-Mailbox deletion and renaming are not very well tested yet.
.IP \[bu]
Using \fBimapsync\fR on two identical servers with a non-existent or
-empty database will duplicate each message due to absence of
+empty database will duplicate each message due to the absence of
local/remote UID association.
.IP \[bu]
-Detecting whether a mailbox has been renamed or deleted while
-\fBimapsync\fR wasn't running is done by looking for a mailbox with same
-UIDVALIDITY. [RFC3501] describes the purpose of UIDVALIDITY as to let
-clients know when to invalidate their UID cache. In particular, there
-is no requirement that two mailboxes can't share same UIDVALIDITY.
-However such a possibility would defeat \fBimapsync\fR's heuristic to
-detect whether a mailbox has been renamed or deleted offline.
-.IP \[bu]
\fBimapsync\fR is single threaded and doesn't use IMAP command
-pipelining. Performance improvement could be achieved by sending
-independent commands to each server in parallel, and for a given server,
-by sending independent commands (such as flag updates) in a pipeline.
+pipelining. Synchronization could be boosted by sending independent
+commands (such as the initial LIST/STATUS command) to each server in
+parallel, and for a given server, by sending independent commands (such
+as flag updates) in a pipeline.
.IP \[bu]
Because the IMAP protocol doesn't have a specific response code for when
a message is moved to another mailbox (using the MOVE command from