Managing Mail Domains with PostfixAdmin

PostfixAdmin is a web interface for managing the MySQL database that Postfix and Dovecot query for virtual domains, mailboxes, and aliases. Without it, you'd manage mail accounts by running SQL queries directly. PostfixAdmin provides domain management, mailbox creation with quota settings, alias configuration, and domain-level alias forwarding. This post covers installing PostfixAdmin on Gentoo with Apache and deploying it as a virtual host.

Prerequisites

• Postfix and Dovecot are configured for virtual mailboxes
• MySQL is running with the mailserver database
• Apache is running with PHP-FPM
• TLS certificates are available

Setting USE Flags

cat > /etc/portage/package.use/postfixadmin << 'EOF'
www-apps/postfixadmin mysql vhosts
EOF

The vhosts flag enables deployment via webapp-config.

Installing PostfixAdmin

emerge -av www-apps/postfixadmin

Creating the Database Tables

PostfixAdmin creates its own database tables in the mailserver database on first setup. Create the PostfixAdmin database user with write access:

mysql << 'EOF'
GRANT ALL PRIVILEGES ON mailserver.* TO 'mailadmin'@'localhost' IDENTIFIED BY 'mailadmin-db-password';
FLUSH PRIVILEGES;
EOF

This user needs full access because PostfixAdmin creates, modifies, and deletes domain, mailbox, and alias records.

Deploying with webapp-config

Deploy PostfixAdmin to a virtual host directory:

webapp-config -I -h mailadmin.example.com -d / postfixadmin $(qatom -F "%{PV}" $(portageq best_visible / www-apps/postfixadmin))

This installs PostfixAdmin to /var/www/mailadmin.example.com/htdocs/.

Configuring PostfixAdmin

PostfixAdmin's configuration file is at the deployment root. Create or edit /var/www/mailadmin.example.com/htdocs/config.local.php:

<?php
$CONF['configured'] = true;

// Database
$CONF['database_type'] = 'mysqli';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'mailadmin';
$CONF['database_password'] = 'mailadmin-db-password';
$CONF['database_name'] = 'mailserver';

// Setup password (bcrypt hash)
$CONF['setup_password'] = 'your-setup-password-hash';

// Domain defaults
$CONF['default_aliases'] = array(
    'abuse'      => 'postmaster@example.com',
    'hostmaster' => 'postmaster@example.com',
    'postmaster' => 'postmaster@example.com',
    'webmaster'  => 'postmaster@example.com'
);

// Mailbox settings
$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';
$CONF['maildir_name_struc'] = 'Maildir/';

// Quota (in MB, 0 = unlimited)
$CONF['maxquota'] = 0;
$CONF['quota'] = 'YES';
$CONF['used_quotas'] = 'YES';

// Password scheme (matches Dovecot)
$CONF['encrypt'] = 'dovecot:SHA512-CRYPT';
$CONF['dovecotpw'] = '/usr/bin/doveadm pw -s SHA512-CRYPT';

// Allowed domains
$CONF['domain_limit'] = 0;  // unlimited
$CONF['alias_limit'] = 0;   // unlimited

// Footer
$CONF['show_footer_text'] = 'NO';

// Logging
$CONF['logging'] = 'YES';
?>

Key Settings

$CONF['encrypt'] = 'dovecot:SHA512-CRYPT' — passwords are hashed using Dovecot's SHA512-CRYPT scheme. This means PostfixAdmin calls doveadm pw to hash passwords, ensuring compatibility with Dovecot's authentication.

$CONF['domain_path'] = 'YES' — mailboxes are stored under domain-specific directories: /var/vmail/example.com/user/Maildir/.

$CONF['default_aliases'] — when a new domain is added, these aliases are created automatically. RFC 5321 requires postmaster@domain to be deliverable.

Generating the Setup Password

Generate the setup password hash by navigating to:

https://mailadmin.example.com/setup.php

Enter a setup password and PostfixAdmin will display the hash. Copy it into the $CONF['setup_password'] line in the config file.

Configuring the Apache Virtual Host

Create /etc/apache2/vhosts.d/mailadmin.example.com.conf:

<VirtualHost *:80>
    ServerName mailadmin.example.com

    DocumentRoot /var/www/mailadmin.example.com/htdocs/public

    # Trust reverse proxy headers
    SetEnvIf X-Forwarded-Proto "https" HTTPS=on

    <Directory /var/www/mailadmin.example.com/htdocs/public>
        Require all granted
        AllowOverride All
        Options FollowSymLinks
    </Directory>

    ErrorLog /var/log/apache2/mailadmin.example.com_error.log
    CustomLog /var/log/apache2/mailadmin.example.com_access.log combined
</VirtualHost>

Note: newer versions of PostfixAdmin serve from the public/ subdirectory.

Restart Apache:

apache2ctl configtest
rc-service apache2 restart

Running the Setup

Navigate to https://mailadmin.example.com/setup.php and:

