Aegis documentation

#PostSRSd

The PostSRSd cube owns sender rewriting for forwarded mail. Without SRS a forwarded message keeps the original envelope sender and fails SPF at the receiver; PostSRSd rewrites it on the way out and reverses the rewrite for bounces. It writes postsrsd.conf, the generated domains file, the manual domains.extra list and the signing secret (mode 0600) under mail.postsrsd.config_dir (/aegis/config/postsrsd), plus its pid and log.

The local domain list comes from the mail database: every active aegis_domains row plus mail.domain, merged with the manual entries. Postfix reaches the daemon through a socketmap on 127.0.0.1:10001 (mail.postsrsd.forward_port). configure re-renders Postfix too, because its canonical maps point at the socketmap, but only after the daemon answers. Settings live under [mail.postsrsd], and enabled = false takes SRS out of the SMTP path entirely.

#Common commands

Cube operations share one wrapper: ✔ postsrsd: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "postsrsd", "result": "<detail>"} with global --json.

expose is the only verb that prints a block instead of that line.

VerbEffect
configuregenerate the secret on first use, render the domain list and config, validate, start, re-render Postfix
validatecheck the three files, the secret mode and that the domain list is not empty
reloadrestart the daemon; the domain list is watched, the rest is read at startup
statusrunning (pid N), stopped, or postsrsd is disabled
startstart the daemon through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint paths, socketmap endpoint, domain count and secret path
helpprint the command list with examples

With enabled = false, service(), start() and reload() refuse to run, and configure removes the socketmap from Postfix and stops the daemon.

#configure

bash
aegis cubes postsrsd configureaegis --json cubes postsrsd configure

The secret is generated once and never overwritten. With no local domain the command reports no local domains: SRS left disabled instead of rewriting every sender; with enabled = false it reports disabled, removes the socketmap from Postfix and stops the daemon.

text
✔ postsrsd: secret generated, configuration present, 2 domains; postfix: role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded{"ok": true, "cube": "postsrsd", "result": "secret present, configuration present, 2 domains; postfix: role aegis_mail, schema in aegis_mail; configuration is valid; configuration reloaded"}

#validate

bash
aegis cubes postsrsd validateaegis --json cubes postsrsd validate

The daemon has no configuration test mode, so the files are checked directly: all three must exist, the secret must be mode 0600, and the domain list must not be empty.

text
✔ postsrsd: configuration present, 2 domains{"ok": true, "cube": "postsrsd", "result": "configuration present, 2 domains"}

#reload

bash
aegis cubes postsrsd reloadaegis --json cubes postsrsd reload

Restarts the daemon. A stopped or disabled daemon fails with postsrsd is not running / postsrsd is disabled in the configuration.

text
✔ postsrsd: stopped (pid 1502), started (pid 1520){"ok": true, "cube": "postsrsd", "result": "stopped (pid 1502), started (pid 1520)"}

#status

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

A disabled configuration answers ✔ postsrsd: postsrsd is disabled.

#start

bash
aegis cubes postsrsd startaegis --json cubes postsrsd start

A disabled configuration fails with postsrsd is disabled in the configuration; one with no local domain fails with postsrsd is not configured: no local domains.

text
✔ postsrsd: started (pid 1502){"ok": true, "cube": "postsrsd", "result": "started (pid 1502)"}

#stop

bash
aegis cubes postsrsd stopaegis --json cubes postsrsd stop
text
✔ postsrsd: stopped (pid 1502){"ok": true, "cube": "postsrsd", "result": "stopped (pid 1502)"}

#restart

bash
aegis cubes postsrsd restartaegis --json cubes postsrsd restart
text
✔ postsrsd: stopped (pid 1502), started (pid 1541){"ok": true, "cube": "postsrsd", "result": "stopped (pid 1502), started (pid 1541)"}

#expose

