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. :)
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 versions through Bookworm.
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:
# Enable installed protocols
!include_try /usr/share/dovecot/protocols.d/*.protocol
protocols = imap lmtp
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
#If the following line is commented out, uncomment it:
disable_plaintext_auth = yes
#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=<%u> method=%m rip=%r lip=%l mpid=%e %c
mail_log_prefix = "%s(%u)<%{pid}>: "
Set up the mail location to match the Flurdy virtual mailboxes, and configure namespaces and user ids and groups:
sudo vi /etc/dovecot/conf.d/10-mail.conf
mail_location = maildir:/var/mail/virtual/%u
#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_cert = </etc/ssl/ssl.crt/mymailserver_certificate.crt
ssl_key = </etc/ssl/ssl.key/mymailserver.key
ssl_ca = </etc/ssl/ssl.crt/mymailserver_intermediate.crt
(The "<" symbol without a matching ">" is not a typo; that's how it actually has to be.)
If you have pem certificates instead of crt and key, such as you might get from Letsencrypt, you don't need the ssl_ca entry:
ssl_cert = </etc/letsencrypt/live/mymailserver.com/fullchain.pem
ssl_key = </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.
Check to make sure the passdb section points to the right file:
sudo vi /etc/dovecot/conf.d/auth-sql.conf.ext
passdb {
driver = sql
args = /etc/dovecot/dovecot-sql.conf.ext
}
By default, Dovecot fetches password authorization separately from user information, in separate queries. But here we'll be using prefetch to get both in a single query, so uncomment the userdb section that says prefetch and comment out the one that says sql:
userdb {
driver = prefetch
}
#userdb {
# driver = sql
# args = /etc/dovecot/dovecot-sql.conf.ext
#}
The dovecot-sql.conf.ext file is where we're going next.
sudo vi /etc/dovecot/dovecot-sql.conf.ext
#For database driver, we want mysql:
driver = mysql
#The connect string will point to the maildb database on the local machine,
#with the user and password you defined when you set it up according to Flurdy.
connect = host=127.0.0.1 dbname=maildb user=mail password=mailPASSWORD
#We'll be using the encrypted password from the mysql database:
default_pass_scheme = CRYPT
#Set the password query to point to the users table:
password_query = SELECT id AS user, crypt AS password, CONCAT(home,'/',maildir) AS userdb_home, \
uid AS userdb_uid, gid AS userdb_gid, CONCAT(home,'/',maildir) AS userdb_mail FROM users WHERE id='%u'
Everything else in this file can stay the same. Because we set the userdb section to prefetch in the previous step, we don't need a separate user query. Please make sure that this file is not set readable by the general public, because it contains your database login credentials in clear text.
If this is an existing server, 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:
sudo service dovecot start
If the 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.