Jump to content
From ArchWiki

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#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-imapAUR. 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 `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`.

Categories:

- Mail server
- Web applications

Hidden category:

- Pages or sections flagged with Template:Expansion