PostfixAdmin

PostfixAdmin is a web interface for Postfix used to manage mailboxes, virtual domains and aliases.

Installation

To use PostfixAdmin, you need a working web server setup. You can either choose a web server, that can serve the web application directly (such as Apache HTTP Server), or a setup in which a web server (e.g Nginx) forwards requests to an application server (e.g. UWSGI or php-fpm).

For IMAP functionality, refer to PHP#IMAP.

Next, install the postfixadmin package.

Note: Postfixadmin should only be accessed over TLS (unless accessed directly from the machine running it), as it otherwise exposes passwords and user data.

Configuration

Edit the PostfixAdmin configuration file:

/etc/webapps/postfixadmin/config.local.php

<?php
$CONF['configured'] = true;
// correspond to dovecot maildir path /home/vmail/%d/%u 
$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';
$CONF['database_type'] = 'mysqli';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfix_user';
$CONF['database_password'] = 'hunter2';
$CONF['database_name'] = 'postfix_db';

// globally change all instances of ''change-this-to-your.domain.tld'' 
// to an appropriate value
$CONF['default_aliases'] = array (
    'abuse' => 'abuse@change-this-to-your.domain.tld',
    'hostmaster' => 'hostmaster@change-this-to-your.domain.tld',
    'postmaster' => 'postmaster@change-this-to-your.domain.tld',
    'webmaster' => 'webmaster@change-this-to-your.domain.tld'
);

$CONF['vacation_domain'] = 'autoreply.change-this-to-your.domain.tld';

$CONF['footer_text'] = 'Return to change-this-to-your.domain.tld';
$CONF['footer_link'] = 'http://change-this-to-your.domain.tld';

If installing dovecot and you changed the password scheme in dovecot (to SHA512-CRYPT for example), reflect that with Postfix

/etc/webapps/postfixadmin/config.local.php

$CONF['encrypt'] = 'dovecot:SHA512-CRYPT';

As of dovecot 2, dovecotpw has been deprecated. You will also want to ensure that your config reflects the new binary name.

Note: As of postfixadmin 2.91 this is set correctly by default.

/etc/webapps/postfixadmin/config.local.php

$CONF['dovecotpw'] = "/usr/sbin/doveadm pw";

Note: For this to work it does not suffice to have dovecot installed, it also needs to be configured. See Dovecot#Dovecot configuration.

Hosting

Note: PostfixAdmin needs to be run as its own user and group (i.e. postfixadmin). It is using /etc/webapps/postfixadmin, /var/lib/postfixadmin and /run/postfixadmin for configurations, template caches and (potentially) sockets (respectively)!

Apache

The apache web server can serve dynamic web applications with the help of modules, such as mod_proxy_fcgi or mod_proxy_uwsgi.

php-fpm

Install and configure Apache HTTP Server with php-fpm. Use a pool run as user and group postfixadmin. The socket file should be accessible by the http user and/or group.

Include the following configuration in your Apache HTTP Server configuration (i.e. /etc/httpd/conf/httpd.conf) and restart the web server:

/etc/httpd/conf/postfixadmin.conf

Alias /postfixadmin "/usr/share/webapps/postfixadmin/public"
<Directory "/usr/share/webapps/postfixadmin/public">
    DirectoryIndex index.html index.php
    <FilesMatch \.php$>
        SetHandler "proxy:unix:/run/postfixadmin/postfixadmin.sock|fcgi://localhost/"
    </FilesMatch>
    AllowOverride All
    Options FollowSymlinks
    Require all granted
    SetEnv PHP_ADMIN_VALUE "open_basedir = /tmp/:/usr/share/webapps/postfixadmin:/etc/webapps/postfixadmin/:/var/cache/postfixadmin/templates_c"
</Directory>

Create a pool for postfixadmin and restart php-fpm.service:

/etc/php/php-fpm.d/postfixadmin.conf

[postfixadmin]
user = postfixadmin
group = postfixadmin
listen = /run/postfixadmin/postfixadmin.sock
listen.owner = root
listen.group = http
listen.mode = 0660
pm = ondemand
pm.max_children = 4
php_admin_value['date.timezone'] = Europe/Berlin
php_admin_value['session.save_path'] = /tmp
php_admin_value['open_basedir'] = /tmp/:/usr/share/webapps/postfixadmin/:/etc/webapps/postfixadmin/:/usr/bin/doveadm:/var/cache/postfixadmin

