Aegis documentation

#OpenDKIM

The OpenDKIM cube signs outgoing mail and publishes the matching public keys. It owns opendkim.conf, the key table, the signing table and the trusted-hosts file under opendkim.config_dir (/aegis/config/opendkim), the per-domain key pairs under opendkim.key_dir (/aegis/data/opendkim/keys), the pid file under run/opendkim and the filter log. The milter listens on inet:<opendkim.port>@127.0.0.1 (default 8891) for Postfix.

Its input is the mail database: every active domain in aegis_domains gets a selector, and the selector column decides the key name. configure generates a 2048-bit key for each missing domain, writes the tables, and publishes the TXT record into the BIND zone when this server is authoritative for the domain. The filter runs as the keeper service aegis-opendkim.

#Common commands

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

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

VerbEffect
configuregenerate missing keys, render the tables and config, publish TXT records, validate
validaterun opendkim -n -x <main conf> without starting
reloadrestart the filter — a SIGHUP only terminates the worker
statusread run/opendkim/opendkim.pid: running (pid N) or stopped
startstart the filter through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint paths, milter socket and key count, then publish the DKIM tools
helpprint the command list with examples

#configure

bash
aegis cubes opendkim configureaegis --json cubes opendkim configure

Keys are created only when missing, so an existing key is never replaced. When the filter is running and a key was generated, it is restarted, because the signing table is read at startup. Publishing skips domains whose zone this server does not host.

text
✔ opendkim: 2 domains, generated example.net, 1 TXT published; configuration is valid{"ok": true, "cube": "opendkim", "result": "2 domains, generated example.net, 1 TXT published; configuration is valid"}

#validate

bash
aegis cubes opendkim validateaegis --json cubes opendkim validate

Parses the configuration with -n; nothing is started and no table is rewritten.

text
✔ opendkim: configuration is valid{"ok": true, "cube": "opendkim", "result": "configuration is valid"}

#reload

bash
aegis cubes opendkim reloadaegis --json cubes opendkim reload

Stops and starts the filter. A stopped filter fails with opendkim is not running; use start for that case.

text
✔ opendkim: stopped (pid 1401), started (pid 1422){"ok": true, "cube": "opendkim", "result": "stopped (pid 1401), started (pid 1422)"}

#status

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

#start

bash
aegis cubes opendkim startaegis --json cubes opendkim start
text
✔ opendkim: started (pid 1401){"ok": true, "cube": "opendkim", "result": "started (pid 1401)"}

#stop

bash
aegis cubes opendkim stopaegis --json cubes opendkim stop

Outgoing mail is no longer signed while the filter is down; Postfix keeps delivering, because the milter is optional at that point only if main.cf says so.

text
✔ opendkim: stopped (pid 1401){"ok": true, "cube": "opendkim", "result": "stopped (pid 1401)"}

#restart

bash
aegis cubes opendkim restartaegis --json cubes opendkim restart
text
✔ opendkim: stopped (pid 1401), started (pid 1440){"ok": true, "cube": "opendkim", "result": "stopped (pid 1401), started (pid 1440)"}

#expose

bash
aegis cubes opendkim exposeaegis --json cubes opendkim expose

keys counts the private keys on disk, not the domains.

text
cube           opendkiminstalled      /aegis/apps/mail/opendkim/2.11configuration  /aegis/config/opendkimstate          running (pid 1401)pid            1401log            /aegis/config/opendkim/opendkim.logconfig         /aegis/config/opendkim/aegis-opendkim.confsocket         inet:8891@127.0.0.1key table      /aegis/config/opendkim/aegis-key.tablekeys           4published      /aegis/bin/opendkim, /aegis/bin/opendkim-genkey, /aegis/bin/opendkim-testkey
text
{"ok": true, "cube": "opendkim", "installed": "/aegis/apps/mail/opendkim/2.11", "configuration": "/aegis/config/opendkim", "state": "running (pid 1401)", "pid": "1401", "log": "/aegis/config/opendkim/opendkim.log", "config": "/aegis/config/opendkim/aegis-opendkim.conf", "socket": "inet:8891@127.0.0.1", "key table": "/aegis/config/opendkim/aegis-key.table", "keys": "4", "published": "/aegis/bin/opendkim, /aegis/bin/opendkim-genkey, /aegis/bin/opendkim-testkey"}

