Dovecot

This page has information about how to configure and use the Dovecot IMAP server. Dovecot can also act as an MDA/LDA (Mail Delivery Agent / Local Delivery Agent), but I have already configured Exim to do that.


Debian packages

This Debian package should pull in all the necessary dependencies

dovecot-imapd


References


System configuration

Users/groups

Installing the Debian packages adds two new system users:

  • dovecot: Dovecot mail server
  • dovenull : Dovecot login user

The packages also add two new system groups dovecot and dovenull, one group for every new system user.

See the Dovecot Manual for details.


Default file

Installing the Debian packages creates this file, which currently does not seem to contain anything useful for me:

/etc/default/dovecot


PAM integration

Installing the Debian packages creates this file, which integrates Dovecot with the PAM authentication system:

/etc/pam.d/dovecot


Systemd integration

Installing the Debian packages creates this file, which integrates Dovecot with Systemd:

/etc/systemd/system/multi-user.target.wants/dovecot.service

The service can now be started/stopped/restarted like this:

systemctl start|stop|restart dovecot


Configuration

Files

Dovecot's configuration files are located in

/etc/dovecot

As is usual in Debian, the Dovecot configuration is split into many small configuration files that are located in

/etc/dovecot/conf.d

The config file syntax is explained in the Dovecot Manual.

I place the server-specific configuration in a new file:

touch /etc/dovecot/conf.d/99-pelargir.conf


Debconf configuration

There is no Debconf configuration when the Dovecot Debian packages are installed.


Network ports

The standard configuration of Dovecot listens on ports 143 (IMAP) and 993 (IMAPS).

To disable port 993 you have to set the port setting of the appropriate service to 0 in the Dovecot configuration. This looks like this in my server-specific config file:

root@pelargir:/etc/dovecot/conf.d# cat 99-pelargir.conf 
service imap-login {
  inet_listener imaps {
    # Disable IMAPS
    port = 0
  }
}


Email message storage

The default location where email messages are stored, and the default format, are set in 10-mail.conf:

mail_location = mbox:~/mail:INBOX=/var/mail/%u

This is not what I want, so I override the setting the server-specific config file 99-pelargir.conf:

mail_location = maildir:~/Maildir

This causes Dovecot to store mail in the so-called Maildir format. It requires that every user has a folder in his or her home directory that corresponds to the Maildir conventions. The folder should be named Maildir, as this is also a common IMAP convention. The folder can be created with the following command:

maildirmake.dovecot /home/<user>/Maildir

Notes:

  • Maildir integration with the Debian MTA Exim is described on the Exim wiki page.
  • The full specification how to configure the mail location can be found in the Dovecot Manual.
  • I am not aware of any special permission requirements for the Maildir folder. Currently I have set the folder to be owned by the user and the user's main group because that was a requirement enforced by Courier IMAP.


Authentication

The default authentication mechanism is set in 10-auth.conf:

auth_mechanisms = plain

The PLAIN authentication mechanism means that the IMAP client must send the password in plain text - which is fine, because it's what most IMAP clients understand and can handle. From a security point of view this is also OK for me because I enforce the use of TLS on this server. The Dovecot Manual has a list of non-plaintext authentication mechanisms that Dovecot supports.


The default password database to use for authentication is set in auth-system.conf.ext (which is included by 10-auth.conf):

passdb {
  driver = pam
}

The use of PAM is perfectly fine for me since my system's PAM configuration is set up to check non-system users against LDAP. Note: For PAM to work a file /etc/pam.d/dovecot must exist - which it does, see the section PAM integration above.


SSL/TLS

At the time of writing, the Dovecot Manual does not seem to have a coherent section explaining all the SSL/TLS configuration options. The only place I have found that collects this information is the Dovecot Wiki.

The default SSL/TSL configuration is set in 10-ssl.conf:

# Basic enabling of SSL/TSL
ssl = yes

# Public certificate and private key
ssl_cert = </etc/dovecot/private/dovecot.pem
ssl_key = </etc/dovecot/private/dovecot.key

# SSL DH parameters file
ssl_dh = </usr/share/dovecot/dh.pem

# Directory with trusted CA certificates
ssl_client_ca_dir = /etc/ssl/certs

