Dovecot Configuration

This guide is a work in progress. For the time being, please see the Dovecot Documentation.

Upgrade from Dovecot 2.2.x to 2.3.x

If you have previously installed version 2.2.x of Dovecot, upgrading to the 2.3.6 packages here may result in a broken configuration that needs some adjustment.

If you are doing a fresh install without a previous version of Dovecot installed, you can skip this section.

First, look at the official migration guide at That guide has the important information regarding changes.

Please note that for the LibreLAMP packaging of Dovecot, we default the ssl_dh parameters to /etc/pki/tls/dh2048.pem which is a set of DH parameters regenerated daily by the cron daemon.

If you follow the migration instructions here, you will not need to worry about migrating your existing ssl-parameters.dat file.

RPM and Configuration Files

Dovecot configuration files are marked in the RPM file as %config(noreplace). What that means is when upgrading from Version A to Version B, if the default configuration file in the packages has not changed, RPM will leave your custom configuration alone. However when the default configuration file has changed, RPM will install the new default but append .rpmnew to the end of the file name, still leaving your existing configuration alone.

In these cases, what you as a system administrator should follow these steps:

  1. Make a backup of your existing configuration file
  2. Copy the .rpmnew version, creating a .UPGRADE version
  3. Read the old configuration file, and migrate changes to the .UPGRADE version
  4. Fully read the .UPGRADE version in case there are other things you wish to change
  5. Copy the .UPGRADE version over the actual configuration file
  6. Start the service and read the /var/log/maillog file looking for any warnings

With the upgrade from the 2.2.x branch of Dovecot to the 2.3.x branch, some default configuration files did change. If you made custom configurations to those files, you will need to go through that process.

On the mail server, I had to migrate both 10-mail.conf and 10-ssl.conf

You may have additional files that need changing, depending on what default configuration files have changed have changed and what customization you previously made.


The only change I had made to this file was to the mail_location directive which I had set to mailder:~/Maildir

The difference between the 10-mail.conf.rpmnew and 10-mail.conf.UPGRADE file after migrating that setting:

--- 10-mail.conf.rpmnew	2018-02-06 00:13:46.000000000 +0000
+++ 10-mail.conf.UPGRADE	2018-02-06 00:20:18.186207545 +0000
@@ -28,6 +28,7 @@
 # <doc/wiki/MailLocation.txt>
 #mail_location = 
+mail_location = maildir:~/Maildir
 # If you need to set multiple mailbox locations or want to change default
 # namespace settings, you can do it by defining namespace sections.

As you can see, I only had to add a single line. You probably will at least need to do that much.


For the SSL configuration file, the only customization I had made was to the location of the private and public keys. I personally like to keep them in the /etc/pki/tls directory tree, and like to have a date stamp in the file name so I can be sure to generate a fresh key pair once a year.

The difference between 10-ssl.conf.rpmnew and 10-ssl.conf.UPGRADE:

--- 10-ssl.conf.rpmnew	2018-02-06 00:13:46.000000000 +0000
+++ 10-ssl.conf.UPGRADE	2018-02-06 00:24:18.773581562 +0000
@@ -10,8 +10,8 @@
 # dropping root privileges, so keep the key file unreadable by anyone but
 # root. Included doc/ can be used to easily generate self-signed
 # certificate, just make sure to update the domains in dovecot-openssl.cnf
-ssl_cert = </etc/pki/dovecot/certs/dovecot.pem
-ssl_key = </etc/pki/dovecot/private/dovecot.pem
+ssl_cert = </etc/pki/tls/certs/
+ssl_key = </etc/pki/tls/private/
 # If key file is password protected, give the password here. Alternatively
 # give it when starting dovecot with -p parameter. Since this file is often

In that case, all I has to do what change two lines and I was good to go.

Future Major Updates

Server software is different than software like PHP or FFmpeg where there are very real benefits to major upgrades. Upgrading the major version on a live server is a real pain in the ass because configuration files need to be changed which can result in downtime that affects a lot of people.

In this case it was necessary because there are loud hints that Dovecot 2.2.x is going end of life soon and will not receive updates from the code maintainer for much longer. Backporting security fixes is not something I want to do, especially since I am not being paid, so that is why I chose to migrate LibreLAMP to the 2.3.x version of Dovecot.

It will likely be a very long time before another major update to Dovecot is necessary.