Promote SSH connections to the remote IMAP server.

1 files changed, 41 insertions, 45 deletions

diff --git a/README b/README
index 5db5b9e..4192812 100644
--- a/README
+++ b/README
@@ -7,53 +7,49 @@ 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.
+
+#######################################################################
+
+
+IMAP traffic is mostly text (beside message bodies perhaps) hence
+compresses pretty well: enabling compression can save a great amount of
+network resources.
+
+However establishing a SSL/TLS connection (type=imaps, or type=imap and
+STARTTLS=YES) yields a small overhead due to the SSL/TLS handshake.
+
+On the other hand if SSH access is allowed on the remote server, one can
+tunnel the IMAP traffic through SSH and use OpenSSH's ControlPersist
+feature to save most of the cryptographic overhead (at the expense of a
+local 'ssh' process and a remote 'imap' process).  Moreover if the IMAP
+user is a valid UNIX user it is possible to use pre-authentication on
+the remote server as well, which saves the extra round trip caused by
+the AUTHENTICATE command.  For instance the following configuration
+snippet saves bandwidth and brings a significant speed gain compared to
+type=imaps.
+
+    local: $XDG_CONFIG_HOME/imapsync:
+      [remote]
+      type = tunnel
+      command = /usr/bin/ssh user@imap.example.net
+
+    local: ~/.ssh/config:
+      Host imap.example.net
+          IdentityFile ~/.ssh/id-imapsync
+          IdentitiesOnly yes
+          ControlPath /run/shm/%u@%n
+          ControlMaster auto
+          ControlPersist 10m
+          StrictHostKeyChecking yes
+          ServerAliveCountMax 3
+          ServerAliveInterval 10s
+          RequestTTY no
+          Compression yes
+
+    remote: ~user/.ssh/authorized_keys:
+      command="/usr/lib/dovecot/imap",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-... id-imapsync