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.
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' => '[email protected]',
'hostmaster' => '[email protected]',
'postmaster' => '[email protected]',
'webmaster' => '[email protected]'
);
$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.
/etc/webapps/postfixadmin/config.local.php
$CONF['dovecotpw'] = "/usr/sbin/doveadm pw";
Hosting
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).
- 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. 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;
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 [email protected] 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.