Gentoo Wiki


Split-arrows.gifIt has been suggested that this article be split into multiple articles accessible from a disambiguation or index page.   (Discuss)



I recently moved my original mail system, built using the Gentoo Virtual How-to, over to a PostfixAdmin run system. Additionally I took this time to add Postgrey and switch to encrypted passwords using Courier's new authlib, which I'll detail as well.

Virtual Mailhosting System with Postfix Guide

Notes From the Author

kashani (2007.04.17): I just ran through this how-to on my new vps server so it's pretty fresh. Should be updating this over the next week.
kashani (2008.06.25): A few updates, but I haven't really looked to hard at what is new in Postfixadmin 2.2
kashani (2008.08.21): Added syslog-ng stuff to split mail out, added mysql account creation stuff a couple of weeks ago.

Notes From Users

Put things you'd like me to fix or comments here

Bigun - Possibly some code on how to setup courier-imapd-ssl and courier-pop3d-ssl, certificates and all

Why PostfixAdmin

PostfixAdmin provides a nice frontend for a Postfix/Courier based virtual mail server. As super admin you can create domain admins, create their domains, own the domains to the domain admin, and now you the Admin can go back to reading the Gentoo forums rather than creating users, changing passwords, or deleting accounts.

And managing your email system with PHPMyadmin sucks.

Which Packages

This How-to assumes you have these versions

Postfix 2.4.x
Courier 4.0.x
Courier-authlib 0.60
PostfixAdmin 2.2.0
Mysql 5.0
PHP 5.2

Default Settings

All mail is in /var/vmail/
All mail is owned by the Postfix user
The database is called postfix
The database user is called postfix
The database password is IheartPostfix You should change that


I like the following USE variables for a standalone mail server, but the minus flags aren't really necessary


USE="apache2 mysql threads nptl libwww sasl ssl maildir imap vhosts -acl -alsa -cups -doc -gnome -gtk -gtk2 -ipv6 -java -kde -nls -oss -qt -sdl -X"


dev-libs/cyrus-sasl     -berkdb -mysql authdaemond urandom
mail-mta/postfix        mysql ssl sasl vda
www-servers/apache      -threads
dev-lang/php            -threads apache2 crypt gd hash imap mhash mysql mysqli session unicode 

We're going to slave SASL off Courier-authlib instead of having it talk directly to the database. This allows us to use encrypted passwords and seems to work better as well. However there have been some weird authlib problems in recent updates so watch your upgrades.

Unicode is required by PHP if you plan to use the Horde framework for your webmail. Squirrel doesn't require it, but you're better off going Unicode sooner rather than later. I like Roundcube Webmail best, but development on it has slowed over the past year.



$ emerge -pv mysql 
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild   R   ] dev-db/mysql-5.0.60-r1  USE="perl ssl -berkdb -big-tables -cluster -debug -embedded -extraengine -latin1 -max-idx-128 -minimal (-selinux) -static" 0 kB 


Once MySQL is up and running you'll need to create your database.

mysql -u root -p
create database postfix;
GRANT ALL PRIVILEGES ON postfix.* TO postfix@localhost IDENTIFIED BY 'IheartPostfix';
flush privileges; 

By default Mysql binds only to, aka localhost, and will not be accessible from outside your server. In order to let it bind to the normal ethernet interface you need to comment out the bind-address line in /etc/mysql/my.cnf. You will also need to change your GRANT line to allow access from more than localhost.



First verify that you have all the proper USE flags enabled. A pretend should look like this.

popmail ~ # emerge -pv postfix

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild   R   ] mail-mta/postfix-2.4.6-r2  USE="mysql pam sasl ssl vda -cdb -dovecot-sasl -hardened
-ipv6 -ldap -mailwrapper -mbox -nis -postgres (-selinux)" 0 kB 

popmail ~ # emerge postfix

Once Postfix is installed you'll need to add local aliases and run new aliases so Postfix will start and be happy. Postifx does not deliver mail to root so you'll want to point the mail for root to some other user or mail account.

