The FreeBSD Diary

If you're reading this, you use email. You probably have more than one email address. I do. I have many. I run 13 domains, plus some more for friends off my two mail servers. If you're like me, you use POP to download your mail to your computer and read it there. POP works best when you use just one computer.

In this article, I will show you how I installed Dovecot and configured it so I could securely get my email. This involves setting up the certificates and configuring Dovecot.

IMAP can be part of a client/server email solution. In short, with IMAP your email remains on the server and you just read a copy of it with your email client. I can think of several immediate advantages with this approach (in no particular order):

1. Easy backups - if all your users' email is on one server, backups are easier
2. Change your email client - if you decide you want Pegasus, not Thunderbird, you can change that at a whim, knowing that all your email will still be available from the new client
3. Multiple access methods - you can access your email from any IMAP client, or even via a web interface
4. Read the same email on different systems - with me, I can be on my laptop, my desktop, the office, wherever, and I may need to have the same email at different times on different mails. IMAP solves that issue.

Those are the first reasons that come to mind. I'm sure you have your favorite reasons.

Before you proceed, I have some required reading for you. It is essential that you understand how email works, how it is delivered, and what IMAP can and can't do for you. Rather than create this myself, I suggest reading MailServerOverview on the Dovecot wiki.

My path to IMAP was unexpected. I had played with IMAP many months ago, but never made a decision to deploy it or not. I recently relocated to start a new job. I ran a private mail server at home which received all my email, and I POP'd the mail from there onto my Windows XP workstation. As I type this, both of those machines are stitting in a dark and cold storage locker wondering what they did wrong after several warm months in Florida.

Just prior to leaving Florida, I threw POP servers onto my two mail servers and let the mail be delivered locally. Then I started using fetchmail on my laptop to grab the mail. This kept me connected, but it still wasn't quite what I wanted. It didn't meet all my needs, as outlined in the advantages listed above.

I initially started into Cyrus IMAP, but abandoned it before deployment. I went with Dovecot. It is much easier to implement. Cyrus has its place, and is much more appropriate for larger environments. But I think it is overkill for my needs.

As a strong advocate of the FreeBSD ports tree, you know I'll be using that. The install looks like this:

cd /usr/ports/mail/dovecot
make install clean

That's it. All the dependencies will be installed for you. That's very valuable. :)

Configuration starts with the example file with some changes to suit my requirements.

cd /usr/local/etc
cp -i dovecot-example.conf dovecot.conf

A good source for configuration is http://wiki.dovecot.org/QuickConfiguration.

Here is a diff which represents the changes I made. I will explain those inline.

--- dovecot-example.conf	Wed Dec  5 15:27:25 2007
+++ dovecot.conf	Wed Dec  5 19:15:12 2007
@@ -21,7 +21,7 @@
 # Protocols we want to be serving: imap imaps pop3 pop3s
 # If you only want to use dovecot-auth, you can set this to "none".
 #protocols = imap imaps
-protocols = imap pop3
+protocols = imaps
 
 # IP or host address where to listen in for connections. It's not currently
 # possible to specify multiple addresses. "*" listens in all IPv4 interfaces.

I only want to run IMAPS (IMAP over SSL). This ensures all data transmitted is encrypted and cannot be viewed by others.

@@ -93,12 +93,17 @@
 # root. Included doc/mkcert.sh can be used to easily generate self-signed
 # certificate, just make sure to update the domains in dovecot-openssl.cnf
 #ssl_cert_file = /etc/ssl/certs/dovecot.pem
 #ssl_key_file = /etc/ssl/private/dovecot.pem

+ssl_cert_file = /etc/ssl/certs/imaps.example.org.cert
+ssl_key_file = /etc/ssl/private/imaps.example.org.key
+ 
 # If key file is password protected, give the password here. Alternatively
 # give it when starting dovecot with -p parameter.
 #ssl_key_password =
 
+ssl_key_password = ImNotTelling
+
 # File containing trusted SSL certificate authorities. Usually not needed.
 # The CAfile should contain the CA-certificate(s) followed by the matching 
 # CRL(s). CRL checking is new in dovecot .rc1

This sets up the certificates to be used by the encryption process. The details of how I created the certificate will be outlined below. The ssl_key_password directive supplies the passphrase for the certificate. No, that's not my real passphrase.

The hostname of my IMAP server is imaps.example.org (not really, but it's an example).

@@ -211,7 +216,8 @@
 # 
 #
 #mail_location = 
-mail_location = mbox:~/mail/:INBOX=/var/mail/%u
+#mail_location = mbox:~/mail/:INBOX=/var/mail/%u
+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.

I want to use the Maildir format, and I will place that Maildir in my home directory.

@@ -423,6 +429,8 @@
 # the performance much better, and it's unlikely to have any side effects.
 #maildir_copy_with_hardlinks = no
 
+maildir_copy_with_hardlinks = yes
+
 # When copying a message, try to preserve the base filename. Only if the
 # destination mailbox already contains the same name (ie. the mail is being
 # copied there twice), a new name is given. The destination filename check is

This is a simple performance issue. :)

@@ -787,6 +795,10 @@
     #args = /etc/dovecot.deny
     #deny = yes
   #}