bash
aegis cubes postsrsd exposeaegis --json cubes postsrsd expose
text
cube           postsrsdinstalled      /aegis/apps/mail/postsrsd/2.4configuration  /aegis/config/postsrsdstate          running (pid 1502)pid            1502log            /aegis/logs/postsrsd/postsrsd.logconfig         /aegis/config/postsrsd/postsrsd.confsocketmap      inet:127.0.0.1:10001domains        2extra          /aegis/config/postsrsd/domains.extrasecret         /aegis/config/postsrsd/secretpublished      /aegis/bin/postsrsd
text
{"ok": true, "cube": "postsrsd", "installed": "/aegis/apps/mail/postsrsd/2.4", "configuration": "/aegis/config/postsrsd", "state": "running (pid 1502)", "pid": "1502", "log": "/aegis/logs/postsrsd/postsrsd.log", "config": "/aegis/config/postsrsd/postsrsd.conf", "socketmap": "inet:127.0.0.1:10001", "domains": "2", "extra": "/aegis/config/postsrsd/domains.extra", "secret": "/aegis/config/postsrsd/secret", "published": "/aegis/bin/postsrsd"}

#help

bash
aegis cubes postsrsd helpaegis cubes help postsrsd
text
ℹ Postsrsd — Sender rewriting for forwarded mailCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Write the secret, domains and config  start      Start the daemon  stop       Stop the daemon  status     Show whether the daemon runs  restart    Restart the daemon  expose     Show where it is installed and how it runs  domains    Manage the SRS exclude list  help       Show every command with examples

The same output ends with the examples, including the postmap query that asks the running daemon to rewrite an address:

bash
postmap -q someone@example.org socketmap:inet:127.0.0.1:10001:forward

#SRS exclude list

A domain that sends mail but is not a mail domain would be rewritten without being listed. Those names are the manual entries in domains.extra; they are merged into the generated domains file on every change, so the daemon's watched file always reflects both sources.

text
aegis cubes postsrsd domains  Manage the SRS exclude listCommands  list    List local domains and their source  add     Exclude extra domains  remove  Drop manual exclusions  edit    Rename a manual exclusionRun 'aegis cubes postsrsd domains <command> --help' for the options of one command.

#domains list

bash
aegis cubes postsrsd domains listaegis --json cubes postsrsd domains list

source is mail, manual, or mail+manual for a name that appears in both.

text
✔ postsrsd: example.com (mail); marketing.example (manual); example.org (mail+manual){"ok": true, "cube": "postsrsd", "result": "example.com (mail); marketing.example (manual); example.org (mail+manual)"}

#domains add

bash
aegis cubes postsrsd domains add marketing.exampleaegis cubes postsrsd domains add partner.example brand.example
ArgumentMeaning
domainone or more domains to exclude from rewriting

Writes domains.extra, regenerates domains, and reports what was added. Names already excluded are listed instead of being added twice.

text
✔ postsrsd: marketing.example; list rewritten, the daemon is watching it{"ok": true, "cube": "postsrsd", "result": "partner.example, brand.example; list rewritten, the daemon is watching it"}

#domains remove

Destructive. Drops manual entries. A mail domain cannot be removed here: the database would put it back on the next render, so the command fails with the instruction to disable it in the mail cube.

bash
aegis cubes postsrsd domains remove marketing.exampleaegis --json cubes postsrsd domains remove partner.example
ArgumentMeaning
domainone or more manual entries to drop
text
✔ postsrsd: marketing.example; list rewritten, the daemon is watching it{"ok": true, "cube": "postsrsd", "result": "partner.example; list rewritten, the daemon is watching it"}

#domains edit

bash
aegis cubes postsrsd domains edit marketing.example marketing.example.comaegis --json cubes postsrsd domains edit old.example new.example
ArgumentMeaning
oldan existing manual entry
newthe replacement name

The rename is refused when the old name is a mail domain or the new name is already excluded.

text
✔ postsrsd: marketing.example -> marketing.example.com; list rewritten, the daemon is watching it{"ok": true, "cube": "postsrsd", "result": "old.example -> new.example; list rewritten, the daemon is watching it"}