1. Verify all requirements are met (database connection, PHP extensions)
2. Enter the setup password to create the admin account
3. Create a superadmin email address and password

PostfixAdmin will create all necessary database tables in the mailserver database.

Adding Domains and Mailboxes

Adding a Domain

1. Log in to PostfixAdmin with the superadmin account
2. Go to Domain List > New Domain
3. Enter the domain name (e.g., example.com)
4. Set mailbox limits and quota defaults
5. Click Add Domain

PostfixAdmin creates the domain entry and the default aliases (abuse, hostmaster, postmaster, webmaster).

Creating a Mailbox

1. Go to Virtual List > Add Mailbox
2. Enter the username (local part, e.g., user)
3. Select the domain
4. Set the password
5. Optionally set a quota
6. Click Add Mailbox

The mailbox is immediately available. Postfix can deliver to it and Dovecot can authenticate it.

Creating Aliases

1. Go to Virtual List > Add Alias
2. Enter the alias address (e.g., info@example.com)
3. Enter the destination address (e.g., user@example.com)
4. Click Add Alias

Domain Aliases

If example.org should accept mail for all the same addresses as example.com:

1. Go to Domain List > Add Domain Alias
2. Select example.org as the alias domain
3. Select example.com as the target domain
4. Click Add

Mail to user@example.org will be delivered to user@example.com's mailbox.

Testing the Setup

Verify Database Tables

mysql mailserver -e "SHOW TABLES;"

You should see tables including domain, mailbox, alias, and alias_domain.

Verify a Mailbox Exists

mysql mailserver -e "SELECT username, domain, maildir FROM mailbox LIMIT 5;"

Test Postfix Lookups

postmap -q example.com mysql:/etc/postfix/mysql-virtual-domains.cf
postmap -q user@example.com mysql:/etc/postfix/mysql-virtual-mailboxes.cf

Both should return results if the domain and mailbox exist.

Test Dovecot Authentication

doveadm auth test user@example.com password

Send a Test Email

echo "Test message body" | mail -s "PostfixAdmin test" user@example.com

Check the mailbox:

ls /var/vmail/example.com/user/Maildir/new/

If a file appears, delivery is working end-to-end.

Command-Line Management

PostfixAdmin includes a CLI tool for managing domains and mailboxes without the web interface. This is useful for scripting and automation.

Adding a Domain via CLI

php /var/www/mailadmin.example.com/htdocs/scripts/postfixadmin-cli.php domain add example.com

Creating a Mailbox via CLI

php /var/www/mailadmin.example.com/htdocs/scripts/postfixadmin-cli.php mailbox add user@example.com \
  --password "secure-password" --password2 "secure-password" --name "User Name" --active 1

Viewing Domain Details

php /var/www/mailadmin.example.com/htdocs/scripts/postfixadmin-cli.php domain view example.com

Creating a Superadmin

php /var/www/mailadmin.example.com/htdocs/scripts/postfixadmin-cli.php admin add admin@example.com \
  --password "admin-password" --password2 "admin-password" --superadmin 1 --active 1

The CLI tool communicates directly with the database using the same config.local.php configuration, so it respects all password hashing and domain settings.

Backing Up PostfixAdmin Data

PostfixAdmin stores all data in MySQL. Back up the mailserver database regularly:

mysqldump mailserver > /var/backups/mailserver-$(date +%Y%m%d).sql

The critical tables are domain, mailbox, alias, and alias_domain. The configuration file (config.local.php) should also be backed up since it contains the database credentials and password scheme settings.

Securing PostfixAdmin

Restrict Access

PostfixAdmin should only be accessible to administrators. If it's behind a reverse proxy, restrict access by IP:

<Directory /var/www/mailadmin.example.com/htdocs/public>
    Require ip 192.168.1.0/24
</Directory>

Remove setup.php Access

After initial setup, block access to the setup page:

<Location /setup.php>
    Require all denied
</Location>

Lock Down the Installer Directory

PostfixAdmin ships with an installer/ directory. Remove access to it after setup:

chmod 0400 -R /var/www/mailadmin.example.com/htdocs/installer/

Password Policy

PostfixAdmin enforces a minimum password length by default. Configure it in config.local.php:

$CONF['password_validation'] = '/^.{8,}/';

This regex requires at least 8 characters. Adjust the pattern if you need stronger requirements (e.g., requiring mixed case or special characters).

Summary

After completing these steps:

• PostfixAdmin provides a web interface for managing virtual domains, mailboxes, and aliases
• Passwords are hashed with SHA512-CRYPT compatible with Dovecot
• Default aliases (postmaster, abuse, hostmaster, webmaster) are created automatically
• Domain aliases forward entire domains to a primary domain
• Quotas can be set per-mailbox and per-domain
• Postfix and Dovecot read directly from the PostfixAdmin-managed database

The next step is Roundcube webmail for users to access their email through a browser.