http:// qmail.jms1.net / dovecot.shtml

Dovecot IMAP/POP3 Server Information

Dovecot is an open-source IMAP and POP3 server. It was written with security as one of its primary goals, and is flexible enough to work with just about any kind of back-end mailbox storage system, including vpopmail's folder structure. It also works with a large number of authentication back-ends, again including vpopmail.

I had previously been using Courier-IMAP for several years, but in May 2008 the developer of courier-imap decided to drop support for vpopmail- which meant it was no longer suitable for my needs, or probably for the needs of a lot of people out there. I did a quick search for other IMAP servers which worked with qmail and vpopmail, and found two- BINC-IMAP and Dovecot. Between the two, Dovecot seemed to be a more mature product, and their web site seems to have better documentation, so I tried it first.

I spent a little time reading through the web site and the documentation which came with the source code, and tried a bit of testing- it turns out the physical directory structure of the mailboxes is identical, in fact the only difference is one of the control files stored within the mailboxes. And the Dovecot web page had a perl script already written to convert this file from courier's format to Dovecot's format.

I did some testing on my own server and found it to be rather painless, so I went ahead and shut down the courier-* services, converted the mailbox control files, and started up the Dovecot service... and found that neither Apple's "Mail.app", nor Thunderbird, was aware that anything had changed at all. It just doesn't get any easier than that.

So I'm writing this page to show how I configured, compiled, and set up Dovecot on my own server.


Compiling and installing the software

The first step, obviously, is to download the Dovecot software from http://www.dovecot.org/download.html. I'm currently using the "stable" version, 1.0.13, on my server.

After downloading the software, expand the tarball and run the appropriate "./configure" command for your system. I normally create a small shell script containing this command, so that I know what options I used to build it, and if I need to upgrade, I can build the new version using the same options. I have a copy of the script I used on the web site, to save you a little bit of typing.

After configuring the software, the last part is to run the normal "make" and "make install" commands. The overall process will look like this:

$ wget http://www.dovecot.org/releases/1.0/dovecot-1.0.13.tar.gz
...
$ wget http://qmail.jms1.net/scripts/configure.dovecot
...
$ chmod 755 configure.dovecot
$ tar xzf dovecot-1.0.13.tar.gz
$ cd dovecot-1.0.13
$ ../configure.dovecot
...
At the end of the process it will print a list of the settings it will build into the software. Make sure these two lines are there:

Building with user database modules . : vpopmail (modules)
Building with password lookup modules : vpopmail (modules)

$ make
...
$ sudo make install
...

I found on my own server that a few directories either weren't created, or were created with bad permissions. The following commands fixed the problems on my server:

# mkdir -m 0755 /usr/local/var \
        /usr/local/var/run \
        /usr/local/var/run/dovecot

# chmod go=u-w /usr/local/share \
        /usr/local/share/doc

# chmod -R go=u-w /usr/local/lib/dovecot \
        /usr/local/libexec/dovecot \
        /usr/local/share/doc/dovecot

The last step is to create a new non-root userid which is used to process authentication requests.

This command is specific to Linux, and will probably need to be adjusted for other systems. The idea is to create a userid which cannot log in, which has no valid shell, and has no home directory- one which, if somebody were to "hack" into it, wouldn't be able to do much.
# useradd -M -d /nohome -s /bin/false -c 'Dovecot user' dovecot


Configuring Dovecot

Dovecot itself is configured using a single control file, which will be "/usr/local/etc/dovecot.conf" (unless you configured the software with a different "--prefix" option.) When you install the software, it creates a dovecot-example.conf file in this directory, and the directions with the software tell you to rename or copy the file to dovecot.conf and then customize it.

I did this on my own server, and after deleting a lot of extra comments I ended up with this dovecot.conf file. Note that I also replaced my server's IP address with an invalid IP, so you will need to customize the file before using it- either that, or use the dovecot-example.conf file and build your own configuration.

