Mail server using Postfix and Dovecot

About this setup
This article is intended to outline the process of setting up the basic framework for an advanced, ISP style, virtual mail server.

This guide will be using:
 * PostfixAdmin 2.3.5 (Virtual Mail Administration)
 * Postfix 2.9.4 (SMTP)
 * Dovecot 2.1.9 (POP3, IMAP, SASL, LMTP + Quota)

Prerequisites
This article assumes the sytem and system administrator meets the follow prerequisites: has the appropriate tools installed for the job (e.g. phpmyadmin, etc) Furthermore, this article assumes everything will be housed on a single machine.
 * A supported database server is installed and ready for use
 * MySQL 5+
 * MariaDB 5+
 * PostgreSQL 9+
 * The Admin has an understanding of basic SQL functions and, if needed,
 * A webserver installed, ready to use, supporting PHP & setup for virtual hosting
 * Apache 2
 * Nginx
 * Lighttpd
 * PHP built with or

Hostnames, FQDNs (mail.example.org), and MX Records
This article uses the standard mail.example.org Hostname. As well, the following assumptions are made:
 * System mail (rejects, etc) should originate from example.org
 * The Fully Qualified Domain Name (FQDN) is mail.example.org
 * The MX record for example.org directs towards mail.example.org

Mail Storage
This article assumes the desired storage scheme is using the Maildir (Qmail style) format.

The directory is considered to be the virtual user's home directory.

This home directory is used for storing things like indexes that are not normally part of the Maildir structure.

PAM Users
The following system users are needed by this setup:

The following groups are used by this setup:

Postfix Admin
Postfix admin not only provides a clean web interface for maintaining a virtual mail server, but also creates the database tables which will be used by Postfix and Dovecot

Installation
Before installing, a few Use Flags will need to be set

During the emerge, is run, automatically installing postfix admin.

For the purposes of this article, the install directory will be changed. Adjust for version and location differences

This will place Postfixadmin's php files in the directory configured with webapp-config.

Usually this will be.

Before continuing, configure your webserver to serve the directory used above.

Once done, verify the install by browsing to mail.example.org/postfixadmin/setup.php.

A page, complaining about nothing being configured, should be displayed.

Configuration
Note: Something is missing here. There appears to be a common issue where the following steps are simply not enough, and the created user does not have enough privileges even if you grant all privileges on the created database to the created user. One could use the root user as a workaround, but this is a widely-known not-so-good way to do things.

Before configuring Postfix Admin, you will need to create a database and a user with nearly full privileges on that database.

To easy achieve this, a temporary sql file can be made, and quickly imported into mysql.

Enter the mysql root user password when prompted

Delete the temporary sql file

After the SQL database and user has been created, the configuration file can be scoured.

While it should be read in it's entirety, here are the important things to change.

Once finished, navigate again to the from before.

This time, the script will populate your database with tables and data.

When it has completed, create a "setup password" hash, and copy it to the config file.

Again, refresh the setup page, and create a mail server admin (e.g. admin@example.org).

Setting up the first Domain, Mailbox, and Aliases
Go to the URL for PostfixAdmin and enter the global admin username and password created when setting up PostfixAdmin.

This article will describe how to set up a single domain with a single mailbox and a catch-all alias

(ie. anything@example.org will go to the same account).

Domain
First, set up the domain.

From the drop-down menus, along the top of the page, select Domain List and then New Domain.

Fill out the form as follows:
 * Domain: Enter the domain name (excluding the "www."). For example, "example.com"
 * Description: This is just a description for reference. Note that the Domain administrator will also be able to see this value.
 * Aliases: The number of aliases that the domain is allowed to have.
 * Mailboxes: The number of mailboxes that the domain is allowed to have.
 * Max Quota: The maximum mail quota for the domain.
 * Add default mail aliases: This adds the default mail aliases configured in the PostfixAdmin configuration file. Enable this.
 * Mail server is backup MX: Is this server the backup MX for this domain? (Generally this will be left disabled).

