PostfixAdmin¶

Inhalt¶

PostfixAdmin 4.0.x
PostgreSQL
Vacation
webbasierte Verwaltung für Domains, Aliases und Mailboxen

Einleitung¶

Dieses HowTo beschreibt die Installation und Konfiguration von PostfixAdmin auf FreeBSD 15+.

PostfixAdmin ist ein webbasiertes Verwaltungswerkzeug für Postfix-Setups mit virtuellen Domains und Benutzern. Es unterstützt unter anderem PostgreSQL als Datenbank-Backend sowie Vacation / Autoresponder. Für FreeBSD ist aber wichtig: Der Port mail/postfixadmin hängt aktuell noch auf einem älteren 3.4-dev-Stand, während Upstream die stabile 4.0-Linie separat pflegt. Dieses HowTo folgt deshalb deinem Ausgangstext und kombiniert den Port mit einem Upstream-Checkout des 4.0-Zweigs. (GitHub)

Voraussetzungen¶

Zu den Voraussetzungen für dieses HowTo siehe bitte: Hosting System

Zusätzlich wird vorausgesetzt:

PostgreSQL ist bereits installiert und erreichbar.
PHP-FPM und ein Webserver wie Apache oder Nginx sind bereits vorhanden.
Der Webserver kann PostfixAdmin unter einer URL wie /postfixadmin ausliefern.
Die veröffentlichte URL /postfixadmin muss auf das Verzeichnis public/ der Anwendung zeigen.
Für dieses Setup wird PostgreSQL als Datenbank-Backend verwendet.

Die offiziellen Installationshinweise nennen genau diese Basis: Webserver, PHP, Datenbank und ein Mapping von /postfixadmin auf das Verzeichnis public/. (GitHub)

Vorbereitungen¶

DNS Records¶

Für dieses HowTo müssen zuvor folgende DNS-Records angelegt werden, sofern sie noch nicht existieren, oder entsprechend geändert werden, sofern sie bereits existieren.

Text Only

mail.example.com.       IN  A       __IPADDR4__
mail.example.com.       IN  AAAA    __IPADDR6__

Gruppen / Benutzer / Passwörter¶

Für dieses HowTo müssen keine zusätzlichen Systemgruppen oder Systembenutzer angelegt werden.

Für dieses HowTo müssen zuvor folgende Passwörter angelegt werden, sofern sie noch nicht existieren, oder entsprechend geändert werden, sofern sie bereits existieren.

Bash

Verzeichnisse / Dateien¶

Für dieses HowTo müssen zuvor folgende Verzeichnisse angelegt werden, sofern sie noch nicht existieren, oder entsprechend geändert werden, sofern sie bereits existieren.

Bash

mkdir -p /usr/local/www/apps

Installation¶

Wir installieren `mail/postfixadmin@php84` und dessen Abhängigkeiten.¶

Der FreeBSD-Port ist aktuell PHP-geflavored. Für dein PHP-8.4-Setup ist deshalb mail/postfixadmin@php84 die saubere Portangabe. In den Portoptionen ist PGSQL die relevante Datenbankoption. (FreshPorts)

Bash

mkdir -p /var/db/ports/mail_postfixadmin
cat <<'EOF' > /var/db/ports/mail_postfixadmin/options
_OPTIONS_READ=postfixadmin-php84-3.4.d.20211018
_FILE_COMPLETE_OPTIONS_LIST=ADDONS DOCS IMAP MYSQL PGSQL SQLITE
OPTIONS_FILE_UNSET+=ADDONS
OPTIONS_FILE_UNSET+=DOCS
OPTIONS_FILE_SET+=IMAP
OPTIONS_FILE_SET+=MYSQL
OPTIONS_FILE_SET+=PGSQL
OPTIONS_FILE_UNSET+=SQLITE

EOF

portmaster -w -B -g -U --force-config mail/postfixadmin@php84 -n

Dienst in `rc.conf` eintragen¶

Nicht erforderlich.

PostfixAdmin ist kein eigener Systemdienst mit rc.d-Skript, sondern eine PHP-Webanwendung hinter Apache oder Nginx. (GitHub)

Upstream-Quellstand `postfixadmin_4.0` ausrollen¶

