From ab6bc80e9935b7c2144300216b0c7e4cc2e1f73a Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 8 Jul 2019 18:43:02 +0200 Subject: Improve wording. --- doc/getting-started.md | 107 ++++++++++++++++++++++++++----------------------- 1 file changed, 56 insertions(+), 51 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 5b59f92..d8f92d5 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -2,10 +2,9 @@ % [Guilhem Moulin](mailto:guilhem@fripost.org); [Gustav Eek](mailto:gustav.eek@fripost.org) -This describes the setup of InterIMAP for a rather usual user-case, where -messages on a remote IMAP server `imaps://imap.example.net` are -synchronized locally. Changes on either end is replicated on the other -one. +This document describes the setup of InterIMAP for a rather usual user-case, +where messages on a remote IMAP server `imap.example.net` are synchronized +locally. Changes on either end is replicated on the other one. Local IMAP server @@ -15,14 +14,14 @@ Background and rationale ------------------------ On a workstation, one's mail storage is often found under `~/Maildir` -(in [*Maildir* format](https://en.wikipedia.org/wiki/Maildir)) or in -`/var/mail/$USER` (in [*mbox* format](https://en.wikipedia.org/wiki/Mbox)). -Local mail clients typically access it directly, and maintain their own -cache in order to speed up message header listing and searches. +(in [*Maildir* format][Maildir]) or in `/var/mail/$USER` (in [*mbox* +format][mbox]). Local mail clients typically access it directly. They +also often maintain their own cache in order to speed up message header +listing and searches. While bidirectional synchronisation software (such as [OfflineIMAP]) is often able to handle a mail storage in Maildir format, *InterIMAP is -not*. Instead, InterIMAP needs an [IMAP4rev1] server on both ends to +not*. Instead, InterIMAP needs an [IMAP4rev1] server on *both* peers to synchronize. This may sound like a severe limitation at first, but by seeing both local and remote mail storages though the same “IMAP lens”, InterIMAP is able to take advantage of the abstraction layer and do @@ -33,33 +32,31 @@ extension for stateful synchronization, hence won't work on IMAP servers that don't advertize support for that extension. Installing an [IMAP4rev1] server on a single-user workstation may sound -overkill, but we argue that Debian GNU/Linux systems generally come with a -[Message Transfer Agent][MTA] installed, and not only on servers. Just -like one may use `/usr/sbin/sendmail` (or a compatible interface) in -order to send mail out, we propose to use an `imap` binary to access -them. +overkill, but we argue that most systems, not only servers, come with a +[Message Transfer Agent][MTA] preinstalled. Just like one may use +`/usr/sbin/sendmail` (or a compatible interface) in order to send mail +out, we propose to use an `imap` binary to access them. In order to fully take advantage of the abstraction layer and InterIMAP's optimizations, one should *always* access the mail storage through the local [IMAP4rev1] server and *never directly*. Otherwise -the IMAP server will keep invalidating its cache when it notices -inconsistencies, yielding a performance hit. (*Or worse*: very likely -many [IMAP4rev1] servers are not able to gracefuly deal with cache -inconsistencies.) As far as the mail client is concerned, the cost of -abstraction seems to be negligible (*TODO* link to benchmark). -Furthermore, we think that approach is in line with the [Unix -philosophy]: the mail client only takes care of the rendering part, -leaving the rest to the IMAP server (searches, sorting/threading, as -well as storage and caching logic). +the IMAP server will invalidate its cache each time it notices +inconsistencies, thereby causing a servere performance hit. (*Or +worse*: very likely many [IMAP4rev1] servers are not able to gracefuly +deal with cache inconsistencies.) As far as the mail client is +concerned, the cost of abstraction seems to be negligible (*TODO* link +to benchmark). Furthermore, we think that approach is in line with the +[Unix philosophy]: the mail client only takes care of the rendering +part, leaving the rest to the IMAP server (searches, sorting/threading, +as well as storage and caching logic). Installation ------------ While this document focuses on [Dovecot](https://dovecot.org), a popular [IMAP4rev1] server, any other [`QRESYNC`][RFC 7162]-capable server -should work equally well. - -On Debian GNU/Linux systems, run the following command (as root): +should work equally well. Run the following command (as root) to +install the Dovecot IMAP server on a Debian GNU/Linux system. $ apt install dovecot-imapd @@ -77,22 +74,27 @@ it can spawn a command and use its standard input (resp. output) for is [Mutt], for which we propose a configuration snippet [below][todo link]. -Since we don't need the Dovecot services nor master process here, we -simply disable it. Run the following as root: +Since we don't need the Dovecot services nor master process in this +example, we disable them and create a local configuration file under +`$XDG_CONFIG_HOME/dovecot`. If you need to keep the system-wise +services (for instance because your [MTA] uses the [LMTP server] for +mailbox delivery) then don't disable them, and modify Dovecot's system +wide configuration instead. Same thing if your mail client isn't able +to spawn a command for IMAP communication and insists on connecting to +an `INET` socket (in that case you'll even need to configure [user +authentication](https://wiki.dovecot.org/Authentication) for the IMAP +service, which is out of scope for the present document). + +Run the following command (as root) to terminate and disable the +system-wide Dovecot processes. $ systemctl mask --now dovecot.socket dovecot.service -*Note*: If your mail client doesn't have this ability, and instead insists on -connecting to a `INET` socket, then you may have to use `socat`(1) or -similar to spawn the command; or alternatively, keep the Dovecot master -process but edit the configuration so the IMAP daemon listens on the -loopback interface. This is however out of scope for the present -document. Consult the [Dovecot wiki](https://wiki.dovecot.org/) for -details. -We store the local Dovecot configuration under `$XDG_CONFIG_HOME/dovecot`: +Create a new directory `$XDG_CONFIG_HOME/dovecot` holding the local +Dovecot configuration: - $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/dovecot + $ install -m0700 -vd ${XDG_CONFIG_HOME:-~/.config}/dovecot $ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF ssl = no @@ -119,10 +121,10 @@ Some remarks on the above: change it later (on an existing mail store). Popular hierarchy delimiters include `/` (slash) and `.` (period). -Let's now test the configuration by starting a pre-authenticated -[IMAP4rev1] session and issuing two command, first `` `LIST "" "*"` `` -to recursively list all mailboxes (along with their hierarchy -delimiter), then `` `LOGOUT` `` to… log out and exit. +Now test the configuration by starting a pre-authenticated [IMAP4rev1] +session and issuing two commands, first `` `LIST "" "*"` `` to +recursively list all mailboxes (along with their hierarchy delimiter), +then `` `LOGOUT` `` to… log out and exit. $ doveadm -c ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf exec imap * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as myuser @@ -134,7 +136,7 @@ delimiter), then `` `LOGOUT` `` to… log out and exit. q OK Logout completed (0.001 + 0.000 secs). Create a wrapper under `~/.local/bin` in order to avoid hard-coding the -Dovecot configuration path: +local Dovecot configuration path: $ install -Dm 0755 /dev/stdin ~/.local/bin/dovecot-imap <<-EOF #!/bin/sh @@ -145,22 +147,22 @@ Dovecot configuration path: exec imap EOF -You can now start a pre-authenticated [IMAP4rev1] session to your local -mail store by simply running `` `~/.local/bin/dovecot-imap` ``. +You can now start a pre-authenticated [IMAP4rev1] session like the one +above by simply running `` `~/.local/bin/dovecot-imap` ``. InterIMAP ======== -On Debian 9 (codename Stretch) and later, installing the packange is one -command away. Simply run the following (as root): +On Debian 10 (codename *Buster*) and later, installing the package is +one command away. Simply run the following (as root): $ apt install interimap -Create config file: +Create directories for the InterIMAP configuration and data files: - $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/interimap \ - ${XDG_DATA_HOME:-~/.local/share}/interimap + $ install -m0700 -vd ${XDG_CONFIG_HOME:-~/.config}/interimap \ + ${XDG_DATA_HOME:-~/.local/share}/interimap $ install -m0600 /dev/stdin ${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF # only consider subscribed mailboxes @@ -192,7 +194,7 @@ between synchronization runs to 20s: $ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d - $ install -m 0644 /dev/stdin ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d/override.conf" <<-EOF + $ cat >${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d/override.conf" <<-EOF [Service] ExecStart= ExecStart=/usr/bin/interimap --watch=20 @@ -221,8 +223,11 @@ Put in your mutt configuration (XXX): [IMAP4rev1]: https://tools.ietf.org/html/rfc3501 [`interimap`(1)]: interimap.1.html -[OfflineIMAP]: https://www.offlineimap.org/ +[LMTP server]: https://wiki.dovecot.org/LMTP +[Maildir]: https://en.wikipedia.org/wiki/Maildir +[mbox]: https://en.wikipedia.org/wiki/Mbox [MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent [Mutt]: http://mutt.org/ +[OfflineIMAP]: https://www.offlineimap.org/ [RFC 7162]: https://tools.ietf.org/html/rfc7162 [Unix philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy -- cgit v1.2.3