Postfix + Dovecot + SSL configuration example

30 March 2013

In this tutorial you will learn how to configure Postfix integrated with Dovecot. Dovecot will be used for user authentication and POP3 service. We will also configure our services to be available over SSL.

Introduction

Postfix mail server delivers a high level of flexibility in what matters to configuration and customization. In this tutorial we will integrate Postfix with Dovecot in order to delegate user authentication and POP3 mail server access to Dovecot itself. We will also configure our mail system to be accessible over SSL.

This tutorial considers the following software and environment:

Ubuntu 12.10
Postfix 2.9.6
Dovecot 2.1.7

Note: This tutorial assumes that you have already configured a Postfix mail server instance. If you haven't configured Postfix yet you should first go through the following tutorial: Postfix Mail Server configuration tutorial.

Note2: This tutorial is suited for Dovecot version 2.X. If you are using Dovecot 1.X the following instructions will not apply as Dovecot configuration changed substantially from version 1.X to 2.X.

You may check which Dovecot version you are running by issuing the following command:

dovecot --version

Note3: This tutorial relies mostly in configuration. The entries we are adding or modifying are kind of self explanatory. If you need clarification on some configuration entries please ask in comments section (or check Postfix / Dovecot reference documentation).

Installing Dovecot

In order to get and install Dovecot we issue the following command:

apt-get install dovecot-imapd dovecot-pop3d

Generating SSL certificates

We will also need a certificate to enable SSL communication. We will use openssl to generate a self-signed certificate.

First issue the following command to generate a private key:

openssl genrsa -out domain.key 1024

The key will be generated and stored in domain.key file. Now issue the following command to generate a certificate request:

openssl req -new -key domain.key -out domain.csr

You will be asked to provide some organizational information. When you are asked for Common Name make sure to provide your full domain name, ex: domain1.com. After conclusion your certificate request will be stored in domain.csr.

Finally we generate the certificate itself based on the private key and the certificate request:

openssl x509 -req -days 3650 -in domain.csr -signkey domain.key -out domain.crt

The certificate will be stored in domain.crt file. You may place the private key file and the certificate file in a directory that is suitable for your needs. We will refer to these files later in the tutorial.

Please note that the names we gave to the private key, the certificate request and the certificate were merely illustrative. You may name these files whatever you wish.

main.cf

Now edit main.cf Postfix configuration file and add the following lines:

smtpd_use_tls=yes
smtpd_tls_session_cache_database = btree:/etc/postfix/tlscache/smtpd_scache
smtp_tls_session_cache_database = btree:/etc/postfix/tlscache/smtp_scache

smtpd_sasl_auth_enable = yes
smtpd_sasl_security_options = noanonymous
smtpd_sasl_local_domain = $myhostname
smtpd_sasl_application_name = smtpd
broken_sasl_auth_clients = yes
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_recipient_restrictions = permit_sasl_authenticated,permit_mynetworks,reject_unauth_destination
smtpd_tls_received_header = yes

smtpd.conf

Now create /etc/postfix/sasl/smtpd.conf file and add the following contents:

mech_list: cram-md5
pwcheck_method: saslauthd

master.cf

Now edit master.cf Postfix configuration file.

After the following line:

smtp inet n - - - - smtpd

Insert the following lines:

-o smtpd_tls_cert_file=/home/root/certs/domain.crt
-o smtpd_tls_key_file=/home/root/certs/domain.key

Uncomment the following line:

smtps inet n - - - - smtpd

And insert the following lines after:

-o smtpd_tls_wrappermode=yes
-o smtpd_tls_cert_file=/home/root/certs/domain.crt
-o smtpd_tls_key_file=/home/root/certs/domain.key

Note: The paths to the key file - domain.key - and the certificate file - domain.crt - should be the ones you have chosen before when we generated the SSL certificates.

TLS cache

Now let's create the TLS cache files. Issue the following commands:

mkdir /etc/postfix/tlscache
chmod 755 /etc/postfix/tlscache

User and Passwords file

Create the users file in:
/etc/dovecot/users

Give the necessary permissions to the file:

chmod 644 /etc/dovecot/users