2008-05-15 I guess I was so excited about everything else working correctly that I didn't notice the fact that there were "double timestamps" on all of the log lines... I just added "log_timestamp = """ to my own dovecot.conf, and to the copy on the web site, and restarted the service, and they went away. Thanks to Nigel Mundy for pointing this out.

vpopmail user

The first thing you'll need to do is adjust the "first_valid_uid" and "last_valid_uid" values in the file. Find the numeric uid of the vpopmail user...

$ id -u vpopmail
89

If the IMAP servers will ONLY be used for vpopmail accounts, make sure both of these values are set to that number (in this case, 89.) Also make sure both lines are un-commented (i.e. remove the "#" in front of the "last_valid_uid" line.)

##
## Mail processes
##

verbose_proctitle = yes
first_valid_uid = 89
last_valid_uid = 89

Namespace and separator character

Different IMAP servers can use different "namespaces" for different collections of folders on the server. The "INBOX" namespace is usually used for your personal inbox, while others might be used for shared mailboxes or other specific services.

Another factor is the "separator" character. This is the character which separates one "layer" of folders from the next. In your IMAP client (the email program on your desktop) you might have an "INBOX" folder, which contains a folder called "storage", which contains a folder called "Personal". If the separator character is ".", then the actual name of that folder would be "INBOX.storage.Personal".

When I set this server up, I was converting from an existing courier-imap system and wanted to minimize the amount of visible change to the users. This meant that I needed to configure Dovecot to use the same namespace and separator character that courier-imap uses.

## ## Mailbox locations and namespaces ## mail_location = maildir:~/Maildir namespace private { separator = . prefix = INBOX. inbox = yes }

Service structure

