Configuration reference

Configuration is TOML. The default location is /etc/syscert/syscert.toml; override it with --config <path> or the SYSCERT_CONFIG environment variable (precedence: --config flag → SYSCERT_CONFIG → default). The shipped systemd unit reads SYSCERT_CONFIG from /etc/default/syscert, so you can point the service at a different file once, with no unit edit.

Ready-to-edit files live in the repo’s examples/ — a fully-commented full.toml covering every option, plus focused starters for Let’s Encrypt, Vault and step-ca.

Secrets never go in this file. DNS-provider tokens, CA credentials and the EAB HMAC are read from the environment (typically /etc/syscert/secrets, mode 0640) and are never logged. See [acme.dns].

[cert] — certificate subject

[cert]
hostname = "host.example.com"
sans     = ["www.example.com"]
key_type = "ec256"

[acme] — CA and challenge

Which directory_url for your CA

Challenge support differs by CA. Vault PKI ACME supports http-01 and tls-alpn-01 only — not dns-01. step-ca supports all three. Let’s Encrypt supports dns-01, http-01, tls-alpn-01.

# Let's Encrypt (production) via DNS-01
[acme]
ca        = "letsencrypt"
email     = "you@example.com"
challenge = "dns-01"

# HashiCorp Vault (internal CA) via HTTP-01
[acme]
ca            = "custom"
directory_url = "https://vault.example.com:8200/v1/pki/acme/directory"
email         = "you@example.com"
challenge     = "http-01"

[acme.dns] — DNS provider + credentials

Used only when challenge is dns-01 or dns-persist-01.

Credentials are supplied via the environment (or a restricted secrets file), never in the config. Each lego provider reads its own variables — e.g. CLOUDFLARE_DNS_API_TOKEN (cloudflare), GANDIV5_PERSONAL_ACCESS_TOKEN (Gandi LiveDNS), or AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION (route53). See the lego provider docs for the exact names.

[acme.dns]
provider          = "gandiv5"
propagation_check = "authoritative"   # only if the local resolver is slow to see public DNS

[acme.eab] — External Account Binding

Some CAs require External Account Binding to register an ACME account: they issue a Key ID + HMAC key out-of-band and the client proves possession at registration. Used by Vault (eab_policy), step-ca (requireEAB), and public CAs like ZeroSSL / Google / SSL.com.

The HMAC key is a secret — supply it via SYSCERT_EAB_HMAC (the base64url key the CA gave you) in /etc/syscert/secrets, never in the TOML and never logged. EAB is checked by the CA only when the account is first created; syscert reuses its persistent account key afterwards.

[acme.eab]
kid = "kid-from-your-ca"          # + export SYSCERT_EAB_HMAC=<base64url-hmac> in /etc/syscert/secrets

[store] — canonical store

[bundle] — all-in-one file

Controls the composition of bundle.pem.

[bundle]
order = ["key", "cert", "chain"]   # key first, no root

The root is dropped automatically when the CA provides none (public CAs). If key is present, any target receiving bundle must use a non-world-readable mode.

[[distribute]] — delivering to consumers

Zero or more blocks; each copies one artifact to a path with the ownership/mode/context that consumer needs. syscert overwrites only the paths it manages and does not reload consumers — see Distributing certs.

[[distribute]]
artifact = "fullchain"
path     = "/etc/nginx/tls/fullchain.pem"
owner    = "root"
group    = "root"
mode     = "0644"

[[distribute]]
artifact = "privkey"
path     = "/etc/nginx/tls/privkey.pem"
owner    = "root"
group    = "root"
mode     = "0600"

[renewal] / [logging]

Operational logs (events, errors, and lego’s ACME output) go to stderr; command results and prompts go to stdout. Secret values are never logged.

Next: Distributing certs · Troubleshooting · full.toml on GitHub