Aegis documentation

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

VerbEffect
configurebootstrap the mail database, render the maps and both config files, validate, start when stopped
validaterun postfix -c <dir> check
reloadrun postfix -c <dir> reload against the running master
statusread queue/pid/master.pid: running (pid N) or stopped
startstart start-fg under the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint paths, backend, map count, then publish the Postfix tools
helpprint the command list with examples

#configure

bash
aegis cubes postfix configureaegis --json cubes postfix configure

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

text
✔ 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

bash
aegis cubes postfix validateaegis --json cubes postfix validate

Runs postfix check with the cube's configuration directory; the last eight lines are shown on failure.

text
✔ postfix: configuration is valid{"ok": true, "cube": "postfix", "result": "configuration is valid"}

#reload

bash
aegis cubes postfix reloadaegis --json cubes postfix reload

Asks the running master to re-read its configuration. A stopped master fails with Postfix's own message.

text
✔ postfix: configuration reloaded{"ok": true, "cube": "postfix", "result": "configuration reloaded"}

#status

bash
aegis cubes postfix statusaegis --json cubes postfix status
text
✔ postfix: running (pid 1201){"ok": true, "cube": "postfix", "result": "running (pid 1201)"}

#start

bash
aegis cubes postfix startaegis --json cubes postfix start
text
✔ postfix: started (pid 1201){"ok": true, "cube": "postfix", "result": "started (pid 1201)"}

#stop

bash
aegis cubes postfix stopaegis --json cubes postfix stop

Mail is queued on disk while the master is down and delivered after the next start.

text
✔ postfix: stopped (pid 1201){"ok": true, "cube": "postfix", "result": "stopped (pid 1201)"}

#restart

bash
aegis cubes postfix restartaegis --json cubes postfix restart
text
✔ postfix: stopped (pid 1201), started (pid 1233){"ok": true, "cube": "postfix", "result": "stopped (pid 1201), started (pid 1233)"}

#expose

bash
aegis cubes postfix exposeaegis --json cubes postfix expose

database is <driver>:<name>. The published tools carry MAIL_CONFIG, so mailq and postconf look at this instance without a -c flag.

text
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
text
{"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

bash
aegis cubes postfix helpaegis cubes help postfix
text
ℹ 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 config

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

text
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

bash
aegis cubes postfix relays listaegis --json cubes postfix relays list
text
✔ 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

bash
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
OptionMeaning
nametransport name; lowercase, a-z, digits and dashes
--bind-iprequired; source address, which must exist on this host
--helorequired; HELO name announced to the remote
--syslogsyslog tag; defaults to aegis-<name>
--disabledstore 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.

text
✔ 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.

bash
aegis cubes postfix relays remove relay1aegis --json cubes postfix relays remove relay2
ArgumentMeaning
namethe relay to delete
text
✔ 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

bash
aegis cubes postfix relays routesaegis --json cubes postfix relays routes
text
✔ postfix: example.org -> relay1{"ok": true, "cube": "postfix", "result": "example.org -> relay1"}

#relays route-add

bash
aegis cubes postfix relays route-add example.org relay1aegis --json cubes postfix relays route-add person@example.net relay2
ArgumentMeaning
destinationa domain (example.org, @example.org) or a full address
relayan existing relay name

The pair is replaced when it already exists, so the command is idempotent.

text
✔ 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 --relay is omitted.

bash
aegis cubes postfix relays route-remove example.org --relay relay1aegis cubes postfix relays route-remove example.org
OptionMeaning
destinationthe routed destination
--relaynarrow the removal to one relay
text
✔ 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.

text
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

bash
aegis cubes postfix hooks listaegis --json cubes postfix hooks list

Each entry shows name, direction, match, handler type and (disabled) when it is switched off.

text
✔ 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

bash
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
OptionMeaning
namehook name; letters, digits, - and _
--handlerrequired; the script path or webhook URL
--typescript (default) or webhook
--directioninbound, outbound or both (default)
--matchall (default), domain or address
--valuethe domain or address matched; required unless --match all
--timeoutseconds, default 30

An existing name is replaced, and an existing disabled hook stays disabled.

text
✔ 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.

bash
aegis cubes postfix hooks remove auditaegis --json cubes postfix hooks remove alert
text
✔ 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.

text
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

bash
aegis cubes postfix security listaegis --json cubes postfix security list
text
✔ 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

bash
aegis cubes postfix security add header 'X-Spam-Flag: YES' --action rejectaegis cubes postfix security add rbl zen.spamhaus.org
OptionMeaning
kindheader, body, sender, helo or rbl
patternthe regexp for the first four kinds, the blocklist zone for rbl
--actionreject (default), defer, discard or warn
--messagerejection or deferral text; empty uses the action's default
--priorityordering 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.

text
✔ 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 #N shown by security list.

bash
aegis cubes postfix security remove 1aegis --json cubes postfix security remove 2
ArgumentMeaning
idthe rule id, a decimal number
text
✔ 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"}