November 2, 2011

Setting up a mail server with Postfix, Dovecot and Postfix Admin on Gentoo

This tutorial covers the installation of the Postfix SMTP server, the Dovecot IMAP server and the Postfix Admin interface to manage the mailbox accounts.


Postfix's default configuration accepts only mails from local users or users within the local network. The problem is that normally the clients which should send emails to this server are not in the same network as the server itself. It is possible to allow all users not within the network to send mails to postfix, but that would be disastrous. After a short time, the server would be a spam sling. The solution is to let postfix only accept mails from authenticated(SMTP-AUTH) users. This can be done using the Simple Authentication and Security Layer (SASL). The good thing is that Postfix can be configured to use Dovecots's SASL implementation instead of using the Cyrus SASL Library.

This article was written for Postfix 2.7, Dovecot 1.2 and Postfix Admin 2.3. Please consult the software documentation for any changes if you are using other versions than these.

In the code blocks I use placeholders, enclosed with square brackets, for values that should be adapted to fit your needs.


PHP, MySQL and the Apache HTTP Server must be installed. PHP must be compiled with the imap and mysqli use flags. The Apache HTTP Server must be configured for virtual hosting. You must create a MySQL database and two MySQL users. The first user is used by Postfix Admin to manage the virtual user accounts and the second one for Dovecot and Postfix to query this data.


The following use flags must be set for this configuration: And here is the list of packages to unmask: Gentoo uses the "mail-mta/ssmtp" package as default MTA. To install postfix this package must be de-installed to avoid conflicts. Start and stop the service so that postfix creates all needed configuration files. This setup uses the Maildir (Qmail style) format. Therefore you must create a directory in which the mails can be stored. Dovecot creates then subdirectories in the format domain/username/Maildir in this new directory. Now create a user and group which owns the newly created directory. Note the UID and the GID, you need this at a later time.


Before you start to edit the configuration files, Postfix must know where it should send mails to local users. Therefore exists the file /etc/mail/aliases. It specifies several aliases for the most system accounts. Postfix must translate these aliases to real addresses. So edit the file and set a real mail address for the root and the operator account. Run the newaliases command to recreate the alias database.

The file /etc/postfix/ contains all configuration parameter which controls the operation of the postfix mail system. As first set the name of the mailbox directory. The next parameters specify the machine's identity and role in the network. A particular description can be found on this Postfix page. Replace the [placeholders] with your settings. Tell Postfix the path to our new created alias database. As next comes the security settings. This setup uses TLS for secure authentication to the server. Certificates can be created with OpenSSL. There exists a GUI tool called TinyCA which is very easy to use. It is also available in portage. Don't forget to replace the placeholders with your created certificate and private key. As mentioned above this setup uses Dovecots’s SASL implementation to authenticate the users to the server. This part defines these settings. Setup the delivery for the emails from the local users. You can activate some settings to reject non RFC conform connections. Pay attention, this settings can cause some side effects with old email clients. And last but not least the virtual settings. This are needed to transport the incoming mails into the virtual mailboxes. The UID and the GID must be replaced with your data for the newly created vmail user and group. In this example the UID and the GID is 1001. The next files contains the SQL queries used to get the virtual aliases, domains and mailboxes. Replace the placeholders with the data from your setup.
The defines which services are available, which daemons should be started for a requested service and how a client connects to a service. In this file we must only setup two additional services. So first of all you must uncomment the smtps service in order to use the secure variant of the smtp protocol. For using the Dovecot LDA to deliver emails for virtual domains, you must add the dovecot service to the end of the file.


