aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/benchmark.md4
-rw-r--r--doc/build.md65
-rw-r--r--doc/development.md77
-rw-r--r--doc/getting-started.md22
-rw-r--r--doc/interimap.1.md2
-rw-r--r--doc/multi-account.md25
6 files changed, 115 insertions, 80 deletions
diff --git a/doc/benchmark.md b/doc/benchmark.md
index 72f51a4..3b58e10 100644
--- a/doc/benchmark.md
+++ b/doc/benchmark.md
@@ -48,8 +48,8 @@ by placing packet counters on the interface.
[OfflineIMAP]: https://www.offlineimap.org/
[benchmark-script]: https://git.guilhem.org/interimap/plain/benchmark/run
[Dovecot]: https://dovecot.org
-[dbox]: https://wiki.dovecot.org/MailboxFormat/dbox
-[maildir]: https://wiki.dovecot.org/MailboxFormat/Maildir
+[dbox]: https://doc.dovecot.org/latest/core/config/mailbox_formats/dbox.html
+[maildir]: https://doc.dovecot.org/latest/core/config/mailbox_formats/maildir.html
-----------------------------------------------------------------------
diff --git a/doc/build.md b/doc/build.md
index 2e4e511..b40760e 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -38,10 +38,10 @@ Additional packages are required in order to run the test suite:
$ sudo apt install dovecot-imapd dovecot-lmtpd openssl procps sqlite3 xxd
<!-- -->
- $ make test
+ $ make check
-(The test suite also needs to bind to TCP ports 10024, 10143 and 10993
-on the loopback interface.)
+(Note also that the test suite needs to bind to TCP ports 10024, 10143
+and 10993 on the loopback interface.)
Generate documentation
======================
@@ -51,32 +51,53 @@ Yet another set of packages is needed to generate the documentation:
$ sudo apt install jq pandoc
Run `` `make manual` `` (or just `` `make` ``) in order to generate the
-manpages. You'll find them at `doc/*.[1-9]`. Use for instance `` `man
--l doc/interimap.1` `` in order to read your copy of the [`interimap`(1)]
-manpage.
+manuals. You'll find them at `build/doc/*.[1-9]`. Then use for
+instance `` `man -l build/doc/interimap.1` `` to read your local copy of
+the [`interimap`(1)] manual.
-The HTML documentation can be built with `` `make html` ``. HTML files
-are generated alongside their Markdown source by default, but you can
-choose another target directory using the `HTML_ROOTDIR` environment
-variable (the value of which defaults to `./doc`). Moreover the
-[`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) is
-needed by default for the local CSS file; this can be controlled with
-the `CSS` environment variable (the value of which defaults to
-`/usr/share/javascript/bootstrap/css/bootstrap.min.css`).
+The HTML documentation can be built with `` `make html` ``. By default
+HTML files are generated at `build/doc/*.html`, and a local CSS file is
+used — namely `/usr/share/javascript/bootstrap4/css/bootstrap.css`,
+shipped the by [`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap)
+package. But this is configurable: use for instance
-For instance, use
+ $ make html builddir="$XDG_RUNTIME_DIR/interimap" \
+ CSS="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/css/bootstrap.min.css"
- $ env CSS="https://guilhem.org/static/css/bootstrap.min.css" \
- HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
- make html
+to generate the HTML documentation under `$XDG_RUNTIME_DIR/interimap/doc`
+using a remote CSS file.
-to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap`
-(which needs to exist) using a remote CSS file.
-
-The `doc` target generates all documentation, manpages as well as HTML
+The `doc` target generates all documentation, manuals as well as HTML
pages.
+Installation without root privileges
+====================================
+
+By default `` `make install` `` installs [`interimap`(1)] under
+`/usr/local`, hence requires root privileges. However another prefix
+can be used in order to perform the (un)installation as an unprivileged
+user. For instance
+
+ $ install -m0700 -vd ${XDG_DATA_HOME:-~/.local/share}/interimap
+ $ make install-nodoc \
+ prefix=$HOME/.local \
+ sitelib=${XDG_DATA_HOME:-~/.local/share}/interimap/lib \
+ systemd_userunitdir=${XDG_DATA_HOME:-~/.local/share}/systemd/user
+
+skips documentation and installs
+
+ * executables into `~/.local/bin` (instead of `/usr/local/bin`);
+ * libraries into `$XDG_DATA_HOME/interimap/lib` or `~/.local/share/interimap/lib`
+ (instead of `/usr/local/lib/site_perl`); and
+ * [systemd user unit files][`systemd.unit`(5)] into `$XDG_DATA_HOME/systemd/user`
+ or `~/.local/share/systemd/user` (instead of `/usr/local/lib/systemd/user`).
+
+Note that for uninstallation one must call `` `make uninstall prefix=…` ``
+with the very same assignment(s) used for installation.
+
+[`systemd.unit`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
+
Build custom Debian packages
============================
diff --git a/doc/development.md b/doc/development.md
index f4578b9..f739dc0 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -15,14 +15,18 @@ Dovecot configuration
=====================
Create a file `$BASEDIR/dovecot.conf`, which will be used as
-configuration for the various Dovecot commands (the system configuration
-will be skipped).
+configuration for the various Dovecot 2.4 commands (the system
+configuration will be skipped).
$ cat >"$BASEDIR/dovecot.conf" <<-EOF
- log_path = "$BASEDIR/dovecot.log"
- ssl = no
- mail_home = "$BASEDIR/%u"
- mail_location = maildir:~/Mail
+ dovecot_config_version = 2.4.0
+ dovecot_storage_version = 2.4.0
+ log_path = "$BASEDIR/dovecot.log"
+ ssl = no
+
+ mail_home = "$BASEDIR/%{user | username | lower}"
+ mail_driver = maildir
+ mail_path = ~/Mail
EOF
Here are some details on the above:
@@ -36,18 +40,17 @@ Here are some details on the above:
`mail_home`
: Dovecot needs the name of the user to (pre-)authenticate. It is shown
- in the greeting line, and also used in [`%`-variable] expansion.
+ in the greeting line, and also used in [settings variables] expansion.
Several [`doveadm`(1)] sub-commands have a `-u` (or `-d`) option which
- can be used to determine the username. When this option is not set,
- the username is taken from the `USER` environment variable. If that
- environment variable is unset as well, then the return string of
- [`getlogin`(3)] is used.
+ can be used to determine the username. To avoid performing the userdb
+ lookup one can pass `--no-userdb-lookup` instead, in which case the
+ username is taken from the `USER` environment variable.
Similarly, the user's home directory is used in (`~`- and)
- [`%`-variable] expansion. It's taken from the `HOME` environment
- variable when the `mail_home` setting is left unset in the Dovecot
- configuration (and not overridden by the [user database][User
- Databases].
+ [settings variables] expansion. It's taken from the `HOME`
+ environment variable when the `mail_home` setting is left unset in
+ the Dovecot configuration (and not overridden by the
+ [user database][User Databases].
`mail_home` can therefore be left unset if the `HOME` environment
variable is consistently set to `$BASEDIR/$USER`. However it's
@@ -55,14 +58,17 @@ Here are some details on the above:
command run in a non-curated environment might mess up with your own
mail storage…
-`mail_location`
+`mail_driver`
- : The user's mail storage resides — in [Maildir] format — in a directory
- `Mail` under their home directory. This is enough if you're fine with
- the default IMAP hierarchy delimiter (which depends on the mail format)
- is used, and if you need a single [IMAP namespace][RFC 2342]. For more
- complex setups you'll need one or more [`namespace {…}` block][Dovecot
- Namespaces].
+ : Use the [Maildir] format for mail storage..
+
+`mail_path`:
+
+ : The user's mail storage resides in a directory `Mail` under their
+ home directory. This is enough if you're fine with the default IMAP
+ hierarchy delimiter (which depends on the mail format) is used, and
+ if you need a single [IMAP namespace][RFC 2342]. For more complex
+ setups you'll need one or more [`namespace {…}` block][Dovecot Namespaces].
Mail storage access
===================
@@ -88,7 +94,7 @@ the latter to create a mailbox `foo`, add a sample message to it, and
finally mark it as `\Seen`.
$ env -i PATH="/usr/bin:/bin" USER="testuser" \
- doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo"
+ doveadm -c "$BASEDIR/dovecot.conf" mailbox create --no-userdb-lookup "foo"
<!-- -->
$ env -i PATH="/usr/bin:/bin" USER="testuser" HOME="$BASEDIR/testuser" \
doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF
@@ -102,7 +108,7 @@ finally mark it as `\Seen`.
EOF
<!-- -->
$ env -i PATH="/usr/bin:/bin" USER="testuser" \
- doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*"
+ doveadm -c "$BASEDIR/dovecot.conf" flags add --no-userdb-lookup "\\Seen" mailbox "foo" "*"
Normally [`dovecot-lda`(1)][Dovecot LDA] tries to do a userdb lookup in
order to determine the user's home directory. Since we didn't configure
@@ -136,7 +142,7 @@ and `remote` accounts.
Run [`interimap`(1)] without `--watch` in order to create the database.
- $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf"
+ $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf"
Creating new schema in database file …/interimap.db
database: Created mailbox INBOX
[…]
@@ -144,7 +150,7 @@ Run [`interimap`(1)] without `--watch` in order to create the database.
You can now run [`interimap`(1)] with `--watch` set, here to one second
to observe synchronization steps early.
- $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf" \
--watch=1 --debug
Use instructions from the [previous section][Mail storage access]
@@ -168,12 +174,12 @@ Create a [`pullimap`(1)] configuration file with as section `[foo]`.
Run [`pullimap`(1)] without `--idle` in order to create the state file.
- $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \
--no-delivery foo
You can now run [`pullimap`(1)] with `--idle` set.
- $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \
--no-delivery --idle --debug foo
Use instructions from the [previous section][Mail storage access]
@@ -193,14 +199,13 @@ recursively remove the directory `$BASEDIR`.
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
[Dovecot]: https://dovecot.org
-[Dovecot Logging]: https://doc.dovecot.org/admin_manual/logging/
-[Dovecot LDA]: https://wiki.dovecot.org/LDA
-[`getlogin`(3)]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getlogin.html
-[User Databases]: https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/
-[Maildir]: https://wiki.dovecot.org/MailLocation/Maildir
+[Dovecot Logging]: https://doc.dovecot.org/latest/core/admin/logging.html#dovecot-logging
+[Dovecot LDA]: https://doc.dovecot.org/latest/core/config/delivery/lda.html
+[User Databases]: https://doc.dovecot.org/latest/core/config/auth/userdb.html
+[Maildir]: https://doc.dovecot.org/latest/core/config/mailbox_formats/maildir.html
[RFC 2342]: https://tools.ietf.org/html/rfc2342
-[Dovecot Namespaces]: https://doc.dovecot.org/configuration_manual/namespace/
+[Dovecot Namespaces]: https://doc.dovecot.org/latest/core/config/namespaces.html
[`interimap`(1)]: interimap.1.html
[`pullimap`(1)]: pullimap.1.html
-[`doveadm`(1)]: https://wiki.dovecot.org/Tools/Doveadm
-[`%`-variable]: https://doc.dovecot.org/configuration_manual/config_file/config_variables/
+[`doveadm`(1)]: https://doc.dovecot.org/latest/core/man/doveadm.1.html
+[settings variables]: https://doc.dovecot.org/latest/core/settings/variables.html
diff --git a/doc/getting-started.md b/doc/getting-started.md
index 74fc8da..e89eb19 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -84,7 +84,7 @@ 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 instead insists on
connecting to a network socket (in that case you'll even need to
-configure [user authentication](https://wiki.dovecot.org/Authentication)
+configure [user authentication](https://doc.dovecot.org/latest/core/config/auth/overview.html)
for the IMAP service, which is out of scope for the present document).
Run the following command to terminate and disable the system-wide
@@ -94,14 +94,19 @@ Dovecot processes.
Create a new directory `$XDG_CONFIG_HOME/dovecot` holding the local
-Dovecot configuration:
+Dovecot 2.4 configuration:
$ install -m0700 -vd ${XDG_CONFIG_HOME:-~/.config}/dovecot
<!-- -->
$ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF
+ dovecot_config_version = 2.4.0
+ dovecot_storage_version = 2.4.0
+
ssl = no
- mail_location = maildir:~/Mail
- namespace {
+ mail_home = /home/%{user | username | lower}
+ mail_driver = maildir
+ mail_path = ~/Mail
+ namespace inbox {
inbox = yes
separator = /
}
@@ -113,9 +118,10 @@ Some remarks on the above:
running `` `doveconf -nc ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf` ``.
* 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.
+ continuing! You may want to choose a different
+ [format](https://doc.dovecot.org/latest/core/config/mailbox_formats/overview.html)
+ here, or simply set `mailbox_list_layout = fs` 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 (even on an existing mail store). Popular hierarchy
@@ -281,7 +287,7 @@ Manual
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
[INI file]: https://en.wikipedia.org/wiki/INI_file
[`interimap`(1)]: interimap.1.html
-[LMTP server]: https://doc.dovecot.org/configuration_manual/protocols/lmtp_server/
+[LMTP server]: https://doc.dovecot.org/latest/core/config/delivery/lmtp.html
[Maildir]: https://en.wikipedia.org/wiki/Maildir
[mbox]: https://en.wikipedia.org/wiki/Mbox
[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 2d588ae..18b3581 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -602,4 +602,4 @@ A _getting started_ guide is available [there](getting-started.html).
[PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html
[`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-verify.html
-[`doveadm-deduplicate`(1)]: https://wiki.dovecot.org/Tools/Doveadm/Deduplicate
+[`doveadm-deduplicate`(1)]: https://doc.dovecot.org/latest/core/man/doveadm-deduplicate.1.html
diff --git a/doc/multi-account.md b/doc/multi-account.md
index cc0a1b8..58fdd2d 100644
--- a/doc/multi-account.md
+++ b/doc/multi-account.md
@@ -82,20 +82,23 @@ 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 indbox {
+ mail_driver = maildir
+ mail_path = ~/Mail
+ inbox = yes
+ separator = /
}
namespace perso {
- prefix = perso/
- location = maildir:~/Mail/perso
- separator = /
+ prefix = perso/
+ mail_driver = maildir
+ mail_path = ~/Mail/perso
+ separator = /
}
namespace work {
- prefix = work/
- location = maildir:~/Mail/work
- separator = /
+ prefix = work/
+ mail_driver = maildir
+ mail_path = ~/Mail/work
+ separator = /
}
EOF
@@ -205,5 +208,5 @@ Template user unit for systemd are provided in order to run these
[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/
+[Dovecot namespaces]: https://doc.dovecot.org/latest/core/config/namespaces.html
[`interimap`(1)]: interimap.1.html
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-01 08:22:13 +0000