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
).
Note
IMAP functionality is no longer supported by Arch Linux, the IMAP php package is no longer packaged.
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, globally change all instances of
change-this-to-your.domain.tld
to an appropriate value:
/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';

$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 configuration 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#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
This article or section needs expansion.
Reason:
Apache section needs
uWSGI
example. (Discuss in
Talk:PostfixAdmin
)
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
.
PostfixAdmin ships a configuration for
uWSGI
.
php-fpm
Install
php-fpm
and
php-imap
AUR
. 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
imap
,
pdo_mysql
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;
        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/postfixadmin/setup.php
if having used Apache or
http://127.0.0.1:8081/setup.php
for Nginx  to finish the setup. Generate your setup password hash at the bottom of the page once it is done. Write the hash to the configuration file
/etc/webapps/postfixadmin/config.local.php
$CONF['setup_password'] = 'yourhashhere';
Now you can create a superadmin account at
http://127.0.0.1/postfixadmin/setup.php
if having used Apache or
http://127.0.0.1:8081/setup.php
for Nginx.
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
.