Difference between revisions of "PostfixAdmin"

From ArchWiki
Jump to navigation Jump to search
m (Touch up and unify apache and nginx php-fpm config)
m (Note for PHP7.4, more readable)
 
(5 intermediate revisions by 4 users not shown)
Line 32: Line 32:
 
// globally change all instances of ''change-this-to-your.domain.tld''  
 
// globally change all instances of ''change-this-to-your.domain.tld''  
 
// to an appropriate value
 
// to an appropriate value
 +
$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';
 +
 
</nowiki>}}
 
</nowiki>}}
  
Line 41: Line 53:
  
 
As of dovecot 2, dovecotpw has been deprecated.  You will also want to ensure that your config reflects the new binary name.
 
As of dovecot 2, dovecotpw has been deprecated.  You will also want to ensure that your config reflects the new binary name.
 +
 +
{{Note|As of postfixadmin 2.91 this is set correctly by default.}}
  
 
{{hc|/etc/webapps/postfixadmin/config.local.php|<nowiki>
 
{{hc|/etc/webapps/postfixadmin/config.local.php|<nowiki>
Line 70: Line 84:
 
     DirectoryIndex index.html index.php
 
     DirectoryIndex index.html index.php
 
     <FilesMatch \.php$>
 
     <FilesMatch \.php$>
         SetHandler "proxy:unix:/run/php-fpm/postfixadmin.sock|fcgi://localhost/"
+
         SetHandler "proxy:unix:/run/postfixadmin/postfixadmin.sock|fcgi://localhost/"
 
     </FilesMatch>
 
     </FilesMatch>
 
     AllowOverride All
 
     AllowOverride All
Line 85: Line 99:
 
user = postfixadmin
 
user = postfixadmin
 
group = postfixadmin
 
group = postfixadmin
listen = /run/php-fpm/postfixadmin.sock
+
listen = /run/postfixadmin/postfixadmin.sock
 
listen.owner = http
 
listen.owner = http
 
listen.group = http
 
listen.group = http
Line 91: Line 105:
 
pm.max_children = 4
 
pm.max_children = 4
 
</nowiki>}}
 
</nowiki>}}
 +
 +
{{Note|If using php7.4, change the settings to the following:
 +
{{hc|/etc/php/php-fpm.d/postfixadmin.conf|<nowiki>
 +
[postfixadmin]
 +
user = postfixadmin
 +
group = postfixadmin
 +
listen = /run/postfixadmin/postfixadmin.sock
 +
listen.acl_users = http
 +
listen.acl_groups = http
 +
pm = ondemand
 +
pm.max_children = 4
 +
</nowiki>}}
 +
Then override the default tmpfiles rule creating the {{ic|/run/postfixadmin}} directory :
 +
cp /usr/lib/tmpfiles.d/postfixadmin.conf /etc/tmpfiles.d/
 +
And append the following rule to it :
 +
{{hc|/etc/tmpfiles.d/postfixadmin.conf|<nowiki>
 +
...
 +
a+ %t/postfixadmin - - - - group:root:rwx
 +
</nowiki>}}
 +
Then reboot.
 +
}}
  
 
To only allow localhost access to postfixadmin (for heightened security), add this to the previous {{ic|<Directory>}} directive:
 
To only allow localhost access to postfixadmin (for heightened security), add this to the previous {{ic|<Directory>}} directive:
Line 111: Line 146:
 
user = postfixadmin
 
user = postfixadmin
 
group = postfixadmin
 
group = postfixadmin
listen = /run/php-fpm/postfixadmin.sock
+
listen = /run/postfixadmin/postfixadmin.sock
 
listen.owner = http
 
listen.owner = http
 
listen.group = http
 
listen.group = http
Line 117: Line 152:
 
pm.max_children = 4
 
pm.max_children = 4
 
</nowiki>}}
 
</nowiki>}}
 +
 +
{{Note|If using php7.4, change the settings to the following:
 +
{{hc|/etc/php/php-fpm.d/postfixadmin.conf|<nowiki>
 +
[postfixadmin]
 +
user = postfixadmin
 +
group = postfixadmin
 +
listen = /run/postfixadmin/postfixadmin.sock
 +
listen.acl_users = http
 +
listen.acl_groups = http
 +
pm = ondemand
 +
pm.max_children = 4
 +
</nowiki>}}
 +
Then override the default tmpfiles rule creating the {{ic|/run/postfixadmin}} directory :
 +
cp /usr/lib/tmpfiles.d/postfixadmin.conf /etc/tmpfiles.d/
 +
And append the following rule to it :
 +
{{hc|/etc/tmpfiles.d/postfixadmin.conf|<nowiki>
 +
...
 +
a+ %t/postfixadmin - - - - group:root:rwx
 +
</nowiki>}}
 +
Then reboot.
 +
}}
  
 
You will need to at least activate the {{ic|imap}} and {{ic|mysqli}} extensions in {{ic|/etc/php/php.ini}}. Make sure you also add {{ic|/var/cache/postfixadmin}} to [[ic|open_basedir]] in your php.ini. Restart [[php-fpm]] for all these to take effect.
 
You will need to at least activate the {{ic|imap}} and {{ic|mysqli}} extensions in {{ic|/etc/php/php.ini}}. Make sure you also add {{ic|/var/cache/postfixadmin}} to [[ic|open_basedir]] in your php.ini. Restart [[php-fpm]] for all these to take effect.

Latest revision as of 14:30, 3 December 2019

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

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

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
$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 config 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's using /etc/webapps/postfixadmin, /var/lib/postfixadmin and /run/postfixadmin for configurations, template caches and (potentially) sockets (respectively)!

Apache

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

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/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 = http
listen.group = http
pm = ondemand
pm.max_children = 4
Note: If using php7.4, change the settings to the following:
/etc/php/php-fpm.d/postfixadmin.conf
[postfixadmin]
user = postfixadmin
group = postfixadmin
listen = /run/postfixadmin/postfixadmin.sock
listen.acl_users = http
listen.acl_groups = http
pm = ondemand
pm.max_children = 4

Then override the default tmpfiles rule creating the /run/postfixadmin directory :

cp /usr/lib/tmpfiles.d/postfixadmin.conf /etc/tmpfiles.d/

And append the following rule to it :

/etc/tmpfiles.d/postfixadmin.conf
...
a+ %t/postfixadmin - - - - group:root:rwx

Then reboot.

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/postfixadmin.conf
[postfixadmin]
user = postfixadmin
group = postfixadmin
listen = /run/postfixadmin/postfixadmin.sock
listen.owner = http
listen.group = http
pm = ondemand
pm.max_children = 4
Note: If using php7.4, change the settings to the following:
/etc/php/php-fpm.d/postfixadmin.conf
[postfixadmin]
user = postfixadmin
group = postfixadmin
listen = /run/postfixadmin/postfixadmin.sock
listen.acl_users = http
listen.acl_groups = http
pm = ondemand
pm.max_children = 4

Then override the default tmpfiles rule creating the /run/postfixadmin directory :

cp /usr/lib/tmpfiles.d/postfixadmin.conf /etc/tmpfiles.d/

And append the following rule to it :

/etc/tmpfiles.d/postfixadmin.conf
...
a+ %t/postfixadmin - - - - group:root:rwx

Then reboot.

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 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: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.