When finished, click the Add Domain button.

The new domain should be visible in the "Domain List" and "Virtual List" screens.

Initial Mailbox
Now that there is a domain, create at least one mailbox for it, called "admin", since this will simplify catching all the standard aliases.

Select Virtual List then, from the drop-down menu that appears, Add Mailbox.

To create the "postmaster" mailbox, fill out the form as follows:
 * Username: "postmaster" (This is the part of the email address before the @)
 * Password (and Password (again)): Enter a password for the account (Don't forget it!).
 * Name: This is a name for the account. It's only visible in PostfixAdmin and has no real effect on the mailbox.
 * Quota: Enter a quota for the mailbox in MB. For example, 1024 for 1GB.
 * Active: Is the mailbox currently active (accepting mail)? You'll want to leave this checked.
 * Send Welcome mail: This sends the welcome email with the text specified in the PostfixAdmin configuration file. Leave this unchecked, as the server has not been setup yet.

When finished, click the Add Mailbox button.

Catch-all Alias
Now that the domain has a mailbox, create an alias for it. In this case, the alias will be a "catch all" alias that causes any email sent to an address for which there is not another alias or mailbox to be sent to the address specified in the catch all alias.

Select Virtual List then, from the drop-down menu that appears, Add Alias.

Fill out the form as follows:
 * Alias: This is the address that emails are addressed to. Because this is a "catch all" alias, enter "*"
 * To: This is the address that emails sent to the address specified above are forwarded to. In this case enter "postmaster@example.com"
 * Active: Is this alias currently active? Leave this checked.

Click the Add Alias button to add the alias.

Create the Postfix and Dovecot SQL User
Since Postfix Admin will be the only service performing database table modifications,

Dovecot and Postfix should use a different user for their queries.

Once again, create a temporary SQL file to place the commands into:

Enter the mysql root user password when prompted

Delete the temporary sql file

Local Aliases
Postfix needs to know where you want mail sent to local users

(e.g., mail sent by cron jobs is usually just sent to "root" - Postfix needs to be able to translate this to a "real" address).

Next, generate the alias database

You may also want to symlink these files into the Postfix configuration directory to make them easier to find:

Dovecot Integration - LDA
In this setup, Postfix Will make use of Dovecot's Local Delivery Agent (LDA). To do this, add the following line to :

Now, tell Postfix to actually use Dovecot's deliver

Dovecot SASL Authentication Integration
This setup uses Dovecot's SASL capability for Postfix authentication.

Add the following to enable SASL and set it to the dovecot interface we configured earlier:

Database Maps
The following files contain details that Postfix will use to look up various details using the postfixadmin database.

Create each of the following files, with the contents below, inside the directory.

Most of the details here should be self explanatory. We use the same database user as Dovecot, since Postfix requires read-only access to the same tables. The password is the same one entered when creating the user.

Now, configure Postfix to use the above queries

Tip: Because this is using the Dovecot's LDA, all results from virtual_mailbox_maps are ignored beyond checking if they exist.

Optional: Relay (Backup MX) Domains
If you don't want your server to relay mail for other domains, you can skip this section.

Create the MySQL map file:

And then add the following to the bottom of :

Optional: Relay Host (Sending Out Through ISP)
If you are using an ISP which blocks personal mail servers, you may have to relay your outgoing mail through their SMTP server.

And edit so that it looks like so:

And generate the hash:

Other Settings
Add the following to set up the restrictions the Postfix will impose on mails:

Optional: You may wish to add the following to the end of smtpd_recipient_restrictions to help prevent spam.

(Please read the usage agreement on Spamhaus' site)

Checking Configuration
You could have Postfix perform a cursory check of your configuration by running:

Start Postfix
Start postfix

Set Postfix to start with the system

Dovecot
This section deals with configuring the Dovecot mail server.

Tip: Since the migration to 2.x, the config files have been split up inside

dovecot.conf

 * Bind to all IPv4 and IPv6 interfaces (like a good mail server)
 * Enable the built-in Local Mail Transfer Protocol (LMTP)

10-auth.conf

 * Disable "plaintext" logins. This does not affect SSL connections
 * Enable the required authorization mechanisms
 * Comment out (disable) the PAM user lookups

10-mail.conf

 * Set the mailbox location. Separating the indexes allows for future flexibility
 * Limit UIDs and GIDs for security
 * Enable the quota plugin

10-master.conf

 * Specify the sockets to allow for authentication mechanisms to use
 * For this setup, there must be a master socket for the Dovecot LDA and a client socket for Postfix
 * For this setup, LMTP will be set to create a socket inside Postfix's spool directory
 * Additionally, for security and PostgreSQL compatibility, the auth-worker will need to be set to the mail user.

15-lda.conf
The Local Delivery Agent (LDA) is the portion of Dovecot that deals with putting messages into the correct mailboxes. If LMTP is enabled, it will inherit these settings.
 * Set the email address used as the From address for error message emails

20-imap.conf

 * Enable the imap_quota plugin

dovecot-sql.conf.ext
Set the database connection details.

Now, tell Dovecot how to use the SQL connection: This article will use the prefetch method to avoid an extra query to the database after authentication.

This method requires no values to be set (because all the information comes from passdb).

This article uses the Dovecot LDA, so we must also include the user query for mail delivery.

Note that Dovecot will only use this for delivery since it comes after the prefetch entry mentioned above.

Start Dovecot
Start Dovecot

Set Dovecot to start with the system

Testing Mail Delivery
Now that the mail server is setup, email delivery should be tested.

Make sure no email files exist currently

/var/mail

Send a test email

Check again to see if the mail was received

/var/mail/ /var/mail/.keep_net-mail_mailbase-0 /var/mail/example.org /var/mail/example.org/admin /var/mail/example.org/admin/indexes /var/mail/example.org/admin/indexes/.INBOX /var/mail/example.org/admin/indexes/.INBOX/dovecot.index.cache /var/mail/example.org/admin/indexes/.INBOX/dovecot.index.log /var/mail/example.org/admin/Maildir /var/mail/example.org/admin/Maildir/dovecot-uidvalidity /var/mail/example.org/admin/Maildir/dovecot-uidvalidity.50a84849 /var/mail/example.org/admin/Maildir/dovecot-uidlist /var/mail/example.org/admin/Maildir/new /var/mail/example.org/admin/Maildir/new/1353205833.M275826P9260.mail,S=346,W=356 /var/mail/example.org/admin/Maildir/cur /var/mail/example.org/admin/Maildir/tmp

Now, preform the same command,, but this time testing from an external source, such as Gmail.

Test with a IMAP/POP3 Client
Set up and fetch the mail for the mailbox. Using the example values above, the details needed for the client are as follows:
 * Server (incoming and outgoing): The servers address (for example: mail.example.com)
 * Username: admin@example.com
 * Password: The password entered when creating the mailbox

First, set up the account as an IMAP account. The Inbox should contain the test emails from above.

Next, set up the account as a POP3 account. Again, the Inbox should contain the test emails from above.

Using an account hosted on another server (e.g. Gmail), send an email to the new mailbox (eg. admin@example.com).

Wait a couple of minutes and collect mail for the account. The email should arrive.

Using the account on the new server, send an email to the webmail account and send a cc to an address other than admin on the new server (eg. something@example.com). Wait a couple of minutes and collect email on both accounts. Both accounts should receive the email.

If all these tests passed, then the server is working as expected.

If any of these tests fail, then check the mail logs, or proceed to Trouble Shooting.

Troubleshooting
The amount of logging that postfix processes, can be changed be adding "-v" or "-v -v" (for more verbosity) to the last parameter of the appropriate line in

Also visit Dovecot Troubleshooting