From f1a6866c265bf63efefce68be7f6eae22d477309 Mon Sep 17 00:00:00 2001 From: Gustav Eek Date: Fri, 5 Jul 2019 22:23:01 +0200 Subject: WIP: getting started document --- doc/getting-started.md | 228 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 doc/getting-started.md (limited to 'doc/getting-started.md') diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 0000000..5b59f92 --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,228 @@ +% Getting started with InterIMAP +% [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. + + +Local IMAP server +================= + +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. + +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 +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 +significant optimizations, yielding much faster synchronization. +(*TODO* link to benchmark) +*Note*: InterIMAP uses the [Quick Mailbox Resynchronization][RFC 7162] +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. + +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). + +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): + + $ apt install dovecot-imapd + +(The leading `$ ` in this document are command-line prompt strings, and +are not part of the command themselves.) + +Configuration +------------- + +Our [`interimap`(1)] instance will use the `imap` command from Dovecot's +`libexec_dir` in order to access the local mail storage. We assume that +the mail client can access it in the same fashion. In other words, that +it can spawn a command and use its standard input (resp. output) for +[IMAP4rev1] commands (resp. responses). An example of such mail client +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: + + $ 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`: + + $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/dovecot + + $ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF + ssl = no + mail_location = maildir:~/Mail + namespace { + inbox = yes + list = yes + separator = / + } + EOF + +Some remarks on the above: + + * SSL/TLS is explicitely turned off so dumping the configuration with + `` `doveconf -c ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf -n` `` + doesn't spew a warning. + * Messages will be stored in Maildir format under `~/Mail`. Ensure + the directory is either *empty* or *doesn't exist* before + continuing! You may want to choose a different [format](https://wiki.dovecot.org/MailboxFormat) + here, or simply append `:LAYOUT=fs` to the `mail_location` value in + order to use a nicer (File System like) Maildir layout. + * The `separator` setting defines the IMAP hierarchy delimiter. This + is orthogonal to the Maildir layout delimiter, and you can safely + 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. + + $ doveadm -c ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf exec imap + * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as myuser + a LIST "" "*" + * LIST (\HasNoChildren) "/" INBOX + a OK List completed (0.001 + 0.000 secs). + q LOGOUT + * BYE Logging out + 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: + + $ install -Dm 0755 /dev/stdin ~/.local/bin/dovecot-imap <<-EOF + #!/bin/sh + set -ue + export PATH="/usr/bin:/bin" + exec env -i PATH="\$PATH" HOME="\$HOME" USER="\$USER" \\ + doveadm -c "\${XDG_CONFIG_HOME:-\$HOME/.config}/dovecot/dovecot.conf" \\ + exec imap + EOF + +You can now start a pre-authenticated [IMAP4rev1] session to your local +mail store 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): + + $ apt install interimap + +Create config file: + + $ mkdir -pvm 0700 ${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 + list-select-opts = SUBSCRIBED + # ignore the mailbox named 'virtual' and its descendants + # WARN: for <=0.4 it should be: ^virtual(?:/|$) + ignore-mailbox = ^virtual(?:\x00|$) + + [local] + type = tunnel + command = exec ~/.local/bin/dovecot-imap + + [remote] + type = imaps + host = imap.example.net + username = myname + password = xxxxxxxx + EOF + +Create the database: + + $ interimap + Creating new schema in database file …/interimap.db + database: Created mailbox INBOX + […] + +Override systemd unit if desired, for instance to reduce the interval +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 + [Service] + ExecStart= + ExecStart=/usr/bin/interimap --watch=20 + EOF + + $ systemctl --user daemon-reload + +Enable unit and start it: + + $ systemctl --user enable --now interimap + + +Configure email client +====================== + +Put in your mutt configuration (XXX): + + $ cat >/tmp/muttrc <<-EOF + set tunnel = "exec ~/.local/bin/dovecot-imap" + set folder = "imap://foo" + set spoolfile = "imap://foo" + EOF + + $ mutt -n -F /tmp/muttrc + + +[IMAP4rev1]: https://tools.ietf.org/html/rfc3501 +[`interimap`(1)]: interimap.1.html +[OfflineIMAP]: https://www.offlineimap.org/ +[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent +[Mutt]: http://mutt.org/ +[RFC 7162]: https://tools.ietf.org/html/rfc7162 +[Unix philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy -- cgit v1.2.3