diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/getting-started.md | 7 | ||||
| -rw-r--r-- | doc/index.md | 1 | ||||
| -rw-r--r-- | doc/multi-account.md | 209 |
3 files changed, 213 insertions, 4 deletions
diff --git a/doc/getting-started.md b/doc/getting-started.md index 9499cbb..1d29231 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -102,7 +102,6 @@ Dovecot configuration: mail_location = maildir:~/Mail namespace { inbox = yes - list = yes separator = / } EOF @@ -219,7 +218,7 @@ synchronize. A user unit for systemd is provided. Run the following command to enable and start the service: - $ systemctl --user enable --now interimap + $ systemctl --user enable --now interimap.service By default the connection to the IMAP servers remains open, and a status update is requested every minute. Thanks to the [`QRESYNC`][RFC 7162] @@ -240,7 +239,7 @@ updates to 20s: <!-- --> $ systemctl --user daemon-reload <!-- --> - $ systemctl --user restart interimap + $ systemctl --user restart interimap.service Email client configuration @@ -263,7 +262,7 @@ Further Reading and Resources Other use-cases: -: *TODO* +: [Multi-remote setup](multi-account.html) Benchmarks: diff --git a/doc/index.md b/doc/index.md index bbd35d0..d475592 100644 --- a/doc/index.md +++ b/doc/index.md @@ -5,6 +5,7 @@ General documentation --------------------- * [Getting started with InterIMAP](getting-started.html) + * [Multi-remote setup for InterIMAP](multi-account.html) * [InterIMAP benchmark metrics and comparison](benchmark.html) Manuals (HTML versions) diff --git a/doc/multi-account.md b/doc/multi-account.md new file mode 100644 index 0000000..cc0a1b8 --- /dev/null +++ b/doc/multi-account.md @@ -0,0 +1,209 @@ +% Multi-remote setup for InterIMAP +% [Guilhem Moulin](mailto:guilhem@fripost.org) + +This document describes the setup of InterIMAP against two remotes +accounts, a *personal* account at `imap.example.net`, and a *work* +account at `imap.example.com`. (The same setup can be adapted to remote +accounts or more.) These remotes accounts are to be synchronized +locally, each being mirrored to its own local namespace in a +bidirectional fashion. + +We assume familiarity with the [Getting Started] tutorial. +Prerequisites, such as installing dependencies, creating directories, +etc., won't be repeated here. + + +Layout +====== + +For this example we assume the *personal* account has the following +mailbox hierarchy (with delimiter `/`): + + INBOX + debian + debian/debian-devel + debian/debian-project + debian/debian-security + archives + +And the *work* account the following mailbox hierarchy (with delimiter `.`): + + INBOX + INBOX.todo + attic + +These remote mailbox hierarchies are to be mirrored locally as: + + INBOX + perso/INBOX + perso/debian + perso/debian/debian-devel + perso/debian/debian-project + perso/debian/debian-security + perso/archives + work/INBOX + work/INBOX/todo + work/attic + +Using again (arbitrarily) `/` as local hierarchy delimiter. (Since 0.5 +each server can choose its own hierarchy delimiter independently on the +other ones, and even change it — for instance after changing the server +software — without breaking synchronization.) + +Note that there are alternative layouts (one can for instance replace +the prefix `perso/` with the empty string), however for this example +we'll focus on the above layout. + + +Local Dovecot configuration +=========================== + +Although it's not required (it's possible to use the default namespace +for everything), we propose to use a dedicated [IMAP namespace][RFC +2342] for each remote account to mirror locally: + + * It provides better isolation of the locally mirrored accounts: one + can use entirely independent mail storage for instance, and even + different hierarchy delimiters. + * One can use `perso/INBOX` as the local `INBOX`. (Per [RFC 3501] the + `INBOX` mailbox has a special nature.) Or even alias a particular + namespace to the default namespace. That being said, one should use + aliases with care as they might have undesired side effects, such as + `perso/INBOX` missing from `LIST` responses when the mailbox is used + as the local `INBOX`; or confusion between `perso/work/foo` and + `work/foo` when `perso/` is aliased to the default namespace. + +We define 3 namespaces: a default namespace holding the local `INBOX`, +as well as a dedicated namespace — with a suitable prefix — for each +remote account to mirror locally. Consult the [Dovecot namespaces] +documentation for more information. Note that mailboxes (and the +messages they contain) residing in the default namespace won't be copied +over: they will only live on the local instance. + + $ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF + ssl = no + namespace { + location = maildir:~/Mail + inbox = yes + separator = / + } + namespace perso { + prefix = perso/ + location = maildir:~/Mail/perso + separator = / + } + namespace work { + prefix = work/ + location = maildir:~/Mail/work + separator = / + } + EOF + + +We can see the three namespaces using the `` `~/.local/bin/dovecot-imap` `` +wrapper defined in the [Getting Started] tutorial. + + $ ~/.local/bin/dovecot-imap + S: * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as myuser + C: a NAMESPACE + S: * NAMESPACE (("" "/")("work/" "/")("perso/" "/")) NIL NIL + S: a OK Namespace completed (0.001 + 0.000 secs). + C: b LIST "" "*" + S: * LIST (\Noselect \HasNoChildren) "/" work + S: * LIST (\Noselect \HasNoChildren) "/" perso + S: * LIST (\HasNoChildren) "/" INBOX + S: b OK List completed (0.001 + 0.000 secs). + C: q LOGOUT + S: * BYE Logging out + S: q OK Logout completed (0.001 + 0.000 secs). + + +InterIMAP configuration +======================= + +We use a dedicated [`interimap`(1)] instance for each remote account to +synchronize, starting with the *personal* account. Again, see the +[Getting Started] guide for details about the configuration file and its +settings. + + $ install -m0600 /dev/null ${XDG_CONFIG_HOME:-~/.config}/interimap/personal +<!-- --> + $ cat >${XDG_CONFIG_HOME:-~/.config}/interimap/personal <<-EOF + database = personal.db + + [local] + type = tunnel + list-reference = perso/ + command = exec ~/.local/bin/dovecot-imap + + [remote] + type = imaps + host = imap.example.net + username = myname + password = xxxxxxxx + EOF +<!-- --> + $ interimap --config=personal + Creating new schema in database file …/personal.db + database: Created mailbox INBOX + local: Created mailbox perso/INBOX + […] + +And similarly for the *work* account: + + $ install -m0600 /dev/null ${XDG_CONFIG_HOME:-~/.config}/interimap/work +<!-- --> + $ cat >${XDG_CONFIG_HOME:-~/.config}/interimap/work <<-EOF + database = work.db + + [local] + type = tunnel + list-reference = work/ + command = exec ~/.local/bin/dovecot-imap + + [remote] + type = imaps + host = imap.example.com + username = myname2 + password = xxxxxxxx + EOF +<!-- --> + $ interimap --config=work + Creating new schema in database file …/work.db + database: Created mailbox INBOX + local: Created mailbox work/INBOX + […] + +The local mail storage should now have the desired local layout: + + $ ~/.local/bin/dovecot-imap + S: * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as myuser + C: b LIST "" "*" + S: * LIST (\Noselect \HasChildren) "/" work + S: * LIST (\HasNoChildren) "/" work/attic + S: * LIST (\HasChildren) "/" work/INBOX + S: * LIST (\HasChildren) "/" work/INBOX + S: * LIST (\HasNoChildren) "/" work/INBOX/todo + S: * LIST (\Noselect \HasChildren) "/" perso + S: * LIST (\HasNoChildren) "/" perso/INBOX + S: * LIST (\HasChildren) "/" perso/debian + S: * LIST (\HasNoChildren) "/" perso/debian/debian-security + S: * LIST (\HasNoChildren) "/" perso/debian/debian-project + S: * LIST (\HasNoChildren) "/" perso/debian/debian-devel + S: * LIST (\HasNoChildren) "/" perso/archives + S: * LIST (\HasNoChildren) "/" INBOX + S: a OK List completed (0.003 + 0.000 + 0.002 secs). + C: q LOGOUT + S: * BYE Logging out + S: q OK Logout completed (0.001 + 0.000 secs). + +Template user unit for systemd are provided in order to run these +[`interimap`(1)] instances as services: + + $ systemctl --user enable --now interimap@{personal,work}.service + +[Getting Started]: getting-started.html +[RFC 2342]: https://tools.ietf.org/html/rfc2342 +[RFC 3501]: https://tools.ietf.org/html/rfc3501 +[Dovecot namespaces]: https://doc.dovecot.org/configuration_manual/namespace/ +[`interimap`(1)]: interimap.1.html |