electronic brain surgery since 2001

Setup Postfix and Dovecot on Debian Etch

Imagine this: Alice, Bob and Charly are sharing a root server. They all three have their own domains and need some simple setup to send and receive mail for a couple of addresses.

This article explains how to do a basic mail setup using Postfix (SMTP) and Dovecot (IMAP). Virtual mail users will be mapped to a single system account. Because only a handful of addresses are needed, no database is involved – all users are stored in a text file.

The installation method and paths assume a Debian system. But most of this tutorial should apply to any other Linux system as well. Some general knowledge on how mail and MTAs work is recommended ;-).

I plan to follow up this article with post(s) on how to setup mail filtering, spam checking and adding SSL support.

To ease the following description, let's assume the following values:

  • The server is named mail.alice.xom
  • All automatic mails will be sent from the domain alice.xom
  • It should accept mails for the domains alice.xom, bob.xom and charly.xom 1)
  • All mail directories shall be stored below /vmail/<domain>/<user>


This is the simplest step2). Just install the needed packages:

#> apt-get install dovecot-imapd postfix-pcre

When asked by debconf, just answer with “No configuration”.

Virtual Users

All users will be managed through Dovecot. Dovecot supports various user databases – for the needs of Alice, Bob and Charly the passwd-file method fits best.

As the name suggests, it uses a simple text file which is formatted similar to the system's passwd(5) file. In this file all virtual users will be listed in the following form:


<uid> and <gid> specify the system user and group which will hold all virtual users. I recommend to use a dedicated vmail user and place him in the standard mail group:

#> useradd -r -c 'virtual mail users' -m -d /vmail -g mail vmail
#> mkdir /vmail
#> chown vmail:mail /vmail

Use the id command to get this new user's uid:

#> id vmail
uid=104(vmail) gid=8(mail) groups=8(mail)

Time to create the user file. All passwords in this file should be stored as a crypted hash. You can create such a hash with the dovecotpw tool:

#> dovecotpw -s SHA1
Enter new password:
Retype new password:

Now create your user file in /etc/dovecot/users.conf:


For security reasons (and because Dovecot will complain otherwise) nobody except root should be able to open this file:

#> chown root:root /etc/dovecot/users.conf
#> chmod 600 /etc/dovecot/users.conf

Configuring Dovecot

After having set up the users, continue with editing Dovecot's config file in /etc/dovecot/dovecot.conf:

protocols = imap

# We only allow our virtual user to login
first_valid_uid = 104
last_valid_uid = 104
first_valid_gid = 8
last_valid_gid = 8

mail_location = maildir:~/Maildir
mail_extra_groups = mail

# debugging - comment in when needed
log_timestamp = "%Y-%m-%d %H:%M:%S "
#mail_debug = yes
#auth_verbose = yes
#auth_debug = yes
#auth_debug_passwords = yes
#verbose_ssl = no

protocol lda {
  # Address to use when sending rejection mails.
  postmaster_address = postmaster@alice.xom

auth default {
  mechanisms = plain
  passdb passwd-file {
    args = /etc/dovecot/users.conf
  userdb passwd-file {
    args = /etc/dovecot/users.conf

  socket listen {
    master {
      path = /var/run/dovecot/auth-master
      mode = 0600
      user = vmail
      group = mail
    client {
      # make auth info available for postfix
      path = /var/spool/postfix/private/auth
      mode = 0600
      user = postfix
      group = mail

The config is pretty straight forward. First it is made sure that only the system account dedicated to the virtual mail user is allowed to access the IMAP server. Then the mail storage format (Maildir) and path to the mail folder is set up.

Later the protocol lda block defines the behavior for accepting incoming mails from postfix via the LDA protocol. Nothing fancy here.

The third part finally configures the authentication mechanism as described in the previous section. The socket listen options are most important. Those make the authentication info available to Postfix which will use them to handle SMTP-Auth. This way all IMAP passwords will be valid for SMTP auth, too.

That's it for Dovecot so far. Just (re)start:

#> /etc/init.d/dovecot restart


Next step is Postfix. Before you continue, a word of warning: Postfix reloads its config periodically – keep this in mind when working on a running mail system!

First you need to create Postfix's main configuration in /etc/postfix/main.cf. Here is the full listing first – explanations below.

smtpd_banner = $myhostname ESMTP $mail_name (Debian/GNU)
biff = no

# setup for local generated mails
append_dot_mydomain = yes
masquerade_domains  = alice.xom
myorigin = alice.xom

# general stuff
myhostname = mail.alice.xom
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
mydestination = mail.alice.xom,
relayhost =
mynetworks =
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all

# helo restrictions
smtpd_delay_reject = yes
smtpd_helo_required = yes
smtpd_helo_restrictions =

# sender restrictions
smtpd_sender_restrictions =

# recipient restriction
smtpd_recipient_restrictions =

#enable SMTP auth for relaying
smtpd_sasl_auth_enable       = yes
broken_sasl_auth_clients     = yes
smtpd_sasl_type              = dovecot
smtpd_sasl_path              = private/auth

# deliver with dovecot
dovecot_destination_recipient_limit = 1
mailbox_transport = dovecot
local_recipient_maps =

Again we start with some generic setup, like the SMTP banner and how mails generated at the local system should be treated. The name of the system is set up and all domains the server should accept mails for are listed in the mydestination setting.

Then a few restrictions follow. These are very important (order does matter) as they will make sure your server is not an open relay and will accept mail only from permitted senders. Only mails generated on the server itself (from mynetworks) and from users who authenticated through SMTP auth first are accepted.

This SMTP auth is set up after the restriction checks. It tells postfix to authenticate via Dovecot's authentication socket we set up earlier.

Received mails are passed over to Dovecot through Dovecot's own delivery agent. This allows us to use Dovecot plugins for filtering incoming mails (more on that in a follow-up post).

To make the last setting work, we need to tell postfix were to find Dovecot's delivery agent. This is done in /etc/postfix/master.cf were we add the following at the very end (leave everything else as is):

# Dovecot LDA
dovecot   unix  -       n       n       -       -       pipe
  flags=DRhu user=vmail:mail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${recipient}

That's it. Before we restart postfix, we'll make sure the alias database exists:

#> newaliases
#> /etc/init.d/postfix restart


Now you can setup a mail client to test the system. You need to give the full email address as username (alice@alice.xom) for IMAP and SMTP.

If it does not work, check /var/lib/mail.log on the server for any error messages.

tutorial, debian, postfix, dovecot
Similar posts:
using .xom instead of .com to avoid any problems with the real domain owners
This is why I love Debian ;-)