Aegis documentation

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

text
        ┌──────────────┐   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)               ▼            internet

In the panel: Mail → Relays, Hooks and the Postfix settings page. Every write there is a task.

#Configuration

toml
[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"
KeyDefaultMeaning
postfix.config_dir/aegis/config/postfixmain.cf, master.cf, maps, security, hooks
postfix.data_dir/aegis/data/postfixdata_directory
postfix.queue_dir…/postfix/queuequeue and pid/master.pid
postfix.log_file/aegis/logs/postfix/mail.logmaillog_file, written via postlogd
postfix.userpostfixdaemons run as this account; SASL socket owner
apps.postfix.databasepgsqlbackend of the mail database and its maps
apps.postfix.compatibility_level3.11Postfix compatibility setting
apps.postfix.inet_protocolsipv4ipv4, ipv6 or all
apps.postfix.message_size_limit5242880050 MB per message
apps.postfix.relayhostemptyglobal smarthost for everything unrouted
apps.postfix.smtp_bind_addressemptyglobal outbound source address
apps.postfix.hooks_usernobodyaccount the aegis-hooks pipe runs as
mail.hostnameemptymyhostname in the banner
mail.domainemptymydomain and the SRS domain
mail.vmail_uid, mail.vmail_gid5000numeric owner of maildirs
mail.vmail_base/aegis/data/mailroot of the maildir tree
mail.database.*see aboveconnection details for the SQL maps
mail.postsrsd.enabledtruerender SRS maps when PostSRSd answers
mail.postsrsd.forward_port10001socketmap port of PostSRSd

The certificate is resolved through the ssl module for mail.hostname; it is not a key here.

#Files

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

  • database — creates the role, the database and applies the schema of the
  • configured backend (see schema.md). The password is generated once and written to config/server.toml.

  • maps — renders the SQL maps for that backend and turns them into
  • pgsql: / mysql: / sqlite: parameters.

  • security — compiles aegis_security_rules into the check files and the
  • smtpd_*_restrictions lists.

  • hooks — renders the runner, hooks.json and the three hook maps, and
  • adds the pipe service to master.cf.

  • main.cf / master.cf — rendered last, with the relay and hook blocks
  • appended.

  • postfix check, then start when the master is not running.
  • Every step is idempotent: files are rewritten only when their content changed.

    #Commands

    bash
    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 tools

    Groups:

    GroupWhat it managesDetails
    relaysoutbound source addresses and routespostfix-relays.md
    securityheader/body/sender/helo/rbl rulesbelow
    hooksscripts and webhooks per messagepostfix-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:

    ParameterMeaning here
    myhostname, mydomain, myoriginidentity announced in the banner, default mail.hostname and mail.domain
    mydestinationonly localhost; every real domain is virtual
    virtual_mailbox_domainsSQL: aegis_domains, active only
    virtual_mailbox_mapsSQL: aegis_mailboxes → maildir
    virtual_alias_mapsSQL: aliases, forwards and catch-all (one UNION query)
    virtual_transportlmtp:unix:<dovecot lmtp socket>
    virtual_uid_maps, virtual_gid_mapsthe 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_restrictionspermit_mynetworks, permit_sasl_authenticated, reject_unauth_destination
    smtpd_sender_restrictionsreject_sender_login_mismatch before the permits
    smtpd_miltersOpenDKIM on 127.0.0.1:8891, milter_default_action = accept
    relayhost, smtp_bind_addressglobal fallback, overridden per relay
    sender_canonical_mapssocketmap:…:forward (SRS) when PostSRSd answers
    recipient_canonical_mapssocketmap:…:reverse (SRS)
    maillog_file<postfix.log_file>; needs postlog in master.cf

    #master.cf

    ServicePurpose
    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-hookspipe service that runs the hook runner
    postloglogging 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:

    kindCompiled intoRestriction
    headersecurity/header_checksheader_checks = regexp:…
    bodysecurity/body_checksbody_checks = regexp:…
    sendersecurity/sender_checkscheck_sender_access in smtpd_sender_restrictions
    helosecurity/helo_checkscheck_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.

    bash
    # 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 3

    Checking what Postfix will read:

    bash
    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

  • inbound: smtpd_tls_cert_file / smtpd_tls_key_file come from the ssl
  • module — 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.

  • outbound: opportunistic TLS by default; per-domain strictness through
  • mail tls set <domain> encrypt|secure|verify, which feeds smtp_tls_policy_maps.

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

    SymptomCauseFix
    TLS has been selected, but TLS support is not compiled inbuilt with the old -DHAS_SSLbuild.toml must use -DUSE_TLS, then rebuild
    SASL support is not compiled inmissing -DUSE_SASL_AUTHadd it and rebuild
    SASL: Connect to Dovecot auth socket … failedchroot or wrong socket pathchroot = n and check dovecot.sasl_socket
    fatal: maillog_file … does not match any prefixno maillog_file_prefixesrendered by the template; check it is present
    fatal: the Postfix mail system is already runningstart-fg when a master runsaegis cubes postfix status first
    tcp lookup error on every recipientPostSRSd is down but maps are renderedaegis cubes postfix configure after starting it
    mail queued but never deliveredLMTP socket missingls -l /aegis/run/dovecot/lmtp, then aegis cubes dovecot configure
    cannot execute postconfrpath missing on buildAUXLIBS must carry -Wl,-rpath,…
    bash
    tail -f /aegis/logs/postfix/mail.logaegis cubes postfix validate/aegis/bin/mailqMAIL_CONFIG=/aegis/config/postfix postqueue -p

    aegis 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

    toml
    "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

    bash
    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 
  • postfix-relays.md — several outbound addresses and routes
  • postfix-hooks.md — scripts and webhooks per message
  • schema.md — every table Postfix reads
  • dovecot.md — authentication and delivery