Jump to content

# PostfixAdmin

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[broken link: invalid section].

## 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;
            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 categories:

- Pages with broken section links
- Pages or sections flagged with Template:Expansion

PostfixAdmin
Add topic