#ssl
aegis ssl inspects and generates the certificates Aegis services ask for by name. There are two sources and one rule: a valid Let's Encrypt lineage is preferred, and a self-signed certificate is generated locally when no issued one covers the name.
| source | location | used for |
|---|---|---|
letsencrypt | <certbot.data_dir>/live/<name>/{fullchain.pem,privkey.pem} | domains with a public name |
local | <ssl.dir>/local/<name>/{cert.pem,privkey.pem} | IP addresses, internal names, a fallback |
Defaults are /aegis/data/certbot and /aegis/config/ssl. The group has three commands and prints human lines; the global --json flag has no effect here.
| exit code | meaning |
|---|---|
0 | the command finished |
1 | openssl failed, or the name could not be resolved |
2 | argparse rejected the arguments |
#Commands
#aegis ssl list
Lists the certificates this host generated locally, with the remaining days and the certificate path. Let's Encrypt lineages are not listed by this command.
aegis ssl list| argument | default | meaning |
|---|---|---|
| — | — | the command takes no options |
aegis ssl listaegis ssl list # after `ssl ensure`name left certificate──────────── ──── ─────────────────────────────────────────────203.0.113.10 825d /aegis/config/ssl/local/203.0.113.10/cert.pemintranet 812d /aegis/config/ssl/local/intranet/cert.pemleft is the number of days until notAfter, computed by openssl x509 against the current time. -1d means the check failed, which is what an expired certificate and an unreadable file both look like. A host with nothing generated prints ℹ no local certificates yet and exits 0.
#aegis ssl ensure
Creates a self-signed certificate for a name, or returns the existing one when it is still valid. The key is EC P-256; the certificate is SHA-256, valid for ssl.days (825 by default), with CN set to the first name and one SAN entry per name.
aegis ssl ensure <name> --san=<name>... --force| argument | default | meaning |
|---|---|---|
<name> | — | directory name; with no --san it is also the CN and the only SAN |
--san | the name itself | repeatable; when given, it replaces the default list, so repeat the main name if it must be covered |
--force | off | regenerate even when a valid certificate exists |
Names are classified for the SAN field: anything that parses as an IP address becomes IP:…, everything else DNS:…. The directory is the name with every character outside letters, digits, . and - replaced by _.
aegis ssl ensure 203.0.113.10aegis ssl ensure intranet --san=intranet --san=intranet.local --san=10.0.0.5aegis ssl ensure intranet --force✔ intranet: /aegis/config/ssl/local/intranet/cert.pem (key /aegis/config/ssl/local/intranet/privkey.pem)An existing certificate that has not expired is returned without touching the files; --force regenerates it. Files are written with 0600 on the key and 0644 on the certificate. When openssl refuses, the command prints the last lines of its output and exits 1:
✖ openssl could not create the certificateThe last lines of the openssl output follow on stderr.
#aegis ssl show
Prints the certificate a service would receive for one name: where it comes from, the two paths, and the remaining days.
aegis ssl show <name>| argument | default | meaning |
|---|---|---|
<name> | — | the name a service asks for: a domain, a host name or an IP |
aegis ssl show example.comaegis ssl show 203.0.113.10Issued certificate:
name: example.comsource: letsencryptchain: /aegis/data/certbot/live/example.com/fullchain.pemkey: /aegis/data/certbot/live/example.com/privkey.pemexpires: 62 daysLocal certificate:
name: 203.0.113.10source: localchain: /aegis/config/ssl/local/203.0.113.10/cert.pemkey: /aegis/config/ssl/local/203.0.113.10/privkey.pemexpires: 825 daysResolution order:
ssl.resolve: an issued lineage whose SANs cover the name — including aone-label wildcard such as *.example.com — otherwise generate a local certificate for the name.
Two consequences worth knowing:
show is not completely read-only. When steps 1 and 2 find nothing and noissued certificate covers the name, step 3 creates the local certificate and prints its path.
printed with expires: -1 days; show does not fall through to the local certificate for it. Services use resolve, which skips an expired issued certificate, so check the expires line rather than assuming the two agree.
expires: -1 days means openssl x509 -checkend 0 failed for the file, which is what both an expired certificate and an unreadable one look like. A name whose resolution fails prints the error and exits 1.