The file /etc/dovecot/dovecot.conf is the main configuration file for the Dovecot server. The first part of the file contains the protocols we wont to be serving and the IP addresses on which the server listens. In this setup Dovecot listens on all IPv4 and IPv6 interfaces. As protocols this setup uses only imap and its secure variant imaps. The SSL part of the config file contains only the domain on which the server listens and the paths to the certificate and private key files. Replace the placeholders with your settings. As next define the directory in which the mailboxes are located. The variables %s/%n create the directories in the form The full list of variables can be found here. For mail_uid and mail_gid set the name of the created vmail user and group. The variables first_valid_* and last_valid_* must be replaced with the UID and GID of the created vmail user and group. In this example the UID and the GID is 1001. Define the plugins for the imap protocol and the lda. The qouta plugin is needed to define a size limit for the user mailboxes. The autocreate plugin is used to create the Trash, Spam, Sent and Drafts folders inside the mailboxes. A list with plugins can be found on this page. As next replace the postmaster address, which will be used when sending rejection mails, with your postmaster address. This part configures the previous defined plugins. For the quota plugin we define only Per-user quota. The limit will be set later by the Postfix Admin web interface. The autocreate and autosubscribe definitions I think are self-explanatory. The last part of the config manages the authentication process. The mechanisms variable defines the allowed authentication mechanisms. Allowed mechanisms are "plain login digest-md5 cram-md5 ntlm rpa apop anonymous gssapi otp skey gss-spnego". As password and user database this example uses the SQL backend to select the data, created with Postfix Admin, from the installed MySQL instance. The socket part defines the sockets to use for the authentication process. We define a master socket for the Dovecot LDA and a client socket for Postfix. The user variable defines the user for the authentication process. This user must only have access to the user and password database. For our scenario the user nobody is sufficient. The count variable specifies the number of authentication processes to create.
The file /etc/dovecot/dovecot-sql.conf defines the access to the password and user database, used for the Dovecot authentication process. Replace here the user, password and dbname placeholers with your settings.

Postfix Admin

The first step is to create a Virtual Host for Postfix Admin, because it was installed without the vhost use flag.
Virtual Host
Go to the directory /etc/apache2/vhosts.d and create a file such as Next copy the following snippet and paste it into the newly created file. Don't forget to replace the placeholders with your settings. This example uses a SSL Name Based Virtual Host. With such a VHost you can use multiple SSL certificates with a single IP address. Furthermore it uses Apache`s basic authentication to protect the access to the Postfix Admin web interface. If you don't need these features, remove the associated lines. Restart the apache web server and enter the the URL for the newly created VHost in your browser. Now you should see the Postfix Admin welcome screen. Near at the bottom of the page is a setup link. After clicking this link you should see the setup page with the following information.
Change into the directory /var/www/localhost/htdocs/postfixadmin and open the file in your favorite editor. Change the database settings to your needs and set $CONF['configured'] to true. Save the file and reload to the setup page in your browser. If all settings are correct then Postfix Admin creates all tables in the specified MySQL database. Now its time to create the setup password for Postfix Admin. This can be done by entering a password in the form at the bottom of the setup page. When submitting the form, the setup script creates a hash of this password, which must be pasted in the configuration file. So edit the file again and change the remaining settings. The configuration file is very well documented, so I will only pick out the most important settings. I think the next settings are self-explanatory. If not, please consult the documentation. This must be set to match the same directory structure(domain/username), that we use for this setup. Set this to use dovecots crypt method. Enable all quota based settings. After saving the file, go back to the Postfix Admin setup page and create a superadmin account. Now you can login with this user into the administration interface. Don't create any domains or mailboxes yet because you must first start the services.


All configuration files are adapted, so its time to start the services. Note: If you get the message "Fatal: listen(::, 143) failed: Address already in use" then your server isn't configured for IPv6. Remove the [::] part from the listen variable in the dovecot.conf file. Add postfix and dovecot to the default runlevel, so that the system start these services at boot time automatically. To test the newly configured mailserver for an open relay, telnet to the address It will do an extensive scan of your IP and immediately report the problems. Many thanks for this tip goes to Sean. Right now you should have a running mail server setup. The last step is to create virtual domains and mailboxes. If you need help doing this, please consult the Postfix Admin web page. Now open your email client and create a new account for one of your mailboxes. Send a mail to it and wait for the incoming message. If you receive the mail after a view seconds in your inbox, congratulations your mail server runs as desired. If it doesn't work, check the logs for the installed services or leave a comment and maybe I can help you.


More informations can be found on the following pages:


  1. Hi,

    Thank you for your nice page, very useful!
    Recently I setup a homemade e-mail server and wrote a full detailed tutorial that you can find in

    using Postfix, Dovecot, SASL, Spamassassin and Squirrel (and a Google account for SMTP relay).

    It may be helpful to some readers.

  2. DB sections is outdated - needed rw