popmail ~ # vi /etc/mail/aliases
popmail ~ # newaliases

Then add Postifx to the default runlevel and start it. You'll want to check the logs in /var/log/messages to make sure Postifx did not complain about anything on startup.

popmail ~ # rc-update add postfix default
popmail ~ # /etc/init.d/postfix start

This is fairly unfancy.

# local settings. Remember any domain you want treated as virtual
# can not be your listed in either relay_domains or mydestination. 
myhostname =
mydomain =
myorigin = $myhostname
inet_interfaces = all
mydestination = $myhostname, localhost.$mydomain, localhost
mynetworks_style = subnet
mynetworks =

# attachement filtering, optional
#mime_header_checks = regexp:/etc/postfix/mime_header_checks.regexp

# Size settings, optional
#message_size_limit= 112400000
#mailbox_size_limit = 224800000

# SASL settings
broken_sasl_auth_clients = yes
smtpd_sasl_auth_enable = yes
smtpd_sasl_authenticated_header = yes
smtpd_sasl_security_options = noanonymous
smtpd_sasl_local_domain =

# TLS stuff
smtpd_use_tls = yes
smtpd_tls_key_file = /etc/postfix/newkey.pem
smtpd_tls_cert_file = /etc/postfix/newcert.pem
smtpd_tls_CAfile = /etc/postfix/cacert.pem
smtpd_tls_loglevel = 3 #### change to 0 after everything works
smtpd_tls_received_header = yes
smtpd_tls_session_cache_timeout = 3600s
tls_random_source = dev:/dev/urandom 

# transport Stuff, optional
#transport_maps = hash:/etc/postfix/transport
#relay_domains = $transport_maps

# virtual stuff. We're going to punt and make all virtual mail users use the same UID:GID of Postfix. 
virtual_alias_maps = proxy:mysql:/etc/postfix/
virtual_gid_maps = static:207
virtual_mailbox_base = /var/vmail/
virtual_mailbox_domains = proxy:mysql:/etc/postfix/
virtual_mailbox_limit = 112400000
virtual_mailbox_maps = proxy:mysql:/etc/postfix/
virtual_minimum_uid = 207
virtual_transport = virtual
virtual_uid_maps = static:207

smtpd_recipient_restrictions = 
        #check_policy_service inet:, needed for sqlgrey and optional

# additional spam fighting checks, optional
#smtpd_helo_restrictions = reject_unknown_helo_hostname
#smtpd_sender_restrictions = reject_unknown_sender_domain
#smtpd_data_restrictions = reject_unauth_pipelining

# you only need this if you plan to act as a backup mx for various domains.
user = postfix
password = IheartPostfix
hosts = localhost
dbname = postfix
query = SELECT domain FROM domain WHERE domain='%s' AND backupmx = '1' AND active = '1'

user = postfix
password = IheartPostfix
hosts = localhost
dbname = postfix
query = SELECT goto FROM alias WHERE address='%s' AND active = '1'

user = postfix
password = IheartPostfix
hosts = localhost
dbname = postfix
query = SELECT domain FROM domain WHERE domain='%s' AND active = '1'

user = postfix
password = IheartPostfix
hosts = localhost
dbname = postfix
query = SELECT maildir FROM mailbox WHERE username='%s' AND active = '1'


You'll need to tweak this somewhat for your system, but I used this in production and have had no complaints. This needs to be all one line.

|vb|vb[esx]|vxd|wab|ws[cfh]))"?\s*$/ REJECT Files attached to emails that contain or end in "$3" are
prohibited on this server as they may contain viruses. The file named "$2" was rejected.

OS stuff


Now that you have Postfix install it's time to create and chown properly our mail directory.

sudo mkdir /var/vmail
sudo chown postfix: /var/vmail

The directory name and location does not matter, but it's a good idea to have it in a large directory. For performance reason in a very busy server you may want to move it to another partition because the Postfix internal queues are also on /var/ and those are write heavy. Moving the main mail store to a partition on another physical disk can increase performance on a box that is struggling under I/O issues.

