Aegis documentation

#Cube: postsrsd

PostSRSd 2.4 rewrites the envelope sender of forwarded mail so SPF survives the hop, and unwraps the rewrite when a bounce comes back. Postfix reaches it through a socketmap endpoint.

In the panel: Mail → the PostSRSd settings page. Every write there is a task.

#Configuration

toml
[mail.postsrsd]enabled = trueforward_port = 10001              # the socketmap portsecret_file = "/aegis/config/postsrsd/secret"config_dir = "/aegis/config/postsrsd"user = "postfix"                  # account the daemon drops to[mail]domain = ""                       # SRS domain; empty uses the primary domain
KeyDefaultMeaning
enabledtruewhen false the cube leaves SRS out of Postfix
forward_port10001single socketmap port serving forward and reverse
secret_file/aegis/config/postsrsd/secretsigning secret, mode 0600, never overwritten
config_dir/aegis/config/postsrsdpostsrsd.conf and the domains file
userpostfixaccount the daemon drops to
mail.domainemptydomain used in the rewritten envelopes

There is no reverse_port and no chroot_dir: PostSRSd 2.4 has one endpoint and runs unchrooted so it can read the secret.

#Files

text
<mail.postsrsd.config_dir>/├── postsrsd.conf            daemon configuration (0644)├── domains                  local domains, one per line (generated)├── domains.extra            manual exclusions, one per line (optional)└── secret                   signing secret, mode 0600<aegis.root>/run/postsrsd/└── postsrsd.pid<aegis.root>/logs/postsrsd/└── postsrsd.log

domains is regenerated on every configure and on every domains command from three sources:

text
domains = { aegis_domains WHERE active }  ∪  { mail.domain }  ∪  domains.extra

The daemon watches the file (domains-file-watch = on), so a change is picked up without a restart. domains.extra is the only file the commands write; it accepts blank lines and # comments.

The secret is created once and never overwritten — replacing it would invalidate every SRS address already in flight.

#Commands

bash
aegis cubes postsrsd configure     # secret, domains, config, start, Postfixaegis cubes postsrsd validate      # files present, secret 0600, domains non-emptyaegis cubes postsrsd reload        # restartaegis cubes postsrsd start|stop|restart|statusaegis cubes postsrsd expose

configure ends by re-rendering and reloading Postfix: the SRS canonical maps are only emitted while the socketmap port answers.

#Managing the exclude list

domains must list every domain this server sends mail for: a sender from a listed domain keeps its envelope address, an unlisted one is rewritten into SRS0=…@<srs-domain>, which breaks DMARC alignment at the receiver.

Mail domains need no command — they come from the database. The commands below manage the extra names, the ones that are not mail domains:

bash
aegis cubes postsrsd domains listaegis cubes postsrsd domains add legacy.test brand.exampleaegis cubes postsrsd domains remove legacy.testaegis cubes postsrsd domains edit brand.example brand.test
text
$ aegis cubes postsrsd domains listexample.com (mail); client.ro (mail); legacy.test (manual)
CommandDoesRefuses when
listone line per domain, with the source—
addappends to domains.extra, rewrites domainsthe name is already excluded (reported, not an error)
removedrops a manual entrythe domain is an active mail domain
editrenames a manual entrythe old name is not manual, or the new one is already excluded

A mail domain is disabled in the mail cube, not here:

bash
aegis cubes mail domains disable client.ro     # leaves the exclude list

The order is what makes this safe: the database is the truth for hosted domains, the file only adds names the database does not know. Removing a domain from aegis_domains therefore drops it from the list at the next render, and no command can put a hosted domain in a state where it is silently rewritten.

Every command rewrites domains in the same run; the daemon re-reads it because of domains-file-watch, so nothing needs a reload. Verify with:

bash
cat /aegis/config/postsrsd/domainscat /aegis/config/postsrsd/domains.extraaegis cubes postsrsd expose          # "domains" and "extra" rows

#Postfix integration

PostSRSd 2.4 speaks the socketmap protocol, one endpoint, two table names:

text
sender_canonical_maps    = socketmap:inet:127.0.0.1:10001:forwardsender_canonical_classes = envelope_senderrecipient_canonical_maps = socketmap:inet:127.0.0.1:10001:reverserecipient_canonical_classes = envelope_recipient

forward rewrites a remote sender into SRS0=…@<srs-domain>; reverse turns it back. Local domains are listed in domains and are never rewritten.

Version trap. The 1.x configuration (sender-domains, secret-file, chroot-dir, forward-port/reverse-port as two tcp: maps) does not exist in 2.4. The shipped template is written for 2.4: domains-file, srs-domain, socketmap, secrets-file, keep-alive, connection-limit.

#Process

toml
[services.postsrsd]command  = <prefix>/sbin/postsrsd -C <conf> -p <pid> -u postfixpid_file = <aegis.root>/run/postsrsd/postsrsd.pid

-p here is the pid file (unlike OpenDKIM), so the keeper tracks the daemon directly.

#Verifying

bash
postmap -q someone@example.org socketmap:inet:127.0.0.1:10001:forward# SRS0=XsZv=JE=example.org=someone@inhive.devpostmap -q 'SRS0=XsZv=JE=example.org=someone@inhive.dev'         socketmap:inet:127.0.0.1:10001:reverse# someone@example.orgpostmap -q postmaster@inhive.dev socketmap:inet:127.0.0.1:10001:forward# (no output, rc=1) — local domains are not rewritten

Use postmap, not a hand-written client: the socketmap framing (netstrings) is easy to get wrong, and postmap is the client Postfix itself uses.

#expose

bash
aegis cubes postsrsd exposecube           postsrsdinstalled      /aegis/apps/mail/postsrsd/2.4configuration  /aegis/config/postsrsdstate          running pid 879844log            /aegis/logs/postsrsd/postsrsd.logconfig         /aegis/config/postsrsd/postsrsd.confsocketmap      inet:127.0.0.1:10001domains        3extra          /aegis/config/postsrsd/domains.extrasecret         /aegis/config/postsrsd/secret

#Notes

  • seccomp sandbox is unavailable in the log means the build had no libseccomp;
  • it is a warning, not a failure.

  • If the daemon is down, Postfix silently drops the canonical maps only after a
  • postfix configure; a stale configuration would defer mail with temporary lookup failure.