OBSOLETE

This documentation is out of date!

We keep it here in case it may be useful. Please see our blog here about setting up PostfixAdmin on Debian Squeeze.

About Postfixadmin

Postfix Admin is a web-based GUI for setting up mail users for a Postfix+MySQL setup.

It will let you create users and aliases per domain.

This HOWTO goes over install Postfix Admin, Postfix with a MySQL backend and SMTP auth enabled, and Dovecot (for POP3/POP3/IMAP/IMAPS) with a MySQL backend.

While this HOWTO is was tested on Debian Etch, the Postfix/MySQL setup is generic and should work fine on most distributions.

Setting up Postfixadmin

For Debian/Ubuntu there are some third party packages available on sourceforge

Download the .deb and run:

dpkg -i postfixadmin_2.2.0_all.deb

Postfixadmin will be installed in /usr/share/postfixadmin/ the configuration file will be in /etc/postfixadmin/config.inc.php and the following alias is added to the apache configuration in the file /etc/apache2/conf.d/postfixadmin:

Alias /postfixadmin /usr/share/postfixadmin

All the above can be done manually if you do decide to install using the source tarball.

In Centos, you will first need to install Postfix with MySQL support from the Centos Plus repository.  You will find instructions to do that here:

http://wiki.centos.org/AdditionalResources/Repositories/CentOSPlus

Then download the PostfixAdmin tarball from sourceforge and unpack in a web directory.

If your using Debian/Ubuntu be sure you have the "postfix-mysql" package installed, that enables MySQL map support for Postfix.  Use the following command to check if MySQL support is enabled:

# postconf -m
btree
cidr
environ
hash
mysql
nis
proxy
regexp
sdbm
static
tcp
unix

If you don't see mysql listed above install Postfix, SASL2 with MySQL support

apt-get install postfix-mysql postfix-tls libsasl2-modules-sql libsasl2-modules

Configure PostfixAdmin to match your setup (e.g. to make the database passwords match, set your default domain, etc)

Edit the file /usr/share/postfixadmin/config.inc.php and set the following:

vi config.inc.php
[...]
$CONF['configured'] = true;
$CONF['postfix_admin_url'] = 'http://yourdomain.tld/postfixadmin';

$CONF['database_type'] = 'mysql';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfixadmin';
$CONF['database_password'] = 'SecretPassword!';
$CONF['database_name'] = 'postfix';

$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';
$CONF['encrypt'] = 'cleartext';

Take a look at the rest of that file if you need to make more tweaks.  Note the passwords are set to "cleartext" so be sure you are using SSL to encrypt connections to postfixadmin.  Newer versions are adding support for MD5-Crypt so this may change in the future, still a good idea to use https.

You can quickly change the default domain to your own:

replace "change-this-to-your.domain.tld" "yourdomain.com" -- /usr/share/postfixadmin/config.inc.php

Create the database and user in mysql:

shell> mysql -u root -p
mysql> create database postfix;
mysql> grant all privileges on postfix.* to 'postfixadmin'@'localhost' identified by 'SecretPassword!';
mysql> flush privileges;
mysql> \q

Then browse to "https://yourdomain.com/postfixadmin/" or "https://yourip/postfixadmin/". It will prompt you to run Setup. Make sure the Setup Checker says 'OK' for everything.

Remove the setup.php as it recommends.

Then browse to https://yourdomain.com/postfixadmin/admin. You should get prompted. Login with the admin email you registered earlier in the setup page.
From here you can add domains, mailboxes, etc. But Postfix won't see these yet. We need to install Postfix, and configure it.

Add the following to /etc/postfix/main.cf

virtual_alias_maps = mysql:/etc/postfix/mysql_virtual_alias_maps.cf
virtual_gid_maps = static:106
virtual_mailbox_base = /home/vmail
virtual_mailbox_domains = mysql:/etc/postfix/mysql_virtual_domains_maps.cf
virtual_mailbox_maps = mysql:/etc/postfix/mysql_virtual_mailbox_maps.cf
virtual_minimum_uid = 106
virtual_transport = virtual
virtual_uid_maps = static:106

broken_sasl_auth_clients = yes
smtpd_recipient_restrictions =
  permit_mynetworks,
  permit_sasl_authenticated,
  reject_non_fqdn_hostname,
  reject_non_fqdn_sender,
  reject_non_fqdn_recipient,
  reject_unauth_destination,
  reject_unauth_pipelining,
  reject_invalid_hostname