#help

bash
aegis cubes opendkim helpaegis cubes help opendkim
text
ℹ Opendkim — DKIM signing keys and their DNS recordsCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Generate keys, write config and publish DNS  start      Start the filter  stop       Stop the filter  status     Show whether the filter runs  restart    Restart the filter  expose     Show where it is installed and how it runs  keys       Manage DKIM keys  help       Show every command with examples

The examples block follows.

#Keys

text
aegis cubes opendkim keys  Manage DKIM keysCommands  list      List domains and key state  generate  Create and publish one key  publish   Publish the TXT records  show      Print the TXT recordRun 'aegis cubes opendkim keys <command> --help' for the options of one command.

#keys list

bash
aegis cubes opendkim keys listaegis --json cubes opendkim keys list

One entry per active mail domain: present when the private key exists, missing otherwise. It takes no options.

text
✔ opendkim: example.com (mail): present; example.net (mail): missing{"ok": true, "cube": "opendkim", "result": "example.com (mail): present; example.net (mail): missing"}

#keys generate

bash
aegis cubes opendkim keys generate example.comaegis --json cubes opendkim keys generate example.net
ArgumentMeaning
domainan active mail domain

Generates a 2048-bit key for the domain's selector, publishes the TXT record, then runs configure to refresh the tables. A domain that is not active in the mail database fails with <domain> is not an active mail domain.

text
✔ opendkim: generated; mail._domainkey.example.com published{"ok": true, "cube": "opendkim", "result": "key already present; mail._domainkey.example.net already published"}

#keys publish

bash
aegis cubes opendkim keys publish example.comaegis cubes opendkim keys publish
ArgumentMeaning
domainoptional; omit to publish every active domain

Adds the selector record to the zone when it is absent, replaces a stale record for the same selector, and validates and applies the zone once at the end of the batch. A domain whose DNS is hosted elsewhere keeps its key but gets no record.

text
✔ opendkim: mail._domainkey.example.com already published{"ok": true, "cube": "opendkim", "result": "mail._domainkey.example.com already published; mail._domainkey.example.net published"}

#keys show

bash
aegis cubes opendkim keys show example.comaegis --json cubes opendkim keys show example.com

Prints the zone line that publishes the selector. A 2048-bit key does not fit a single DNS string, so the value is split into 255-character quoted chunks on one line.

text
✔ opendkim: mail._domainkey IN TXT ( "v=DKIM1; k=rsa; p=JsZpzQgUrEDlModSshxKpkUNFileTuwwNWoGqRHCOYOq6+EtXaOO7r/BshO+ZQSY34QZGU1aJsfgpQrxVoU8eSbGac0IFKxA5TKHUrIcSqZFDRYpXk7sMDVqBqkRwjmDquvhLV2jju6/wbITvmUEmN+EGRlNWibH4KUK8VaFPHkmxmnNCBSsQOUyh1KyHEqmRQ0WKV5O7DA1agapEcI5g6rr4S1do47uv8GyE75lBJjfhBkZTVomx+ClCvFWhTx" "5JsZpzQgUrEDlModSshxKpkUNFileTuwwNWoGqRHCOYOq6+EtXaOO7r/BshO+ZQSY34QZGU1aJsfgpQrxVoU8eSbGac0IFKxA5TKHUrIcSqZFDRYpXk7sMDVqBqkRwjmDquvhLV2j" )

The second chunk is the remainder of the same key; a longer key simply produces more chunks.