+
+  passdb passwd-file {
+    args = /var/db/dovecot.users
+  }
 
   # PAM authentication. Preferred nowadays by most systems. 
   # Note that PAM can only be used to verify if user's password is correct,

I will use my own password file, and not use the system password file (/etc/passwd). I decided to do this to keep my IMAP login from my ssh login password.

I use CACert.org for my certificates. It is free and easy to do. I prefer not to use self-signed certificates, but there is no reason why you can't use them for this purpose. In a previous article about Bacula TLS, I showed how I did this. I will repeat the process here, in brief.

# openssl genrsa -des3 -out imaps.example.org.key 1024
Generating RSA private key, 1024 bit long modulus
.......................................++++++
................................++++++
e is 65537 (0x10001)
Enter pass phrase for imaps.example.org.key:
Verifying - Enter pass phrase for imaps.example.org.key:
#

It is the above passphrase that you use in the dovecot.conf file with the ssl_key_password directive.

# openssl req -new -key imaps.example.org.key -out imaps.example.org.csr
Enter pass phrase for imaps.example.org.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:San Jose
Organization Name (eg, company) [Internet Widgits Pty Ltd]:The FreeBSD Diary
Organizational Unit Name (eg, section) []:Gnome Wrestling
Common Name (eg, YOUR name) []:imaps.example.org
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

The resulting .csr file goes to the certificate authority, in my case, CACert.org. There are many existing documents on creating your own self-signed certificates. You will be able to find them easily with a quick search.

For the record, here is an error I encountered, in case you make the same mistake.

# openssl req -new -key imaps.example.org.key -out imaps.example.org.csr
Error opening Private Key imaps.example.org.key
32301:error:02001002:system library:fopen:No such file or
directory:/usr/src/secure/lib/libcrypto/../../../crypto/openssl/crypto/
                  bio/bss_file.c:278:fopen('imaps.example.org.key','r')
32301:error:20074002:BIO routines:FILE_CTRL:system
lib:/usr/src/secure/lib/libcrypto/../../../crypto/openssl/crypto/bio/bss_file.c:280:
unable to load Private Key

The cause of this error was mine. On the -out argument for the genrsa step, I supplied imaps.example.org instead of imaps.example.org.key.

I did this to fix the problem:

mv imaps.example.org imaps.example.org.key

I then reissued the original command.

In this section, I will outline how I configured Dovecot's authentication. This decides how Dovecot will validate your credentials before letting you have access to the mail.

I decided to use a password file. This file is compatible with a normal /etc/passwd file. In the dovecot.conf file, the file specified is /var/db/dovecot.users (see the patch above). Here is what I placed in that file.

dan:{MD5-CRYPT}$1$T3XHXQXL$J8wiZb.N8khkJGSNTdioX1:1001:1001::/home/dan

Bonus points to those that decrypt that password and post it in the comments. No, it's not my real password. It is the above login details that you set in the configuration for your email client.

I created that password with this command:

# dovecotpw -s MD5-CRYPT
Enter new password:
Retype new password:
{MD5-CRYPT}$1$T3XHXQXL$J8wiZb.N8khkJGSNTdioX1

Adding this entry to /etc/rc.conf will allow Dovecot to start at boot time:

dovecot_enable=YES

# /usr/local/etc/rc.d/dovecot start
Starting dovecot.

Looking at the processes, this is what you'll see:

# ps auwx | grep dovecot
root    34606 94.9  0.0  6188  1836  ??  R     5:27PM   0:06.07 ssl-build-param /var rs.dat
root    34605  0.0  0.0  2744  1172  ??  Ss    5:27PM   0:00.00 /usr/local/sbin/dove
root    34607  0.0  0.0  4992  1160  ??  S     5:27PM   0:00.00 dovecot-auth
dovecot 34608  0.0  0.0  6352  2260  ??  S     5:27PM   0:00.01 imap-login
dovecot 34609  0.0  0.0  6352  2260  ??  S     5:27PM   0:00.01 imap-login
dovecot 34610  0.0  0.0  6352  2260  ??  S     5:27PM   0:00.01 imap-login

What's this ssl-build-param? These entries from /var/log/messages explains it:

dovecot: Dovecot v1.0.7 starting up
dovecot: Generating Diffie-Hellman parameters for the first time. This 
         may take a while..
dovecot: ssl-build-param: SSL parameters regeneration completed

I will be using procmail to ensure my mail gets delivered to the right location. My MTA is Postfix and I could do that directly with the home_mailbox directive, but decided to do it with procmail instead. Actually, I'm using procmail anyway, and it just made sense to do it that way.

The Dovecot documentation explains all this very well, including the proper way to configure procmail with Devecot:

The proper way to configure procmail to deliver to a Maildir is to use Maildir/ as the destination.

I have something like this in my ~/.procmailrc:

:0
$HOME/Maildir/

I've been using IMAP for a few days now. So far, I've used KMail and Thunderbird as mail clients. When my Windows XP workstation is powered up again, I'll try my old favorite, Pegasus.

I'm sure you have your favourite email clients. Now you can use them from whenever and whereever you want. Enjoy IMAP.