Upstream empfiehlt für stabile Git-Deployments den Branch postfixadmin_4.0. Seit PostfixAdmin 4.0 muss danach zusätzlich install.sh ausgeführt werden, um Composer und die benötigten Drittbibliotheken lokal zu installieren. (GitHub)

Bash

git clone -o postfixadmin -b postfixadmin_4.0 --depth 1 https://github.com/postfixadmin/postfixadmin.git /usr/local/www/apps/postfixadmin
git -C /usr/local/www/apps/postfixadmin pull --rebase

cd /usr/local/www/apps/postfixadmin

sed -e 's|\(/bin/bash.*\)$|/usr/local\1|' \
    -e 's|/usr/bin/\(.*\)$|/usr/local/bin/\1|g' \
    -i '' /usr/local/www/apps/postfixadmin/install.sh

/usr/local/bin/bash /usr/local/www/apps/postfixadmin/install.sh

Konfiguration¶

Webroot und Schreibrechte¶

Laut offizieller Installationsanleitung soll der Webserver nicht auf das Projektwurzelverzeichnis zeigen, sondern auf public/. Schreibzugriff braucht PostfixAdmin im Normalfall nur auf templates_c; die übrigen Dateien können lesbar bleiben. (GitHub)

Bash

chmod 750 /usr/local/www/apps/postfixadmin/templates_c
chown www:www /usr/local/www/apps/postfixadmin/templates_c

chown -R www:www /usr/local/www/apps/postfixadmin/public

`config.local.php` einrichten¶

Die offizielle Konfiguration sagt klar: config.inc.php nicht direkt ändern. Eigene Einstellungen gehören in config.local.php im PostfixAdmin-Webroot. (GitHub)

Bash

cat <<'EOF' > /usr/local/www/apps/postfixadmin/config.local.php
<?php
$CONF['database_type'] = 'pgsql';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfix';
$CONF['database_password'] = '__PASSWORD_POSTFIX__';
$CONF['database_name'] = 'postfixadmin';
$CONF['encrypt'] = 'ARGON2ID';
$CONF['configured'] = true;
$CONF['default_language'] = 'de';
$CONF['setup_password'] = '__SETUP_HASH__';
$CONF['smtp_server'] = 'localhost';
$CONF['smtp_port'] = '465';
$CONF['smtp_type'] = 'tls';
$CONF['smtp_client'] = 'mail.example.com';
$CONF["admin_email"] = "Support Person <support@example.com>";
$CONF['dovecotpw'] = "/usr/local/sbin/doveadm pw";
if(@file_exists('/usr/local/bin/doveadm')) {
    $CONF['dovecotpw'] = "/usr/local/bin/doveadm pw";
}
$CONF['password_validation'] = array(
    '/.{5}/'                                         => 'password_too_short 5',      # minimum length 5 characters
    '/([a-zA-Z].*){3}/'                              => 'password_no_characters 3',  # must contain at least 3 characters
    '/([0-9].*){2}/'                                 => 'password_no_digits 2',      # must contain at least 2 digits
    '/([!\".,*&^%$£)(_+=\-`\'#@~\[\]\\<>\/].*){1,}/' => 'password_no_special 1', # must contain at least 1 special character
    /*  support a 'callable' value which if it returns a non-empty string will be assumed to have failed, non-empty string should be a PALANG key */
    // 'length_check'                                   => function($password) { if (strlen(trim($password)) < 3) { return 'password_too_short'; } },
);
$CONF['show_password'] = 'YES';
$CONF['page_size'] = '100';
$CONF['default_aliases'] = array (
    'abuse'       => 'abuse@example.com',
    'security'    => 'security@example.com',
    'hostmaster'  => 'hostmaster@example.com',
    'postmaster'  => 'postmaster@example.com',
    'webmaster'   => 'webmaster@example.com',
    'dmarc'       => 'dmarc@example.com'
);
$CONF['aliases'] = '1000';
$CONF['mailboxes'] = '100';
$CONF['maxquota'] = '2048';
$CONF['domain_quota_default'] = '204800';
$CONF['quota'] = 'YES';
$CONF['new_quota_table'] = 'YES';
$CONF['transport'] = 'YES';
$CONF['transport_options'] = array (
    'virtual',  // for virtual accounts
    'local',    // for system accounts
    'relay',    // for backup mx
    'vacation'  // for vacation
);
$CONF['transport_default'] = 'virtual';
$CONF['vacation'] = 'NO';
$CONF['vacation_domain'] = 'autoreply.example.com';
$CONF['special_alias_control'] = 'YES';
$CONF['backup'] = 'YES';
$CONF['sendmail_all_admins'] = 'YES';
$CONF['show_header_text'] = 'YES';
$CONF['header_text'] = ':: Postfix Admin on mail.example.com ::';
$CONF['footer_text'] = 'Return to mail.example.com';
$CONF['footer_link'] = 'https://mail.example.com';
$CONF['emailcheck_localaliasonly'] ='YES';
$CONF['dkim'] = 'YES';
$CONF['dkim_all_admins'] = 'YES';
$CONF['recipient_delimiter'] = "+";
$CONF['used_quotas'] = 'YES';
$CONF['smtp_active_flag'] = 'YES';
?>
EOF
chown www:www /usr/local/www/apps/postfixadmin/config.local.php
chmod 640 /usr/local/www/apps/postfixadmin/config.local.php