This file should contain the users you want for each domain you are hosting, one line per user.
Each user should be in the following format:

[email protected]::5000:5000::/home/vmail/domain1.com/john.doe/:/bin/false::

Note: 5000 is the user and group of the mailbox owner we created in the previous tutorial while configuring the Postfix instance: Postfix Mail Server configuration tutorial.

Now create the passwords file in:
/etc/dovecot/passwd

Give the necessary permissions to the file:

chmod 644 /etc/dovecot/passwd

This file should contain the passwords for each user present in the users file, again one user/password pair per line.
Each line should be in the following format:


[email protected]:{CRAM-MD5}e02d374fde0dc75a17a557039a3a5338c7743304777dccd376f332bee68d2cf6

In order to generate the password hash you may run the following command:

doveadm pw

Note: Once again the path to the maildir directory in the users file is the one we defined in the previous tutorial while configuring the Postfix instance: Postfix Mail Server configuration tutorial.

Refreshing the aliases DB

Now we refresh our aliases DB file by issuing the following command:

newaliases

10-auth.conf

Now edit:
/etc/dovecot/conf.d/10-auth.conf

Add or change the following entry:

auth_mechanisms = plain login cram-md5

10-mail.conf

Now edit:
/etc/dovecot/conf.d/10-mail.conf

Add or change the following entries:

mail_location = maildir:/home/vmail/%d/%n
mail_uid = 5000
mail_gid = 5000

Note: Once again the path to the maildir directory is the one we defined in the previous tutorial while configuring the Postfix instance: Postfix Mail Server configuration tutorial. The same applies to the user and group IDs.

10-master.conf

Now edit:
/etc/dovecot/conf.d/10-master.conf

Add or change the following entries:

service pop3-login {
  inet_listener pop3 {
    port = 110
  }
  inet_listener pop3s {
    port = 995
    ssl = yes
  }
}

unix_listener /var/spool/postfix/private/auth {
  mode = 0666
}

Note: The path to the SASL auth socket is the same we defined above in main.cf Postfix configuration file

10-ssl.conf

Now edit:
/etc/dovecot/conf.d/10-ssl.conf

Add or change the following entries:

ssl_cert = </home/root/certs/domain.crt
ssl_key = </home/root/certs/domain.key

Note: The paths to the key file - domain.key - and the certificate file - domain.crt - should be the ones you have chosen before when we generated the SSL certificates.

auth-system.conf.ext

Now edit:
/etc/dovecot/conf.d/auth-system.conf.ext

Add or change the following entries:

passdb {
  driver = passwd-file
  args = scheme=cram-md5 username_format=%u /etc/dovecot/passwd
  #driver = pam
  # [session=yes] [setcred=yes] [failure_show_msg=yes] [max_requests=<n>]
  # [cache_key=<key>] [<service name>]
  #args = dovecot
}

userdb {
  driver = passwd-file
  args = username_format=%u /etc/dovecot/passwd
  # <doc/wiki/AuthDatabase.Passwd.txt>
  #driver = passwd
  # [blocking=no]
  #args =

  # Override fields from passwd
  #override_fields = home=/home/virtual/%u
}

Note: The paths to the passwd file are equal to the one we defined previously on this tutorial when we created the passwd file

Testing

We are now ready for testing. Chose your favourite mail client software, such as Thunderbird or Outlook, and connect to the mail server using SSL ports both for sending and receiving. You may get a warning because the certificate we are using is self-signed. Don't forget to select POP3 as the receiving protocol.

In order to confirm you are sending message to your server through a secure connection you may send a test message and inspect the message source in the receiver. You should be able to trace the information generated by your email server and extract a portion of the message meta data that is similar to:

Received: from [192.168.1.32] (someprovider.com [213.54.225.31])
(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
by domain1.com (Postfix) with ESMTPA id E12AB5D9EBA
for <[email protected]>;

Configuring a mail server can be problematic especially if you are doing it for the first time. Both Postfix and Dovecot provide a robust logging mechanism and by looking at the logs you can almost certainly check what went wrong. The log file is located at:

/var/log/mail.log