Your personal GMail-like mail system: dovecot, the IMAP server

Now you have the e-mail storage with current up-to-date messages, and it is time to set up the access to it.

As stated in the design goals, the e-mail storage should be available via IMAP protocol. This allows proper concurrent access to the same e-mail storage while using multiple computers, laptops and the mobile devices. And since the IMAP server is local, the connection is very fast (it doesn’t feel like remote storage at all) and bandwidth is not an issue.

Installing dovecot

I reviewed and tried to install several different IMAP servers and decided to use dovecot. It supports Maildir storage natively, has an extensive set of features, is secure enough to be used by major ISPs and is easy to configure. Also it seems to be included in every major Linux distribution, saving you time and efforts. I installed dovecot20 rpm packaged with OpenSUSE 12.1, which provided the with the version 2.0.14. Although it also instals in tow three SQL backends, this  isn’t an issue as you don’t have to use them.

Before processing with dovecot configuration you need to generate the SSL certificate. Do it now.

Configuring dovecot

Find your dovecot configuration directory. Most likely it gonna be /etc/dovecot, but may be different in your case. It has the dovecot.conf file as well as conf.d directory with a bunch of other files which can on the first glance scare even an experienced system administrator. However it is fairly simple to configure, and I will explain the options you need to change.

Each section below explains which parameters were changed from their defaults, and why.


Here we set up the supported protocols and IP addresses (but not port numbers) to listen on.

# Uncomment protocols as we only server IMAP, no POP3/LMTP
protocols = imap

# If you have a multi-homed host and want to listen only on specific IP addresses, 
# uncomment and fill up listen as well
listen =,


Here we set up the authentication mechanisms we will use for the user authentication. We also enable some options to make the installation more secure.

# Uncomment it as we want to disable plaintext auth on non-encrypted connections
disable_plaintext_auth = yes

# Lowercase the username before doing the database lookup. Very helpful with
# mobile devices which tend to capitalize the username when it is entered
auth_username_format = %Lu

# We will use file-based authentication with virtual users, so uncomment this line
!include auth-passwdfile.conf.ext


Here we temporarily enable more detailed logging to help us debugging the various configuration problems. Keep the copy of this file so you can revert it back once the server is working and the issues are ironed out.

auth_verbose = yes
mail_debug = yes


Here you can change the port number IMAP is listenin on (inet_listener imaps entry) if you do not like the default 993 port.


Our SSL configuration for IMAP. Here we go!

# We require SSL
ssl = required

# SSL certificate and the private key we generated before
ssl_cert = </etc/dovecot/ssl/certificate.pem
ssl_key = </etc/dovecot/ssl/certificate.key


Here you can enable workarounds for some buggy clients. Howeveer as you use Maildir there are no necessary changes.


Here we tell Dovecot that we store our virtual users in the file /etc/dovecot/users and we will use MD5 passwords

passdb {
 driver = passwd-file
 args = scheme=MD5 username_format=%u /etc/dovecot/users

userdb {
 driver = passwd-file
 args = username_format=%u /etc/dovecot/users

Setting up virtual users

Virtual user file format maps the virtual users authenticated by dovecot into system user IDs. Since we use the same system user and home directory for all our virtual users, we will return the same user ID but different mail directories. So let’s configure two users, pers with the password personal and busi with the password business, to access the personal and business mail storage respectively.

First we need to find the user and group ID of our mailman user:

# grep mailman /etc/passwd

so the user ID is 1001 and group ID is 100. Then we need to encode the passwords. Since we specified the MD5 as password scheme, we need to store the MD5 hashes of our passwords. So let’s find out them:

# echo -n "personal" | md5sum -
0be5a6c82893ecaa8bb29bd36831e457 -
# echo -n "business" | md5sum -
f5d7e2532cc9ad16bc2a41222d76f269 -

Now we have all necessary information to create our /etc/dovecot/users file. Its format is similar to /etc/passwd, as it has the following fields separated by a colon:

  • Virtual username
  • MD5 password
  • User ID of the system user which is used to access the mailbox, in our case it is 1001
  • Group ID of the system user which is used to access the mailbox, in our case it is 100
  • An empty field
  • Home directory of the mail storage. When combined with the value of userdb_mail parameter should produce a complete path to the mail storage root.
  • An empty field
  • Other options. In our case we need to use the userdb_mail option to specify the directory where the mail is stored inside the home directory described above. We also specify the mail storage format maildir.

So we end up with the following file:


Now we can start dovecot, which is done via the way supported by your Linux distro. For RedHat, CentOS and OpenSUSE it is done by running the startup script:

/etc/init.d/dovecot start

and try to connect to your IMAP server using the credentials.


If the installation doesn’t work, the first thing to check is the system log file. Dovecot writes into the /var/log/mail file, which contains the valuable information about problems encountered by your IMAP server. Most common errors would likely be authentication failed (verify the MD5 password checksum and that you copied the whole string into the users file) and lack of permissions to access the mailbox (make sure the user ID specified in the users file belongs to the user which has permissions to access the mailbox)

Manual test

If the problem still persists, it may help to attempt to connect to the IMAP server manually. This may help to diagnose the problem better.

First use openssl to connect to the IMAP server:

# openssl s_client -connect my.ip.address:993
.. a lot of text output from openssl ...
* OK [CAPABILITY ...] Dovecot ready.

If the connection failed, either the IMAP server did not start up properly (check the log files), it doesn’t listen on the proper IP address (check the configuration), or the connection is firewalled and you need to open the port in the firewall.

Then we can try to log in using our credentials (note the first dot, it is required):

. LOGIN pers personal

. OK [CAPABILITY IMAP4rev1 ...other capabilties]

If login didn’t success, you have authentication problem – check the log files.

Now you can try to list the folders:

. LIST "" "*"

* LIST (\HasNoChildren) "." "Sent"
* LIST (\HasNoChildren) "." "Drafts"
* LIST (\HasNoChildren) "." "INBOX"
. OK List completed.

Your list may be different, but if the boxes are listed, your IMAP server is likely to work properly, and the problem is in your e-mail client configuration.


This entry was posted in Email.

One Response to Your personal GMail-like mail system: dovecot, the IMAP server

  1. Johan Ekenberg says:

    After migrating my config to a newer version of dovecot, I couldn’t log in getting “password mismatch” errors. Turned out I needed to regenerate the password hashes with the command ‘doveadm pw’. The new format looks like “{CRAM-MD5}eeb45323b….”. After replacing the new hashes into /etc/dovecot/users, login worked again.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.