Aegis documentation

#Cube: opendkim

OpenDKIM 2.11 as a milter: one RSA key per mail domain, generated on first configure and published as a TXT record through the bind cube.

In the panel: Mail → DKIM settings; the TXT record is on DNS Manager. Every write there is a task.

#Configuration

toml
[opendkim]port = 8891user = "postfix"                  # account the filter drops toconfig_dir = "/aegis/config/opendkim"key_dir = "/aegis/data/opendkim/keys"selector = "mail"                 # default for new domains
KeyDefaultMeaning
port8891milter socket port on 127.0.0.1
userpostfixaccount the keys must be readable by
config_dir/aegis/config/opendkimopendkim.conf, key/signing tables, pid
key_dir/aegis/data/opendkim/keys<domain>/<selector>.private
selectormailfallback when aegis_domains.dkim_selector is empty

Per-domain selectors live in the mail database, not here.

#Files

text
<opendkim.config_dir>/├── opendkim.conf            filter configuration├── key.table                selector name -> domain:selector:key-file├── signing.table            *@domain -> selector name└── trusted.hosts            hosts and domains whose mail is signed<opendkim.key_dir>/└── <domain>/    ├── <selector>.private   mode 0600    └── <selector>.txt       public key in zone format<aegis.root>/run/opendkim/└── opendkim.pid

key.table, signing.table and trusted.hosts are regenerated from the database on every configure: adding a domain is a row plus a key, never a hand edit.

#Commands

bash
aegis cubes opendkim configure          # keys for every domain, tables, configaegis cubes opendkim validate           # opendkim -n -x <conf>aegis cubes opendkim reload             # restart (tables are re-read at start)aegis cubes opendkim start|stop|restart|statusaegis cubes opendkim keys listaegis cubes opendkim keys generate <domain>aegis cubes opendkim keys publish domainaegis cubes opendkim keys show <domain>aegis cubes opendkim expose

Every table behind this is documented in schema.md.

#Key lifecycle

bash
aegis cubes opendkim keys listaegis cubes opendkim keys generate inhive.dev     # 2048-bit, selector from the DBaegis cubes opendkim keys show inhive.dev         # the TXT recordaegis cubes opendkim keys publish                 # all domains

keys generate runs opendkim-genkey -b 2048 -d <domain> -D <key dir> -s <selector> -v, then publishes the record. keys publish is idempotent: it compares the record in the zone with the key and only rewrites when they differ.

#DNS publishing

keys publish goes through the bind cube:

  • the zone is created with the default template when it does not exist;
  • the record is compared with the key — a stale record (rotated key, older
  • release) is removed first, not left next to the new one;

  • named-checkzone runs and the daemon reloads.
  • The value is split into 255-character strings, which is the DNS limit for one TXT string:

    text
    mail._domainkey IN TXT ( "v=DKIM1; k=rsa; p=MIIBIjAN…" "…" )

    #Postfix integration

    The postfix cube renders these lines once OpenDKIM is installed:

    text
    smtpd_milters         = inet:127.0.0.1:8891non_smtpd_milters     = $smtpd_miltersmilter_default_action = accept

    accept is deliberate: an unsigned message is a smaller problem than a stopped mail queue when the filter is down.

    #Process

    toml
    [services.opendkim]command  = <prefix>/sbin/opendkim -x <config_dir>/opendkim.confpid_file = <aegis.root>/run/opendkim/opendkim.pid

    Two details that cost time to find:

  • -p is not the pid file. On the command line -p sets the *milter
  • socket*; the pid file comes from PidFile in opendkim.conf.

  • The daemon forks. It writes the pid only after daemonising, so the keeper
  • waits up to DAEMON_GRACE (2.5 s) for the pid file instead of declaring the start failed the moment the parent exits.

    #expose

    bash
    aegis cubes opendkim exposecube           opendkiminstalled      /aegis/apps/mail/opendkim/2.11configuration  /aegis/config/opendkimstate          running pid 877393log            /aegis/run/opendkim/config         /aegis/config/opendkim/opendkim.confsocket         inet:8891@127.0.0.1key table      /aegis/config/opendkim/key.tablekeys           2published      /aegis/bin/opendkim /aegis/bin/opendkim-genkey 

    #Verifying

    bash
    dig @127.0.0.1 mail._domainkey.inhive.dev TXT +shortopendkim-testkey -d inhive.dev -s mail -x /aegis/config/opendkim/opendkim.conf -vjournalctl -t opendkim -n 10 --no-pager     # "DKIM-Signature field added"

    opendkim-testkey prints key not secure when the resolver does not validate DNSSEC; that is a warning about the resolver, not about the key.