Setup-Hash erzeugen und eintragen¶

setup.php wird laut Upstream für Installation und Setup verwendet. Dafür braucht PostfixAdmin einen gültigen setup_password-Hash in config.local.php. (GitHub)

Bash

# Passwort für PostfixAdmin "setup_hash" erzeugen und
# in /var/db/passwords/postfixadmin_setup_hash speichern
install -b -m 0600 /dev/null /var/db/passwords/postfixadmin_setup_hash
openssl rand -hex 64 | openssl passwd -5 -stdin | tr -cd '[[:print:]]' | \
  cut -c 2-17 | tee /var/db/passwords/postfixadmin_setup_hash | xargs -I % \
  php -r "echo password_hash('%', PASSWORD_DEFAULT);" | xargs -I % \
  sed -e "s|__SETUP_HASH__|%|g" -i '' /usr/local/www/apps/postfixadmin/config.local.php

PostgreSQL-Passwort in `config.local.php` eintragen¶

Bash

cat /var/db/passwords/postgresql_user_postfix | xargs -I % \
  sed -e "s|__PASSWORD_POSTFIX__|%|g" -i '' /usr/local/www/apps/postfixadmin/config.local.php

Konfiguration prüfen¶

Vor dem ersten Browser-Setup sollte zumindest geprüft werden, ob die lokale Konfigurationsdatei existiert und die Anwendung vollständig ausgerollt wurde.

Bash

test -f /usr/local/www/apps/postfixadmin/config.local.php && echo OK
test -d /usr/local/www/apps/postfixadmin/public && echo OK
test -d /usr/local/www/apps/postfixadmin/templates_c && echo OK

Datenbanken¶

PostgreSQL-Benutzer `postfix` anlegen¶

Für PostgreSQL reicht hier ein normaler Login-Role-User. Zusätzliche Rechte wie CREATEROLE oder CREATEDB sind für PostfixAdmin selbst nicht nötig. Die offizielle Installationsanleitung verlangt nur Benutzer plus Datenbank. (GitHub)

Bash

# Passwort für PostgreSQL-Benutzer "postfix" erzeugen und
# in /var/db/passwords/postgresql_user_postfix speichern
install -b -m 0600 -o postgres -g postgres /dev/null /var/db/passwords/postgresql_user_postfix
openssl rand -hex 64 | openssl passwd -5 -stdin | tr -cd '[[:print:]]' | \
  cut -c 2-17 | tee /var/db/passwords/postgresql_user_postfix

# PostgreSQL-Benutzer "postfix" mit Passwort anlegen
su -l postgres -c "psql <<'EOF'
\set content `cat /var/db/passwords/postgresql_user_postfix`
DROP ROLE IF EXISTS \"postfix\";
CREATE ROLE \"postfix\";
ALTER ROLE \"postfix\" WITH NOSUPERUSER INHERIT CREATEROLE CREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD :'content';
\unset content
EOF"

PostgreSQL-Datenbank `postfixadmin` für `postfix` anlegen¶

Die offizielle Anleitung zeigt für PostgreSQL genau das Muster „Benutzer anlegen, Datenbank anlegen, Owner setzen“. (GitHub)

Bash

su -l postgres -c "psql <<'EOF'
DROP DATABASE IF EXISTS \"postfixadmin\";
CREATE DATABASE \"postfixadmin\";
ALTER DATABASE \"postfixadmin\" OWNER TO \"postfix\";
EOF"

