#Postfix
The Postfix cube owns the MTA and the database behind it. It renders main.cf and master.cf, the SQL lookup maps in maps/ (mode 0640, root:postfix, because they carry the database password), the hook runner and BCC maps in hooks/, and the compiled check files in security/. It also creates the mail role, database and schema on the first configure, using the backend selected by apps.postfix.database (pgsql, mysql or sqlite). The queue and data directories live under postfix.data_dir and postfix.queue_dir, and the mail log under postfix.log_file. The daemon runs as the keeper service aegis-postfix with postfix -c <config_dir> start-fg.
configure has a fixed order: bootstrap the database, render the maps, render the security and hook files, then main.cf and master.cf. Every command that changes a row re-renders and then reloads (or restarts) only when the master is already running; it never starts a stopped daemon behind your back. Because that re-render repeats the bootstrap step, the reported detail starts with role aegis_mail, schema in aegis_mail.
#Common commands
Cube operations share one wrapper: ✔ postfix: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "postfix", "result": "<detail>"} with global --json.
expose is the only verb that prints a block instead of that line.
| Verb | Effect |
|---|---|
configure | bootstrap the mail database, render the maps and both config files, validate, start when stopped |
validate | run postfix -c <dir> check |
reload | run postfix -c <dir> reload against the running master |
status | read queue/pid/master.pid: running (pid N) or stopped |
start | start start-fg under the keeper |
stop | SIGTERM, then SIGKILL after 15 seconds |
restart | stop, then start |
expose | print paths, backend, map count, then publish the Postfix tools |
help | print the command list with examples |
#configure
aegis cubes postfix configureaegis --json cubes postfix configureCreates the role and the database when they are missing, applies the schema as the mail role (so the tables are owned by the account the maps connect with), renders everything, validates, and starts the master if it is not running.
✔ postfix: role aegis_mail, schema in aegis_mail; configuration is valid{"ok": true, "cube": "postfix", "result": "role aegis_mail, schema in aegis_mail; configuration is valid"}#validate
aegis cubes postfix validateaegis --json cubes postfix validateRuns postfix check with the cube's configuration directory; the last eight lines are shown on failure.
✔ postfix: configuration is valid{"ok": true, "cube": "postfix", "result": "configuration is valid"}#reload
aegis cubes postfix reloadaegis --json cubes postfix reloadAsks the running master to re-read its configuration. A stopped master fails with Postfix's own message.
✔ postfix: configuration reloaded{"ok": true, "cube": "postfix", "result": "configuration reloaded"}#status
aegis cubes postfix statusaegis --json cubes postfix status✔ postfix: running (pid 1201){"ok": true, "cube": "postfix", "result": "running (pid 1201)"}#start
aegis cubes postfix startaegis --json cubes postfix start✔ postfix: started (pid 1201){"ok": true, "cube": "postfix", "result": "started (pid 1201)"}#stop
aegis cubes postfix stopaegis --json cubes postfix stopMail is queued on disk while the master is down and delivered after the next start.
✔ postfix: stopped (pid 1201){"ok": true, "cube": "postfix", "result": "stopped (pid 1201)"}#restart
aegis cubes postfix restartaegis --json cubes postfix restart✔ postfix: stopped (pid 1201), started (pid 1233){"ok": true, "cube": "postfix", "result": "stopped (pid 1201), started (pid 1233)"}#expose
aegis cubes postfix exposeaegis --json cubes postfix exposedatabase is <driver>:<name>. The published tools carry MAIL_CONFIG, so mailq and postconf look at this instance without a -c flag.
cube postfixinstalled /aegis/apps/mail/postfix/3.11configuration /aegis/config/postfixstate running (pid 1201)pid 1201log /aegis/logs/postfix/mail.logconfig /aegis/config/postfix/main.cfqueue /aegis/data/postfix/queuedatabase pgsql:aegis_mailmaps 9published /aegis/bin/postfix, /aegis/bin/postconf, /aegis/bin/postmap, /aegis/bin/mailq, /aegis/bin/newaliases{"ok": true, "cube": "postfix", "installed": "/aegis/apps/mail/postfix/3.11", "configuration": "/aegis/config/postfix", "state": "running (pid 1201)", "pid": "1201", "log": "/aegis/logs/postfix/mail.log", "config": "/aegis/config/postfix/main.cf", "queue": "/aegis/data/postfix/queue", "database": "pgsql:aegis_mail", "maps": "9", "published": "/aegis/bin/postfix, /aegis/bin/postconf, /aegis/bin/postmap, /aegis/bin/mailq, /aegis/bin/newaliases"}#help
aegis cubes postfix helpaegis cubes help postfixℹ Postfix — MTA: SQL maps, relays, security rules and hooksCommands validate Check the configuration reload Reload the running daemon configure Bootstrap the mail database and write configThe list continues with start, stop, status, restart, expose, relays, hooks, security and help, then the examples.
#Relays
A relay is a named transport in master.cf with its own source address and HELO name, so one server can send from several IPs. Routes decide which destinations use which relay and live in the SQL transport map.
aegis cubes postfix relays Manage outbound relaysCommands list List relays add Create or update a relay remove Delete a relay and its routes routes List routes route-add Send a destination via a relay route-remove Remove a routeRun 'aegis cubes postfix relays <command> --help' for the options of one command.#relays list
aegis cubes postfix relays listaegis --json cubes postfix relays list✔ postfix: relay1 bind=203.0.113.10 helo=mail.example.com{"ok": true, "cube": "postfix", "result": "relay1 bind=203.0.113.10 helo=mail.example.com"}#relays add
aegis cubes postfix relays add relay1 --bind-ip 203.0.113.10 --helo mail.example.comaegis cubes postfix relays add relay2 --bind-ip 198.51.100.20 --helo mail2.example.com --syslog aegis-relay2| Option | Meaning |
|---|---|
name | transport name; lowercase, a-z, digits and dashes |
--bind-ip | required; source address, which must exist on this host |
--helo | required; HELO name announced to the remote |
--syslog | syslog tag; defaults to aegis-<name> |
--disabled | store the relay but leave it out of master.cf |
The address is checked against ip -o addr show, and two active relays may not share one address. Adding an existing name updates that relay.
✔ postfix: created relay relay1 (203.0.113.10, helo mail.example.com); role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postfix", "result": "updated relay relay1 (203.0.113.10, helo mail.example.com); role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}#relays remove
Destructive. Deletes the relay and, through the foreign key, every route that points at it. Mail for those destinations then follows the default transport.
aegis cubes postfix relays remove relay1aegis --json cubes postfix relays remove relay2| Argument | Meaning |
|---|---|
name | the relay to delete |
✔ postfix: deleted relay relay1; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postfix", "result": "deleted relay relay2; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}#relays routes
aegis cubes postfix relays routesaegis --json cubes postfix relays routes✔ postfix: example.org -> relay1{"ok": true, "cube": "postfix", "result": "example.org -> relay1"}#relays route-add
aegis cubes postfix relays route-add example.org relay1aegis --json cubes postfix relays route-add person@example.net relay2| Argument | Meaning |
|---|---|
destination | a domain (example.org, @example.org) or a full address |
relay | an existing relay name |
The pair is replaced when it already exists, so the command is idempotent.
✔ postfix: route example.org -> relay1; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postfix", "result": "route person@example.net -> relay2; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}#relays route-remove
Destructive. Removes the route, or every route of the destination when
--relayis omitted.
aegis cubes postfix relays route-remove example.org --relay relay1aegis cubes postfix relays route-remove example.org| Option | Meaning |
|---|---|
destination | the routed destination |
--relay | narrow the removal to one relay |
✔ postfix: removed route example.org; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postfix", "result": "removed route example.org; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}#Hooks
Postfix cannot run an arbitrary program per message, so every hook is served by one pipe transport: matching mail is blind-copied to a synthetic address, a small Python runner executes the hooks that apply, and the copy is discarded. Adding or removing a hook restarts the master, because a reload leaves the old BCC maps in the cleanup daemons.
aegis cubes postfix hooks Manage mail hooksCommands list List hooks add Create or replace a hook remove Delete a hookRun 'aegis cubes postfix hooks <command> --help' for the options of one command.#hooks list
aegis cubes postfix hooks listaegis --json cubes postfix hooks listEach entry shows name, direction, match, handler type and (disabled) when it is switched off.
✔ postfix: demo-in [inbound/all] script; demo-out [outbound/all] script{"ok": true, "cube": "postfix", "result": "demo-in [inbound/all] script; demo-out [outbound/all] script"}#hooks add
aegis cubes postfix hooks add audit --handler /usr/local/bin/audit.sh --direction inboundaegis cubes postfix hooks add alert --handler https://example.com/hook --type webhook --match domain --value example.com| Option | Meaning |
|---|---|
name | hook name; letters, digits, - and _ |
--handler | required; the script path or webhook URL |
--type | script (default) or webhook |
--direction | inbound, outbound or both (default) |
--match | all (default), domain or address |
--value | the domain or address matched; required unless --match all |
--timeout | seconds, default 30 |
An existing name is replaced, and an existing disabled hook stays disabled.
✔ postfix: hook audit created; configuration is valid; stopped (pid 1233), started (pid 1267){"ok": true, "cube": "postfix", "result": "hook alert updated; configuration is valid; stopped (pid 1233), started (pid 1267)"}#hooks remove
Destructive. Deletes the hook and restarts the master. The handler script or URL is not touched.
aegis cubes postfix hooks remove auditaegis --json cubes postfix hooks remove alert✔ postfix: hook audit removed; configuration is valid; stopped (pid 1267), started (pid 1290){"ok": true, "cube": "postfix", "result": "hook alert removed; configuration is valid; stopped (pid 1267), started (pid 1290)"}#Security rules
Rules live in aegis_security_rules and are compiled into header_checks, body_checks, regexp access maps for senders and HELO names, and reject_rbl_client entries. The compiled checks are appended after permit_mynetworks, permit_sasl_authenticated, so local and authenticated clients are never affected. Adding or removing a rule re-renders and reloads.
aegis cubes postfix security Manage anti-abuse rulesCommands list List rules add Add a rule remove Delete a ruleRun 'aegis cubes postfix security <command> --help' for the options of one command.#security list
aegis cubes postfix security listaegis --json cubes postfix security list✔ postfix: #1 header /X-Spam-Flag: YES/ reject; #2 rbl /zen.spamhaus.org/ reject{"ok": true, "cube": "postfix", "result": "#1 header /X-Spam-Flag: YES/ reject; #2 rbl /zen.spamhaus.org/ reject"}#security add
aegis cubes postfix security add header 'X-Spam-Flag: YES' --action rejectaegis cubes postfix security add rbl zen.spamhaus.org| Option | Meaning |
|---|---|
kind | header, body, sender, helo or rbl |
pattern | the regexp for the first four kinds, the blocklist zone for rbl |
--action | reject (default), defer, discard or warn |
--message | rejection or deferral text; empty uses the action's default |
--priority | ordering inside a kind, default 100 |
Write the pattern without surrounding slashes: X-Spam-Flag: YES, not /X-Spam-Flag: YES/. A pattern may not contain a newline.
✔ postfix: added header rule X-Spam-Flag: YES (reject); role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postfix", "result": "added rbl rule zen.spamhaus.org (reject); role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}#security remove
Destructive. Deletes the rule by id and recompiles the check files. The id is the
#Nshown bysecurity list.
aegis cubes postfix security remove 1aegis --json cubes postfix security remove 2| Argument | Meaning |
|---|---|
id | the rule id, a decimal number |
✔ postfix: deleted rule 1; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postfix", "result": "deleted rule 2; role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}