PostfixAdmin - ArchWiki

# PostfixAdmin

From ArchWiki
Jump to navigation Jump to search

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), 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

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: in-code comments (Discuss in Talk:PostfixAdmin#)

Edit the PostfixAdmin configuration file:

    /etc/webapps/postfixadmin/config.local.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

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.

    /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's 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 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 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/php-fpm/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/php-fpm/postfixadmin.sock
     listen.owner = http
     listen.group = http
     pm = ondemand
     pm.max_children = 4

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/www.conf

     [postfixadmin]
     user = postfixadmin
     group = postfixadmin
     listen = /run/php-fpm/postfixadmin.sock
     listen.owner = http
     listen.group = http
     pm = ondemand
     pm.max_children = 4

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 `postfixadmin@uwsgi-secure.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

## 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 or sections flagged with Template:Style
- Pages or sections flagged with Template:Expansion