smtpd_sasl_auth_enable = yes
smtpd_sasl_local_domain = $myhostname
smtpd_sasl_security_options = noanonymous

Note: UID/GID 106 may be different on your system. Check your postfix (or vmail) user in /etc/passwd and set accordingly. For example on my server:

# grep postfix /etc/passwd
postfix:x:102:105::/var/spool/postfix:/bin/false
--> uid: 102; gid: 105

Also keep in mind that postfix may complain about not being able to connect to mysql. This is because postfix runs in a chroot by default. If later on when you are testing the setup postfix fails to connect, change all the "hosts = localhost" lines to "hosts = 127.0.0.1" to force postfix to connect via tcp instead of via socket. You can also edit master.cf and allow postfix to run non-chrooted.

Note: the syntax for the following files is based on the postfix mysql_table(5) manual as per http://www.postfix.org/mysql_table.5.html

Create the following files in /etc/postfix/:

mysql_virtual_alias_maps.cf

user = postfix
password = SecretPassword!
hosts = localhost
dbname = postfix
table = alias
select_field = goto
where_field = address

The alternative syntax for that file is:

user = postfix
password = SecretPassword!
hosts = localhost
dbname = postfix
query = SELECT goto FROM alias WHERE address = '%s'

The same can be applied for the rest of these files.

mysql_virtual_domains_maps.cf

user = postfix
password = SecretPassword!
hosts = localhost
dbname = postfix
table = domain
select_field = domain
where_field = domain
additional_conditions = and backupmx = '0' and active = '1'

mysql_virtual_mailbox_maps.cf

user = postfix
password = SecretPassword!
hosts = localhost
dbname = postfix
table = mailbox
select_field = maildir
where_field = username

If you want to be be able to relay mail through your server with SMTP AUTH, setup the following in /etc/postfix/sasl/smtpd.conf:

pwcheck_method: auxprop
mech_list: PLAIN LOGIN
auxprop_plugin: sql
sql_verbose: yes
sql_engine: mysql
sql_hostnames: localhost
sql_user: postfix
sql_passwd: SecretPassword!
sql_database: postfix
sql_select: select password from mailbox where username = '%u@%r'

Create the directory structure, including a directory for the first domain. You'll also want to go into PostfixAdmin and create a 'test' account for the yourdomain.com to match this.

mkdir -p /home/vmail/yourdomain.com/test
chmod -R 770 /home/vmail
chown -R postfix:postfix /home/vmail/

Install Dovecot with MySQL support

apt-get install dovecot-common dovecot-imapd dovecot-pop3d

Configure the Dovecot/MySQL setup in /etc/dovecot/dovecot-mysql.conf using these settings:

driver = mysql
connect = dbname=postfix user=postfixadmin host=localhost password=SecretPassword!
default_pass_scheme = PLAIN
password_query = SELECT password FROM mailbox WHERE username = '%u'
user_query = SELECT maildir, 106 AS uid, 106 AS gid FROM mailbox WHERE username  = '%u'

Caveat: Newer versions of dovecot might require using MD5-CRYPT instead of PLAIN for the default_pass_scheme. If you find that you cannot authenticate using imap/pop but are using the correct username and password, try changing to MD5-CRYPT.

Then configure Dovecot to use MySQL by setting these options in /etc/dovecot/dovecot.conf:

protocols = imap imaps pop3 pop3s
disable_plaintext_auth = no
log_timestamp = "%Y-%m-%d %H:%M:%S "
mail_location = maildir:/home/vmail/%d/%n
mail_access_groups = mail
first_valid_uid = 106
first_valid_gid = 106
protocol imap {
}
  
protocol pop3 {
  pop3_uidl_format = %08Xu%08Xv
}
auth default {
  mechanisms = digest-md5 plain
  passdb sql {
    args = /etc/dovecot/dovecot-mysql.conf
  }
  userdb sql {
    args = /etc/dovecot/dovecot-mysql.conf
  }
  user = root
}

Restart Dovecot and Postfix and test it all out.

More information about the dovecot configuration can be found in http://wiki.dovecot.org/AuthDatabase/SQL and http://wiki.dovecot.org/Variables

At the end of it, you should be able to add new domains, mailboxes and aliases using PostfixAdmin and have it all work properly, including SMTP authentication. Note that you don't need saslauthd for SMTP authentication to work.