Notes:

  • Basic enabling of SSL/TSL allows the client to choose whether or not to actually use SSL/TSL. I want to be more strict, I want SSL/TSL to be required, so ssl = yes will have to change.
  • The public certificate and private key obviously must be changed so that they point to files managed by Let's Encrypt.
  • The default SSL DH parameters file provided by the Debian package is OK for now, it has bit size 4096. The custom-generated SSL DH parameters file that I use for other services (/etc/ssl/private/dhparams-2048-bit.pem) only has bit size 2048. Why is this important? With the advent of the Logjam attack, it has become important to have a DH group file with increased bit size - see Guide to Deploying Diffie-Hellman for TLS. Some modern clients such as the iOS mail client app in iOS 9 will refuse to connect to the IMAP server if the SSL DH parameters use a bit size that is too low. See the OpenSSL wiki page for instructions how to read and create an SSL DH parameters file.
  • The directory with trusted CA certificates is not actually needed, because on my server Dovecot does not act as an SSL client. Nevertheless, the value that is set by default is the correct one.


So here's what I have in my server-specific config file 99-pelargir.conf:

# Force clients to use SSL/TLS, i.e. STARTTLS on the default port 143. 
# Attempts to login without SSL/TLS will fail immediately.
ssl = required

# Disable all plaintext authentication mechanisms unless SSL/TLS is used
# (not strictly necessary since ssl = required is already set).
# Note: Test this from external hosts only. For localhost connections 
# plaintext authentication is always allowed because these connections 
# are assumed to be secure.
disable_plaintext_auth = yes

# SSL certificate/key files are in restricted location, but
# Dovecot server starts up as root and can read the files
# without special permissions.
ssl_cert = </etc/letsencrypt/live/herzbube.ch/fullchain.pem
ssl_key = </etc/letsencrypt/live/herzbube.ch/privkey.pem

# Recommended by the Dovecot Wiki.
ssl_prefer_server_ciphers = yes

Notes:

  • The Dovecot server reads the certificate and key files while still running as root, so no special permissions are needed. For other services (such as Exim) that start up with a special user, that special user needs to be placed into the ssl-certs group because only that group has access to the Let's Encrypt folders where the certificate and key files are stored. See the Let's Encrypt and Exim wiki pages for details.
  • The option ssl_min_protocol could be used to set a minimum TLS version. The default is TLS v1, which I trust ist good enough.
  • The option ssl_cipher_list could be used to restrict which ciphers are allowed. I'm trusting Dovecot to use a sensible setting.


Migration from Courier

Debian package installation

The first thing that you'll notice is that when you want to install the Dovecot Debian packages you are forced to uninstall the Courier packages - they are mutually exclusive.


Dovecot configuration

The next step is to configure Dovecot so that it uses the same "INBOX" namespace as Courier IMAP. The following snippet goes into the server-specific configuration file 99-pelargir.conf:

# Courier IMAP compatibility. It's important that the namespace has a name!
# Example is from here:
# https://doc.dovecot.org/configuration_manual/namespace/#backwards-compatibility-courier-imap
namespace inbox {
  prefix = INBOX.
  separator = .
  inbox = yes
}


Maildir migration

Last but not least, the Maildir data in each user's home directory needs to be migrated. Dovecot offers a Perl script for that purpose: courier-dovecot-migrate.pl. The script can be downloaded from here: https://wiki.dovecot.org/Migration/Courier.


Place the script anywhere you like, give it executable permission, then launch it in one of two ways:

  • Test mode: ./courier-dovecot-migrate.pl --to-dovecot /home/foo/Maildir
  • If no errors are shown in test mode, do the actual conversion: ./courier-dovecot-migrate.pl --to-dovecot --convert /home/foo/Maildir


Notes:

  • The script does not delete any of the Courier IMAP files (e.g. courierimapacl, courierimapuiddb, courierimapkeywords).
  • The Dovecot Wiki page that has the download link also shows an example how to do the Dovecot namespace configuration. This example is bad because it omits the namespace name. Using the example as-is will generate hundreds (if not thousands) of error log messages when the first client connects, also the connection attempt will appear to be very slow.


Administration

Dovecot has two dedicated command line tools for administration purposes:

  • doveadm: Interacts with the Dovecot service. Allows to start/stop/restart the service (warning: systemd may need additional config before you can use this, read this), and also other stuff - read the man page or invoke doveadm help for details.
  • doveconf: Interacts with the Dovecot configuration stored on disk. Read the man page for details.


Troubleshooting

Service fails to start

If the Dovecot service fails to start, then you should find an error message with a clue in /var/log/syslog. Example:

Dec 28 17:29:13 pelargir dovecot[56437]: doveconf: Fatal: Error in configuration file /etc/dovecot/conf.d/99-pelargir.conf line 11: ssl_key: Can't open file /etc/letsencrypt/live/herzbube.ch/privkey.pemx: No such file or directory


Testing the TLS connection

This command performs a basic test to see whether or not Dovecot is set up correctly for TLS:

openssl s_client -connect mail.herzbube.ch:143 -starttls imap