From f5b7ec21e9d53ac7d93797a83c3c100dfa4de076 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sat, 5 Sep 2015 17:30:07 +0200 Subject: [PATCH] Add README file. --- README | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 README 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. -- 2.39.2