I first learned to set up and administer mail services using Ivar Abrahamsen's excellent guide How to set up a mail server on a GNU / Linux system at Flurdy.com.
The Flurdy email server is generally a fine robust configuration, with lots of expandability. But over time I grew dissatisfied with Courier IMAP's performance, and eventually I switched to Dovecot, which performs much better. Apparently Dovecot is now widely preferred over Courier, for exactly this reason.
What follows is a detailed guide for how to do the migration, in a format Flurdy users may find familiar. :)
Also, a word of advice: if you're using this guide to upgrade from a previous version of Dovecot, I suggest you back up your Dovecot configuration, then uninstall Dovecot, delete the /etc/dovecot directory, and reinstall Dovecot. Many of the Dovecot configuration options have changed with version 2.4.x, and this will ensure you're not trying to start with deprecated config options.
Like the Flurdy guide it supplements, this guide assumes your server's focus is on IMAP and not the outmoded POP3. There are some POP3-related instructions here, but they're not guaranteed to be complete. The assumption is that you want to set up a secure IMAP service using SSL/TLS authentication on a working server configured according to the latest version of the Flurdy guide, currently in its 15th edition.
Please note that as soon as you start this process, Courier may be removed from your system and IMAP will be unavailable to your users until you complete the configuration, so it might be best to do your configuration work on a non-production box until you're ready to migrate.
Also, this guide was developed on Debian, not Ubuntu as in the Flurdy instructions. This shouldn't make a whole lot of difference, but it's possible some configuration files may be in different places than shown here, so don't freak out. It works on Debian Trixie.
First, install Dovecot:
sudo apt-get install dovecot-core dovecot-imapd dovecot-lmtpd dovecot-mysql
This step may uninstall Courier, but leave Courier's config files in place in case you find you have to revert. Watch the screen for a notification that Courier is being removed. If you don't see it, we'll uninstall it at the end.
If you allow POP3 clients on your server, you will want to install dovecot-pop3d at this step as well:
sudo apt-get install dovecot-pop3d
Open the main Dovecot config file for editing:
sudo vi /etc/dovecot/dovecot.conf
Enable the protocols you want to use:
# Protocols we want to be serving.
protocols = imap lmtp
!include_try /usr/share/dovecot/protocols.d/*.protocol
Again, note pop3 is not in the list, but if you wanted to do it, this is where you would put it. Save the file.
Next we'll set up secure authentications. We're going to limit authentications to SSL/TLS connections only. With that restriction, PLAIN and LOGIN authentications are fine.
sudo vi /etc/dovecot/conf.d/10-auth.conf
#Set clear text authentications to no:
auth_allow_cleartext = no
#Set the auth mechanisms to allow only PLAIN and LOGIN:
auth_mechanisms = plain login
#Enable sql auths by uncommenting this line:
!include auth-sql.conf.ext
#If this line is enabled, comment it out:
#!include auth-system.conf.ext
I find Dovecot's log lines to be needlessly long-winded, so I made some optional changes:
sudo vi /etc/dovecot/conf.d/10-logging.conf
login_log_format_elements = user=<%{user}> method=%{mechanism} rip=%{remote_ip} lip=%{local_ip} mpid=%{mail_pid} %{secured}
mail_log_prefix = "%{service}(%{user})<%{process:pid}>: "
Set up the mail locations to match the Flurdy virtual mailboxes, and configure namespaces and user ids and groups:
sudo vi /etc/dovecot/conf.d/10-mail.conf
mail_driver = maildir
mail_home = /var/mail/virtual/%{user}
mail_path = /var/mail/virtual/%{user}
mail_inbox_path = /var/mail/virtual/%{user}
#In the first namespace section, make sure the following lines are uncommented:
namespace inbox {
separator = .
prefix = INBOX.
inbox = yes
}
#Set the mail user id and group id, and the virtual mailbox group setting, again corresponding to the Flurdy values:
mail_uid = 5000
mail_gid = 5000
mail_privileged_group = virtual
Everything else in the file can be left as it is. I've left out a lot of explanatory namespace-related comments that appear in this configuration file, but I recommend reading them to get a clearer idea of what we're doing here.
Make sure the imap listeners are on the default ports. If you want to use some other port, that is a little beyond the scope of this howto, but you'd do it here by uncommenting the port = lines and changing to the desired port number.
sudo vi /etc/dovecot/conf.d/10-master.conf
service imap-login {
inet_listener imap {
#port = 143
}
inet_listener imaps {
#port = 993
#ssl = yes
}
...
}
#Disable POP3 if you don't use it, by setting the port numbers to 0:
service pop3-login {
inet_listener pop3 {
port = 0
}
inet_listener pop3s {
port = 0
#ssl = yes
}
}
Everything else in the file can be left as is.
Turn on SSL:
sudo vi /etc/dovecot/conf.d/10-ssl.conf
ssl = yes
If you had actual certificates set up for Courier, you can use those. These are my paths and filenames, but yours will probably be different:
ssl_server_cert_file = /etc/letsencrypt/live/mymailserver.com/fullchain.pem
ssl_server_key_file = /etc/letsencrypt/live/mymailserver.com/privkey.pem
If you want to use a self-signed cert instead, follow the instructions here. Everything else in this file can be left alone.
Some clients open up more user connections at once than you might think, so I like to make sure Dovecot allows sufficient user connections:
sudo vi /etc/dovecot/conf.d/20-imap.conf
protocol imap {
mail_max_userip_connections = 25
}
If your email client gets random failures to connect during a session, especially a webmail client like Roundcube, try increasing this value.
Set the database driver to mysql:
sudo vi /etc/dovecot/conf.d/auth-sql.conf.ext
# Database driver: mysql, pgsql, sqlite
sql_driver = mysql
Set up the mysql connection:
mysql 127.0.0.1 {
user = mail
password = mailPASSWORD
dbname = maildb
}
Set up the password query and the userdb query:
passdb sql {
default_password_scheme = SHA512
query = SELECT id AS user, crypt AS password FROM users WHERE id='%{user}'
}
userdb sql {
query = SELECT CONCAT(home,'/',maildir) AS home, uid AS uid, gid AS gid, CONCAT(home,'/',maildir) AS mail FROM users WHERE id='%{user}'
}
Please make sure that this file is not set readable by the general public, because it contains your database login credentials in clear text.
Optional step: At this point, you may want to switch to using Dovecot's SASL auth service for smtp, instead of the Cyrus and saslauthd setup in the Flurdy default configuration. It's a lot less twiddly.
sudo vi /etc/dovecot/conf.d/10-master.conf
service auth {
unix_listener /var/spool/postfix/private/auth {
mode = 0666
user = postfix
group = postfix
}
}
sudo vi /etc/postfix/main.cf
#SASL
#Add these two lines:
smtpd_sasl_auth_enable = yes
smtpd_sasl_type = dovecot
#Set the relay restrictions if they're not already set:
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination
#And comment out this line:
#cyrus_sasl_config_path = /etc/postfix/sasl
If this is an existing server, you will probably have user passwords stored in mysql in the CRYPT format. These need to be updated to SHA512. If your database tables follow the Flurdy setup, you will also have the passwords in clear text in the users table, making this easy. Log in to the maildb database in mysql and run the following command:
update users set crypt = SHA2(clear,512);
If this is an existing server and you are converting to Dovecot, your users will already have mail indexed by Courier in the virtual mail directories. Dovecot uses its own indexing. To prevent clients from downloading all their IMAP mail again, Dovecot provides a handy Courier mailbox migration utility.
To run the utility, do the following:
cd /var/mail/virtual
courier-dovecot-migrate.pl --to-dovecot --recursive .
Inspect the output. This will spit out a list of everything the conversion script will do, but it won't actually do it until you include the --convert parameter:
courier-dovecot-migrate.pl --to-dovecot --recursive --convert .
Finally, start the Dovecot service and restart Postfix:
sudo systemctl restart postfix.service
sudo systemctl restart dovecot.service
If the Dovecot service doesn't start, follow the instructions in the error message to view the system messages. The most likely problem is misconfigured SSL certificate setup.
Testing your Dovecot setup is pretty much the same as testing Courier was in the Flurdy guide's Courier testing section. Do the check shown there, then fire up an actual email client and connect to a known good account. It helps to tail /var/log/mail.log and /var/log/auth.log to troubleshoot any authentication problems.
For general testing procedures, see the testing section of the Flurdy guide.
Once you are confident that your new Dovecot installation is working correctly, you will want to explicitly remove Courier if it didn't happen automatically at the beginning. On Debian at least, leaving Courier in place may cause distribution version upgrade issues; the situation may be the same for Ubuntu.
sudo apt-get remove courier*
This will remove Courier but leave its config files in place in case you need to revert.
Jon Jerome, longtime contracting consultant. I spend my day at work staring at glowing rectangles and then come home and do it some more, for fun. Go figure.
If you find an error in this guide, or have suggestions for making it better, you can contact me here.
If you're having trouble and want help, in all honesty you'll probably get a faster answer in the Debian Forums, the Ubuntu Forums, or simply by googling, but you can still contact me if you want to. I promise to read it, but I can't guarantee I'll be able to help.
If you found this guide helpful, you may also like my guide to setting up SASL for ISP SMTP relays.