To only allow localhost access to postfixadmin (for heightened security), add this to the previous <Directory> directive:

   Order Deny,Allow
   Deny from all
   Allow from 127.0.0.1

Nginx

Nginx can proxy application servers such as php-fpm and uWSGI, that run a dynamic web application. The following examples describe a folder based setup over a non-default port (for simplicity).

Note: For server entry management in nginx have a look at Nginx#Managing server entries.

Note: Postfixadmin ships a configuration for uWSGI.

php-fpm

Install php-fpm and php-imap. Setup nginx with php-fpm and use a pool run as user and group postfixadmin. The socket file should be accessible by the http user and/or group, but needs to be located below /run/postfixadmin. This can be achieved by adding the following lines.

/etc/php/php-fpm.d/postfixadmin.conf

[postfixadmin]
user = postfixadmin
group = postfixadmin
listen = /run/postfixadmin/postfixadmin.sock
listen.owner = root
listen.group = http
listen.mode = 0660
pm = ondemand
pm.max_children = 4
php_admin_value['date.timezone'] = Europe/Berlin
php_admin_value['session.save_path'] = /tmp
php_admin_value['open_basedir'] = /tmp/:/usr/share/webapps/postfixadmin/:/etc/webapps/postfixadmin/:/usr/bin/doveadm:/var/cache/postfixadmin

You will need to at least activate the imap and mysqli extensions in /etc/php/php.ini. Make sure you also add /var/cache/postfixadmin to open_basedir in your php.ini. Restart php-fpm for all these to take effect.

Add the following configuration for nginx and restart it.

/etc/nginx/sites-available/postfixadmin.conf

    server {
      listen 8081;
      server_name postfixadmin;
      root /usr/share/webapps/postfixadmin/public/;
      index index.php;
      charset utf-8;
     
      access_log /var/log/nginx/postfixadmin-access.log;
      error_log /var/log/nginx/postfixadmin-error.log;
     
      location / {
        try_files $uri $uri/ index.php;
      }
     
      location ~* \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        include fastcgi_params;
        fastcgi_pass unix:/run/postfixadmin/postfixadmin.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
      }
    }

uWSGI

Install uwsgi-plugin-php, create a per-application socket for uWSGI (see UWSGI#Accessibility of uWSGI socket for reference) and activate the uwsgi-secure@postfixadmin.socket unit.

Add the following configuration for nginx and restart nginx.

/etc/nginx/sites-available/postfixadmin.conf

    server {
      listen 8081;
      server_name postfixadmin;
      root /usr/share/webapps/postfixadmin/public/;
      index index.php;
      charset utf-8;
     
      access_log /var/log/nginx/postfixadmin-access.log;
      error_log /var/log/nginx/postfixadmin-error.log;
     
      location / {
        try_files $uri $uri/ index.php;
      }

      # pass all .php or .php/path urls to uWSGI
      location ~ ^(.+\.php)(.*)$ {
        include uwsgi_params;
        uwsgi_modifier1 14;
        uwsgi_pass unix:/run/postfixadmin/postfixadmin.sock;
      }
    }

Setup

Finally, navigate to http://127.0.0.1:80/postfixadmin/setup.php to finish the setup. Generate your setup password hash at the bottom of the page once it is done. Write the hash to the config file

/etc/webapps/postfixadmin/config.local.php

$CONF['setup_password'] = 'yourhashhere';

Now you can create a superadmin account at http://127.0.0.1:80/postfixadmin/setup.php

Tips and tricks

Pacman hook

Sometimes the database needs to be upgraded after a version bump. You will see a message saying 'The PostfixAdmin database layout is outdated' on the login page in such case.

You can set up a hook that runs the needed upgrade.php script automatically via a pacman hook:

/etc/pacman.d/hooks/postfixadmin.hook

[Trigger]
Operation = Install
Operation = Upgrade
Type = Package
Target = postfixadmin

[Action]
Description = Run Postfixadmin upgrade.php to make sure database is up to date
When = PostTransaction
Exec = /usr/bin/runuser -u postfixadmin -- /usr/bin/php /usr/share/webapps/postfixadmin/public/upgrade.php

Troubleshooting

Configuration not found

If you go to yourdomain/postfixadmin/setup.php and the application states, that it is unable to find config.inc.php, add /etc/webapps/postfixadmin to the open_basedir line in /etc/php/php.ini (see PHP#Configuration for reference).

Blank page on access

If you get a blank page check the syntax of the configuration with php -l /etc/webapps/postfixadmin/config.inc.php.