Owning the /var/vmail to Postfix allows Postfix to create new mail directories for new users when the first piece of mail comes in for that user. I recommend setting Postfixadmin to send a welcome message to new users to make sure their .maildir is created.


Gentoo's default logging dumps everything in /var/log/messages which is okay, but sort of a pain in the ass if you're running a mail server. Let's split it out into it's own file. Make these changes to /etc/syslog-ng/syslog-ng.conf

destination mail { file("/var/log/mail.log"); };

filter f_mail { facility(mail); };
filter f_messages { level(info..warn) # this line should already exist
       and not facility(mail); };    # make sure this line is under the above line.

log { source(src); filter(f_mail); destination(mail); };



Again verify the use variables

popmail ~ # emerge -pv courier-authlib

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild     R ] net-libs/courier-authlib-0.55 +berkdb +crypt -debug 
+gdbm -ldap +mysql +pam -postgres 1,959 kB

Config files


#DEFAULT_DOMAIN         domain.tld
MYSQL_DATABASE          postfix
MYSQL_GID_FIELD         '207'
MYSQL_HOME_FIELD        '/var/vmail'
MYSQL_LOGIN_FIELD       username
MYSQL_NAME_FIELD        name
MYSQL_OPT               0
MYSQL_PASSWORD          IheartPostfix
# Uncomment below if you want quota support.
MYSQL_SERVER            localhost
MYSQL_UID_FIELD         '207'
MYSQL_USERNAME          postfix
MYSQL_USER_TABLE        mailbox
# You can also turn off IMAP authentication when a user is
# marked as inactive. Be aware that this will cause webmail auth,
# smtp relay if slaved off courier-authlib, and POP3/IMAP logins to fail.
#MYSQL_WHERE_CLAUSE     active='1'

You'll need to make sure that this line includes authmysql first.


authmodulelist="authmysql authpam"

Socket permissions

You may need to loosen permissons on /var/lib/courier/authdaemon/socket I'd try it on your system first and if you see permission denied errors this is likely the problem.

popmail ~ # chmod +x /var/lib/courier/authdaemon


And finally add courier-authlib to your default runlevel

rc-update add courier-authlib default



Again verify USE flags.

popmail ~ # emerge -pv courier-imap              

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild   R   ] net-mail/courier-imap-4.0.1  +berkdb -debug -fam +gdbm
-ipv6 -nls* (-selinux) 0 kB 


For large virtual systems remember to increase per IP connections in /etc/courier-imap/imapd and any other services you plan to offer to the public. Even on a small system Thunderbird tends to cache several connections to the server. I run my personal mail servers to allow 40 connections from a single IP for IMAP. That seems to work.


Why Greylist?

It's the simplest way to stop significant spam and it uses far less resources than just about any other method. I've been using sqlgrey on multiple servers and it seems to work well so that's what we'll use here.


emerge sqlgrey
echo "POSTGREY_OPTS=\"--delay=30\"" >> /etc/conf.d/postgrey
rc-update add sqlgrey default

Delay Time

I recommend a very small delay time as I've used above. Many webmail sites like Hotmail will attempt to delivery every thirty seconds for the first three minutes. The next retry will be fifteen minutes after the last retry. By using a very small delay you can still provide effective greylisting, but keep the total delay to a minimum.

Server Scripts

rc-update add apache2 default
rc-update add mysql default
rc-update add courier-imapd default
rc-update add courier-pop3d default
rc-update add sqlgrey default
rc-update add postfix default
rc-update add saslauthd default


I have not in the past covered the setup of Postfixadmin itself. Overall their documentation is pretty good and if you read it you should have no problem getting your installation working. However I am working on a minimal setup process that would walk you through getting the basics done.


Here are a couple of weird issues that I ran into while installing Postfix Admin or using it.

Adding Multiple Emails to an Alias

Create an alias pointing to a single address. Now edit the alias again. You'll be able to add multiple email addresses, one per line, to the alias now.

Retrieved from ""

Last modified: Wed, 03 Sep 2008 09:04:00 +0000 Hits: 38,358