One decision you will need to make is how you plan to start dovecot on your server. I use daemontools, however it can also be done using an "init" script, or from inetd or xinetd, or by adding a line to an "rc.local" file somewhere (if you don't mind it not starting back up by itself if it happens to die, of course.) This being a qmail-related site, the examples below will show how to set things up using daemontools. I know that it's possible to set it up in other ways, but I don't know the details- I use daemontools and have no real need to know how to do it using other methods.

Dovecot itself consists of several processes. There is a master "dovecot" process which handles incoming requests, one or more "dovecot-auth" processes which handle finding and validating users and passwords, one or more "imap-login" and/or "pop3-login" processes which handle the userid and password negotiations with the client, and one or more "imap" and/or "pop3" processes which handle the rest of the process (i.e. speaking IMAP or POP3 with the client, accessing the files in the mailboxes, and so forth.)

There are two ways to start Dovecot. The more common way, how I'm doing it now, and which I will explain below, is to run the "dovecot" process, which starts up all of the others. This is easier, however it limits you to not being able to support IMAP or POP3 on more than one IP address (i.e. you can run no more than one of each of the four service types- IMAP, SSL-IMAP, POP3, and SSL-POP3.)

The other way is to set up individual services which run inetd, xinetd, tcpserver, or sslserver to answer incoming connections, and configure them to run "imap-login" or "pop3-login" directly. If there is no master dovecot process running, they will automatically start one. They then connect to the dovecot-auth process (which they may have just started), and send the ID and password to be validated. This method allows you to run more than one of any single service (i.e. run non-encrypted IMAP services on 127.0.0.1 and a private IP, but not on a public IP) and it allows you to control access to the service(s) using tcpserver or sslserver access control files.

If you're going to run one single service which handles all of the IMAP and POP3 services, set the IP addresses and ports within the dovecot.conf file, using the listen and ssl_listen lines. There are existing lines in the file as examples- you should configure your IP address as needed, and make sure only the services you plan to offer are un-commented.

The first part is to configure which protocols should be handled by the main "dovecot" process:

protocols imap imaps pop3s

Whichever services you are using, you need to configure the IP and port on which each one will listen.

protocol imap { listen = 127.0.0.1:143 ssl_listen = 123.45.67.89:993 ... } protocol pop3 { # listen = 987.65.43.21:110 ssl_listen = 123.45.67.89:995 ... }

If you plan to use separate daemontools services for each IMAP or POP3 service, you will still need to configure the master "dovecot" process, since it starts the "dovecot-auth" process which handles validating the clients' userids and passwords. To do this, you only need to configure one line in the dovecot.conf file:

protocols none

Once this is done, if dovecot starts it will also start the dovecot-auth process, but nothing else. It will be up to tcpserver or sslserver to start the actual imap-login or pop3-login process for each connection. The first instance of imap-login or pop3-login to start will make the master dovecot and dovecot-auth processes start, and they will stay running in order to service requests from other clients.


Building the daemontools service(s)

This shows how to set up a daemontools service which starts the main dovecot process, which will listen for incoming IMAP and/or POP3 connections as specified in the dovecot.conf file.

On my server, all of my daemontools physical service directories are in the "/var/service" directory. Your own server may be different- the physical directory can be anywhere on the system, except within the "/service" directory itself.
# cd /var/service
# mkdir -m 0755 dovecot dovecot/log
# cd dovecot/log
# wget -O run http://qmail.jms1.net/scripts/service-any-log-run
...
# chmod 0755 run
# cd ..
# wget -O run http://qmail.jms1.net/scripts/service-dovecot-run
...
# chmod 0755 run

To set up a daemontools service to handle just one specific type of service, the process is similar but it needs to be configured a bit more carefully. This example will be an SSL-IMAP service on port 993.

# cd /var/service
# mkdir -m 0755 dovecot-imaps dovecot-imaps/log
# cd dovecot-imaps/log
# wget -O run http://qmail.jms1.net/scripts/service-any-log-run
...
# chmod 0755 run
# cd ..
# wget -O run http://qmail.jms1.net/scripts/service-dovecot-xxx-run
...
# chmod 0755 run
# nano run Use your text editor of choice.

Like the other "service-blah-run" scripts, this one consists of configuration variables at the top, followed by code to build the final command line, and then run it. The variables are:


Convert the mailbox control files

We are about to start the Dovecot services. Of course, this means any existing IMAP and/or POP3 services should be shut down first. Use whatever procedure you would normally use for this- and if they are daemontools services, create "down" files in each of the service directories so that they don't accidentally try to restart on their own in the future.

Before starting the Dovecot service(s), if you are currently running courier-imap, you need to "convert" the mailboxes from courier-imap to Dovecot. Actually, the only thing being converted is a few of the control files within the Maildir directories, and it's not strictly necessary to do this conversion- the files which need to be "converted" will automatically be created the first time the client connects. Doing the "conversion" will just save the clients a little bit of time when they connect to Dovecot for the first time.

This page on the Dovecot Wiki gives more details about what files are being created and how to do the conversion. Below is a quick example.

# cd /usr/local/sbin
# wget http://www.dovecot.org/tools/courier-dovecot-migrate.pl
...
# chmod 0700 courier-dovecot-migrate.pl
# cd ~vpopmail/domains

This command will do a "dry run" to make sure things will work correctly...
# /usr/local/sbin/courier-dovecot-migrate.pl --recursive

This command actually does the conversion.
# /usr/local/sbin/courier-dovecot-migrate.pl --recursive --convert


Start up Dovecot

This is just like starting up any other daemontools service - create a symlink from /service/something to the physical service directory, wait about ten seconds, and make sure it's running.

# ln -s /var/service/dovecot /service/
#
Wait about ten seconds...
# svstat /service/dovecot /service/dovecot/log
/service/dovecot: up (pid 23841) 8 seconds
/service/dovecot/log: up (pid 23843) 8 seconds


2008-05-13 Thanks to David Wadson for reminding me to include a few details that I had originally skipped over when writing the page.


2008-07-22 Bob Wooldridge, KC0DXF, is running Dovecot on his server, but in a way which is slightly different from how I'm doing it. He has a web page similar to this one, you may want to look through his page and see how he's doing things.

As of the time I'm writing this he's still working on the page. I've sent him a few hints on how to improve it, however it looks pretty good so far.