aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2015-09-05 17:30:07 +0200
committerGuilhem Moulin <guilhem@fripost.org>2015-09-05 17:36:31 +0200
commitf5b7ec21e9d53ac7d93797a83c3c100dfa4de076 (patch)
tree073a1124dfaeb88d01580778b8a9c2f8173a7632 /README
parent9ec7513acbf34732ad7983ca3be24cef6b64b9a9 (diff)
Add README file.
Diffstat (limited to 'README')
-rw-r--r--README59
1 files changed, 59 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..5db5b9e
--- /dev/null
+++ b/README
@@ -0,0 +1,59 @@
+imapsync performs stateful synchronization between two IMAP4rev1
+servers. Such synchronization is made possible by the QRESYNC extension
+from [RFC7162]; for convenience reasons servers must also support
+LIST-EXTENDED [RFC5258], LIST-STATUS [RFC5819] and UIDPLUS [RFC4315].
+Furthermore, while imapsync 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.
+
+
+Stateful synchronization is only possible for mailboxes supporting
+persistent message Unique Identifiers (UID) and persistent storage of
+mod-sequences (MODSEQ); any non-compliant mailbox will cause imapsync to
+abort. Furthermore, because UIDs are allocated not by the client but by
+the server, imapsync needs to keep track of associations between local
+and remote UIDs for each mailbox. The synchronization state of a
+mailbox consists of its UIDNEXT and HIGHESTMODSEQ values on each server;
+it is then assumed that each message with UID < $UIDNEXT have been
+replicated to the other server, and that the metadata (such as flags) of
+each message with MODSEQ <= $HIGHESTMODSEQ have been synchronized.
+Conceptually, the synchronization algorithm is derived from [RFC4549]
+with the [RFC7162, section 6] amendments, and works as follows:
+
+
+ 1. SELECT (on both servers) a mailbox the current UIDNEXT or
+ HIGHESTMODSEQ values of which differ from the values found in the
+ database (for either server). Use the QRESYNC SELECT parameter from
+ [RFC7162] to list changes (vanished messages and flag updates) since
+ $HIGHESTMODSEQ to messages with UID<$UIDNEXT.
+
+ 2. Propagate these changes onto the other server: get the corresponding
+ UIDs from the database, then a/ issue an UID STORE + UID EXPUNGE
+ command to remove messages that have not already been deleted on
+ both servers, and b/ issue UID STORE commands to propagate flag
+ updates (send a single command for each flag list in order the
+ reduce the number of round trips). (Conflicts may occur if the
+ metadata of a message has been updated on both servers with
+ different flag lists; in that case imapsync issues a warning and
+ updates the message on each server with the union of both flag
+ lists.) Repeat this step if the server sent some updates in the
+ meantime. Otherwise, update the HIGHESTMODSEQ value in the
+ database.
+
+ 3. Process new messages (if the current UIDNEXT value differ from the
+ one found in the database) by issuing an UID FETCH command and for
+ each message RFC822 body received, issue an APPEND command to the
+ other server on-the-fly. Repeat this step if the server received
+ new messages in the meantime. Otherwise, update the UIDNEXT value
+ in the database. Go back to step 2 if the server sent some updates
+ in the meantime.
+
+ 4. Go back to step 1 to proceed with the next unsynchronized mailbox.
+
+
+Consult the manual for more information.
+
+imapsync is Copyright© 2015 Guilhem Moulin ⟨guilhem@fripost.org⟩, and
+licensed for use under the GNU General Public License version 3 or
+later. See ‘COPYING’ for specific terms and distribution information.