PostgreSQL-Verbindung als `postfix` testen¶

Bash

psql -h 127.0.0.1 -U postfix -d postfixadmin -c 'SELECT current_user, current_database();'

Datenbankschema initialisieren¶

Im aktuellen Upstream-Setup ist das manuelle Einspielen eines riesigen statischen SQL-Dumps nicht mehr der saubere Primärweg. setup.php ist ausdrücklich für Installation/Setup da, und der Port verweist für Schema-Updates ebenfalls auf den Web-Setup-Weg. Deshalb wird das Schema in diesem HowTo nicht manuell aus einem fest eingebrannten SQL-Dump importiert, sondern im Abschluss über das Web-Setup initialisiert. (GitHub)

Zusatzsoftware¶

Mögliche Zusatzsoftware wird hier installiert und konfiguriert.

Für dieses HowTo ist keine zusätzliche Software erforderlich.

Vacation ist eine PostfixAdmin-Funktion und kein separates Zusatzpaket. (GitHub)

Aufräumen¶

Überflüssige oder temporäre Verzeichnisse und Dateien entsorgen.

Zusatzsoftware Installation¶

Nicht erforderlich.

Zusatzsoftware Konfiguration¶

Nicht erforderlich.

Abschluss¶

Das PostfixAdmin-Setup muss nun im Browser gestartet und abgeschlossen werden.

Voraussetzung dafür ist, dass dein Webserver die URL /postfixadmin auf /usr/local/www/apps/postfixadmin/public abbildet. Genau diesen Aufbau beschreibt die offizielle Installationsanleitung. setup.php ist dabei der vorgesehene Einstieg für Installation und Setup. (GitHub)

Bash

https://mail.example.com/postfixadmin/setup.php

Für spätere Schema-Updates:

Bash

https://mail.example.com/postfixadmin/upgrade.php

Referenzen¶

FreshPorts: mail/postfixadmin — Beschreibung, Flavors, Optionen, pkg-message. (FreshPorts)
FreeBSD Ports Tree: mail/postfixadmin/Makefile — aktueller Portstand 3.4.dev.20211018. (FreeBSD Git)
PostfixAdmin GitHub-README — Stable-Release 4.0.1, Branch postfixadmin_4.0, Hosting-Anforderungen. (GitHub)
PostfixAdmin INSTALL.md — install.sh, Webserver-Mapping auf public/, Datenbankanlage, config.local.php, templates_c. (GitHub)
PostfixAdmin config.inc.php — lokale Overrides gehören in config.local.php. (GitHub)
PostfixAdmin public/setup.php — Setup-Einstieg für Installation und Initialisierung. (GitHub)

PostfixAdmin¶

Inhalt¶

Einleitung¶

Voraussetzungen¶

Vorbereitungen¶

DNS Records¶

Gruppen / Benutzer / Passwörter¶

Verzeichnisse / Dateien¶

Installation¶

Wir installieren mail/postfixadmin@php84 und dessen Abhängigkeiten.¶

Dienst in rc.conf eintragen¶

Upstream-Quellstand postfixadmin_4.0 ausrollen¶

Konfiguration¶

Webroot und Schreibrechte¶

config.local.php einrichten¶

Setup-Hash erzeugen und eintragen¶

PostgreSQL-Passwort in config.local.php eintragen¶

Konfiguration prüfen¶

Datenbanken¶

PostgreSQL-Benutzer postfix anlegen¶

PostgreSQL-Datenbank postfixadmin für postfix anlegen¶

PostgreSQL-Verbindung als postfix testen¶

Datenbankschema initialisieren¶

Zusatzsoftware¶

Aufräumen¶

Zusatzsoftware Installation¶

Zusatzsoftware Konfiguration¶

Abschluss¶

Referenzen¶

Wir installieren `mail/postfixadmin@php84` und dessen Abhängigkeiten.¶

Dienst in `rc.conf` eintragen¶

Upstream-Quellstand `postfixadmin_4.0` ausrollen¶

`config.local.php` einrichten¶

PostgreSQL-Passwort in `config.local.php` eintragen¶

PostgreSQL-Benutzer `postfix` anlegen¶

PostgreSQL-Datenbank `postfixadmin` für `postfix` anlegen¶

PostgreSQL-Verbindung als `postfix` testen¶