Aegis documentation

#Postfix: relays and routes

A relay is a named outbound transport with its own source address and HELO name, so one server can send different mail from different IPs. A route decides which destinations use which relay.

text
example.org  ──route──▶ relay1 (203.0.113.10, helo mail.example.com)shop.example ──route──▶ relay2 (203.0.113.11, helo shop.example.com)anything else ────────▶ default smtp transport (server's primary IP)

Use cases: separate IPs per customer domain for reputation, a second IP after a blocklisting, or an IP with a matching reverse DNS for transactional mail.

Configuration for the cube itself (paths, database backend, hook user) is in postfix.md; this page covers only the relay tables and the generated services.

#How it is built

A relay is not a database abstraction over relayhost; it is a real Postfix service:

  • aegis_relays holds one row per relay (see schema.md).
  • Every configure (or relays command) writes a block into master.cf:
  • text
       # BEGIN AEGIS RELAYS — generated by the postfix cube, do not edit   aegis-relay1 unix - - n - - smtp     -o syslog_name=aegis-relay1     -o smtp_bind_address=203.0.113.10     -o smtp_helo_name=mail.example.com   # END AEGIS RELAYS
  • aegis_relay_domains holds the routes. The SQL transport map turns them
  • into aegis-relay1:, which is the service name above.

  • Postfix reloads; nothing else changes.
  • #Commands

    bash
    aegis cubes postfix relays listaegis cubes postfix relays routesaegis cubes postfix relays add <name> --bind-ip <ip> --helo <name>aegis cubes postfix relays remove <name>aegis cubes postfix relays route-add <destination> <relay>aegis cubes postfix relays route-remove <destination> --relay <name>

    #Creating relays

    bash
    # first IP, for customer Aaegis cubes postfix relays add relay1     --bind-ip 203.0.113.10 --helo mail.example.com# second IP, its own HELO and its own syslog tagaegis cubes postfix relays add relay2     --bind-ip 203.0.113.11 --helo shop.example.com     --syslog aegis-shop# created but not rendered (kept for later)aegis cubes postfix relays add standby     --bind-ip 203.0.113.12 --helo mail.example.com --disabled

    add creates or updates: running it again with the same name changes the address, HELO or state, which is how a relay is edited.

    Validation happens before anything is written:

    RuleRejected example
    name: lowercase, starts with a letter, [a-z0-9-], max 31 charsRelay_1, 1relay
    bind_ip must parse as an IP address203.0.113.999
    bind_ip must be configured on this hostan IP of another machine
    two active relays may not share bind_iprelay2 --bind-ip 203.0.113.10
    helo_name must be a hostnamemail example.com
    syslog_name: [A-Za-z0-9._-], max 64aegis shop

    The host check reads ip -o addr show; if iproute2 is missing the check is skipped and the mistake surfaces later as smtp_bind_address failing at delivery time.

    #Routing destinations

    bash
    aegis cubes postfix relays route-add example.org relay1aegis cubes postfix relays route-add '@shop.example' relay2aegis cubes postfix relays route-add billing@example.org relay1aegis cubes postfix relays routes# example.org -> relay1; @shop.example -> relay2; billing@example.org -> relay1aegis cubes postfix relays route-remove example.orgaegis cubes postfix relays route-remove billing@example.org --relay relay1

    The destination is matched by the transport map as a whole value, so write what Postfix looks up: a bare domain (example.org) or a full address (billing@example.org). A @domain form matches only the domain part in this implementation — use the bare domain for "everything at example.org".

    Every command above re-renders master.cf, runs postfix check and reloads the daemon, so the change is live without a restart.

    #Removing

    bash
    aegis cubes postfix relays remove relay1

    The schema has ON DELETE CASCADE on the routes, so removing a relay removes its routes in the same statement; the next configure drops both the master.cf block and the transport rows.

    #Verifying

    bash
    # the service exists and carries the right addressaegis cubes postfix relays listpostconf -c /aegis/config/postfix -M | grep aegis# the route resolves to the service namepostmap -q example.org pgsql:/aegis/config/postfix/maps/transport.cf# aegis-relay1:# a message actually leaves from the relaygrep 'relay=aegis-relay1' /aegis/logs/postfix/mail.log

    A successful delivery through a relay logs the service name, not the transport column:

    text
    postfix/smtp[1234]: ABC123: to=<user@example.org>, relay=example.org[192.0.2.10]:25,    delays=0.02/0.01/0.3/0.2, dsn=2.0.0, status=sent (250 2.0.0 Ok)

    and the syslog_name you set appears as the log tag (postfix/aegis-shop).

    #Testing without real mail

    bash
    # does the map return the right transport?postmap -q example.org pgsql:/aegis/config/postfix/maps/transport.cf# does Postfix accept the generated master.cf?aegis cubes postfix validate# which source address would be used for one destination?postconf -c /aegis/config/postfix -M | grep -A3 aegis-relay1

    #Limits and gotchas

  • No smarthost authentication yet. aegis_relays has host, port,
  • username, password and tls columns, but the generated transport only sets smtp_bind_address and smtp_helo_name: a relay sends directly to the destination's MX. Use [apps.postfix] relayhost for a global smarthost.

  • The IP must exist on the host before the relay is created; adding an
  • address to an interface is an operator step (ip addr add …).

  • A route wins over the default transport, but not over an explicit
  • aegis_transport row: the transport map lists the manual entries first.

  • Removing a relay does not flush the queue. Messages already queued keep
  • their aegis-relay1: transport and are deferred; flush or requeue them after the change.

  • Every relay is a unix service in master.cf; a name that collides with a
  • Postfix built-in (smtp, relay, lmtp, …) is rejected by the name regex only if it does not start with a letter — otherwise give it a distinct name.