ACME lets a certificate authority (CA) verify that you control a domain and issue its TLS certificate. Fluxheim can obtain, store and renew that certificate, then load it for new HTTPS connections. It does not create DNS records or open your firewall. You still own those parts of deployment.
This guide describes the current implementation, including known scheduling limitations. See the complete ACME options for defaults, recovery and incident operations, and the certificate lifecycle guide for deeper details. Configuration examples are templates: replace domains, paths, contact and issuer agreement. They do not authorize accepting a CA's terms on your behalf.
| Workflow | Configuration | Who runs renewal? |
|---|---|---|
| One serving process | automation = "background" |
Fluxheim checks certificates, then sleeps for check_interval_secs after each tick |
| Timer or separate renewal container | automation = "external" |
Your scheduler runs fluxheim-acme renew; the server still serves challenges |
| Certificates supplied by another tool | Static [vhosts.tls.certificate] paths |
That tool; do not enable managed ACME for the same certificate |
Use a build with acme-client for issuance. The companion validates the ACME
parts of the same server configuration without requiring unrelated cache/PHP
features or a PHP executable. Starting the webserver still requires full server
validation. Do not switch to a full image just to renew a PHP site's certificate.
Choose one renewal owner per deployment. Sharing state does not make two independent schedulers a coordinated fleet. Keep the server and companion on the same protected storage and compatible configuration; do not independently copy only the certificate file while dropping its private key or account state.
Start with the HTTP-01 template. It explicitly listens on loopback HTTP 8080 and HTTPS 8443. Those are application ports, not a promise of public reachability. A container deployment would normally bind inside the container on its interfaces and publish public TCP 80 to 8080 and TCP 443 to 8443. A loopback-only listener inside a container cannot receive that published traffic. On a host, configure the desired public listen addresses and arrange port forwarding or privileged-port binding separately.
- Point every requested public domain at the gateway. Make any advertised
IPv6 path work as well as IPv4. Use real domains you control, not
.test. - Create a private persistent ACME directory accessible to the service user.
On Unix use mode
0700; private keys and EAB secret files need0600. On Windows use the documented private ACL policy, not Unix mode commands. - Set the contact email, storage, vhost hosts and certificate domains.
hostsselects requests;domainsselects names on the certificate. Adding a name to a certificate alone does not configure HTTP routing for that name. - Begin with a staging CA. Define an explicit issuer entry and review its advertised HTTPS terms URL. Only then set agreement to true. An explicit issuer array replaces the built-in list, so include every issuer you use.
- Validate the configuration and storage as the service user, then run the server. Ensure public HTTP port 80 reaches its challenge handler.
- After issuance, verify HTTPS from outside the deployment, including SNI and the returned chain. Staging certificates are not publicly trusted. Change to your intended production issuer only after testing and reviewing its terms.
The template intentionally leaves agreement false:
[[tls.acme.issuers]]
name = "letsencrypt-staging"
directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"
terms_of_service_agreed = false
# After reviewing the CA's exact advertised URL:
# terms_of_service_url = "https://..."
# Change terms_of_service_agreed above to true; do not duplicate the key.These commands check local configuration/state, not public validation:
fluxheim --config /etc/fluxheim/fluxheim.toml --check-tls-storage
fluxheim-acme --config /etc/fluxheim/fluxheim.toml targets
fluxheim-acme --config /etc/fluxheim/fluxheim.toml status
fluxheim-acme --config /etc/fluxheim/fluxheim.toml doctordoctor is offline by default but is not read-only: it creates storage and
recovers managed certificate transactions. With doctor --online, HTTP-01
also writes a temporary probe and requests the domain's HTTP port 80. The
TLS-ALPN-01 doctor check is only TCP reachability to port 443, not proof that a
CA can complete an ALPN challenge. Neither doctor mode replaces real issuance.
Managed certificates can initially be missing. The server may start with that SNI pending; HTTPS then uses an available fallback or fails until issuance and reload. This exception does not allow missing operator-provided static keys.
HTTP-01 serves token files beneath /.well-known/acme-challenge/. Keep that
path reachable by the CA even when the rest of the site redirects to HTTPS.
Fluxheim's managed challenge handling has its own route; an external HTTP-01
forwarder takes precedence if you enable one on the same vhost.
the documented limitation: native TLS-ALPN-01 serving is incomplete. Use HTTP-01 for managed issuance today. The accepted configuration below is not a working alternative merely because it validates:
[tls.acme]
# Keep the other settings from the base template.
challenge = "tls-alpn-01"This is a replacement field in the existing table, not a second table to paste
at the bottom. It requires rustls and a TLS listener. However, the native listener
does not attach the challenge-capable resolver/store: with the root application's
ACME/TLS features it negotiates acme-tls/1 but serves an ordinary fallback
certificate, even when challenge files exist and after certificate reload. The
loopback handshake characterization checks that mismatch. The certificate-generation
and resolver primitives exist; their production integration does not.
The correction must prove actual CA validation, in-process and external
publication/removal, correct SNI and strict ALPN selection. Public port 443 and a
TLS path that preserves acme-tls/1 remain prerequisites, not a fix for the missing
integration. DNS-01 and wildcard certificate issuance are not supported.
To forward HTTP-01 to a different ACME agent instead of Fluxheim's token store:
[vhosts.acme_challenge]
enabled = true
upstream = "127.0.0.1:8090"
connect_timeout_secs = 5
read_timeout_secs = 10
send_timeout_secs = 10That agent must actually serve the challenge path. This does not run the agent, register an account, copy its certificate or reload Fluxheim for it. Prefer a single challenge owner. See the option reference for multiple upstreams/TLS.
The built-in names are letsencrypt, letsencrypt-staging, actalis,
google-trust-services and google-trust-services-staging. These are configured
directory mappings, not guarantees of current CA availability or eligibility.
Custom issuers require a unique name and HTTPS directory URL. Use a private
ca_bundle_file trust configuration for an internal test CA; do not disable
server verification to make a staging endpoint work.
Some issuers require External Account Binding (EAB). This binds a new ACME account to credentials from that issuer. The Actalis template uses systemd credentials. Containers can instead mount two read-only secret files and replace its EAB table with:
[tls.acme.issuers.eab]
key_id_file = "/run/secrets/actalis-eab-kid"
hmac_key_file = "/run/secrets/actalis-eab-hmac-key"Environment and systemd-credential alternatives, constraints and defaults are listed in the reference. Select exactly one source for each value. Never put the HMAC secret into a command argument, checked-in TOML, diagnostic output or this documentation. Protect secret parents as well as the files themselves.
fluxheim-acme status shows the local plan and observed expiry, not a live CA
decision. Choose the policy under [tls.acme.renewal]:
| Goal | Settings | What happens |
|---|---|---|
| Normal renewal (default) | enabled = true, no renew_after |
Use the local schedule and issuer renewal information (ARI). |
| Delay routine renewals | Future renew_after, hold_mode = "elective" (default) |
Missing certificates, expiry within seven days (inclusive), or a due issuer-advised renewal can override the date. |
| Freeze automatic issuance | Future renew_after, hold_mode = "absolute" |
No unforced order or ARI lookup until the deadline. Explicit force still works. A missing certificate can stay missing. |
| Turn renewal off | enabled = false |
No background or CLI renewal targets, even with force. Existing certificates stay installed. Re-enable explicitly; no date re-enables renewal. |
For example, to freeze automatic issuance until a maintenance window:
[tls.acme.renewal]
hold_mode = "absolute"
renew_after = 2027-01-01T02:00:00+02:00Before midnight UTC on January 1 in this example, background and CLI due runs skip even missing and expired certificates, without contacting the CA. Neither issuer renewal information (ARI) nor the emergency window overrides the hold. At the deadline normal scheduling resumes; it does not force a fresh certificate to renew. Only an explicit forced renewal bypasses the hold. Choose the deadline carefully: a held site can remain without a usable certificate.
To delay only routine work, change the example to hold_mode = "elective".
If upgrading from a development build that treated every date as an absolute
freeze, set hold_mode = "absolute" explicitly to preserve that behavior.
To switch off both scheduled and forced renewals, use:
[tls.acme.renewal]
enabled = falseWith renewal off, run fluxheim-acme --config /etc/fluxheim/fluxheim.toml status
to check the installed leaf certificate for every managed vhost. Add
--vhost NAME after status to check just one. This is a local read:
it does not create storage, read the private key, contact the CA or renew.
For example, target: shop status=missing renewal=off not_after=missing
means the vhost is managed but no certificate is installed.
The exit status is nonzero if a selected leaf is missing, invalid, unreadable, not yet valid, expired, or expires within seven days (inclusive). All selected vhosts are reported even when one fails. A parsed leaf reports its expiry as Unix seconds. A successful inventory checks dates only: it does not prove that the live listener serves the leaf or that a client trusts the chain.
Other scheduling considerations:
- Current limitation:
retry_initial_secsandretry_max_secsvalidate but the background loop does not use them for per-target failure backoff. It runs a tick, then waitscheck_interval_secs. Keep that interval conservative and monitor failures; lowering it can repeatedly retry a failing CA. - Current limitation: background renewal reloads whenever a reload handle exists,
irrespective of
reload_after_renewal. The companion and reload-control service planning do honor that flag.zero_downtime_reloadhas no runtime consumer; setting false does not select a restart-based reload mode.
For a deliberate pause, stop the external timer/renewal invocation and use
automation = "external" to stop background scheduling. Leaving
renewal.enabled = true keeps targets available for intentional companion
operations. Setting it false removes renewal targets, including forced
renewals. Apply changes through the supported config/service lifecycle; editing
the TOML alone does not update a running process. Monitor expiry during any pause.
ARI is an advisory CA renewal window. The implementation uses bounded lookups and a process-local cache, with expiry-based fallback and an emergency seven-day window. It is separate from failed-issuance backoff. A fresh companion process does not inherit a previous process's ARI cache.
For an external workflow on Unix:
fluxheim-acme --config /etc/fluxheim/fluxheim.toml renew
fluxheim-acme --config /etc/fluxheim/fluxheim.toml status --vhost site.example.test
fluxheim-acme --config /etc/fluxheim/fluxheim.toml reloadrenew --vhost NAME selects one target; --force-renew bypasses ordinary due
selection and can consume CA limits. --no-reload installs without requesting
the gateway's Unix certificate-reload socket. The legacy fluxheim acme-renew
also installs but does not request that socket. Installation and serving the
new certificate are distinct steps; verify the certificate on a new connection.
The companion's reload command requires Unix sockets and is unavailable on
Windows. For external Windows renewal use --no-reload, then the supported
server lifecycle to load the new pair. Background renewal uses the in-process
handle and is a different path. Do not infer socket support from Windows ACME
issuance support.
| Symptom | Check |
|---|---|
| No targets | Global TLS/ACME, vhost TLS/ACME, concrete domains and renewal enabled |
| Agreement error | Exact issuer entry, reviewed terms URL, explicit acceptance |
| HTTP-01 failure | DNS, public port 80, container listen/publish addresses, correct vhost, external-forwarder precedence |
| TLS-ALPN-01 failure | Native challenge serving is incomplete; use HTTP-01 rather than repeatedly forcing orders |
| Files renewed but old certificate served | Reload result, serving process storage, default-vhost/SNI routing; use a new TLS connection |
| EAB/ownership error | Secret source, service identity, mounts, symlinks and writable ancestors; do not solve by making keys public |
| Repeated renewal failures | CA errors/limits, clock, credentials and the current unwired backoff limitation |
For issuer selection, registration, EAB and account incident limitations, see ACME accounts and issuers. In particular, account deactivation can misreport remote outcomes; do not use its exit status as confirmation that an account was deactivated.
Keep the persistent storage through upgrades; account credentials are not
disposable cache. Use the recovery guide for backups, ambiguous transaction
recovery and revocation. account-deactivate --issuer NAME --confirm and
revoke --vhost NAME --confirm are destructive remote operations, not smoke
tests. account-rollover is exposed by the CLI but currently fails closed
because crash-safe key rollover is not implemented. Do not delete recovery
journals to force an ambiguous operation through.
The coverage ledger separates configuration tests, current-behavior reproductions and outstanding real-CA/platform qualification. This guide is not a claim that all certificate lifecycle failure cases have been freshly retested.