Aegis documentation

#certbot

The certbot cube configures Let's Encrypt issuance; it does not build certbot, which ships in the bundled Python runtime. It writes two files under certbot.config_dir (/aegis/config/certbot): cli.ini with the ACME defaults, and rfc2136.ini (mode 0600) with the BIND TSIG credentials, so the DNS-01 challenge is answered by the bind cube. Certbot's own state lives under certbot.data_dir (/aegis/data/certbot, with each lineage's certificates in live/<name>/), its work directory and logs beside it. There is no database and no daemon.

The cube also registers the scheduled job ssl-renew, which is what renews certificates; issuance and renewal are separate operations.

#Common commands

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

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

VerbEffect
configurerender cli.ini and rfc2136.ini from the current BIND TSIG key, create the data, work and log directories
validateboth ini files exist and rfc2136.ini carries the current TSIG secret
reloadalways reports that there is nothing to reload
certificatesrun certbot certificates and print its output
exposeprint the ini paths, data directory and number of lineages
helpprint the command list with examples

There is no start, stop, status or restart: certbot runs on demand.

#configure

bash
aegis cubes certbot configureaegis --json cubes certbot configure

Reads the TSIG secret from <dns.config_dir>/keys/tsig.key and fails with no TSIG key at <path> when the bind cube has not configured one yet. The credentials file is written with mode 0600.

text
✔ certbot: configured, cli.ini and rfc2136.ini are consistent with BIND{"ok": true, "cube": "certbot", "result": "configured, cli.ini and rfc2136.ini are consistent with BIND"}

#validate

bash
aegis cubes certbot validateaegis --json cubes certbot validate

Checks that both files exist and that the secret in rfc2136.ini still matches BIND's key — the check that catches a rotated TSIG key before a challenge fails.

text
✔ certbot: cli.ini and rfc2136.ini are consistent with BIND{"ok": true, "cube": "certbot", "result": "cli.ini and rfc2136.ini are consistent with BIND"}

#reload

bash
aegis cubes certbot reloadaegis --json cubes certbot reload

Certbot is not a daemon; the consumers pick a renewed certificate up. The command exists so every cube answers the same verb, and it takes no options.

text
✔ certbot: nothing to reload; services pick the certificate up{"ok": true, "cube": "certbot", "result": "nothing to reload; services pick the certificate up"}

#certificates

bash
aegis cubes certbot certificatesaegis --json cubes certbot certificates

Prints certbot's own report verbatim, one block per lineage. It takes no options.

text
✔ certbot: Saving debug log to /aegis/logs/certbot/letsencrypt.log- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Found the following certs:  Certificate Name: example.com    Serial Number: 4a1f9c2d7b    Key Type: RSA    Domains: example.com www.example.com    Expiry Date: 2026-02-15 09:12:33+00:00 (VALID: 89 days)    Certificate Path: /aegis/data/certbot/live/example.com/fullchain.pem    Private Key Path: /aegis/data/certbot/live/example.com/privkey.pem- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#expose

bash
aegis cubes certbot exposeaegis --json cubes certbot expose

certificates counts the directories under <data_dir>/live. published shows up when /aegis/bin/certbot was written.

text
cube           certbotinstalled      /aegis/apps/tls/certbot/5.10configuration  /aegis/config/certbotcli.ini        /aegis/config/certbot/cli.inicredentials    /aegis/config/certbot/rfc2136.inicertificates   2data           /aegis/data/certbotpublished      /aegis/bin/certbot
text
{"ok": true, "cube": "certbot", "installed": "/aegis/apps/tls/certbot/5.10", "configuration": "/aegis/config/certbot", "cli.ini": "/aegis/config/certbot/cli.ini", "credentials": "/aegis/config/certbot/rfc2136.ini", "certificates": "2", "data": "/aegis/data/certbot", "published": "/aegis/bin/certbot"}

#help

bash
aegis cubes certbot helpaegis cubes help certbot
text
ℹ Certbot — Let's Encrypt certificates through the BIND DNS-01 challengeCommands  validate      Check the configuration  reload        Reload the running daemon  configure     Write cli.ini and the RFC 2136 credentials  certificates  List the issued certificates  expose        Show where it is installed and how it runs  issue         Obtain a certificate  help          Show every command with examples

The examples block follows the command list.

#Issuance

#issue

bash
aegis cubes certbot issue example.com www.example.comaegis --json cubes certbot issue shop.example.com
ArgumentMeaning
domainone or more names; repeatable positionally, at least one required

Runs certbot certonly with --config <cli.ini> and --cert-name set to the first name. Every name is passed as -d, so one lineage covers them all. The DNS-01 challenge is written to BIND with the TSIG key. Without certbot.email the command adds --register-unsafely-without-email.

The certificate name is the lineage name used later by certificates and by the services that load it. A name that already exists updates that lineage rather than creating a second one.

text
✔ certbot: certificate for example.com, www.example.com at /aegis/data/certbot/live/example.com/fullchain.pem{"ok": true, "cube": "certbot", "result": "certificate for shop.example.com at /aegis/data/certbot/live/shop.example.com/fullchain.pem"}

A validation error is reported with the last fifteen lines of certbot's output and exit code 1.

#Renewal

#keeper cron-run ssl-renew

bash
aegis keeper cron-run ssl-renewaegis keeper cron

ssl-renew is registered by this cube with an interval of certbot.renew_interval seconds (default 21600, six hours) and run by the keeper. cron-run executes it immediately, whether it is due or not; cron (the second example) lists the registered jobs with their interval, last run and result. cron-run takes the job name and nothing else.

The job measures the remaining days of every lineage and only calls certbot renew when at least one is inside certbot.renew_days (default 30). After a successful renewal it reloads nginx, postfix and dovecot, skipping any service that is not running.

text
✔ ssl-renew: nothing to renew (window 30d)
text
✔ ssl-renew: renewed example.com; reloaded nginx, dovecot

When it does nothing because no lineage is close to expiry, the exit code is still 0; renewed …; reloaded nothing means the certificate was renewed and no consumer was running.