ACME server
local-cert exposes an ACME endpoint (RFC 8555) at /acme/directory. Any tool that can request a certificate from Let's Encrypt can request it from local-cert instead, for hosts that Let's Encrypt could never reach.
https://certs.example.com/acme/directoryWhat it is, and what it isn't
It is not a certificate authority. local-cert signs nothing: it acts as an intermediary between your ACME client and Let's Encrypt, and the certificate you receive is a real Let's Encrypt certificate, trusted everywhere.
The problem it solves: a regular ACME client proves it controls a name by answering on port 80 (HTTP-01), which requires Let's Encrypt to be able to reach the machine. On a LAN that is impossible. Proving control through DNS (DNS-01) works, but means handing DNS credentials to every machine. local-cert keeps those credentials to itself and does the DNS proof on the client's behalf.
How a certificate is issued
- Registration. The client creates its ACME account by presenting an EAB credential. This happens once; after that it signs with its own account key.
- Order. The client requests a certificate for one or more names. local-cert checks that they belong to a managed domain, and that the EAB credential is allowed on it. Otherwise the order is rejected immediately.
- Challenge. local-cert offers an HTTP-01 challenge, like an ordinary CA. The client prepares its response and signals that it is ready.
- Actual validation. local-cert never fetches the HTTP response. Instead, it opens an order with Let's Encrypt, writes the
_acme-challengeTXT record in your zone, waits for it to propagate, has it validated, then deletes the record. The client's challenge turnsvalidwhen this is done. - Finalization. The client sends its CSR. local-cert forwards it to Let's Encrypt and returns the certificate chain. The private key never left the client.
EAB credentials
EAB stands for External Account Binding. It is the mechanism ACME provides so that a CA only accepts clients it already knows: when creating its account, the client proves it holds a secret handed to it in advance. Here, it replaces the API key.
An EAB credential consists of two values, plus the server URL:
| Value | Where to find it | In this guide |
|---|---|---|
| ACME directory | fixed for each instance | https://certs.example.com/acme/directory |
| Key ID (kid) | Keys & access → EAB credentials | eab_XXXXXXXXXXXXXXXX |
| HMAC key | shown only once, at creation | CLE_HMAC |
It is created in Keys & access → EAB credentials → + New credential, with:
- a name, so you know which client it was handed to;
- an optional expiry;
- the allowed domains: the client can only request certificates under those.
Good to know
- The HMAC key is displayed only once. If you lose it, you must create a new credential.
- The client only uses it at registration, but local-cert re-reads the credential on every request: revoking it or letting it expire also cuts off clients that are already registered.
- One credential can serve several clients. One credential per client lets you cut them off separately and see who issued what.
- The key is base64url-encoded, the format all clients expect (
hmacEncoded,--eab-hmac-key,mac_key…).
What the client must be able to do
Three things, which nearly all modern ACME clients support:
- use a custom directory URL;
- register with an External Account Binding;
- solve an HTTP-01 challenge.
| Tool | Support | Guide |
|---|---|---|
| Traefik | native | open |
| Caddy | native | open |
| Apache httpd | native (mod_md) | open |
| Nginx | via certbot or acme.sh | open |
| HAProxy | via acme.sh | open |
| Nginx Proxy Manager | manual import | open |
| Kubernetes | native (cert-manager) | open |
| Dokploy | native (Traefik) | open |
| Coolify | native (Traefik) | open |
| Synology DSM | via acme.sh | open |
| Proxmox VE | native (pvenode) | open |
| certbot, acme.sh, lego | native | open |
For everything else, see Other systems.
Rules and limits
- A name outside the managed domains is rejected (
rejectedIdentifier); so is a domain the credential isn't authorized for (unauthorized). - All names in a single order must belong to the same managed domain.
- Wildcards (
*.home.example.com) are accepted: since the actual validation is done with DNS-01, the usual HTTP-01 restriction doesn't apply. Some clients nevertheless refuse a wildcard over HTTP-01 on their own. - These certificates show up in Certificates with the
externalkey type, with no private key and no automatic renewal: the client does the renewing. - An ACME account can revoke the certificates it obtained. Account key rollover (
keyChange) is not implemented.
Troubleshooting
| Symptom | Cause |
|---|---|
JWS "url" is … but this endpoint is … | local-cert is behind a proxy that doesn't forward X-Forwarded-Proto / X-Forwarded-Host. Forward them, or set the PUBLIC_URL variable. |
externalAccountRequired | The client is registering without EAB. Check its configuration. |
unauthorized at registration | Unknown, revoked or expired credential, or wrong HMAC key. |
rejectedIdentifier | The requested name is not under any managed domain. |
| The client gives up after ~1 minute | Its timeout is shorter than the DNS validation. Run it again: the order in progress is resumed. |
| TLS error when connecting to local-cert | local-cert is served with a certificate the client doesn't trust. Serve it with a public certificate, or add its CA to the client's trust store. |