aboutsummaryrefslogtreecommitdiffstats
path: root/imapsync.1
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2015-07-28 00:24:17 +0200
committerGuilhem Moulin <guilhem@fripost.org>2015-07-28 00:24:17 +0200
commit9f8e0003e9f9797fe5161c6589557682ff7b8222 (patch)
treee96c16b3b28be11f6225d394b62271fc2fd2b183 /imapsync.1
parentb198cebd245942349d972a7958407b0d332da639 (diff)
parentfed8c5f21771b27c4b268e1820ed05a51012fc76 (diff)
Merge branch 'master' into debian
Diffstat (limited to 'imapsync.1')
-rw-r--r--imapsync.1134
1 files changed, 90 insertions, 44 deletions
diff --git a/imapsync.1 b/imapsync.1
index f4f6965..59093ef 100644
--- a/imapsync.1
+++ b/imapsync.1
@@ -4,21 +4,20 @@
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
.PP
.B imapsync\fR performs stateful synchronization between two IMAP4rev1
-servers, then (unless the flag \fB\-\-oneshot\fR is set) keeps both
-connection open and wait for new changes to arrive.
+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
@@ -70,20 +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.
-
-.PP
-In its default mode (unless the flag \fB\-\-oneshot\fR or
-\fB\-\-repair\fR is set), \fBimapsync\fR does not exit once all
-mailboxes have been synchronized. Instead, it keeps both connection
-open and uses the NOTIFY command from [RFC5465] to be notified of new
-changes (on any mailbox) as soon as they arrive. If no update is sent
-in 15 minutes, a NOOP command is issued in order not to trigger the
-servers' inactivity timeout and be logged out.
+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
@@ -96,23 +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.
-
-.TP
-.B \-1\fR, \fB\-\-oneshot\fR
-Exit as soon as all mailboxes are synchronized, instead of passively
-waiting for updates from the open connections.
-Using \fB\-\-oneshot\fR removes the requirement that IMAP servers must
-advertise support the NOTIFY extension [RFC5465].
+.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
@@ -124,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.
@@ -168,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 pattern 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.
@@ -248,21 +304,11 @@ 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
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,