#Cube: postfix
Postfix is the MTA of the platform. It accepts mail for every virtual domain, looks addresses up in the mail database, hands the message to Dovecot over LMTP, signs it with OpenDKIM, rewrites forwarded senders through PostSRSd and applies the anti-abuse rules stored in the database.
┌──────────────┐ SQL maps ┌──────────────────┐smtp ──▶│ smtpd │──────────────▶│ mail database │submission│ (25/587/465)│ │ domains, boxes, │ └──────┬───────┘ │ aliases, policy │ │ milter └──────────────────┘ ▼ ┌──────────────┐ BCC copy ┌──────────────────┐ │ opendkim │──────────────▶│ hook runner │ └──────┬───────┘ └──────────────────┘ │ queue ▼ ┌──────────────┐ unix socket ┌──────────────────┐ │ lmtp client │──────────────▶│ Dovecot │ └──────────────┘ └──────────────────┘ │ outbound (SRS via socketmap, relays per route) ▼ internetIn the panel: Mail → Relays, Hooks and the Postfix settings page. Every write there is a task.
#Configuration
[postfix]config_dir = "/aegis/config/postfix"data_dir = "/aegis/data/postfix"queue_dir = "/aegis/data/postfix/queue"log_file = "/aegis/logs/postfix/mail.log"user = "postfix" # account the daemons drop to[apps.postfix]database = "pgsql" # pgsql | mysql | sqlitecompatibility_level = "3.11"inet_protocols = "ipv4"message_size_limit = 52428800relayhost = "" # global smarthost, per-relay routes winsmtp_bind_address = "" # global source addresshooks_user = "nobody" # account the hook pipe runs as[mail]hostname = "" # myhostname; empty uses setup.hostnamedomain = "" # mydomain; empty uses the primary domainvmail_uid = 5000vmail_gid = 5000vmail_base = "/aegis/data/mail"[mail.database]host = "127.0.0.1"user = "aegis_mail"password = "" # generated once, written to server.tomlname = "aegis_mail"sqlite_path = "/aegis/data/mail/mail.sqlite3"[mail.postsrsd]enabled = trueforward_port = 10001 # socketmap port Postfix asks for "forward"| Key | Default | Meaning |
|---|---|---|
postfix.config_dir | /aegis/config/postfix | main.cf, master.cf, maps, security, hooks |
postfix.data_dir | /aegis/data/postfix | data_directory |
postfix.queue_dir | …/postfix/queue | queue and pid/master.pid |
postfix.log_file | /aegis/logs/postfix/mail.log | maillog_file, written via postlogd |
postfix.user | postfix | daemons run as this account; SASL socket owner |
apps.postfix.database | pgsql | backend of the mail database and its maps |
apps.postfix.compatibility_level | 3.11 | Postfix compatibility setting |
apps.postfix.inet_protocols | ipv4 | ipv4, ipv6 or all |
apps.postfix.message_size_limit | 52428800 | 50 MB per message |
apps.postfix.relayhost | empty | global smarthost for everything unrouted |
apps.postfix.smtp_bind_address | empty | global outbound source address |
apps.postfix.hooks_user | nobody | account the aegis-hooks pipe runs as |
mail.hostname | empty | myhostname in the banner |
mail.domain | empty | mydomain and the SRS domain |
mail.vmail_uid, mail.vmail_gid | 5000 | numeric owner of maildirs |
mail.vmail_base | /aegis/data/mail | root of the maildir tree |
mail.database.* | see above | connection details for the SQL maps |
mail.postsrsd.enabled | true | render SRS maps when PostSRSd answers |
mail.postsrsd.forward_port | 10001 | socketmap port of PostSRSd |
The certificate is resolved through the ssl module for mail.hostname; it is not a key here.
#Files
<postfix.config_dir>/├── main.cf every parameter, rendered├── master.cf services; relay and hook blocks appended├── maps/ SQL lookup maps (see schema.md)│ ├── domains.cf virtual_mailbox_domains│ ├── mailboxes.cf virtual_mailbox_maps│ ├── aliases.cf virtual_alias_maps + catch-all│ ├── transport.cf transport_maps│ ├── relocated.cf relocated_maps│ ├── sender_bcc.cf sender_bcc_maps│ ├── recipient_bcc.cf recipient_bcc_maps│ ├── sender_login.cf smtpd_sender_login_maps│ ├── tls_policy.cf smtp_tls_policy_maps│ └── quota.cf reference only├── security/ compiled from aegis_security_rules│ ├── header_checks header_checks = regexp:…│ ├── body_checks body_checks = regexp:…│ ├── sender_checks check_sender_access│ └── helo_checks check_helo_access└── hooks/ ├── runner.py executes the hooks ├── hooks.json enabled hooks and local domains ├── recipient_bcc inbound match map (regexp) ├── sender_bcc outbound match map (regexp) └── transport synthetic hook addresses → pipe service<postfix.data_dir>/ data_directory<postfix.queue_dir>/ queue, and pid/master.pid<postfix.log_file> maillog_file (via postlogd)#First run: what configure does
configured backend (see schema.md). The password is generated once and written to config/server.toml.
pgsql: / mysql: / sqlite: parameters.
aegis_security_rules into the check files and thesmtpd_*_restrictions lists.
hooks.json and the three hook maps, andadds the pipe service to master.cf.
appended.
postfix check, then start when the master is not running.Every step is idempotent: files are rewritten only when their content changed.
#Commands
aegis cubes postfix configure # every step aboveaegis cubes postfix validate # postfix -c … checkaegis cubes postfix reload # postfix -c … reloadaegis cubes postfix start|stop|restart|statusaegis cubes postfix expose # paths, backend, map count, published toolsGroups:
| Group | What it manages | Details |
|---|---|---|
relays | outbound source addresses and routes | postfix-relays.md |
security | header/body/sender/helo/rbl rules | below |
hooks | scripts and webhooks per message | postfix-hooks.md |
#main.cf in plain words
The file is generated, but every value comes from configuration or the database, so it is safe to read. The interesting groups:
| Parameter | Meaning here |
|---|---|
myhostname, mydomain, myorigin | identity announced in the banner, default mail.hostname and mail.domain |
mydestination | only localhost; every real domain is virtual |
virtual_mailbox_domains | SQL: aegis_domains, active only |
virtual_mailbox_maps | SQL: aegis_mailboxes → maildir |
virtual_alias_maps | SQL: aliases, forwards and catch-all (one UNION query) |
virtual_transport | lmtp:unix:<dovecot lmtp socket> |
virtual_uid_maps, virtual_gid_maps | the numeric mail uid/gid (5000) |
smtpd_tls_* | certificate from the ssl module, may for port 25, encrypt for submission |
smtpd_sasl_* | Dovecot SASL socket, AUTH only after STARTTLS |
smtpd_relay_restrictions | permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination |
smtpd_sender_restrictions | reject_sender_login_mismatch before the permits |
smtpd_milters | OpenDKIM on 127.0.0.1:8891, milter_default_action = accept |
relayhost, smtp_bind_address | global fallback, overridden per relay |
sender_canonical_maps | socketmap:…:forward (SRS) when PostSRSd answers |
recipient_canonical_maps | socketmap:…:reverse (SRS) |
maillog_file | <postfix.log_file>; needs postlog in master.cf |
#master.cf
| Service | Purpose |
|---|---|
smtp (25) | inbound mail, opportunistic TLS, AUTH after STARTTLS |
submission (587) | clients, TLS required |
smtps (465) | clients, implicit TLS |
lmtp (unix) | delivery to Dovecot |
smtp (unix) | outbound, default source address |
aegis-<relay> | one per active relay, with its own bind/helo |
aegis-hooks | pipe service that runs the hook runner |
postlog | logging for maillog_file |
No service is chrooted. The queue, the Dovecot sockets, the SQL maps and the key files all live outside the queue directory, so a chroot would hide them; a chrooted smtpd cannot see /aegis/run/dovecot/auth-client.
#Security rules
Rules live in aegis_security_rules and are compiled on every configure:
kind | Compiled into | Restriction |
|---|---|---|
header | security/header_checks | header_checks = regexp:… |
body | security/body_checks | body_checks = regexp:… |
sender | security/sender_checks | check_sender_access in smtpd_sender_restrictions |
helo | security/helo_checks | check_helo_access in smtpd_helo_restrictions |
rbl | — | reject_rbl_client <zone> in smtpd_client_restrictions |
Actions: reject, defer, discard, warn. permit_mynetworks and permit_sasl_authenticated always come first, so local and authenticated clients are never caught by a rule.
# refuse a headeraegis cubes postfix security add header 'X-Spam-Flag: YES' --action reject --message 'Spam refused'# block a sender domain (regexp)aegis cubes postfix security add sender '@spam\\.example$' --action reject# reject clients listed in a DNS blocklistaegis cubes postfix security add rbl zen.spamhaus.org# defer instead of reject, with a lower priority numberaegis cubes postfix security add body 'viagra' --action defer --priority 20# what is compiled right nowaegis cubes postfix security listaegis cubes postfix security remove 3Checking what Postfix will read:
cat /aegis/config/postfix/security/header_checkspostconf -c /aegis/config/postfix -h header_checks smtpd_client_restrictionspostmap -q 'Subject: spam' regexp:/aegis/config/postfix/security/header_checks#TLS
smtpd_tls_cert_file / smtpd_tls_key_file come from the sslmodule — a Let's Encrypt certificate when one exists for the mail hostname, otherwise the local one. Port 25 is may, submission and smtps are encrypt.
mail tls set <domain> encrypt|secure|verify, which feeds smtp_tls_policy_maps.
openssl s_client -starttls smtp -connect 127.0.0.1:587 -servername mail.example.com </dev/null | openssl x509 -noout -subject -dates#Logs and troubleshooting
mail.log is written by Postfix itself (maillog_file), not by syslog.
| Symptom | Cause | Fix |
|---|---|---|
TLS has been selected, but TLS support is not compiled in | built with the old -DHAS_SSL | build.toml must use -DUSE_TLS, then rebuild |
SASL support is not compiled in | missing -DUSE_SASL_AUTH | add it and rebuild |
SASL: Connect to Dovecot auth socket … failed | chroot or wrong socket path | chroot = n and check dovecot.sasl_socket |
fatal: maillog_file … does not match any prefix | no maillog_file_prefixes | rendered by the template; check it is present |
fatal: the Postfix mail system is already running | start-fg when a master runs | aegis cubes postfix status first |
tcp lookup error on every recipient | PostSRSd is down but maps are rendered | aegis cubes postfix configure after starting it |
| mail queued but never delivered | LMTP socket missing | ls -l /aegis/run/dovecot/lmtp, then aegis cubes dovecot configure |
cannot execute postconf | rpath missing on build | AUXLIBS must carry -Wl,-rpath,… |
tail -f /aegis/logs/postfix/mail.logaegis cubes postfix validate/aegis/bin/mailqMAIL_CONFIG=/aegis/config/postfix postqueue -paegis exports MAIL_CONFIG for every published wrapper, so /aegis/bin/mailq and /aegis/bin/postconf already point at this instance instead of the compiled-in default.
#Build flags that matter
"CCARGS=… -DUSE_TLS -DUSE_SASL_AUTH … -DHAS_PGSQL -DHAS_MYSQL -DHAS_SQLITE …""AUXLIBS=… -lssl -lcrypto … -Wl,-rpath,{lib:openssl}/lib …"Postfix 3.9 renamed -DHAS_SSL to -DUSE_TLS; with the old flag smtpd builds without TLS and says so in the log. The rpath is there because Postfix re-execs its own tools (postlog runs postconf) with a sanitised environment, so LD_LIBRARY_PATH does not survive — and makedefs refuses to build when it is set.
#expose
aegis cubes postfix exposecube postfixinstalled /aegis/apps/mail/postfix/3.11configuration /aegis/config/postfixstate running pid 767677pid 767677log /aegis/logs/postfix/mail.logconfig /aegis/config/postfix/main.cfqueue /aegis/data/postfix/queuedatabase pgsql:aegis_mailmaps 10published /aegis/bin/postfix /aegis/bin/postconf /aegis/bin/mailq