Introduction

acme-proxy is an ACME server: the thing certbot, acme.sh, lego, Traefik and Caddy talk to when they ask for a certificate. It serves the whole RFC 8555 flow — account, order, authorization, challenge, finalize, certificate — plus revocation, account key rollover (§7.3.5) and Renewal Information (RFC 9773). What it deliberately does not implement is listed on Protocol Support.

What it does behind that interface is the point. Clients prove control of their names to acme-proxy, under whatever policy you configure, and it decides how the certificate is actually produced — signing locally, relaying to a public CA, or handing the request to a script.

The problem

Internal servers and IoT devices need TLS certificates, and cannot easily get them:

1. Public CAs (like Let’s Encrypt) require DNS or HTTP validation, which internal servers hidden behind firewalls cannot easily satisfy.
2. Handing out the company’s global DNS API credentials to every internal server to perform DNS-01 challenges is a massive security risk.
3. Legacy internal PKI systems often do not speak the ACME protocol, forcing operators to write custom bash scripts to rotate certificates.
4. When using external or commercial CAs, organizations are sometimes restricted to a single account or a limited number of External Account Binding (EAB) credentials validated for specific domains. Distributing these scarce upstream credentials directly to hundreds of internal servers is both impractical and risky.

The solution

acme-proxy solves this by standing between your internal clients and the actual Certificate Authority. By registering a single account with the upstream CA, it acts as an account multiplexer—allowing you to issue unlimited local EAB credentials to your internal teams without exhausting your upstream limits.

graph LR
    subgraph clients["Your network"]
        A["Internal server<br/>certbot"]
        B["IoT device<br/>acme.sh"]
        C["Traefik / Caddy"]
    end

    P{{"acme-proxy"}}

    subgraph backends["One of these actually signs"]
        LOCAL["Embedded CA<br/>key on disk or in an HSM"]
        UP["Upstream ACME CA<br/>Let's Encrypt, ZeroSSL, commercial"]
        SCRIPT["Your script<br/>legacy PKI, internal API"]
    end

    A --> P
    B --> P
    C --> P
    P --> LOCAL
    P --> UP
    P --> SCRIPT

Clients speak ordinary ACME to acme-proxy and prove control of their names to it. Which of the three backends produces the certificate is a configuration choice they never see — and it can differ per endpoint, so one process can serve a local CA at /profile/dev and a Let’s Encrypt relay at /profile/prod.

• As a Proxy: It intercepts ACME requests from internal clients, opens a corresponding order with Let’s Encrypt, and safely solves the external DNS-01 challenges on the client’s behalf using a single, centrally secured DNS TSIG key.
• As a Filter: It inspects the client’s IP and requested DNS names against strict policies — including asking your IPAM (NetBox or phpIPAM) whether that address owns those names — before allowing the request to proceed.
• As a Local CA: It can operate entirely offline, issuing from an embedded ECDSA CA whose key is a file on disk or a PKCS#11 token.
• As a Multi-Tenant Server: Through its Profile system, a single binary can host a Local CA on /profile/dev and a strictly-filtered Let’s Encrypt relay on /profile/prod.
• As a Record: Every issuance and every refusal is written to an append-only audit trail, naming the actor, the address it came from and the names it asked for — the question “who got this certificate, and from where” has an answer.

It is built on axum, tokio and sqlx, and stores everything in one SQLite file in WAL mode. There is no second datastore, no message queue and no scheduler to operate.

It is published on crates.io, so cargo install acme-proxy gets you the whole thing — server and admin CLI in one binary. See Installation.

Core Concepts & Glossary

Eight words carry most of the meaning in the rest of this book. This page defines them once, in the order you meet them, so that every other page can use them without re-explaining.

Profile

A profile is an independent ACME endpoint, and the isolation boundary everything else sits inside. Rather than running one process per environment, you define several profiles in one; each is served at /profile/<name>/directory.

Accounts and orders are isolated per profile — the same client key at two profiles is two unrelated accounts — and each profile carries its own signer, filters, challenge validation and EAB policy. A dev profile backed by a local CA can sit beside a prod profile relaying to Let’s Encrypt under strict NetBox filtering, in one process, over one socket and one database.

See Profiles & Routing.

Signer

A signer is what actually produces the certificate once a client has been authorized. Which one runs is a per-profile configuration choice, and the client never sees the difference.

• Local CA — an embedded certificate authority signing directly. The issuing key is a file, or a PKCS#11 token.
• Relay — opens its own order with an upstream ACME CA and returns what that CA signs.
• Custom script — anything else: a legacy PKI, an internal API, a CA that does not speak ACME.

See Signers.

Filter

A filter is a policy applied to a request before anything is signed. Filters answer “may this client ask for this?”, which challenge validation does not: a client can genuinely control a name and still have no business holding a certificate for it from you.

[filter] is a small policy engine rather than a list of switches. A check is one named question about a request — “is this address in the management network?” — and a rule is a boolean expression over check names plus what a match means. filter.rules says which rules run and in what order, and the first match wins; a stage where a rule was applicable and none matched falls to filter.default.

Rules act at two points — on the connection, and on the identifiers, the latter running again at finalize against the names in the CSR.

See Filters.

EAB (External Account Binding)

External Account Binding (RFC 8555 §7.3.4) makes newAccount require a credential you minted out of band — a key identifier and an HMAC secret. Reaching the directory is then no longer enough to register: an operator has to have issued that client a credential first.

It runs in the other direction too. A commercial CA that granted you one scarce EAB credential is exactly the case the relay backend exists for: one upstream credential, any number of local ones.

See External Account Binding.

ARI (ACME Renewal Information)

ACME Renewal Information (RFC 9773) lets the CA tell a client when to renew, rather than leaving it to guess from the expiry date. Two things follow: a fleet spreads its renewals across a window instead of stampeding at the same moment, and a CA that needs certificates replaced early can say so and be listened to.

See Renewal Information.

Order

An order is a client’s request for a certificate. It names the identifiers wanted and progresses through the states RFC 8555 defines:

• pending — created; one or more authorizations still need to be satisfied.
• ready — every authorization is valid; the client may now finalize.
• processing — issuance is under way but not finished.
• valid — the certificate is available.
• invalid — terminal failure.

stateDiagram-v2
    [*] --> pending: newOrder
    pending --> ready: every authorization valid
    ready --> pending: an authorization is deactivated (§7.5.2)
    ready --> processing: finalize
    processing --> valid: the worker signed
    processing --> invalid: signer refused or gave up
    pending --> invalid: an authorization failed, or expires passed
    valid --> [*]
    invalid --> [*]

acme-proxy enforces these states and transitions in the database itself. The set of states is a CHECK constraint on the status column — see Database Schema — and every transition is an UPDATE guarded on the state it leaves. A validation or a signing that finishes after the order moved on, because the client deactivated an authorization or a sibling challenge already decided it, therefore changes nothing above its own challenge.

ready → pending is the one backwards edge, and it exists only so §7.5.2 can hold: deactivating an authorization on an order that already reached ready has to demote it, or the order would be finalizable for a name no longer authorized.

Two details are easy to trip on:

• Every finalize answers processing. Signing needs the CA key, which only the worker role holds, so finalize checks the CSR, claims the order and queues the signing, and the client polls until the order is valid. With local_ca that is a moment; with relay it is as long as the upstream CA takes. A CSR the backend itself rejects makes the order invalid with a badCSR error, since the client is already polling by then; a CSR finalize can refuse on its own leaves the order ready for a corrected one.
• Revocation is orthogonal to this machine. RFC 8555 defines no “revoked” order status, so a revoked order’s status stays valid. The revocation timestamp and reason are recorded separately, and both admin front ends show them and can revoke — acme-proxy order show/order revoke, and the order detail page in the panel. See Revocation & CRL.

Job

A job is one unit of work the server owes itself: a relayed issuance to finish, a notification to deliver, a table to sweep. Jobs are rows in the same SQLite file as everything else, drained by one runner per process, so they survive a restart and need no scheduler beside the server.

What is worth carrying away is how a handler reports failure. Retry says the attempt decided nothing — a refused connection, a proxy, a 503 — and the job goes back in the queue under a growing backoff; Failed says the other side stated a reason and is believed at once. That split is what keeps a client’s order processing through a five-second upstream blip rather than terminally invalid, and it is why an order that is not progressing is a question for acme-proxy jobs list before it is a question for anything else.

See Admin CLI → Job queue.

Challenge

A challenge is the concrete proof that a client controls an identifier: serving a token over HTTP, publishing a DNS TXT record, or presenting a special certificate in a TLS handshake.

Each authorization carries one challenge per enabled type, and satisfying any one of them makes the authorization valid — the others stay pending for ever, which is correct rather than a stuck state.

Triggering one queues the check rather than performing it, so a triggered challenge answers processing and the client polls it.

See Challenge Validation.

Quick Start

Get acme-proxy running in a couple of minutes with an auto-generated Local CA.

Step 1 — Write a configuration file

acme-proxy serves ACME only through profiles, so at least one enabled profile is required — the server refuses to start without one. Everything else has a working default.

By default the server also performs real domain-control validation (HTTP-01). To test a client against the proxy locally without routing port 80 or configuring DNS, this quick start turns validation off with challenge.bypass.

Create config.toml in your current directory:

[challenge]
# Testing only. See "Moving to production" below.
bypass = true

[profiles.default]

[profiles.default] is not empty by accident — a profile’s enabled key defaults to true, so naming the profile is all that is required. The profile name becomes part of the URL, and of every kid a client stores.

Step 2 — Run the server

acme-proxy serve

serve is also the default, so a bare acme-proxy does the same thing.

There is no --config flag. The server reads config.toml from the current working directory; point it elsewhere with ACME_PROXY_CONFIG:

ACME_PROXY_CONFIG=/etc/acme-proxy/config.toml acme-proxy serve

(The extension may be omitted — the format is then inferred.) A missing configuration file is not an error: the server falls back to defaults, which is why an environment-only deployment works.

Individual keys can also be overridden with ACME_PROXY_* environment variables; see the Configuration Reference.

The server binds [::]:3000 and serves the ACME directory at http://localhost:3000/profile/default/directory. On first run it creates sqlite.db, ca.pem and ca.key in the working directory.

Step 3 — Request a certificate

Point any standard ACME client at the profile’s directory URL. Examples for internal.example.com:

certbot

certbot certonly \
  --server http://localhost:3000/profile/default/directory \
  --standalone \
  --domain internal.example.com \
  --email admin@example.com \
  --agree-tos \
  --no-eff-email

acme.sh

acme.sh --issue \
  --server http://localhost:3000/profile/default/directory \
  -d internal.example.com \
  --standalone

lego

lego --server http://localhost:3000/profile/default/directory \
  --email admin@example.com \
  --domains internal.example.com \
  --http \
  run

Traefik

In Traefik’s static configuration (traefik.yml):

certificatesResolvers:
  myresolver:
    acme:
      caServer: http://localhost:3000/profile/default/directory
      email: admin@example.com
      httpChallenge:
        entryPoint: web

Caddy

In your Caddyfile:

internal.example.com {
    tls admin@example.com {
        ca http://localhost:3000/profile/default/directory
    }
    respond "Hello, world!"
}

What just happened?

1. The client fetched the directory from acme-proxy.
2. It registered an account and created a new order.
3. acme-proxy offered an HTTP-01 challenge.
4. Because challenge.bypass = true, the proxy marked the challenge valid the moment the client triggered it, without making any network request back to the client’s responder.
5. The proxy signed the CSR with its auto-generated local ECDSA CA and returned the certificate.

The certificate is signed by a CA nothing trusts yet. See Trusting the CA for how to install ca.pem where your clients will accept it.

Step 4 — Moving to production

The defaults are safe; this quick start deliberately relaxed them. Before exposing the server:

1. Remove the bypass. Delete challenge.bypass = true so acme-proxy actually validates domain control. With bypass on, [filter] is the only access control there is — which is exactly why bypass is not the default. See Challenge Validation.
2. Enable filters. Configure allowed_ip, identifiers or ipam to restrict which clients may request which names. See Filters & Policies.
3. Choose where state lives. The defaults write sqlite.db and the CA material to the current working directory. Set database.url and signer.local_ca.cert_path / signer.local_ca.key_path to permanent paths — note these are the CA’s files, distinct from server.tls.cert_path / server.tls.key_path, which belong to the HTTPS listener.
4. Serve over HTTPS. RFC 8555 §6.1 expects ACME over HTTPS: either put the server behind a reverse proxy, or turn on TLS termination.

Installation

acme-proxy is a Rust application, published on crates.io. There are four ways to get it: cargo install, a source build, the published container image, or a container image you build yourself. Only the published image comes prebuilt; no standalone prebuilt binaries are published.

The result is a single binary carrying both the server and the admin CLI, so a deployment never needs a second tool.

Prerequisites

• Rust toolchain: the crate is edition 2024 and declares a rust-version in Cargo.toml (currently 1.97). That file is the source of truth; cargo refuses to build with anything older.
• Cargo: the Rust package manager.

SQLite is not a prerequisite: the driver is bundled with sqlx, the database file is created automatically, and DATABASE_URL is not needed to compile. The PostgreSQL driver is bundled the same way, so the same binary speaks both — what it does need is a server and a database that already exist. A sqlite3 binary is only useful if you want to inspect the database by hand.

You can install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

From crates.io

cargo install acme-proxy

This fetches the published crate, compiles it, and puts the binary in ~/.cargo/bin — which needs to be on your PATH. Confirm it with:

acme-proxy --version

Tab completion and a man page come out of the binary itself, so there is nothing extra to download:

acme-proxy completions zsh > ~/.zfunc/_acme-proxy
acme-proxy man | sudo tee /usr/share/man/man1/acme-proxy.1 > /dev/null

Both are generated from the command tree, so regenerate them when you upgrade. The per-shell paths are in the admin CLI chapter.

To pin a version, or to move to a specific one later, name it:

cargo install acme-proxy --version 0.6.0

Upgrading is cargo install acme-proxy --force. Before doing so across a minor version, read the ### Breaking section of the changelog. Before 1.0.0 the database schema is the only compatibility guarantee, so the data survives an upgrade but a configuration key may have been renamed.

Building from source

Prefer this if you intend to change anything, or want the test suite and the book sources alongside the binary.

1. Clone the repository:

   git clone https://github.com/acme-proxy/acme-proxy.git
   cd acme-proxy
   

2. Build the project in release mode for production use:

   cargo build --release
   

The binary will be located at target/release/acme-proxy.

Optional features

The default build has no optional features. One is available:

cargo install acme-proxy --features hsm    # or, from a clone:
cargo build --release --features hsm

It is off by default because it pulls in cryptoki and its bindings, which a deployment signing with an on-disk key does not need. The PKCS#11 module itself is loaded at runtime, so enabling this adds no build-time C toolchain requirement. Configuring signer.local_ca.key_source = "pkcs11" on a binary built without it is a startup error naming the feature, never a silent fallback to the file key.

The published container image is the default build, without hsm. A deployment that needs it builds its own binary.

Container (Docker / Podman)

Every release is published to the GitHub Container Registry as a multi-architecture image, for linux/amd64 and linux/arm64:

podman pull ghcr.io/acme-proxy/acme-proxy:0.6.0

Run a version tag, or 0.6 to take patch releases without a change on your side. Avoid latest for an unattended deployment. Before 1.0.0 a minor release may rename a configuration key, so a pull of latest can stop a server from starting; the ### Breaking sections of the changelog list every such change. edge is for trying what the next release will hold, never for a certificate authority anyone depends on.

Every image holds the release build with the default features: the binary cargo install acme-proxy produces.

To build the image yourself instead, use the Containerfile in a clone of the repository:

podman build -t acme-proxy .

That is the same release build as the published image, fat LTO included, so it takes tens of minutes.

The image’s working directory is /data and its entrypoint is the acme-proxy binary, so mount a volume there for the SQLite database, the configuration and the CA key material — all of which default to paths relative to the working directory. The image runs as a non-root user, so the mounted directory must be writable by it — the :U flag below is the rootless-Podman way; see Deployment for Docker.

podman run -d \
  -p 3000:3000 \
  -v ./data:/data:U \
  ghcr.io/acme-proxy/acme-proxy:0.6.0

Drop a config.toml into ./data (it must define at least one profile — see the Quick Start), or configure the container entirely through ACME_PROXY_* environment variables:

podman run -d \
  -p 3000:3000 \
  -v ./data:/data:U \
  -e ACME_PROXY_PROFILES__DEFAULT__ENABLED=true \
  -e ACME_PROXY_SERVER__BASE_URL=https://acme.example.com \
  ghcr.io/acme-proxy/acme-proxy:0.6.0

Verifying the image

Each published image carries a signed build provenance attestation. It records the repository, the commit and the workflow run that built the image. Check it with the GitHub CLI before you run the image:

gh attestation verify oci://ghcr.io/acme-proxy/acme-proxy:0.6.0 \
  --repo acme-proxy/acme-proxy

The attestation is on the multi-architecture index, the object a tag resolves to. The digest of one architecture’s image, on its own, has no attestation to find.

Trusting the CA

With the local_ca signer, acme-proxy mints certificates from a CA it generated itself. Those certificates are perfectly valid, but nothing on your network trusts the CA that signed them yet — so browsers, curl, and every TLS library will reject them until you install the root.

This page covers distributing that root. It does not apply when you use the relay backend to relay to a public CA, whose roots are already trusted everywhere.

Getting the root certificate

Each profile serves its own CA material unauthenticated at {base_url}/profile/<name>/ca.pem, as application/x-pem-file:

curl -o internal-root.pem https://acme.internal/profile/default/ca.pem

These are exactly the bytes appended to every certificate that profile issues, so a client that fetches them here and one that reads the tail of its own chain end up trusting the same anchor.

Two things worth knowing about the route. It is not advertised in the ACME directory — it is CA infrastructure rather than an ACME resource, so a client will not find it on its own and you distribute the URL yourself. And it is served inside the profile router, which means it sits behind that profile’s filter policy: if you restrict the endpoint by address, the hosts that most need the root — the ones that do not have it yet — may be exactly the ones refused. Add a path check allowing /ca.pem if so.

The same file is on the server’s disk at signer.local_ca.cert_path, ca.pem by default in the working directory, which is the way to get it when the server is not reachable or is not running:

scp acme-host:/var/lib/acme-proxy/ca.pem ./internal-root.pem

Inspect it before distributing it:

openssl x509 -in internal-root.pem -noout -subject -issuer -dates -ext basicConstraints

A freshly generated root is self-signed (subject equals issuer) and carries CA:TRUE, pathlen:0.

If cert_path holds a bundle — an intermediate followed by a root, as in the multi-tier setup — then the last certificate in the file is the root, and it is the only one your clients need to trust. The intermediate is shipped with every issued certificate and does not need installing.

# Split a bundle into its constituent certificates.
csplit -z -f cert- -b '%02d.pem' ca_bundle.pem '/-----BEGIN CERTIFICATE-----/' '{*}'

Installing it

Debian / Ubuntu

The file must have a .crt extension, and must be PEM despite the name.

sudo cp internal-root.pem /usr/local/share/ca-certificates/acme-proxy-root.crt
sudo update-ca-certificates

RHEL / Fedora / CentOS

sudo cp internal-root.pem /etc/pki/ca-trust/source/anchors/acme-proxy-root.pem
sudo update-ca-trust extract

Alpine

sudo cp internal-root.pem /usr/local/share/ca-certificates/acme-proxy-root.crt
sudo update-ca-certificates

Verify

curl -v https://internal.example.com 2>&1 | grep -i 'SSL certificate verify'
# or, without a server:
openssl verify -CAfile internal-root.pem issued-cert.pem

Applications with their own trust store

Updating the system store is not enough for everything. These maintain their own:

Distributing at scale

Installing a root by hand does not survive a fleet. In practice:

• Ansible / Puppet / Chef — ship the file and run the update command as a handler. This is the common approach for Linux estates.
• Active Directory Group Policy — Computer Configuration → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities.
• MDM (Jamf, Intune, …) — deploy as a certificate payload.
• Golden images — bake the root into your base image so new hosts trust it from first boot.

Whichever you use, deploy the root before you start issuing certificates from it, or the first clients to renew will break.

Revocation

If you revoke certificates, clients need to be able to see the CRL. It is served unauthenticated at {base_url}/profile/<name>/crl as application/pkix-crl:

curl -o internal.crl https://acme.internal/profile/default/crl
openssl crl -in internal.crl -inform DER -noout -text

Like /ca.pem, the CRL is not advertised in the ACME directory and sits behind the profile’s filter policy. Issued certificates carry a CRL distribution point only when you set signer.local_ca.crl_distribution_points; leave it unset and a client will not find the CRL automatically, so distribute the URL alongside the root if your validation policy needs it. See Revocation & CRL.

Planning ahead

The root’s validity is finite, and replacing it later means touching every host that trusts it. Two things make that easier:

• Use an intermediate. Keep an offline root and hand acme-proxy only an intermediate. The root you distribute then long outlives any single signing key, and a compromised proxy costs you an intermediate rather than your whole trust anchor. See Multi-Tier PKI.
• Distribute early, rotate overlapping. Trust stores accept multiple roots, so push a replacement root well before it is needed and remove the old one only after nothing is signed by it.

Deployment

While acme-proxy can be run in a container, many organizations prefer running infrastructure components directly on standard Linux VMs using systemd.

systemd service setup

Below is an example systemd service file that runs acme-proxy securely.

1. Create a dedicated user:

   sudo useradd -r -s /bin/false acme-proxy
   

2. Prepare directories:

   sudo mkdir -p /etc/acme-proxy
   sudo mkdir -p /var/lib/acme-proxy
   sudo chown acme-proxy:acme-proxy /var/lib/acme-proxy
   

3. Create the service file: Create /etc/systemd/system/acme-proxy.service:

   [Unit]
   Description=ACME Proxy Server
   After=network.target
   
   [Service]
   Type=simple
   User=acme-proxy
   Group=acme-proxy
   ExecStart=/usr/local/bin/acme-proxy serve
   ExecReload=/bin/kill -HUP $MAINPID
   WorkingDirectory=/var/lib/acme-proxy
   
   # Configuration. The extension may be omitted, in which case the format
   # is inferred.
   Environment="ACME_PROXY_CONFIG=/etc/acme-proxy/config.toml"
   Environment="ACME_PROXY_DATABASE__URL=sqlite:///var/lib/acme-proxy/acme.db"
   
   # Security / Sandboxing
   ProtectSystem=strict
   ReadWritePaths=/var/lib/acme-proxy
   ProtectHome=true
   PrivateTmp=true
   NoNewPrivileges=true
   
   Restart=on-failure
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   

ProtectSystem=strict makes the whole filesystem read-only except ReadWritePaths, so everything the server writes must land in /var/lib/acme-proxy. With WorkingDirectory set there, the defaults already do: signer.local_ca.cert_path (ca.pem), key_path (ca.key), crl_path (ca.crl) and the lock beside it are all resolved relative to the working directory, as are server.tls.cert_path / key_path if you enable TLS. If you set any of them to an absolute path, add that path to ReadWritePaths too.

acme-proxy shuts down gracefully on SIGTERM (and on Ctrl+C when run in a terminal), so systemctl restart and systemctl stop let in-flight requests finish rather than cutting them off. Both listeners stop together. It also reloads its configuration on SIGHUP without restarting, which is what the ExecReload line above wires up — see Reloading the Configuration for what a reload may change and what it refuses. One case still deserves a quiet period: a request that waits — a custom script’s crl or renewal_info hook, or a relay revocation waiting on its job — can take up to server.request_timeout_ms. If systemd’s TimeoutStopSec (90 s by default) is shorter than that, systemd sends SIGKILL first and the graceful path is skipped — raise it, or lower the request timeout. Challenge validation and issuance are not among these: they run in the job queue, and a job left unfinished by a restart is reclaimed by lease expiry.

4. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable --now acme-proxy
   

Where each socket belongs

acme-proxy opens two listeners when the web admin is enabled, and they belong on different sides of your boundary. The ACME listener answers unauthenticated clients by design; the admin listener has no filter chain and no admission control, and its only access controls are the bind address, TLS and the session.

graph TD
    subgraph internal["Internal network"]
        CLIENTS["ACME clients<br/>certbot, acme.sh, Traefik"]
        OPS["Operator workstation"]
    end

    subgraph host["The acme-proxy host"]
        RP["Reverse proxy (optional)<br/>sets X-Forwarded-For"]
        ACME[":3000 — ACME listener<br/>filters, admission, nonces"]
        ADMIN[":3001 — admin listener<br/>loopback by default"]
        DB[("sqlite.db + WAL")]
        CAKEY[["ca.key — 0600, or a PKCS#11 token"]]
    end

    CLIENTS --> RP --> ACME
    OPS -.->|"SSH tunnel or VPN,<br/>NOT an open port"| ADMIN
    ACME --> DB
    ADMIN --> DB
    ACME --> CAKEY

    ACME -->|"challenge validation:<br/>back to the client, :80 / :443 / DNS"| CLIENTS
    ACME -->|"upstream ACME, DNS updates, SMTP"| OUT(["Egress"])

Two edges are the ones people get wrong:

• The dotted one. If the admin listener is reachable from anywhere but loopback, startup refuses unless admin.tls.enabled is on — and even then, a tunnel is the better answer. See below.
• The validation edge points back at the client. With challenge.bypass = false, the server opens connections to the machines asking for certificates. A firewall that only permits inbound traffic leaves orders sitting at pending.

Reverse proxy (optional)

acme-proxy acts as an HTTP server, typically binding to port 3000. You can bind it directly to 80 (requires CAP_NET_BIND_SERVICE) or place it behind a reverse proxy like Nginx or Traefik, which can provide TLS termination for the ACME API itself.

Two things to get right when proxying:

• Set server.base_url to the public URL. It is what the directory advertises and what every signed request is checked against (RFC 8555 §6.4), so a mismatch rejects every client. It is never derived from the request.
• If you want IP-based filters to see the real client rather than the proxy, set filter.trusted_proxies to the proxy’s addresses and, if it is not x-forwarded-for, filter.forwarded_header. Note these are [filter] keys, not [server] keys.

Alternatively, skip the reverse proxy and let acme-proxy terminate TLS itself — see TLS Termination.

Exposing the web admin (or rather, not)

The Web Admin is a second listener and is off by default. When you turn it on, it binds 127.0.0.1:3001 and stays there unless you say otherwise.

The recommended way to reach it is an SSH tunnel, which needs no configuration change and no second certificate:

$ ssh -N -L 3001:127.0.0.1:3001 ca.example.com

Then open http://localhost:3001. admin.base_url stays at its default, because from the browser’s point of view the panel really is on localhost.

If you must bind it to a real interface, TLS is mandatory — startup refuses a non-loopback bind while admin.tls.enabled is false, because the session cookie is sent Secure and a browser silently declines to store one over plain HTTP anywhere but localhost:

[admin]
enabled      = true
bind_address = "0.0.0.0:3001"
base_url     = "https://admin.example.com:3001"

[admin.tls]
enabled = true

Two things this listener does not have, deliberately: admission control and a filter chain. Access control here is the bind address, TLS, and the session. Note also that it does not honour X-Forwarded-For — behind a reverse proxy the sign-in rate limiter counts the proxy, which is one more reason to prefer the tunnel.

Under systemd, nothing extra is needed: the panel shares the process, the unit and the database. Bootstrap the first operator once, before or after enabling it:

$ printf '%s' "$PASSWORD" | acme-proxy admin user create alice

Container deployments (Docker / Podman)

For containerized environments, you can run acme-proxy using Docker Compose or Podman.

Each release is published as ghcr.io/acme-proxy/acme-proxy:<version>, for linux/amd64 and linux/arm64, and the examples below pin one. Installation covers why to pin, building the image yourself from the Containerfile, and verifying its provenance:

podman pull ghcr.io/acme-proxy/acme-proxy:0.6.0

The image’s working directory is /data and its entrypoint is the binary itself, so /data is where the database, the CA key material and the CRL land unless you override their paths.

The image runs as a non-root user (acme-proxy, uid/gid 1000), so the directory you mount at /data must be writable by that uid. How you arrange that depends on the runtime:

• Rootless Podman — add U to the mount flags (-v ./data:/data:U, or :Z,U on SELinux systems). Podman then chowns the volume’s contents to the user the container runs as. Alternatives: podman unshare chown -R 1000:1000 ./data beforehand, or use a named volume (-v acme-proxy-data:/data), which Podman initializes with the right owner.
• Docker / Docker Compose — create the directory owned by uid 1000 before the first run: mkdir -p ./data && sudo chown 1000:1000 ./data. Or override the uid to your own (--user "$(id -u):$(id -g)", or a Compose user: line) and own ./data yourself — the server only needs to read and write that one directory.

Docker Compose

Create a docker-compose.yml file:

services:
  acme-proxy:
    image: ghcr.io/acme-proxy/acme-proxy:0.6.0
    container_name: acme-proxy
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - ACME_PROXY_PROFILES__DEFAULT__ENABLED=true
      - ACME_PROXY_DATABASE__URL=sqlite:///data/acme.db
      - RUST_LOG=acme_proxy=info

Create the data directory with the right owner before the first run:

mkdir -p ./data && sudo chown 1000:1000 ./data

Run the stack using:

docker compose up -d

ACME_PROXY_PROFILES__DEFAULT__ENABLED=true is what defines the profile when there is no configuration file — the server serves nothing without at least one. For anything beyond a single default profile, mount a config.toml into /data instead.

Podman (rootless)

Under rootless Podman you can run the container directly. The U flag chowns the mounted directory to the non-root user the container runs as; add Z as well on SELinux-enabled systems (RHEL/Fedora) for the mount label.

podman run -d --name acme-proxy \
  -p 3000:3000 \
  -v ./data:/data:U \
  -e ACME_PROXY_PROFILES__DEFAULT__ENABLED=true \
  -e ACME_PROXY_DATABASE__URL=sqlite:///data/acme.db \
  ghcr.io/acme-proxy/acme-proxy:0.6.0

Running the roles as separate processes

acme-proxy serve runs three jobs in one process: serving ACME, serving the web admin, and draining the job queue. --role splits them across processes of the same binary, reading the same configuration.

All-in-one is still the default and nothing about it changes: acme-proxy serve with no --role behaves exactly as it always did. The split is worth doing when you want privilege separation — the process parsing untrusted JWS and CSRs from the internet is then not the one holding operator sessions, and neither is the one making outbound connections to client-chosen hosts. Each can run under its own uid and its own systemd sandbox.

Only the worker holds signing material. finalize queues the signing and answers processing, a revocation is a database row or a queued job, and the CA’s certificate, its CRL and renewal information are served from ca.pem and the database. So the acme and admin processes never read ca.key, never log in to a PKCS#11 token and never use a relay’s upstream account. Make ca.key (0600) readable by the worker’s uid alone; the others need ca.pem and the database. A custom signer’s script must still be present where acme runs if it serves the CRL or renewal information, since those hooks answer a request.

Three things to get right:

1. Initialise once, first. acme-proxy init migrates the database and generates the CA key, the upstream account and any self-signed TLS certificate. Run it as the uid that should own those files. A process that does not run worker refuses to start against a schema that is behind, naming acme-proxy migrate, and without the CA certificate, naming acme-proxy init — so starting the others before the schema or the CA exists fails loudly rather than racing, and never generates a second CA.
2. Give each process its own metrics.bind_address. The counters are per-process memory, so three processes are three scrape targets; sharing one address means the second one to start fails to bind. Set ACME_PROXY_METRICS__BIND_ADDRESS per unit, point each at its own file with ACME_PROXY_CONFIG, or turn metrics.enabled off where you do not want it. Every series carries a role label naming the roles that process runs, so one scrape config can tell them apart.
3. Run at least one worker. A process without it logs server_role_no_worker at startup; a deployment without one issues nothing, because challenge validation, issuance, CRL signing, relay and custom revocations, notifications and the periodic sweeps are all queued work. A worker in another process picks a row up within the job poll interval, so clients see a second or so more processing than all-in-one; a revocation for a relay or custom profile still running when its request’s deadline nears answers 503 with Retry-After, and asking again follows it.

A worked topology, one systemd unit per role:

# acme-proxy-worker.service
ExecStart=/usr/local/bin/acme-proxy serve --role worker
Environment=ACME_PROXY_METRICS__BIND_ADDRESS=127.0.0.1:3002

# acme-proxy-acme.service
ExecStart=/usr/local/bin/acme-proxy serve --role acme
Environment=ACME_PROXY_METRICS__BIND_ADDRESS=127.0.0.1:3012

# acme-proxy-admin.service
ExecStart=/usr/local/bin/acme-proxy serve --role admin
Environment=ACME_PROXY_METRICS__BIND_ADDRESS=127.0.0.1:3022

One host, one filesystem — on SQLite. SQLite across processes is fine on a local disk in WAL mode, and busy_timeout is already set — it is not safe on NFS or across nodes. Multi-node needs PostgreSQL: point database.url at a server instead of a file, run acme-proxy migrate once, and the three roles can then live on different hosts. Nothing else about the deployment changes.

An existing SQLite deployment moves across with its accounts, orders and audit trail intact — stop the server, create and migrate the target, then acme-proxy transfer --to <url>. Starting the new deployment empty instead would leave every certificate it has already issued impossible to revoke, so this is not an optional step.

Run one admin process either way; its login rate limiter is in memory, so two would each get their own budget.

Each process reloads independently on SIGHUP, so a configuration change means reloading all three.

Upgrading

Replace the binary, migrate, and restart. The schema is append-only as of 0.1.0 — a new release only ever adds migrations, never rewrites the ones your database has already applied.

Migrations no longer run as a side effect of opening the database. acme-proxy serve running the worker role (which the default does) still applies them at startup, so a single-process deployment can simply restart; anything else — an admin command, or a split deployment’s acme/admin process — checks the schema and refuses by name until acme-proxy migrate has run.

systemctl stop acme-proxy
install -m 0755 acme-proxy /usr/local/bin/acme-proxy
acme-proxy migrate          # explicit; the default `serve` would also do it
systemctl start acme-proxy
journalctl -u acme-proxy -n 50

A container is upgraded the same way, with the image tag in place of the binary: pull the new tag, migrate with it against the same /data, then recreate the container on it. With Docker Compose, after changing the image: line:

docker compose pull
docker compose stop acme-proxy
docker compose run --rm acme-proxy migrate
docker compose up -d
docker compose logs -n 50 acme-proxy

migrate after the service name replaces the image’s default serve command for that one container. A single-container deployment would also migrate as it starts; running it as a step of its own stops the upgrade on the error, instead of leaving a server in a restart loop. A split deployment must migrate before any of its acme or admin containers start on the new tag. The advice below applies unchanged, the database backup first of all.

Worth knowing before you do it:

• Take a copy of the database first. SQLite in WAL mode means three files; copy them together with the server stopped, or use sqlite3 acme.db ".backup backup.db" on a running one. Migrations are not reversible, so a downgrade means restoring this copy.
• db_migration_failed at startup means the process is not serving. The most likely cause is running an older binary against a database a newer one has already migrated.
• Files outside the database are untouched. The CA key and certificate, the exported ca.crl, the upstream account key and its .kid sidecar all persist across an upgrade — back them up on the same schedule as the database, since the CA key is the one thing that cannot be regenerated without redistributing trust. See Trusting the CA.
• Read the changelog’s Breaking section first. Before 1.0.0 the schema is the only compatibility guarantee: configuration keys, profile names, the admin JSON API, log event names and the CLI may all have moved, and every such change is listed there. See Compatibility. A renamed key is normally refused by name at startup — the server stops with an error naming the replacement rather than coming up looking configured — so acme-proxy filter show and a --help are cheap pre-restart checks.

TLS Termination

ACME strictly expects traffic over HTTPS (RFC 8555 §6.1).

While you can place acme-proxy behind a reverse proxy (like Nginx, HAProxy, or Traefik) and let it terminate TLS, acme-proxy is fully capable of terminating TLS itself via the highly secure rustls crate.

Architectural security (Slowloris protection)

Terminating TLS in async frameworks requires care to avoid denial-of-service vectors. In acme-proxy, handshakes run off the accept path. When a TCP connection arrives, a background task spawns the TLS handshake into a bounded channel. The handshake is strictly bounded by handshake_timeout_ms. If this were done inline, a single stalled client (e.g., a Slowloris attack) could block every other connection for the length of the timeout.

Client IP preservation

Under the hood, acme-proxy wraps the TLS listener in a TapIo struct. This is load-bearing. Without this wrapper, the Axum HTTP layer would lose visibility into the underlying TCP socket’s peer address once TLS is wrapped around it. By using TapIo, acme-proxy ensures that the allowed_ip and reverse_dns filters can correctly identify the true client IP, failing closed if it cannot be determined.

Configuration

To serve HTTPS directly, configure the [server.tls] section.

Note: Setting server.tls.enabled = true replaces the cleartext HTTP listener entirely. You do not get both HTTP and HTTPS simultaneously.

[server]
base_url = "https://acme.internal:3000"
bind_address = "[::]:3000"

[server.tls]
enabled = true

# The PEM encoded certificate chain (leaf first) and private key
cert_path = "server.pem"
key_path  = "server.key"

# Budget for one TLS handshake
handshake_timeout_ms = 10000

If cert_path or key_path files are missing on disk at startup, acme-proxy will automatically generate a self-signed certificate for the host specified in server.base_url and write it to disk.

The web admin listener

[admin.tls] is the same mechanism on a second socket: the same load-or-generate provisioning, the same TapIo wrapper preserving the peer address, the same 0600 on a generated key. Only the defaults differ.

[admin.tls]
enabled   = true
cert_path = "admin.pem"     # not server.pem
key_path  = "admin.key"

The paths are separate on purpose: the two listeners answer to different names (admin.base_url versus server.base_url, and a generated certificate takes its name from whichever applies), and sharing one certificate between them should be a decision, not an accident. The log lines carry a listener field ("acme" or "admin") so certificate churn on one is distinguishable from the other.

Unlike the ACME listener, TLS here is not optional once the panel leaves loopback — startup refuses that combination outright. See Web Admin.

Profiles

acme-proxy is a multi-tenant ACME server. It serves ACME entirely through Profiles.

A single process, running on a single port with a single database, can host multiple isolated ACME endpoints. Each profile is mounted under the /profile/<name>/directory namespace.

Why use profiles?

• Serve an internal self-signed CA at /profile/local/directory for dev environments.
• Serve a strict Let’s Encrypt relay at /profile/prod/directory for production services.
• Apply different network filters (e.g., strict IP allowlists for production, bypass for dev) without needing to run multiple binary instances.

One process, several endpoints

Everything below the router is per profile — its own signer, filters, challenge validators and EAB policy. Everything above it is shared: one socket, one database, one process.

graph TD
    REQ["Incoming request"] --> ROOT["Root router<br/>/health, /, tracing, hardening headers"]
    ROOT -->|"/profile/dev/*"| PDEV["Profile: dev"]
    ROOT -->|"/profile/prod/*"| PPROD["Profile: prod"]
    ROOT -->|"/profile/staging/*"| PSTG["Profile: staging"]

    PDEV --> SDEV["signer: local_ca<br/>filters: none"]
    PPROD --> SPROD["signer: relay<br/>filters: ipam"]
    PSTG --> SSTG["signer: local_ca<br/>filters: none"]

    SDEV --> B1["Arc&lt;dyn SignerBackend&gt; #1"]
    SSTG --> B1
    SPROD --> B2["Arc&lt;dyn SignerBackend&gt; #2"]

    B1 --> DB[("one SQLite file<br/>rows tagged by profile")]
    B2 --> DB

Note the fan-in: dev and staging have identical [signer] sections, so they share one backend instance rather than constructing two. Two profiles sharing ca.key while differing elsewhere is a startup error: one CA key under two configurations would issue under two policies from one identity — two different crl_distribution_points for one CRL, say — and that is refused rather than left to half-work.

Hard database isolation

Profiles act as a strict isolation boundary in the SQLite database.

The accounts table uses a constraint: UNIQUE(profile, pubkey). This means if a client registers a key at /profile/default, and then uses the exact same cryptographic key to connect to /profile/le, the database creates two independent ACME accounts. This ensures endpoints cannot cross-pollinate authorizations, orders, or nonces.

Inheritance and configuration

Profiles inherit from the base (global) configuration keys. A profile only needs to override the specific keys that differ.

Eight sections can be overridden, and no others: signer, filter, ipam, challenge, eab, order, notify and meta. Everything else — the listen socket, the database, logging, audit, the admin listener — is process-wide.

graph LR
    ENV["ACME_PROXY_* env"] --> BASE
    FILE["config.toml"] --> BASE["Base configuration"]
    BASE --> MERGE{{"merge, per key"}}
    OVR["[profiles.prod]<br/>only the keys that differ"] --> MERGE
    MERGE --> EFF["Effective configuration<br/>for profile 'prod'"]

Inheritance is per key, not per section. A profile that sets only challenge.bypass keeps the global challenge.enabled rather than reverting it to the compiled default. Arrays, however, replace wholesale — they never append. Precedence is: profile key, then global key, then compiled default.

That split is why [filter] is shaped the way it is. filter.rules is an array, so a profile naming its own rules replaces the sequence outright — which is right, because order is the policy. [filter.check.<name>] and [filter.rule.<name>] are tables, so they merge per key, and a profile can dry-run one rule without restating anything:

[profiles.staging.filter.rule.inventory-owned]
mode = "warn"

A profile inherits every globally defined check and cannot remove one, which costs nothing: a check no selected rule names is never built. A global [filter] section can therefore carry a library of checks and each profile pick the subset its own filter.rules uses.

[signer]
backend = "local_ca"

[filter]
rules = ["corp-only"] # The base selection; each profile may replace it

# The library. Both checks and both rules are declared once, globally.
[filter.check.corp-net]
type  = "allowed_ip"
allow = ["10.0.0.0/8"]

[filter.check.corp-names]
type  = "identifiers"
allow = ["*.corp.example.com"]

[filter.rule.corp-only]
when = "corp-net"
then = "allow"

[filter.rule.named-and-corp]
when = "corp-net and corp-names"
then = "allow"

# Profile 1: Uses the global local_ca, and the inherited address-only rule.
# `corp-names` is named by no rule it selects, so it is never built.
[profiles.default]
enabled = true

# Profile 2: Relays to Let's Encrypt, and replaces the selection with the
# stricter rule — which is what pulls `corp-names` into existence here.
[profiles.le]
enabled = true
signer.backend = "relay"
signer.relay.directory_url = "https://acme-v02.api.letsencrypt.org/directory"
filter.rules = ["named-and-corp"]

acme-proxy filter show --profile <name> prints the built policy for one profile, which is the quickest way to confirm a profile selected what you intended. A check that no selected rule names is reported as filter_check_unused — an advisory, not an error.

At runtime, acme-proxy deduplicates the signer backends in memory so that two profiles sharing the exact same signer configuration (e.g., two profiles using the same local_ca) don’t duplicate background polling threads or memory overhead.

Signers

The signer is what actually produces a certificate, once the client has proved control of its names and the filters have allowed the request. Everything before this point is the same whichever backend you choose; everything after it is the backend’s business.

There are three, and they answer three different questions.

Choosing one

Start from what has to trust the certificate:

• Only your own machines? local_ca. You distribute the CA certificate once (see Trusting the CA) and the whole thing works offline, including revocation via the CRL.
• Browsers, partners, anything you do not control? You need a public CA, so relay. Your internal clients keep proving control to this server — over HTTP, DNS or TLS, whichever suits them — while the upstream challenge is solved once, centrally, with a credential no client ever holds.
• An existing corporate PKI that issues by ticket, script or API? custom. It is the escape hatch, and it is deliberately a shell contract rather than a plugin API, so anything that can be scripted can be a signer.

Nothing stops you from running more than one. [signer] is a per-profile section, so a local_ca at /profile/dev can sit beside a relay at /profile/prod in the same process.

What every backend has to provide

All three implement the same trait, and the shape of it is worth knowing because it is what the rest of the server can rely on. It comes in two halves, split by who holds the key: the backend — issue, revoke — is built only by the process running the worker role, and the read side — the CRL, the trust anchor, renewal information — is built by every process from public material, so the one parsing client requests never holds signing material:

• issue — the only required capability. It receives the order’s identifiers and the client’s CSR and returns a chain, or refuses with badCSR.
• revoke — must be idempotent. Revoking twice is not an error, because the server cannot always know whether a previous attempt reached the authority.
• crl_der and renewal_info — optional, and default to “nothing to say here”. local_ca publishes a CRL; the relay passes the upstream’s renewal window through, explanationURL and all.

issue never runs inside a client’s request: finalize queues it, answers the order processing, and the worker calls the backend. A backend may itself answer processing rather than a certificate, meaning “this finishes later”. Only the relay does — signing upstream takes as long as the upstream takes — and the order simply stays processing until it has.

Configuration

[signer]
backend = "local_ca"   # or "relay", or "custom"

Each backend then reads its own table — [signer.local_ca], [signer.relay], [signer.custom] — documented on its own page.

Reference

backend (String) — Default: "local_ca" | Env: ACME_PROXY_SIGNER__BACKEND

Which backend issues certificates: local_ca, relay or custom. Any other value is a startup error.

Backends are shared by configuration, not per profile

Two profiles whose [signer] sections are identical share one backend instance rather than constructing two. Revocations and the CRL live in the database, keyed by the CA’s key, so two instances over one CA would still agree on what is revoked; what they could not agree on is everything else in the section.

Two profiles sharing ca.key while differing anywhere else in [signer] is therefore a startup error, not a race to discover later. See Profiles & Routing.

Local CA Signer

The local_ca backend uses an internal ECDSA key to act as a fully functional Certificate Authority. It is capable of generating its own self-signed root, or it can act as a subordinate (Intermediate) CA if provided with an existing key and certificate.

Reach for it for development environments, CI pipelines, and isolated internal networks — anywhere the certificates only need to be trusted by machines you control.

Security constraints

When processing a Certificate Signing Request (CSR) from a client, the local_ca is deeply distrustful of the requested extensions:

1. Overwriting Extensions: The Local CA overwrites every extension the CSR asked for before signing — a fresh random serial, fixed key usages, and its own validity window. This matters more than it sounds: the CSR parser otherwise copies a requested basicConstraints/keyUsage straight into the signed leaf.
2. Basic Constraints: The issued leaf is never a CA. Without the reset above, a client authorized for one name could submit a CSR carrying CA:TRUE
   • keyCertSign and receive a working intermediate CA, which it could then use to mint arbitrary trusted certificates. (In implementation terms the leaf is built with IsCa::NoCa rather than ExplicitNoCa — an explicit CA:FALSE broke certbot’s chain parser — but the security property is the same.)
3. Subject Alternative Names (SANs): The DNS SANs in the CSR must be exactly the set of identifiers the order authorized — no more, no fewer — or issuance fails with badCSR.
4. Non-DNS SANs are rejected, not stripped: a CSR carrying an IP, email or URI SAN is refused outright with badCSR. Do not expect local_ca to quietly drop them.
5. The subject is emptied: the issued leaf carries no distinguished name at all, so a Common Name in the CSR cannot leak into it. (A CN that looks like a domain the order does not cover is separately rejected earlier, at finalize — see Troubleshooting.)

Certificate validity

Leaves are valid for leaf_validity_days, starting one hour in the past to absorb clock skew between the CA and its clients.

A client may narrow that window using the order’s notBefore/notAfter (RFC 8555 §7.4), but never widen it: a requested start is honoured only if it is later than the default start, and a requested end only if it is earlier than the default end. A request whose clamped window would be empty or inverted is discarded whole, the policy default is used, and a local_ca_requested_validity_discarded warning is logged.

Configuration

[signer]
backend = "local_ca"

[signer.local_ca]
cert_path = "ca.pem"
key_path = "ca.key"
key_type = "ecdsa-p256"
crl_path = "ca.crl"
leaf_validity_days = 90

Reference

cert_path (String) — Default: "ca.pem" | Env: ACME_PROXY_SIGNER__LOCAL_CA__CERT_PATH

The path where the CA certificate is stored. If this file does not exist, a new self-signed Root CA is generated on startup and saved here.

key_path (String) — Default: "ca.key" | Env: ACME_PROXY_SIGNER__LOCAL_CA__KEY_PATH

The path where the CA private key is stored. A generated key is created with mode 0600 at creation time, not chmod’ed afterwards, so there is no window in which another local user could read it.

key_type (String) — Default: "ecdsa-p256" | Env: ACME_PROXY_SIGNER__LOCAL_CA__KEY_TYPE

Algorithm for a generated CA key. "ecdsa-p256" is currently the only accepted value; anything else is a startup error. (An existing key supplied on disk is used as-is, whatever its type.)

crl_path (String) — Default: "ca.crl" | Env: ACME_PROXY_SIGNER__LOCAL_CA__CRL_PATH

Where the current Certificate Revocation List (RFC 5280) is exported as PEM, for publishing from a static web server. The revocations and the CRL GET /crl serves live in the database; this file is rewritten whenever a new CRL is stored and is never read back. Writers lock ca.json.lock beside it, which stays empty. The path also locates the JSON ledger a CA kept before the database did (ca.crl → ca.json), imported once; see Revocation.

crl_distribution_points (Array<String>) — Default: [] | Env: ACME_PROXY_SIGNER__LOCAL_CA__CRL_DISTRIBUTION_POINTS

Where a relying party can fetch that CRL. Each URL is written into every issued leaf as cRLDistributionPoints (RFC 5280 §4.2.1.13); empty — the default — emits no extension at all, which is why a certificate from this CA says nothing about revocation until you set this.

Nothing derives it, deliberately. The URL is frozen into every certificate signed while it is set, so a value read from server.base_url would silently break certificates already issued the day that changed. And this server’s own copy is served at {base_url}/profile/<name>/crl, inside the profile router and therefore behind that profile’s filter policy — an address-based rule would refuse it to exactly the relying parties the extension exists for. Name a URL you know is publicly reachable; a webroot or CDN copy of crl_path is the usual answer.

Several entries mean one CRL reachable in several places, not several different CRLs. http:// is idiomatic and gets no warning: fetching a signed CRL over TLS means validating that connection’s certificate first, which is the loop this extension exists to break. Credentials in the URL, a non-http(s) scheme, and any value the URL parser would normalize (a missing trailing /, a leading space from an environment-variable list) are each a startup error naming the key and the value.

Note that two profiles sharing one CA share this list too: they share one [signer] section, one set of revocations and one CRL, so there is one place that CRL is published. Giving them different URLs while they share ca.key is refused at startup — see Profiles & Routing.

ca_issuer_urls (Array<String>) — Default: [] | Env: ACME_PROXY_SIGNER__LOCAL_CA__CA_ISSUER_URLS

Where a relying party can fetch this CA’s own certificate, written into every issued leaf as authorityInfoAccess with the caIssuers access method (RFC 5280 §4.2.2.1). Empty — the default — emits no extension. Same reasoning, same validation and the same startup errors as crl_distribution_points above.

The sibling access method, id-ad-ocsp, is never written: this server runs no OCSP responder, and a pointer at one that does not exist is worse than none.

leaf_validity_days (Integer) — Default: 90 | Env: ACME_PROXY_SIGNER__LOCAL_CA__LEAF_VALIDITY_DAYS

The validity period (in days) for issued leaf certificates. Distinct from order.validity_seconds, which bounds the ACME order object, not the certificate.

key_source (String) — Default: "file" | Env: ACME_PROXY_SIGNER__LOCAL_CA__KEY_SOURCE

Where the issuing private key lives. "file" is everything described on this page: a PEM key at key_path, loaded or generated. "pkcs11" puts the key in a hardware token instead, and reads the [signer.local_ca.pkcs11] table — see Hardware Keys. Any other value is a startup error, and so is "pkcs11" on a binary built without --features hsm: there is deliberately no silent fallback, since falling back would hand an operator who asked for hardware a software key with no indication of it.

[signer.local_ca.subject]

The X.509 Subject (Distinguished Name) of the CA certificate acme-proxy generates for itself. It is read only on the startup that generates the CA — supplying your own cert_path means supplying your own DN, and editing this table afterwards changes nothing, because the certificate already exists. To change it, retire the CA and generate a new one.

Every key is optional and String-valued. An unset or empty value is omitted from the Subject rather than written blank; the empty string is treated as absent because the environment source cannot distinguish the two. The one exception is common_name, which falls back to "acme-proxy local CA" so the CA always carries one. Leaving the whole table out therefore yields a CommonName-only Subject — which is exactly what this backend produced before the table existed.

This is the CA’s own DN, not the leaf’s. Issued certificates deliberately carry an empty Subject and identify themselves through subjectAltName, which is what every modern client reads.

common_name — Default: "acme-proxy local CA" | Env: ACME_PROXY_SIGNER__LOCAL_CA__SUBJECT__COMMON_NAME

organization — Default: unset | Env: ACME_PROXY_SIGNER__LOCAL_CA__SUBJECT__ORGANIZATION

organizational_unit — Default: unset | Env: ACME_PROXY_SIGNER__LOCAL_CA__SUBJECT__ORGANIZATIONAL_UNIT

country — Default: unset | Env: ACME_PROXY_SIGNER__LOCAL_CA__SUBJECT__COUNTRY

A two-letter ISO 3166-1 country code, e.g. "US".

state — Default: unset | Env: ACME_PROXY_SIGNER__LOCAL_CA__SUBJECT__STATE

locality — Default: unset | Env: ACME_PROXY_SIGNER__LOCAL_CA__SUBJECT__LOCALITY

[signer.local_ca.subject]
common_name  = "Example Corp Internal CA"
organization = "Example Corp"
country      = "US"

Hardware-backed keys

The CA key described above is a file, and a file can be copied. If the CA is one your fleet actually trusts, the issuing key can instead live in a PKCS#11 token — a YubiKey, an enterprise HSM, or SoftHSM2 for development — where it is created once and can never be read back out.

Everything on this page still applies; only where the signature comes from changes. See Hardware Keys (PKCS#11). Note that it requires a build with --features hsm, which is not the default.

Multi-tier PKI (using an intermediate CA)

For production internal deployments, you should avoid using an auto-generated Root CA directly on the server. Instead, you can use a Multi-Tier Hierarchy: create an offline Root CA, use it to sign an Intermediate CA, and hand the Intermediate CA to acme-proxy.

Here is how you can do this in practice using OpenSSL.

Step 1 — Create the offline root CA

Generate a private key and a self-signed Root certificate (keep this key highly secure and offline):

# Generate the Root private key
openssl ecparam -genkey -name prime256v1 -out root_ca.key

# Create the self-signed Root certificate (valid for 10 years)
openssl req -x509 -new -nodes -key root_ca.key -sha256 -days 3650 \
  -out root_ca.pem \
  -subj "/CN=My Company Offline Root CA"

Step 2 — Create the intermediate CA for acme-proxy

Generate the private key and CSR for the Intermediate CA:

# Generate the Intermediate private key
openssl ecparam -genkey -name prime256v1 -out acme_intermediate.key

# Create the CSR
openssl req -new -key acme_intermediate.key -out acme_intermediate.csr \
  -subj "/CN=My Company ACME Intermediate CA"

Create an OpenSSL extension file (v3_ext.cnf) to ensure the Intermediate CA is allowed to sign other certificates:

[ v3_intermediate_ca ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true, pathlen:0
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

(Note: pathlen:0 ensures this intermediate can issue leaf certificates, but cannot issue further intermediate CAs).

Now, sign the Intermediate CSR using the Offline Root CA:

openssl x509 -req -in acme_intermediate.csr -CA root_ca.pem -CAkey root_ca.key \
  -CAcreateserial -out acme_intermediate.pem -days 1825 -sha256 \
  -extfile v3_ext.cnf -extensions v3_intermediate_ca

Step 3 — Configure acme-proxy

Finally, point acme-proxy to your newly minted Intermediate CA. The cert_path must contain the Intermediate certificate followed by the Root certificate (the bundle), so clients can verify the full chain.

cat acme_intermediate.pem root_ca.pem > ca_bundle.pem

Update your config.toml:

[signer.local_ca]
cert_path = "ca_bundle.pem"
key_path = "acme_intermediate.key"

Now acme-proxy issues certificates signed by the Intermediate CA, mirroring a standard enterprise PKI hierarchy.

The order inside the bundle is load-bearing. The signing issuer is parsed from the first PEM block in cert_path; the remaining blocks are only appended to the chain served to clients. Concatenating root-first instead would not fail loudly — it would sign with the root’s identity using the intermediate’s key, producing certificates nothing can verify. Always cat intermediate.pem root.pem, never the reverse.

Two further caveats:

• Nothing checks that key_path actually corresponds to the certificate in cert_path. A mismatched pair produces unverifiable certificates rather than a startup error. (This caveat is specific to key_source = "file"; the PKCS#11 path does verify the pair at startup.)
• The whole bundle is emitted with every issued certificate, root included. Most clients tolerate this, but if you would rather not ship the root, put only the intermediate in cert_path and distribute the root out of band — see Trusting the CA.

Hardware Keys (PKCS#11)

By default the Local CA’s issuing key is a PEM file on disk, protected by nothing but its 0600 permissions. key_source = "pkcs11" moves that key into a hardware token — a YubiKey, a network HSM, or SoftHSM2 for development — where it is created once and can never be read back out. acme-proxy sends the token the bytes to be signed and receives a signature; the private key never enters this process’s memory.

PKCS#11 rather than a vendor-specific PIV library, so a YubiKey today and an enterprise HSM tomorrow are the same configuration with a different module_path.

What this protects, and what it does not

Everything else about the Local CA is unchanged: the same CSR sanitisation, the same leaf_validity_days clamping, the same CRL and revocations. Only where the signature comes from moves.

It protects the CA issuing key — the one that, if stolen, lets an attacker mint certificates your fleet trusts. It does not protect the ACME account keys, the TLS server key (server.tls.key_path), or the database; those stay on disk.

Requirements

• A build with the hsm feature. It is off by default, so the stock binary does not have it and key_source = "pkcs11" on one is a startup error naming the feature:

  cargo build --release --features hsm
  

• A PKCS#11 module (.so), loaded at runtime — nothing is linked at build time.

• An existing CA certificate, for the reason below.

Two rules that differ from the software path

Both are startup errors, so you will meet them immediately rather than in production.

The CA is never generated

With key_source = "file", a missing cert_path/key_path means “generate a CA and write it here”. With key_source = "pkcs11" there is no such thing: the private key is created inside the token by its own tooling, and this server cannot produce one that a token would then hold. So cert_path must already exist, and key_path is neither read nor written.

Both walkthroughs below cover creating that certificate.

The key and the certificate are cross-checked

At startup, the token key’s SubjectPublicKeyInfo is compared against the one in cert_path. A mismatch — almost always a wrong key_label — stops the server.

This is stricter than the file path, where (as Local CA warns) nothing checks that key_path corresponds to cert_path, and a mismatched pair simply produces certificates that verify nowhere. Here a typo is caught before the first certificate is issued rather than discovered by a client days later.

Reference

Reaching this table at all takes signer.local_ca.key_source = "pkcs11", which is documented with the rest of [signer.local_ca] in Local CA. Everything below is [signer.local_ca.pkcs11], read only when that key is set.

pkcs11.module_path (String) — Default: "" | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__MODULE_PATH

The PKCS#11 module to load. Required. See each walkthrough for the usual paths.

pkcs11.token_label (String) — Default: "" | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__TOKEN_LABEL

Which token to use, by label. Preferred over slot_id: slot numbers are assigned dynamically and change across reboots and re-plugs on most drivers (SoftHSM2 will hand you something like 276468771).

pkcs11.slot_id (Integer) — Default: unset | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__SLOT_ID

Which slot to use, for tokens with no usable label. Consulted only when token_label is empty.

pkcs11.key_label (String) — Default: "" | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__KEY_LABEL

The private key’s CKA_LABEL. Required. On a YubiKey the labels are fixed by the driver, so this is something you look up rather than choose — see below.

pkcs11.key_id (String) — Default: "" | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__KEY_ID

The key’s CKA_ID as hex (01, or 01:ff), to disambiguate a token holding several keys under one label. Optional; two keys sharing a label and no key_id to separate them is a startup error rather than a coin flip.

pkcs11.pin_file (String) — Default: "" | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__PIN_FILE

A file holding the user PIN. Trailing whitespace is trimmed, so a PIN written with echo works. The file is checked for permissions and warns if it is world-readable, exactly as ca.key does.

pkcs11.pin (String) — Default: "" | Env: ACME_PROXY_SIGNER__LOCAL_CA__PKCS11__PIN

SENSITIVE. The PIN directly. Prefer pin_file, or set this through the environment variable; a PIN in config.toml is a long-lived secret in a file that tends to get copied around. pin_file wins when both are set, and having neither is a startup error.

A PIN is not a password. Tokens block after a small number of wrong attempts — three on a YubiKey PIV applet, after which you need the PUK. This is why acme-proxy retries a failed signature at most once, and why the trailing newline in your PIN file is worth getting right.

Walkthrough A — SoftHSM2

SoftHSM2 is a software token: no hardware needed, and the same setup the project uses in CI. Use it to try the feature before committing to hardware.

# Debian/Ubuntu
sudo apt install softhsm2
# Arch
sudo pacman -S softhsm

Step 1 — Create a token

softhsm2-util --init-token --free --label acme-ca --so-pin 3737 --pin 1234

--free takes the first uninitialised slot. Note that the token is reassigned to a new slot number afterwards — which is exactly why token_label is the selector to use, not slot_id.

Step 2 — Create the CA key and certificate

The key must exist inside the token, and cert_path must hold a certificate for it. For SoftHSM2 the simplest route is to generate both locally, import the key, and destroy the local copy:

# The CA key and its self-signed certificate
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out ca.key

openssl req -x509 -new -key ca.key -sha256 -days 3650 -out ca.pem \
  -subj "/CN=Example Corp Issuing CA/O=Example Corp" \
  -addext "basicConstraints=critical,CA:true,pathlen:0" \
  -addext "keyUsage=critical,keyCertSign,cRLSign"

# Move the key into the token, then remove it from disk
softhsm2-util --import ca.key --token acme-ca --label ca-key --id 01 --pin 1234
shred -u ca.key

For a real HSM, generate the key in the token instead so it never exists outside it — pkcs11-tool --module <module> --token-label acme-ca --login --keypairgen --key-type EC:prime256v1 --label ca-key --id 01 (from the opensc package), then certify that public key with your offline root. The import above is a development convenience, and the reason it is acceptable here is that a SoftHSM2 token is a directory of files anyway.

pathlen:0 matches what the Local CA generates for itself: it may issue leaves but no further CAs.

Step 3 — Configure

[signer]
backend = "local_ca"

[signer.local_ca]
cert_path  = "ca.pem"
crl_path   = "ca.crl"
key_source = "pkcs11"

[signer.local_ca.pkcs11]
module_path = "/usr/lib/softhsm/libsofthsm2.so"
token_label = "acme-ca"
key_label   = "ca-key"
pin_file    = "/etc/acme-proxy/hsm.pin"

printf '1234' > /etc/acme-proxy/hsm.pin
chmod 600 /etc/acme-proxy/hsm.pin

If SoftHSM2’s token store is not in its default location, SOFTHSM2_CONF must be set in the server’s environment — it is read by the module, not by acme-proxy.

Step 4 — Confirm it is really using the token

RUST_LOG=info acme-proxy serve

INFO acme_proxy::signer::local_ca::pkcs11: the local CA's issuing key is on a PKCS#11 token
  event="local_ca_pkcs11_opened" module=/usr/lib/softhsm/libsofthsm2.so
  slot=276468771 key_label=ca-key algorithm=PKCS_ECDSA_P256_SHA256
  mechanism=CKM_ECDSA_SHA256
INFO acme_proxy::signer::local_ca: event="local_ca_pkcs11_loaded" cert_path="ca.pem" key_label=ca-key

local_ca_pkcs11_opened is the line that proves it: it names the module, the slot the token actually landed in, the curve read off the key, and the mechanism chosen. If you see local_ca_loaded or local_ca_generated instead, the configuration is still on the file path.

Then issue something and check it chains:

openssl verify -CAfile ca.pem /path/to/issued/cert.pem
# cert.pem: OK

Walkthrough B — YubiKey (libykcs11)

A YubiKey 5 exposes its PIV applet through libykcs11, shipped with yubico-piv-tool.

# Debian/Ubuntu → /usr/lib/x86_64-linux-gnu/libykcs11.so
sudo apt install yubico-piv-tool
# Arch → /usr/lib/libykcs11.so
sudo pacman -S yubico-piv-tool

Both paths are in circulation; check which one you have before configuring module_path.

Step 1 — Generate the key and certificate on the device

Use slot 9c (Digital Signature). Its PIV policy requires the PIN for every private-key operation, which is the right posture for a CA key and the reason to prefer it over 9a.

# Generate the key inside the YubiKey — it never leaves
yubico-piv-tool -s 9c -a generate -A ECCP256 -o ca_pub.pem

# Self-sign a certificate for it, on the device
yubico-piv-tool -s 9c -a verify-pin -a selfsign-certificate \
  -S '/CN=Example Corp Issuing CA/O=Example Corp/' \
  --valid-days 3650 -i ca_pub.pem -o ca.pem

# Store the certificate in the slot as well (optional, but conventional)
yubico-piv-tool -s 9c -a import-certificate -i ca.pem

Copy ca.pem to wherever cert_path points.

Touch policy must be never for the CA slot. If the slot is provisioned to require a touch, every issuance blocks until somebody physically touches the key. That is correct for an offline root and catastrophic for an ACME server expected to issue unattended.

Step 2 — Find the key label

You do not choose the label on a YubiKey — libykcs11 assigns fixed ones per PIV slot. Read it off the device:

pkcs11-tool --module /usr/lib/libykcs11.so --list-objects --login

Slot 9c reports as Private key for Digital Signature; 9a as Private key for PIV Authentication. Use that string verbatim.

Step 3 — Configure

[signer.local_ca]
cert_path  = "ca.pem"
crl_path   = "ca.crl"
key_source = "pkcs11"

[signer.local_ca.pkcs11]
module_path = "/usr/lib/libykcs11.so"
token_label = "YubiKey PIV #12345678"
key_label   = "Private key for Digital Signature"
pin_file    = "/etc/acme-proxy/hsm.pin"

The PIN is the PIV PIN (factory default 123456), not the PIV management key and not the FIDO PIN.

Step 4 — Expect CKM_ECDSA

libykcs11 does not offer CKM_ECDSA_SHA256, so acme-proxy computes the SHA-256 digest itself and asks the token to sign that. The startup line reads:

mechanism=CKM_ECDSA+SHA256

This is normal and not a downgrade — the same signature, with the hashing done on this side of the USB cable.

Performance

A YubiKey signature takes roughly 50–300 ms, and signings are serialised by a mutex. That is comfortable for hundreds of certificates a day and is not a throughput solution; the signing call runs on the blocking thread pool, so it does not stall the rest of the server while it waits. For higher volumes use a networked HSM, or the Custom Script signer against a KMS.

Operations

Backup and disaster recovery

The key cannot be backed up. That is the point of the feature, and it makes recovery something to plan before you need it. Two workable approaches:

• Two tokens, one offline root. Keep an offline root CA, use it to certify an intermediate held on each of two tokens, and hand acme-proxy one of them. A lost token is replaced by provisioning a new intermediate; clients trust the root and never notice. See Multi-Tier PKI.
• Accept re-enrolment. For a small internal fleet, losing the CA and distributing a new one is survivable — just make sure it is a decision rather than a discovery.

Revocations live in the database like every other CA’s, so backing up the database backs them up; crl_path is only an export of the current CRL.

When the token disappears

If the session drops — the YubiKey is unplugged, a network HSM times out — acme-proxy reopens the session, logs back in and retries the signature once. The relevant log lines are local_ca_pkcs11_session_lost followed by either a successful issuance or local_ca_pkcs11_reconnect_failed.

If that fails, finalize requests return serverInternal (500) and clients retry, which is the right behaviour: the order stays valid and issuance resumes once the token is back. GET /crl keeps working throughout — the current CRL is read from the database and serving it signs nothing.

Sharing one token between profiles

Several profiles may use the same module, and even the same key. acme-proxy opens one PKCS#11 context per module for the whole process and shares it, so this works without special configuration. Two profiles naming the same token key with otherwise different signer settings is refused at startup, for the same reason two profiles sharing ca.key are: one key under two configurations would issue under two policies from one identity.

Troubleshooting

See also Maintenance & Troubleshooting.

Relay

The relay backend keeps this server answering ACME to its own clients while a real upstream CA does the signing. It captures internal ACME requests and fulfils them through an upstream external CA (Let’s Encrypt, ZeroSSL, or a commercial CA).

How it works

There are two ACME conversations, and keeping them apart is the whole trick to reading this page. acme-proxy is the server in one and the client in the other. Each has its own account, its own account key, its own order and its own challenges, and nothing crosses between them.

sequenceDiagram
    autonumber
    participant C as Internal client<br/>(certbot, acme.sh)
    participant P as acme-proxy
    participant U as Upstream CA<br/>(Let's Encrypt)

    Note over C,P: Conversation 1 — acme-proxy is the SERVER.<br/>Client's own account key, client's own order.
    C->>P: newOrder (example.internal)
    P-->>C: 201, order pending
    C->>P: trigger challenge
    P->>C: validate control (http-01 / dns-01 / tls-alpn-01)
    P-->>C: 200, challenge valid — order ready
    C->>P: finalize (CSR)

    Note over P,U: Conversation 2 — acme-proxy is the CLIENT.<br/>Its OWN upstream account key, a SECOND order.
    P-->>C: 200, order processing
    P->>U: newOrder (same identifiers)
    U-->>P: 201, upstream order pending
    alt challenge_strategy = dns01
        P->>P: publish TXT via RFC 2136 + TSIG
    else challenge_strategy = http01
        P->>P: publish token on its own /.well-known route
    else challenge_strategy = bypass
        P->>U: trigger — the upstream already trusts this account
    end
    U->>P: validate (against the proxy's thumbprint)
    P->>U: finalize (the client's CSR, relayed unchanged)
    U-->>P: certificate

    Note over C,P: Back in conversation 1.
    C->>P: poll order
    P-->>C: 200, order valid + certificate URL

Two consequences fall straight out of the diagram:

• The key authorization at the upstream uses the proxy’s own thumbprint, never the client’s. They are different accounts on different servers, so the client could not answer the upstream’s challenge even in principle.
• finalize stays processing for longer. Every backend’s finalize answers processing and is signed by the worker, but here conversation 2 takes as long as the upstream takes, so the client polls for minutes rather than for the moment local_ca needs — see Core Concepts.

Challenge strategies

The strategy names the one challenge type the proxy answers upstream. A CA offers several — Let’s Encrypt currently poses four — and every type the strategy does not name is ignored, including ones this server has no implementation for at all. Nothing falls back: if the upstream authorization does not offer the type the strategy names, the relay says so and stops, rather than trying a type it could not finish.

dns01 (RFC 2136 TSIG)

This is the strategy that can prove a wildcard. The proxy intercepts internal HTTP-01 or DNS-01 challenges, but to satisfy the external CA, the proxy solves the external DNS-01 challenge itself. It does this using an rfc2136 provider powered by hickory-proto. It securely authenticates with the DNS server using TSIG (Transaction Signature) to publish the TXT record. Note: The TXT record uses the thumbprint of the proxy’s upstream account key, not the internal client’s key.

DNS alias mode

By default the record is written at _acme-challenge.<domain>, so the update key needs write access to every zone a profile issues for. Alias mode moves the record to one name in a zone set aside for it, the way acme.sh’s --challenge-alias does. Delegate each domain once with a CNAME, then point zone and challenge_alias at the alias zone:

_acme-challenge.www.example.com.  CNAME  _acme-challenge.acme-alias.net.
_acme-challenge.api.example.org.  CNAME  _acme-challenge.acme-alias.net.

[signer.relay.dns01]
challenge_alias = "acme-alias.net."

[signer.relay.dns01.rfc2136]
zone = "acme-alias.net."

The CA follows the CNAME itself; nothing changes on its side. Every domain of the profile shares the one record name, which is safe because values are added and removed one by one. The alias is configured rather than found by following the CNAME, because this server’s resolver need not see what the CA sees, and a record published at the wrong name invalidates the upstream authorization for good.

Whoever can write the alias name can pass dns-01 for every domain pointing at it. Domains that must not share that power belong in separate profiles, each with its own alias and key.

http01

The proxy answers the upstream’s http-01 challenge by serving the key authorization itself, from a route on its own root router at /.well-known/acme-challenge/<token>.

Like dns01, the value served is derived from this proxy’s upstream account thumbprint, not the internal client’s — the two are different accounts on different servers, so the client cannot answer it even in principle. Unlike dns01, the body is the key authorization verbatim rather than its SHA-256 digest (RFC 8555 §8.3 versus §8.4).

This is the opposite direction of the inbound http-01 challenge, which is this server validating its own clients. The two share the well-known path and nothing else.

Two constraints are worth knowing before choosing it:

• It needs a forwarder. acme-proxy does not open a second listener and does not bind port 80. The upstream CA fetches http://<identifier>:80/.well-known/acme-challenge/<token>, so something must forward or redirect that path to acme-proxy — see Deploying the http-01 responder below.
• It cannot prove a wildcard. Nothing answers HTTP on the name *.example.com. An upstream authorization for a wildcard is refused with an error naming dns01, which is the strategy that can.

There is no [signer.relay.http01] table: setting challenge_strategy = "http01" is the whole configuration.

bypass

Used when the upstream CA implicitly trusts the proxy’s account (e.g., a commercial CA with pre-validated domains). The proxy simply tells the upstream “I have validated this”, bypassing external challenges entirely.

This is the one strategy that does not name a type: it triggers whatever the authorization offers. It prefers a challenge it could have satisfied had it needed to, since an upstream that validates out of band still decides against the challenge it was pointed at.

Deploying the http-01 responder

Only relevant with challenge_strategy = "http01".

The upstream CA fetches on port 80 of each name being issued, so put the existing web server for that name in front of acme-proxy and hand it that one path. Either shape works — RFC 8555 §8.3 explicitly permits following redirects, and every real CA does, so the target need not share the name:

# nginx, on the name being certified. Proxy it:
location /.well-known/acme-challenge/ {
    proxy_pass http://acme-proxy:3000;
}

# ...or just redirect it, which needs no upstream block:
location /.well-known/acme-challenge/ {
    return 301 http://acme-proxy:3000$request_uri;
}

# Caddy
handle /.well-known/acme-challenge/* {
    reverse_proxy acme-proxy:3000
}

# Traefik, as a dynamic-configuration router
http:
  routers:
    acme-challenge:
      rule: "PathPrefix(`/.well-known/acme-challenge/`)"
      service: acme-proxy
      priority: 100
  services:
    acme-proxy:
      loadBalancer:
        servers:
          - url: "http://acme-proxy:3000"

The route is mounted on the root router, beside GET /health — it is not under a profile’s /profile/<name> prefix, carries no filter chain, mints no nonce, and answers a plain 404 rather than an ACME problem document for an unknown token. It exists only while some profile’s signer uses this strategy; with any other backend the path is not routed at all. A http_01_responder_mounted line at startup confirms it is live.

Configuration

[signer]
backend = "relay"

[signer.relay]
directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"
account_key_path = "upstream_account.key"
contact = ["mailto:admin@example.com"]
challenge_strategy = "bypass"
poll_interval_ms = 2000
poll_timeout_secs = 300

Several relaying profiles

[signer] is a per-profile section, so one server can relay to several upstreams at once — a Let’s Encrypt endpoint beside a commercial CA, or one internal CA per environment. Each profile gets its own [signer.relay], and they must not share an account_key_path: two backends over one upstream account key would overwrite each other’s registration, and startup refuses it by name.

[profiles.public.signer]
backend = "relay"
relay.directory_url = "https://acme-v02.api.letsencrypt.org/directory"
relay.account_key_path = "public_account.key"

[profiles.partner.signer]
backend = "relay"
relay.directory_url = "https://acme.commercial-ca.example/directory"
relay.account_key_path = "partner_account.key"

Two profiles whose [signer] sections are byte-for-byte identical share one backend and one upstream account; anything that differs makes them independent. See Profiles for what else a profile separates.

Reference

directory_url (String) — Default: "" | Env: ACME_PROXY_SIGNER__RELAY__DIRECTORY_URL

The upstream ACME server’s directory URL.

Starting the server registers an account. The first acme-proxy serve with this backend configured contacts directory_url and performs newAccount there, writing the assigned account URL to the .kid sidecar. There is no confirmation step and no dry-run — merely booting a configuration that names a production CA creates a real account at it, and account creation is itself rate limited (Let’s Encrypt allows 10 per IP address per 3 hours). Point directory_url at a staging endpoint (https://acme-staging-v02.api.letsencrypt.org/directory) while you are still working out a configuration, and switch to production only once it is settled. Subsequent starts reuse the .kid sidecar and do not contact the upstream.

account_key_path (String) — Default: "upstream_account.key" | Env: ACME_PROXY_SIGNER__RELAY__ACCOUNT_KEY_PATH

Path to this proxy’s own account key at the upstream CA. If the file is absent, an ECDSA P-256 key is generated on startup. The assigned kid is stored beside it with a .kid extension.

contact (Array) — Default: [] | Env: ACME_PROXY_SIGNER__RELAY__CONTACT

Optional contacts sent with newAccount to the upstream CA.

challenge_strategy (String) — Default: "bypass" | Env: ACME_PROXY_SIGNER__RELAY__CHALLENGE_STRATEGY

How the proxy satisfies the upstream’s domain-control checks: bypass (the upstream validates nothing), dns01 (publish the TXT record the upstream asks for) or http01 (serve the challenge file from this server’s own root router, which requires a reverse proxy in front of it and cannot prove a wildcard). Any other value is a startup error.

poll_interval_ms (Integer) — Default: 2000 | Env: ACME_PROXY_SIGNER__RELAY__POLL_INTERVAL_MS

How often to poll an upstream order/authorization while it resolves.

poll_timeout_secs (Integer) — Default: 300 | Env: ACME_PROXY_SIGNER__RELAY__POLL_TIMEOUT_SECS

Total budget (in seconds) for one upstream issuance before the local order is marked invalid.

[signer.relay.dns01]

Only consulted when challenge_strategy = "dns01".

provider (String) — Default: "rfc2136" | Env: ACME_PROXY_SIGNER__RELAY__DNS01__PROVIDER

DNS provider used to publish the upstream TXT record. rfc2136 is currently the only implementation.

challenge_alias (String) — Default: "" | Env: ACME_PROXY_SIGNER__RELAY__DNS01__CHALLENGE_ALIAS

A domain, e.g. acme-alias.net., under which every challenge record is published as _acme-challenge.<alias> — see DNS alias mode. Empty publishes at each domain’s own _acme-challenge name. The alias must lie inside rfc2136.zone; one outside it, a wildcard, or a value that already starts with _acme-challenge. is a startup error.

[signer.relay.dns01.rfc2136]

All default to "" and are required once the dns01 strategy is selected.

server — Env: ACME_PROXY_SIGNER__RELAY__DNS01__RFC2136__SERVER host:port of the nameserver accepting the dynamic update, e.g. 10.0.0.53:53. This is the update target, distinct from dns.resolver, which governs lookups.

zone — Env: ACME_PROXY_SIGNER__RELAY__DNS01__RFC2136__ZONE The zone the update is sent for, fully qualified with a trailing dot, e.g. internal.company.com..

tsig_key_name — Env: ACME_PROXY_SIGNER__RELAY__DNS01__RFC2136__TSIG_KEY_NAME Name of the TSIG key the update is signed with.

tsig_key_secret — Env: ACME_PROXY_SIGNER__RELAY__DNS01__RFC2136__TSIG_KEY_SECRET The TSIG shared secret, in standard base64 — note this differs from EAB secrets, which are base64url. A value that is not valid base64 is a startup error, not a runtime one. This key is legitimately long-lived, so unlike a one-shot EAB credential it belongs in configuration; still prefer the environment variable over a file on disk.

tsig_algorithm (String) — Default: "" (read as hmac-sha256) | Env: ACME_PROXY_SIGNER__RELAY__DNS01__RFC2136__TSIG_ALGORITHM The TSIG algorithm: hmac-sha256, hmac-sha384 or hmac-sha512. Must match the key as your nameserver defines it.

Records are added and removed by value, so other TXT values at the same name — another order’s for that name, or ones this server did not write — are left alone. The challenge name must lie inside zone; one outside it is refused before anything is sent.

Updates are sent over UDP and retried over TCP when the response is truncated — a TSIG-signed update readily exceeds 512 bytes, so the TCP path is a normal occurrence rather than an edge case. Only a UDP answer from server itself is accepted.

A successful answer counts only when it is TSIG-signed by the configured key, for this update, within the server’s time window (RFC 8945); anything else fails the update. A refusal is reported as the server sent it, with its TSIG error explained: BADKEY means the server does not know tsig_key_name under tsig_algorithm, BADSIG that tsig_key_secret does not match, and BADTIME that the two clocks disagree.

[signer.relay.dns01.propagation]

What the dns01 strategy waits for between publishing the TXT record and asking the upstream to validate it. The upstream looks once: a record it cannot see yet makes the authorization invalid for good, which fails the client’s order and, at a public CA, counts against its failed-validation limit.

mode (String) — Default: "none" | Env: ACME_PROXY_SIGNER__RELAY__DNS01__PROPAGATION__MODE

none triggers the challenge right after the update succeeds, which is right when the update server is itself what the CA asks. delay sleeps delay_secs first, for a provider that accepts an update before serving it (a DNS API behind an RFC 2136 bridge) or secondaries that lag their primary. Any other value is a startup error.

delay_secs (u64) — Default: 30 | Env: ACME_PROXY_SIGNER__RELAY__DNS01__PROPAGATION__DELAY_SECS

Seconds to wait under delay; ignored under none. Zero is refused (use none), and so is a value not less than poll_timeout_secs, which bounds the whole relay attempt. The delay runs once for each name in the order, so a multi-name order needs poll_timeout_secs above the delay times the number of names plus the time the upstream takes.

The wait is a fixed delay rather than a poll of a public resolver on purpose. A CA resolves through the zone’s authoritative nameservers itself, while a recursive resolver answers from whichever one it reached and caches a “no such record” from a lagging one for the zone’s negative TTL — and never sees an internal or split-horizon zone at all.

[signer.relay.eab]

An upstream External Account Binding credential supplied in configuration rather than through acme-proxy upstream register. Both keys are empty by default, which means “no configuration-file credential”. Read only by acme-proxy serve, and only on a startup that finds no .kid sidecar beside account_key_path — see EAB considerations below for which of the two mechanisms to prefer.

kid (String) — Default: "" | Env: ACME_PROXY_SIGNER__RELAY__EAB__KID

The key id the upstream’s operator issued alongside the secret.

hmac_key (String) — Default: "" | Env: ACME_PROXY_SIGNER__RELAY__EAB__HMAC_KEY

Sensitive. The shared secret, in base64 — url-safe, unpadded url-safe or standard are all accepted, the same three forms acme-proxy upstream register takes. A value that decodes as none of them is a startup error, as is setting either key without the other. Prefer the environment variable to a file on disk, and clear it once registration has succeeded: while it stays non-empty the server logs a signer_relay_eab_secret_in_config warning on every startup.

EAB considerations

An External Account Binding (EAB) credential is a one-time use token that authorizes a single newAccount request and is useless afterwards — registration itself only ever runs once, guarded by the .kid sidecar that ends up next to account_key_path. There are two ways to supply it:

The Admin CLI, registering the proxy with the upstream CA out of band:

acme-proxy upstream register --profile prod --eab-kid "..." --eab-hmac-key-file /path/to/secret

The secret may also be piped on stdin. It is never accepted as a command-line argument, because argv is visible to every user on the host via ps. Nothing about this credential is ever written to disk — only the resulting account kid persists.

--profile is required whenever the configuration defines more than one profile: [signer] is a per-profile section, so registering “the upstream” without saying which one would be registering nothing.

[signer.relay.eab] in configuration, read by acme-proxy serve itself on the first startup with no .kid sidecar yet:

[signer.relay.eab]
kid = "..."
hmac_key = "..."   # base64: url-safe, unpadded url-safe, or standard

This is the trade-off the CLI path exists to avoid: a bootstrap secret sitting in configuration for the life of the server, in exchange for not needing a separate imperative step — useful when config.toml is already populated by a secrets manager or a templated deployment. Once registration succeeds, serve logs a signer_relay_eab_secret_in_config warning on every startup for as long as hmac_key stays non-empty, the same treatment challenge.bypass and ipam.netbox.insecure_skip_verify get — clear it out once acme-proxy upstream show confirms a kid is stored. Setting kid without hmac_key, or vice versa, is a startup error.

If the upstream requires EAB and neither mechanism supplies a working credential, acme-proxy serve fails at startup naming both.

The outbound client validates the upstream’s TLS certificate against webpki-roots — unlike challenge.http_01, which deliberately does not validate the responder’s certificate. Here the certificate is the only thing identifying the CA being handed your CSRs.

Custom Script Signer

The custom signer backend delegates certificate issuance, revocation and metadata retrieval to an external script (Bash, Python, Go, …). Use it to integrate acme-proxy with legacy PKI systems, HSMs, or internal APIs that do not speak ACME natively.

acme-proxy still serves ACME to its own clients and still enforces domain control, filters and EAB; only the signing step is handed off.

Configuration

[signer]
backend = "custom"

[signer.custom]
script_path = "/usr/local/bin/legacy-pki-bridge.sh"
timeout_ms = 15000
args = []
supports_crl = false
supports_renewal_info = false

Reference

script_path (String) — Default: "" | Env: ACME_PROXY_SIGNER__CUSTOM__SCRIPT_PATH

Path to the executable. An empty value is a startup error once this backend is selected.

timeout_ms (Integer) — Default: 5000 | Env: ACME_PROXY_SIGNER__CUSTOM__TIMEOUT_MS

Budget for one invocation. issue and revoke run in the job queue, so there it bounds one attempt. The crl and renewal_info hooks answer a request inline, so while either is enabled this must stay below server.request_timeout_ms — the server refuses to start otherwise.

args (Array) — Default: [] | Env: ACME_PROXY_SIGNER__CUSTOM__ARGS

Static arguments passed on every invocation. These are the only command-line arguments the script receives; the hook is not passed as an argument.

supports_crl (Boolean) — Default: false | Env: ACME_PROXY_SIGNER__CUSTOM__SUPPORTS_CRL

Whether the script implements the crl hook. While false, the hook is never invoked — no process is spawned at all — and GET /crl has nothing to serve.

With it on, the answer is cached for a minute and re-served, so a burst of requests to the unauthenticated GET /crl is one run of the script rather than one per request. At most four read hooks (crl and renewal_info together) run at a time, whatever the request rate.

supports_renewal_info (Boolean) — Default: false | Env: ACME_PROXY_SIGNER__CUSTOM__SUPPORTS_RENEWAL_INFO

Whether the script implements the renewal_info hook. While false, the hook is never invoked and GET /renewalInfo/{certID} falls back to the server’s own local estimate.

These two flags default to false and gate the hooks entirely. A renewal_info hook written without setting supports_renewal_info = true will simply never run, with no error to explain why.

Hooks

The hook is selected by the ACME_SIGNER_HOOK environment variable, not by a command-line argument. Every hook receives a JSON object on stdin.

csr_der_base64 and cert_der_base64 are standard base64 of the DER bytes — not PEM, and not ACME’s base64url.

issue

Exit codes are the contract:

• 0 — stdout is the PEM chain (leaf first, issuers after). Trailing whitespace is trimmed and exactly one newline re-appended, since a strict parser needs a newline after the final -----END CERTIFICATE-----.
• 3 — reserved: the CSR is bad. The order becomes invalid with a badCSR error, which the client reads when it polls. Do not use this exit code for backend failures.
• anything else — an internal failure. The issuance is retried under the job queue’s attempt budget, and the order is marked invalid (terminal, but pollable) once it runs out.

The script runs in the worker role, in the signer_issue job finalize queues: the client is answered processing and polls until the certificate is there. It never runs inside a client’s request, so it may take as long as its timeout_ms without holding one open.

The order’s requested notBefore/notAfter (RFC 8555 §7.4) are not passed to the script — there is no contract for it, and inventing one would break existing scripts. Your script decides validity on its own. (The local_ca backend does honour them, clamped.)

revoke

Exit 0 means revoked. Any non-zero exit is an internal failure, and acme-proxy then leaves the order un-revoked so the operation can be retried — the CA-side action is authoritative.

Revocation must be idempotent: acme-proxy may call this hook for a certificate your PKI already considers revoked, and that must succeed rather than error.

renewal_info

stdout drives RFC 9773:

• empty — no opinion; the server falls back to its own estimate.
• <start> <end> — the renewal window, as epoch seconds.
• <start> <end> <explanationURL> — additionally supplies RFC 9773 §4.2’s optional explanationURL. The URL is last and optional so an existing two-token script keeps working unchanged.

Any other token count, or a non-integer timestamp, is an internal failure.

crl

stdout is the raw DER of the CRL, served by GET /crl. Empty stdout means “no CRL”. Failures here are logged and swallowed — a broken crl hook degrades to no CRL rather than taking the endpoint down.

Environment variables

There is no ACME_SIGNER_PROFILE; the signer backend is never told which profile it is serving. (Backends are shared between profiles with identical [signer] configuration, so there would not always be one answer.)

Security & process isolation

1. Environment clearing: env_clear() is called. The script inherits a minimal PATH plus the ACME_SIGNER_* variables above — nothing else. The server’s own environment may hold the NetBox token, SMTP password or RFC 2136 TSIG key, and a signing script has no business reading them.
2. Zombie protection: the child runs with kill_on_drop(true) under a tokio::time::timeout. A timeout alone only drops the future, so without this a hung script would outlive its deadline and leak a process per request.
3. Failure reporting: on a non-zero exit, the first non-empty line of stdout (falling back to stderr) is used as the error detail.

See Custom Plugins Examples for a complete script.

Challenge Validation

A challenge is how a client proves to acme-proxy that it controls the identifiers it is asking for. Every authorization created by newOrder carries one challenge per enabled type; satisfying any one of them makes the authorization valid, and an order becomes ready once every authorization is.

acme-proxy implements all three challenge types RFC 8555 and RFC 8737 define:

• http-01 — serve a token over HTTP.
• dns-01 — publish a TXT record.
• tls-alpn-01 — present a special certificate in a TLS handshake.

This is validation acme-proxy performs against its own clients. It is separate from how the relay signer backend satisfies an upstream CA’s challenges on your behalf; the two are configured independently and need not match.

Configuration

[challenge]
# Types offered, in this order. Empty or unknown = startup error.
enabled = ["http-01", "dns-01"]

# Skip validation entirely. Testing only.
bypass = false

# Budget for one validation attempt.
timeout_ms = 5000

[challenge] is a per-profile section: each endpoint can offer a different set of types. See Profiles & Routing.

Reference

enabled (Array) — Default: ["http-01"] | Env: ACME_PROXY_CHALLENGE__ENABLED

Which types each new authorization offers, and in what order. Clients pick one. Valid values are http-01, dns-01 and tls-alpn-01. An empty list, or an unrecognised name, is a startup error — even when bypass is on, because a bypassing server still has to advertise a challenge for the client to trigger.

bypass (Boolean) — Default: false | Env: ACME_PROXY_CHALLENGE__BYPASS

Mark a triggered challenge valid immediately, with no network check. With this on, [filter] is the only access control there is — which is why it is not the default.

timeout_ms (Integer) — Default: 5000 | Env: ACME_PROXY_CHALLENGE__TIMEOUT_MS

Budget for one validation attempt, applied at the registry level whatever the type. It bounds a job attempt in the runner, not a request — see Validation runs in the job queue — and it must stay below server.request_timeout_ms, which server::profile::build_all refuses to start otherwise.

max_in_flight_per_account (Integer) — Default: 32 | Env: ACME_PROXY_CHALLENGE__MAX_IN_FLIGHT_PER_ACCOUNT

How many of one account’s challenges may be validating at once. 0 is no limit.

A validation is queued work that reaches out to an address the client named, and an account can create as many orders as it likes. Without a cap, one busy — or hostile — account fills the runner with outbound probes while signings, revocations and CRL regenerations wait behind them. A trigger over the cap is answered 429 rateLimited with a Retry-After, and the challenge is left pending: the client re-triggers it once one of its own validations has settled, and loses no order.

Raise it for a deployment that renews many certificates at once from one account; the ceiling that matters is jobs.max_concurrent, which is how many validations actually run in parallel.

Per-type keys live under [challenge.http_01] and [challenge.tls_alpn_01]; see those pages. dns-01 has no table of its own — it is governed by dns.resolver.

Bypass is not a shortcut

With challenge.bypass = true, [filter] is the only access control the server has. Anyone who can reach the endpoint can obtain a certificate for any name it will accept, without proving anything.

Bypass exists for two legitimate cases: local testing (as in the Quick Start), and a deployment where an IPAM-backed filter such as ipam is genuinely the authority on which host may hold which name, making a network round-trip redundant.

It defaulted to true early in this project’s life. That was reconsidered: an empty filter.rules plus the default bind on every interface made the combination an open CA, so the default is now false.

The two state machines

An authorization and its challenges are separate objects with separate statuses, and the edge between them is the one worth internalising: an authorization becomes valid as soon as any one of its challenges does. The siblings stay pending for ever and that is correct.

stateDiagram-v2
    direction LR
    state "authorization" as A {
        [*] --> a_pending: created with the order
        a_pending --> a_valid: any one challenge valid
        a_pending --> a_invalid: a challenge failed
        a_pending --> a_deactivated: §7.5.2
        a_valid --> a_deactivated: §7.5.2
        a_pending --> a_expired: expires passed
    }
    state "challenge" as C {
        [*] --> c_pending: created with the authorization
        c_pending --> c_valid: proof accepted
        c_pending --> c_invalid: proof refused — terminal
    }
    c_valid --> a_valid: promotes its parent

a_invalid and c_invalid are terminal: the client must create a new order, and re-triggering the same challenge will not retry it. Deactivation is the operator- or client-initiated exit — see Deactivation below.

Validation runs in the job queue

Triggering a challenge with POST /chall/{id} does not perform the check. It claims the challenge, writes a challenge_validate job and answers straight away with the challenge in the processing state, plus a Retry-After. The job runner performs the outbound check and records the verdict.

RFC 8555 has the states for exactly this. §7.1.6: challenges “transition to the processing state when the client responds to the challenge”. §8.2 pairs that with a Retry-After on the challenge resource, which is what the client polls against. certbot, acme.sh and lego all poll.

sequenceDiagram
    participant C as ACME client
    participant P as acme-proxy
    participant W as job runner
    participant T as The name being proven<br/>(port 80 / 443 / DNS)
    participant D as SQLite

    C->>P: POST /chall/{id}
    P->>D: claim: pending → processing
    P->>D: enqueue challenge_validate
    P-->>C: 200 + challenge object (processing)<br/>+ Retry-After + Link: rel="up"
    W->>D: claim the job
    rect rgb(240, 240, 240)
        Note over W,T: in the runner, under challenge.timeout_ms
        W->>T: fetch token / query TXT / TLS handshake
        T-->>W: answer, or timeout
    end
    W->>D: one transaction:<br/>challenge + authorization + order
    Note over D: "is every authorization valid?"<br/>is read INSIDE this transaction
    C->>P: POST /chall/{id} (retry — not a state change)
    P-->>C: 200 + challenge object — valid or invalid

Three consequences:

• challenge.timeout_ms bounds a job attempt, not an HTTP request. It is therefore independent of server.request_timeout_ms, and the server no longer refuses to start when it exceeds it.
• A client that points a name at an unreachable host no longer occupies one of server.max_concurrent_requests while the server waits for it.
• The server still needs egress to the client. For http-01 and tls-alpn-01 it must be able to open a connection back to the machine requesting the certificate — a common source of “the order just sits at pending” in firewalled networks.

A validation is attempted once: a check that ran records its verdict, pass or fail. The job is retried only when the attempt could not happen at all — the database was unreachable, or the endpoint’s profile is not mounted by the process that picked the row up.

Both outcomes are 200

A validation failure returns 200 OK with the challenge object, its status set to invalid and an error member describing what went wrong. It is not a 4xx.

This follows RFC 8555 §7.5.1, and it is load-bearing: certbot’s acme library surfaces an HTTP error status as a transport failure, which would obscure the actual reason the challenge failed. Read the challenge object’s status, not the HTTP status.

Responses also carry a Link: rel="up" header pointing at the authorization, which that same library requires.

A challenge that reaches invalid is terminal. The client must create a new order; re-triggering the same challenge will not retry it.

Wildcards

A wildcard identifier such as *.example.com is accepted only when dns-01 is among enabled — it is the only challenge type that can prove control of a whole subtree. Otherwise newOrder refuses with rejectedIdentifier, naming dns-01.

For a wildcard identifier:

• The authorization is created on the base name (example.com), with "wildcard": true in the authorization object.
• It offers dns-01 alone, even if other types are enabled.

Ordering example.com and *.example.com together therefore produces two authorizations on the same base name, and the TXT record for each goes to the same _acme-challenge.example.com. acme-proxy matches any TXT record at that name, so publishing both values side by side works.

Only a single leading *. is legal. *.*.example.com and foo.*.example.com are rejected as malformed.

What happens on success

Success is committed as one transaction covering the challenge, its authorization, and the order — including the “is every authorization now valid?” read that promotes the order to ready. Doing that read inside the transaction is deliberate: two concurrent validations of one order could otherwise each read before the other’s write landed, and neither would promote the order.

Note the promotion depends on every authorization being valid, not every challenge. An authorization with three challenges needs only one of them.

Deactivation

A client can deactivate an authorization it no longer wants by POSTing {"status": "deactivated"} to the authorization URL (§7.5.2). If the order had already reached ready, it is demoted back to pending.

Deactivation is refused once the order is valid — at that point the certificate exists, and revocation, not deactivation, is what undoes it.

HTTP-01

The default challenge type. The client serves a token at a well-known path over plain HTTP, and acme-proxy fetches it.

Not to be confused with the http01 upstream strategy. This page is about acme-proxy validating its own clients. The relay signer has a challenge_strategy = "http01" that runs the same challenge type in the opposite direction — acme-proxy serving the file, to prove itself to an upstream CA. The two share the well-known path and nothing else, and are configured independently.

How it works

1. The client is given a random token on the challenge object.
2. It computes the key authorization: token + "." + base64url(SHA256(JWK thumbprint of its account key)).
3. It serves that string at http://<identifier>/.well-known/acme-challenge/<token>.
4. It triggers the challenge with POST /chall/{id}.
5. acme-proxy resolves the identifier, fetches the URL, trims whitespace from the body, and compares it to the key authorization it computed independently.

The body is compared to the key authorization verbatim — unlike dns-01, which compares a SHA-256 digest of it. Serving the digest here is a common mistake when hand-rolling a responder.

Every ACME client implements a responder for this type, usually via a --standalone mode or a webroot.

Limitations

• No wildcards. *.example.com cannot be proven this way; use dns-01.
• The name must resolve, and be reachable. acme-proxy connects to the client, using dns.resolver to find it. A host behind a firewall that blocks inbound port 80 from the proxy cannot be validated.

Configuration

[challenge]
enabled = ["http-01"]

[challenge.http_01]
port = 80
https_port = 443
follow_redirects = true
max_redirects = 5
max_response_bytes = 4096

Reference

port (Integer) — Default: 80 | Env: ACME_PROXY_CHALLENGE__HTTP_01__PORT

Port the challenge is fetched from. RFC 8555 fixes this at 80 for the public Internet; it is configurable here because internal deployments frequently cannot bind low ports.

https_port (Integer) — Default: 443 | Env: ACME_PROXY_CHALLENGE__HTTP_01__HTTPS_PORT

Port used when a redirect sends the fetch to https.

follow_redirects (Boolean) — Default: true | Env: ACME_PROXY_CHALLENGE__HTTP_01__FOLLOW_REDIRECTS

Follow 3xx responses. Required by the specification, and commonly needed in practice — many hosts redirect all HTTP to HTTPS.

max_redirects (Integer) — Default: 5 | Env: ACME_PROXY_CHALLENGE__HTTP_01__MAX_REDIRECTS

Hop limit before the validation fails.

max_response_bytes (Integer) — Default: 4096 | Env: ACME_PROXY_CHALLENGE__HTTP_01__MAX_RESPONSE_BYTES

Cap on how much of the response body is read. A key authorization is under 100 bytes; this exists so a client cannot make the server read an unbounded stream.

The TLS certificate presented after a redirect to HTTPS is not validated (RFC 8555 §8.3) — at validation time the client by definition does not yet have a trusted certificate for the name.

Redirects are an SSRF surface

Following redirects means a client can steer the server’s fetch at an address of its choosing. Boulder’s usual mitigation — refusing to connect to RFC 1918 space — cannot apply here, because serving private networks is the entire point of this server.

What contains it instead:

• Only http and https schemes are followed.
• Only the two configured ports (port and https_port) are connected to.
• At most max_redirects hops.
• The shared challenge.timeout_ms bounds the whole attempt, redirects included.
• follow_redirects = false turns the surface off entirely.
• Nothing the fetch learned is echoed back to the client. The error a client sees names its kind — connection or unauthorized — and the identifier, and says the server’s log has the reason. The status, the body length, the socket error and any redirect target stay in challenge_validation_failed; a truncated body preview is logged at debug. This is what stops the challenge from becoming a read primitive or a port scanner against your internal network. What remains is the kind itself: a client can still tell “nothing answered” from “something answered wrongly”.

If your threat model does not tolerate this, disable redirects, or use dns-01, which makes no outbound connection to the client at all.

Troubleshooting

Look for these events in the log:

A connection failure usually means one of: the name does not resolve through dns.resolver; nothing is listening on port; or a firewall blocks the proxy’s egress to the client.

DNS-01

The client publishes a TXT record proving control of the domain. This is the only challenge type that can authorize a wildcard, and the only one that requires no inbound connectivity to the client at all.

How it works

1. The client is given a random token.
2. It computes the key authorization: token + "." + base64url(SHA256(JWK thumbprint)).
3. It publishes a TXT record at _acme-challenge.<identifier> whose value is base64url(SHA256(keyAuthorization)).
4. It triggers the challenge, and acme-proxy queries that name through dns.resolver.

The value is the digest, not the key authorization. This is the single most common mistake when writing a DNS responder by hand: http-01 serves the key authorization verbatim, dns-01 serves the base64url-encoded SHA-256 of it. The two are not interchangeable.

acme-proxy matches any TXT record present at the name. That is required rather than lenient: an order covering both example.com and *.example.com produces two authorizations that publish two different values to the same _acme-challenge.example.com, and both must be able to validate.

Configuration

There is no [challenge.dns_01] table — unlike the other two types, dns-01 has no per-type key. Enable it, and point dns.resolver wherever your authoritative data lives:

[challenge]
enabled = ["dns-01"]

[dns]
# host:port of the nameserver every lookup goes through.
resolver = "10.0.0.53:53"

Leaving dns.resolver unset uses the system configuration (/etc/resolv.conf).

The resolver is deliberately uncached

The shared resolver performs no caching. This matters here more than anywhere else: a client typically publishes its TXT record and triggers the challenge seconds later, and a cached negative answer — an NXDOMAIN or empty NOERROR from the moment before publication — would defeat validation for the whole negative-TTL window.

(The one component that does cache is filter.reverse_dns, which builds its own resolver. PTR lookups for an address that keeps connecting are exactly what a cache is for.)

What this does not remove is propagation delay in your own DNS infrastructure. If dns.resolver points at a recursive resolver rather than the authoritative server, the record still has to reach it. Pointing straight at the authoritative nameserver is the reliable choice for an internal deployment.

Wildcards

[challenge]
enabled = ["dns-01"]     # required for *.example.com to be accepted at all

Without dns-01 enabled, newOrder refuses a wildcard identifier with rejectedIdentifier. With it enabled:

• the authorization is created on the base name, flagged "wildcard": true;
• it offers dns-01 and nothing else, regardless of what else is enabled;
• the TXT record still goes to _acme-challenge.example.com — there is no _acme-challenge.*.example.com.

Client support

Every major client implements dns-01, but each needs a provider plugin or hook script to write the record: certbot’s --manual with an auth hook or a DNS plugin, acme.sh --dns dns_<provider>, lego’s --dns <provider>.

If you would rather your clients did not hold DNS credentials, that is exactly what the relay signer backend exists for: your clients prove control to acme-proxy however you like, and acme-proxy holds the single RFC 2136 TSIG key that answers the upstream CA.

Troubleshooting

If the lookup returns nothing, check in this order: the record exists at _acme-challenge.<name> (not at the name itself); its value is the digest; dns.resolver can actually see the zone; and the record has finished propagating to whatever dns.resolver points at.

A TXT record split into multiple character-strings is reassembled by concatenation before comparison, so a long value chunked by your DNS server is handled correctly.

TLS-ALPN-01

Defined by RFC 8737. The client proves control by answering a TLS handshake on port 443 with a special self-signed certificate, rather than by serving anything over HTTP.

Its appeal is operational: validation happens entirely within the TLS layer, so a host that terminates TLS but serves no plain HTTP at all can still be validated, and nothing needs to be routed on port 80.

How it works

1. The client is given a random token and computes the key authorization as usual.
2. It generates a self-signed certificate that contains:
   • a single dNSName SAN equal to the identifier being validated, and
   • a critical id-pe-acmeIdentifier extension (OID 1.3.6.1.5.5.7.1.31) whose value is SHA256(keyAuthorization).
3. It arranges for that certificate to be presented when a handshake arrives with SNI set to the identifier and ALPN protocol acme-tls/1.
4. acme-proxy performs that handshake and inspects the certificate it gets back.

The proof is verified without ever completing an application-layer exchange: the certificate presented during the handshake is the answer.

What acme-proxy checks

• Exactly one dNSName SAN, matching the identifier. Not “at least one”.
• The id-pe-acmeIdentifier extension is present and marked critical, as RFC 8737 requires.
• Its value equals the expected digest, compared in constant time.

The presented certificate is otherwise untrusted by design — it is self-signed and issued by the entity being challenged, so there is no chain to validate.

Configuration

[challenge]
enabled = ["tls-alpn-01"]

[challenge.tls_alpn_01]
port = 443

Reference

port (Integer) — Default: 443 | Env: ACME_PROXY_CHALLENGE__TLS_ALPN_01__PORT

Port the validation handshake connects to. RFC 8737 fixes this at 443 for the public Internet; it is configurable here for internal deployments that cannot bind it.

Client support

Support is thinner than for the other two types:

• lego implements a responder (--tls). This is what the project’s end-to-end suite uses.
• certbot and acme.sh do not implement a tls-alpn-01 responder. Listing this type is harmless for them — they simply pick another enabled type — but it cannot be their only option.
• Servers that manage their own certificates, such as Caddy and Traefik, generally do support it natively.

If tls-alpn-01 is the only entry in challenge.enabled, certbot and acme.sh clients will not be able to complete an order at all.

Limitations

• No wildcards. Use dns-01.
• Requires inbound connectivity from acme-proxy to the client on port, the same constraint as http-01.
• The responder must serve the ACME certificate only for the acme-tls/1 ALPN protocol, and its normal certificate otherwise. Serving it unconditionally would break ordinary traffic to that host for the duration.

Troubleshooting

A handshake that fails outright usually means the responder did not negotiate acme-tls/1 — many TLS servers simply fall through to their normal certificate when they do not recognise the ALPN protocol, and the certificate then has no id-pe-acmeIdentifier extension to find.

Filters

Filters provide access control for acme-proxy. They restrict which clients can reach the server and which identifiers (e.g. DNS names) those clients can request certificates for.

[filter] is a small policy engine with two halves:

• a check is one named question about a request — “is this address in the management network?”, “does the inventory say this address owns this name?”. Each is a [filter.check.<name>] with a type saying which question it asks.
• a rule is a boolean expression over check names plus what a match means. Each is a [filter.rule.<name>], and filter.rules lists the ones to evaluate, in order. First match wins.

Everything is a named check — custom included — and two checks of the same type are ordinary rather than impossible.

[filter]
rules = ["mgmt-bypass", "inventory-owned"]

[filter.check.mgmt-net]
type  = "allowed_ip"
allow = ["10.0.0.0/8"]

[filter.check.corp-names]
type  = "identifiers"
allow = ["*.corp.example.com", "corp.example.com"]

[filter.check.inventory]
type = "ipam"

[filter.rule.mgmt-bypass]
when = "mgmt-net"
then = "allow"

[filter.rule.inventory-owned]
when    = "corp-names and (inventory or mgmt-net)"
then    = "allow"
message = "this address owns no such name in the inventory"

See Policy: rules and conditions for the condition language and how rules are evaluated, and Checks for the types and their keys.

The two hooks

A check can act at two points, and both default to “pass” for a check that does not implement them:

• the connection stage — runs on every request, before anything else. Refusal is 403 access_denied.
• the identifier stage — runs at newOrder and again at finalize against the names projected out of the CSR. It runs after the account is resolved, so a check can bind names to an account as well as to an address. Refusal is 403 rejectedIdentifier at newOrder, 400 badCSR at finalize.

Checking again at finalize is what stops a client from passing a benign newOrder and then smuggling extra names into the CSR:

graph LR
    REQ["Any request"] --> CONN["connection stage<br/>rules over address/path checks"]
    CONN -->|deny| D403["403 access_denied"]
    CONN -->|allow| ROUTE{"which resource?"}
    ROUTE -->|"newOrder"| ID1["identifier stage<br/>names from the order"]
    ROUTE -->|"finalize"| ID2["identifier stage<br/>names from the CSR"]
    ROUTE -->|"anything else"| OK["handler"]
    ID1 -->|deny| DREJ["403 rejectedIdentifier"]
    ID2 -->|deny| DCSR["400 badCSR"]
    ID1 --> OK
    ID2 --> OK

Both stages must allow. They are evaluated independently, each over the subset of rules that can run there, so a connection-stage allow does not skip the identifier stage. A stage no rule applies to allows without consulting filter.default — otherwise a policy made entirely of identifiers checks would refuse every request before a name had been mentioned.

Available check types

allowed_ip reads nothing but the client address, which both stages carry, and that is what makes mgmt-net or inventory writable at all: the address half is still answerable at the point where the inventory is consulted.

Seeing what a policy does

acme-proxy filter show prints the resolved policy, with every condition re-parenthesized so you can see what the parser understood. acme-proxy filter explain evaluates it against a hypothetical request and reports each check’s verdict, which rule matched, and the HTTP answer. See the CLI reference.

Reference

rules (Array) — Default: [] | Env: ACME_PROXY_FILTER__RULES

Which [filter.rule.<name>] entries to evaluate, and in what order. Empty means no filtering at all — anyone who can reach the server can obtain a certificate if they satisfy the challenges (or, with challenge.bypass on, with no proof at all). The server logs a filter_disabled warning at startup saying so.

default (String) — Default: "deny" | Env: ACME_PROXY_FILTER__DEFAULT

What happens at a stage where a rule was applicable and none of them matched: "allow" or "deny". Never consulted at a stage no rule applies to.

trusted_proxies (Array) — Default: [] | Env: ACME_PROXY_FILTER__TRUSTED_PROXIES

CIDRs (or bare addresses) whose forwarded-for header is believed. A request from any other peer is attributed to its own address, and its forwarded header is ignored. Note this is a [filter] key — placing it under [server] silently does nothing.

forwarded_header (String) — Default: "x-forwarded-for" | Env: ACME_PROXY_FILTER__FORWARDED_HEADER

The header consulted for the forwarded client address.

Fail-closed semantics

Every check that depends on the client address fails closed when it cannot determine one — including in deny-only (blocklist) mode. An address the server cannot see is not “absent from the deny list, therefore fine”.

This makes one deployment detail load-bearing: the server must be served with connection info attached, which it is by default. Behind a reverse proxy, set trusted_proxies — otherwise every request is correctly, but unhelpfully, attributed to the proxy.

A check that cannot reach its authority — a DNS timeout, an unreachable inventory — is a third answer, neither pass nor fail, and becomes a retryable 500 rather than a refusal the client would believe permanent. What that means for a policy built out of or is worth reading in Policy.

Keys the policy engine replaced

Each of these is refused by name at startup, so a configuration written against the older shape stops the server rather than coming up looking configured and filtering nothing. The refusal is a diagnostic and nothing more: none of these keys is still read, and the errors themselves go away at 1.0.0. Before then a configuration key may be renamed in any release, with every such change listed in the changelog.

Policy: rules and conditions

A rule is a boolean expression over check names plus what a match means. filter.rules lists the rules to evaluate, in order, and the first match decides.

[filter]
rules   = ["mgmt-bypass", "inventory-owned"]
default = "deny"

[filter.rule.mgmt-bypass]
when = "mgmt-net"
then = "allow"

[filter.rule.inventory-owned]
when    = "corp-names and (inventory or mgmt-net)"
then    = "allow"
message = "this address owns no such name in the inventory"
mode    = "enforce"

The condition language

expr   := term ( "or" term )*
term   := factor ( "and" factor )*
factor := "not" factor | "(" expr ")" | name
name   := [a-z0-9-]+

not binds tightest, then and, then or; and and or are left-associative, so a or b and c means a or (b and c). The three keywords are matched case-insensitively and cannot be used as check names. A parse error names the column it gave up at:

filter.rule.r.when: expected a check name, `not` or `(` at column 9 in "net and )"

acme-proxy filter show re-prints every condition with the grouping made explicit, which is the quickest way to confirm the parser read what you meant.

Where a rule runs

A rule is evaluated at the intersection of the stages its checks can decide at — never the union. Evaluating a rule at a stage where one of its checks cannot run would silently treat that check as passing and change the boolean answer, so the intersection is the only composition that cannot lie.

The consequence worth knowing: a rule combining a connection-only check with an identifiers-only one has no stage at all. That is a startup error naming both sides, not a rule that quietly never fires.

filter.rule.strict combines `has-ptr` (connection only) and `corp-names`
(identifiers only), so there is no point in a request where both can be
evaluated. Give `has-ptr` stages = ["identifiers"] if it can decide there, or
split the rule in two.

Both stages must allow, and each evaluates its own applicable subset independently. A stage no rule applies to allows without consulting filter.default.

When a check cannot decide

A check has three possible answers, not two: it passed, it failed, or it could not decide. The third covers a DNS timeout, an unreachable inventory, a script that would not spawn — cases where the server learned nothing, which is not the same as learning “no”.

Conditions combine them with three-valued logic, where an unknown propagates only if it could change the answer:

The two bold rows are the point. mgmt-net or inventory keeps working through an inventory outage, because a disjunction whose other side already passed does not care what the unknown would have been. inventory on its own still becomes a retryable 500 — the or buys resilience for the addresses it names and nothing more.

The same principle applies at the rule level. A rule whose condition came back unknown is not skipped: it is remembered, and once the policy reaches an answer it is asked whether that would have mattered. If the unknown rule’s effect differs from the effect actually reached, the whole stage is a 500. If it agrees, the answer stands. This is what stops rule order from deciding whether an outage is survivable.

Warn mode

mode = "warn" makes a matching rule log filter_rule_warned and not decide — evaluation continues to the next rule. It is how a tightened policy is rolled out: deploy it in warn mode, watch for the event, and switch to enforce once no legitimate client trips it.

[filter.rule.inventory-owned]
mode = "warn"

A policy of nothing but warn rules therefore falls through to filter.default.

Because rules are a map rather than an array of tables, a profile can dry-run one rule and inherit the rest:

[profiles.staging.filter.rule.inventory-owned]
mode = "warn"

What the client is told

In order: the matching rule’s message if it has one; otherwise the first check that actually refused, in evaluation order; otherwise a generic sentence. A message is the way to say “ask the network team” instead of exposing which check bit.

A check that could not decide never reaches the client — the response is a plain 500, and the specifics stay in the logs.

Reference

filter.rule.<name>.when (String) — Required | Env: ACME_PROXY_FILTER__RULE__<NAME>__WHEN

The condition, in the language above. Empty is a startup error: a rule with no condition is what filter.default is for.

filter.rule.<name>.then (String) — Required | Env: ACME_PROXY_FILTER__RULE__<NAME>__THEN

"allow" or "deny". No default — a rule that does not say what a match means is one whose author has not finished writing it.

filter.rule.<name>.message (String) — Default: "" | Env: ACME_PROXY_FILTER__RULE__<NAME>__MESSAGE

Shown to the client verbatim in place of whichever check failed.

filter.rule.<name>.mode (String) — Default: "enforce" | Env: ACME_PROXY_FILTER__RULE__<NAME>__MODE

"enforce" or "warn". A warn rule matches, logs and does not decide.

Startup refusals

Every one of these stops the server rather than producing a policy that does not mean what it says.

Checks

A [filter.check.<name>] is one named question about a request. It takes a type saying which question, plus that type’s own keys:

[filter.check.mgmt-net]
type  = "allowed_ip"
allow = ["10.0.0.0/8"]

[filter.check.corp-names]
type  = "identifiers"
allow = ["*.corp.example.com", "corp.example.com"]

Two checks of the same type are ordinary — two identifier lists with different rules, an address list per network, several script hooks — which is the main thing the older filter.enabled shape could not express.

Naming

Each name must match ^[a-z0-9-]+$: lowercase letters, digits and -, the same restriction profile names have. The reason is that a name is also an environment variable segment (ACME_PROXY_FILTER__CHECK__<NAME>__…), and the config crate lowercases those, so MgmtNet in a file and MGMTNET in the environment would silently become two entries instead of one overriding the other.

and, or and not are the condition language’s own words and cannot name a check.

Only what a rule names is built

A check defined here but mentioned by no selected rule is never constructed. It opens no connection, spawns no client and validates nothing; it is reported once at startup as filter_check_unused.

That is deliberate, and it is what makes profile inheritance usable: a global [filter] section can carry a library of checks, every profile inherits all of them, and each profile’s filter.rules picks the subset it actually wants without paying for — or failing startup on — the rest.

Keys by type

type and stages are universal. Everything else belongs to one type, and setting a key that belongs to a different type is a startup error naming both — the keys are one flat namespace, so without that check script_path on an allowed_ip check would simply be read by nothing.

Defaults, where a type has one: require_forward_confirm = true, timeout_ms = 2000 for reverse_dns and 5000 for custom, pass_stdin = true, allow_wildcards = false, require_active = false, allowed_types = ["dns", "cn"].

Every list defaults to empty, and empty always means “this type’s natural default”, never “none”. That is not a style choice: an unset list environment variable arrives as an empty list rather than as absent, so stages = [] has to mean “infer” and allowed_types = [] has to mean ["dns", "cn"].

Matching: globs first, regexes on request

The name-matching checks take globs in allow/deny, where * matches one label:

• *.example.com matches a.example.com; it does not match a.b.example.com, and it does not match example.com. List the bare name too, exactly as you would in a certificate.
• Everything else is literal. No ?, no character classes, no **.
• Matching is case-insensitive.

allow_regex/deny_regex take regexes instead, automatically anchored as ^(?:…)$, and are unioned with the globs — so a policy can be mostly globs with one regex where a glob will not do. Anchoring is not optional: the regex crate searches rather than matches, so an unanchored example\.com would also accept example.com.evil.net, which is precisely the bypass an allowlist exists to prevent. Write .*\.example\.com for a suffix.

On allowed_ip the two lists are CIDRs or bare addresses instead; on path they are path globs where * stops at /.

Allow and deny

One rule, shared by every check that has the pair:

• deny is checked first and wins. Plain membership, not longest-prefix-match: a /32 in allow does not beat a /8 in deny.
• An empty allow imposes no constraint, so a deny-only configuration is a working blocklist rather than a list that refuses everything.

Which gives three usable shapes: allow-only (a strict allowlist), deny-only (a blocklist, everything else served), or both (an allowlist with holes punched in it).

Stages

There are two hook points — the connection, and the identifiers — and each type answers at the ones it can:

reverse_dns is the one whose default is narrower than its capability: it could answer at the identifier stage from the same address, but a PTR plus forward-confirmation exchange at newOrder and again at finalize triples the lookups for an answer that has not changed. Opt in when you need it in an identifier-stage rule:

[filter.check.has-ptr]
type   = "reverse_dns"
stages = ["identifiers"]

Naming a stage the type cannot serve is a startup error saying why — an ipam check at the connection stage would query the inventory on every newNonce.

That allowed_ip answers at both stages is load-bearing rather than incidental: it is what makes mgmt-net or inventory a rule that can be evaluated at all, since the address half must still be answerable at the point where the names are known.

Reference

filter.check.<name>.type (String) — Required | Env: ACME_PROXY_FILTER__CHECK__<NAME>__TYPE

Which check type this instance is: allowed_ip, path, reverse_dns, identifiers, eab, ipam or custom. An unknown value is refused by name, as is the old netbox, which became ipam with its settings in [ipam.netbox].

filter.check.<name>.stages (Array) — Default: [] | Env: ACME_PROXY_FILTER__CHECK__<NAME>__STAGES

Override where this instance decides: "connection", "identifiers", or both. Empty infers from the type, per the table above.

Allowed IP Filter

The allowed_ip filter provides network-level access control based on the client’s IP address. It can operate as an allowlist, a blocklist, or both.

How it works

This filter implements standard allow/deny semantics using CIDR matching:

• Deny wins: The deny list is checked first. If a client matches any CIDR in the deny list, the request is immediately rejected.
• Allow list: If an allow list is provided, the client must match at least one CIDR. If the list is empty, no allow constraint is imposed (functioning purely as a blocklist).

Client IP resolution & proxies

acme-proxy resolves the client IP securely. If the server is behind a reverse proxy, the proxy must be trusted. Trusted proxies are declared under [filter], not [server]:

[filter]
trusted_proxies = ["10.0.0.0/8"]
forwarded_header = "x-forwarded-for"   # the default

Get the section right. Unknown keys are ignored rather than rejected, so trusted_proxies written under [server] is silently dropped — no warning, no startup error. The forwarded header is then never believed, and every request is attributed to the reverse proxy’s own address instead of the client’s.

When a connection originates from a trusted proxy, acme-proxy walks the forwarded-for header right-to-left, skipping trusted hops until it finds the true client IP. Requests arriving from an address that is not in trusted_proxies are attributed to their peer address, and any forwarded header they carry is ignored — which is what makes a spoofed X-Forwarded-For header useless. IP addresses are canonicalized internally (IpAddr::to_canonical()), meaning IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.1.1) are properly treated as IPv4.

Important (Fail Closed): The filter subsystem operates with strict fail-closed semantics. If the client IP cannot be determined (e.g., misconfigured reverse proxy or missing TapIo wrapper), ConnectionContext::require_client_ip() fails. The filter will deny access rather than assuming the client is safe.

Configuration

[filter]
rules = ["internal-only"]

[filter.check.internal-nets]
type = "allowed_ip"
# Deny external bad actors
deny = ["203.0.113.9", "198.51.100.0/24"]
# Allow internal networks
allow = ["192.168.1.0/24", "10.0.0.0/8", "fd00::/8"]

[filter.rule.internal-only]
when = "internal-nets"
then = "allow"

allow and deny take CIDRs or bare addresses (a bare address becoming a host route), IPv4 or IPv6. Both empty while a rule names the check is a startup error: an empty allow imposes no constraint, so the check would accept everything, and an operator who configured it did not mean to turn on something inert.

The shared allow/deny semantics, and the keys themselves, are documented under Checks.

This check answers at both stages, since it reads nothing but the client address — which is what lets a rule say internal-nets or inventory and still have the address half answerable once the requested names are known.

Path Check

type = "path" matches the request path, so a rule can be about what is being asked for as well as who is asking.

[filter.check.public-paths]
type  = "path"
allow = ["/crl"]

[filter.rule.public]
when = "public-paths"
then = "allow"

Connection stage only. By the identifier stage the path is always /newOrder or /finalize/{id}, so a rule combining this with a name check would be asking a question with a constant answer.

The /crl and /ca.pem trap

Both are served by the profile router, which means they sit behind the filter policy exactly like /newOrder does. Turn on an address-based check without accounting for them and two things break quietly:

• every relying party outside your allowlist loses revocation checking, and relying parties are precisely not the ACME clients you allowlisted;
• a host that has not installed the root yet cannot fetch it — which is the one moment it needs to, and the refusal looks like the CA being down.

So any address-based policy wants a companion rule:

[filter]
rules = ["public", "mgmt-only"]

[filter.check.public-paths]
type  = "path"
allow = ["/crl", "/ca.pem"]

[filter.check.mgmt-net]
type  = "allowed_ip"
allow = ["10.0.0.0/8"]

[filter.rule.public]
when = "public-paths"
then = "allow"

[filter.rule.mgmt-only]
when = "mgmt-net"
then = "allow"

Because public comes first and first match wins, both are served to anyone while everything else still requires the management network.

Server-level routes — GET /health, GET /, and the http-01 responder — are served by the root router, which no profile’s policy ever sees. They are already unfiltered and need no entry here.

Paths are profile-stripped

Matching is against the path with the /profile/<name> prefix removed, so /directory — not /profile/default/directory — is the value to list, and one check covers every endpoint the process serves.

Globs

* matches one or more characters other than /, i.e. one path segment:

Everything else in a glob is literal, so a path containing regex syntax cannot smuggle a pattern in. allow/deny follow the shared rule described in Checks: deny wins, an empty allow imposes no constraint.

A check with both lists empty is a startup error — it would match every request, which is a check that does nothing.

Combining with other checks

The reason this is a check rather than the flat filter.exempt_paths list it replaces is that a path is rarely the whole answer:

# Only the operator network may revoke.
[filter.check.revocation]
type  = "path"
allow = ["/revokeCert"]

[filter.rule.no-remote-revocation]
when    = "revocation and not mgmt-net"
then    = "deny"
message = "revocation is restricted to the management network"

The old list could only say “skip the connection stage entirely for this exact string”, and could not express /renewalInfo/* at all.

Reverse DNS Filter

The reverse_dns filter provides advanced access control by resolving the client’s IP address back to its associated hostnames via DNS PTR records.

This allows you to write policies based on the physical infrastructure naming convention rather than static IP addresses, which is incredibly useful in environments with dynamic IP allocation.

Resolution logic

When a client connects, the filter performs the following:

1. It queries the DNS for PTR records associated with the client’s IP.
2. Forward Confirmation (Optional): If require_forward_confirm = true (the default), it takes the resulting hostnames and queries their A/AAAA records to ensure they point back to the original client IP. This prevents malicious actors from setting up a fake PTR record on an IP they control to spoof an internal hostname.
3. The resulting, validated hostnames are then checked against the allow and deny regex lists.

Crucial Detail: acme-proxy applies the deny list across every PTR candidate returned by the DNS query, not just the one that would otherwise be accepted. If a client’s IP resolves to good.internal AND evil.hacker.net, and your deny list blocks evil, the connection is denied, even if good matches the allow list.

Timeout budget

DNS queries happen on the hot path — this is a connection-level filter, so it runs on every non-exempt request, newNonce included. The filter operates with a strict timeout_ms budget across all DNS queries so slow nameservers cannot tie up the ACME server.

To keep that affordable, reverse_dns builds its own, caching resolver — deliberately unlike every other DNS consumer in the server, which shares one uncached resolver. A PTR lookup for an address that keeps connecting is exactly what a cache is for, whereas the shared resolver must stay uncached so a dns-01 TXT record published moments before a challenge is triggered is not defeated by a cached negative answer. Both honour dns.resolver.

Configuration

[filter]
rules = ["known-hosts"]

[filter.check.has-ptr]
type = "reverse_dns"
# Require the PTR record to correctly forward-resolve back to the IP
require_forward_confirm = true
# Allow any host in the specific internal domain
allow = ["*.corp.example.com"]
# Deny the guest network infrastructure
deny = ["*.guest.example.com"]
timeout_ms = 2000

[filter.rule.known-hosts]
when = "has-ptr"
then = "allow"

allow/deny take globs over the resolved hostname; allow_regex/deny_regex take anchored regexes and are unioned with them. The keys and their defaults are documented under Checks.

Connection stage by default. It is capable of the identifier stage from the same address, but a PTR plus forward-confirmation exchange at newOrder and again at finalize triples the lookups for an answer that has not changed — so opt in with stages = ["identifiers"] when a rule needs it there.

Identifiers Filter

The identifiers filter controls which domains, IPs, or URIs a client is allowed to request a certificate for. This is crucial for preventing a compromised client from requesting a certificate for a sensitive internal domain.

Type flattening and cn handling

A Certificate Signing Request (CSR) can contain identifiers in multiple places (Subject Alternative Names (SANs) and the legacy Subject Common Name (CN)). acme-proxy flattens all of these into a single list of typed identifiers (dns, ip, email, uri, other, cn).

• Deny applies everywhere: A deny rule applies to every single type. If you deny *.evil.com, a client cannot sneak it into the Subject Common Name to bypass the filter.
• Allow skips cn: allow rules explicitly skip the cn type (SUBJECT_ONLY_TYPES). A CN is legacy metadata and often contains human labels (e.g., "rcgen self signed cert"). It is not a true identifier the certificate is for, so it is exempt from strict allow-listing.

What reaches the filter

An order’s dns identifiers are checked for shape before any rule runs: a value that is not a DNS name is malformed, and one the URL parser would read as an IPv4 or IPv6 address — 10.0.0.5, but also 2130706433 or 0x7f.1, which name 127.0.0.1 — is rejectedIdentifier. A rule written for names therefore never has to anticipate an address spelled as one.

Regex anchoring

All matching is performed via Regular Expressions (Regex).

Security Notice: acme-proxy automatically anchors all regexes as ^(?:pattern)$ and makes them case-insensitive. You do not need to manually anchor your regexes. This prevents substring bypasses (e.g., an unanchored example\.com would accidentally match example.com.evil.net).

Configuration

[filter]
rules = ["corp-names-only"]

[filter.check.corp-names]
type = "identifiers"
allowed_types = ["dns", "cn"]
allow = ["*.corp.example.com", "corp.example.com"]
deny  = ["secret.corp.example.com"]
allow_wildcards = false

[filter.rule.corp-names-only]
when = "corp-names"
then = "allow"

allow/deny take globs, where * is one label — so *.corp.example.com does not cover corp.example.com and both are listed, exactly as they would be in a certificate. allow_regex/deny_regex take anchored regexes and are unioned with the globs, for what a glob cannot express. The keys and their defaults are documented under Checks.

Two instances of this type with different lists are ordinary, which is the usual way to say “these names from this network, those names from that one”:

[filter.rule.tenant-a]
when = "tenant-a-net and tenant-a-names"
then = "allow"

[filter.rule.tenant-b]
when = "tenant-b-net and tenant-b-names"
then = "allow"

EAB Check

type = "eab" matches on the External Account Binding credential the requesting account registered under. It is the multi-tenant lever: mint one credential per tenant, bind each to its own name space, and no tenant can request another’s names.

[filter]
rules = ["tenant-a", "tenant-b"]

[filter.check.is-tenant-a]
type  = "eab"
allow = ["tenant-a"]

[filter.check.tenant-a-names]
type  = "identifiers"
allow = ["*.tenant-a.example.com"]

[filter.rule.tenant-a]
when = "is-tenant-a and tenant-a-names"
then = "allow"

Identifier stage only — at the connection stage no account has been authenticated, so there is no credential to ask about.

Why the label and not the account

The obvious handle for “which client is this” would be the account id, and it is the wrong one. An account id is a UUID v7 generated when the account is created, so a policy naming one can only be written after the fact, and you would be editing configuration in response to a client registering.

An EAB credential is the other way round: acme-proxy eab create --label tenant-a mints it before any account exists, and you choose the label. It also survives what the account does next — a key rollover keeps the same account, and a client re-registering under the same credential lands in the same tenant. Credentials are deliberately reusable, so one label naturally covers a whole team.

Blocking a single misbehaving account is a different job and already has a lever: acme-proxy account deactivate <id>.

No credential means refused

An account registered without EAB has no credential, and this check refuses it. That is the only defensible reading of a question about which credential authorised the account — “none” cannot satisfy a tenant rule.

It follows that an eab check under a profile whose eab.enabled is false could never do anything but refuse, so that combination is a startup error rather than a policy.

Matching

allow/deny are globs over the label, with the usual semantics described in Checks — deny first and winning, an empty allow imposing no constraint. allow_regex/deny_regex take anchored regexes and union with them.

kids pins credentials by their kid instead, for an operator who would rather not rely on labels being unique. It is a second allow source rather than a separate gate: either the kid being listed or the label matching is enough.

[filter.check.is-tenant-a]
type  = "eab"
allow = ["tenant-a"]
kids  = ["4f1c…"]     # this exact credential, whatever its label says

A credential minted with no label cannot match a label allowlist. That is the same rule seen from the other side, and it is why eab create is worth always giving a --label.

Making revocation retroactive

Revoking an EAB credential stops new registrations. Accounts already created under it keep issuing, for ever — which is what the credential’s role as a registration-time authorisation implies, and what accounts.eab_kid’s own migration meant by calling it an audit trail.

require_active = true changes that for this check: the credential must still be active, so acme-proxy eab revoke <kid> reaches existing accounts too.

[filter.check.live-credential]
type           = "eab"
require_active = true

A deleted credential goes further than a revoked one, with or without require_active: an account whose kid names a row that no longer exists resolves to no credential at all, and every eab check refuses it, exactly as it refuses an account registered without EAB. See Deleting a credential.

Off by default, because turning it on retroactively changes what eab revoke means for a deployment. It is the lever to reach for when a tenant’s credential leaks — and it is a usable policy on its own, with no labels at all: “any tenant, but not one whose credential we have withdrawn”.

Cost

Resolving the credential is two indexed reads, and they happen only when the policy contains an eab check. A deployment without one pays nothing.

Reference

filter.check.<name>.kids (Array) — Default: [] | Env: ACME_PROXY_FILTER__CHECK__<NAME>__KIDS

Credential kids matched exactly, beside the label globs in allow. A second allow source, not a separate gate.

filter.check.<name>.require_active (Boolean) — Default: false | Env: ACME_PROXY_FILTER__CHECK__<NAME>__REQUIRE_ACTIVE

Also require the credential to still be active, so revoking it refuses accounts already registered under it.

A check that sets none of allow, deny, kids or require_active only asks whether the account used EAB at all, which the [eab] section already guarantees. That is a startup error rather than a check that always passes.

Custom Script Filter

The custom filter lets operators write arbitrary scripts (Bash, Python, …) to decide whether a connection or a CSR should be permitted. Use it for policy that cannot be expressed with the built-in filters.

Configuration

[filter]
rules = ["scripted"]

[filter.check.check-network]
type        = "custom"
script_path = "/etc/acme-proxy/filters/check-network.sh"
timeout_ms  = 5000
pass_stdin  = true
args        = []

[filter.rule.scripted]
when = "check-network"
then = "allow"

custom is an ordinary check type: there is no separate selection list, because filter.rules already says which checks run and in what order. Several [filter.check.<name>] entries may point at the same script — each is told which one invoked it through ACME_FILTER_CHECK_NAME, so one script can serve them all and branch on it.

The keys and their defaults are documented under Checks. An empty script_path on a check some rule names is a startup error.

Hooks

The script is invoked at both filter hooks, distinguished by ACME_FILTER_HOOK:

If your script only cares about one hook, branch on this variable and exit 0 otherwise — the script is called for both.

Data passing

Environment variables

connection hook:

identifiers hook:

ACME_FILTER_IDENTIFIERS is safe to split on , and safe to read line by line. A request whose identifiers could not survive that join is refused before the script runs, with badCSR, so a script never has to defend against it.

That guarantee needs stating because it is not free. At the newOrder stage every identifier is a DNS name the server has already validated. At the CSR stage the list also carries the certificate request’s subject CommonName, which is arbitrary text — routinely a human label such as Example Corp Issuing CA rather than a host name, and therefore not validated as one. A CommonName holding a comma or a newline would otherwise reach the script as extra entries.

The typed JSON on stdin has no such ambiguity and is the better source when a script cares which identifier is which: each entry is its own object with a type, so a cn is distinguishable from a dns there and not here.

JSON on stdin

When pass_stdin is true (the default), a JSON object — not a bare array — is written to the script’s standard input.

connection:

{"hook":"connection","client_ip":"203.0.113.5","method":"POST","path":"/newOrder"}

identifiers:

{
  "hook": "identifiers",
  "client_ip": "203.0.113.5",
  "account_id": "…",
  "stage": "newOrder",
  "identifiers": [{"type": "dns", "value": "a.example.com"}]
}

client_ip is null rather than a string when the address is unknown.

At the CSR stage the identifiers list is the flattened projection of the whole CSR — SANs and the subject Common Name — so entries of type ip, email, uri, other and cn appear alongside dns. That is deliberate: a deny rule cannot be dodged by moving a name from a SAN into the CN.

Return codes

• 0 — permitted.
• Any non-zero exit — denied. This includes exit code 255 and death by signal; the check is simply “did it exit successfully”.
• Timeout, or failure to spawn — treated as an internal error (500), so the client retries rather than seeing a permanent refusal.

On denial, the reason sent to the ACME client is the first non-empty line of stdout, falling back to the first non-empty line of stderr, and finally to a generic “script exited with status …” message. Keep it to one line, and remember it is client-visible — do not leak internal detail into it.

Execution model and security

1. Environment clearing (env_clear): the child runs with a scrubbed environment, inheriting only a minimal PATH and the ACME_FILTER_* variables above. The server’s own environment may hold secrets — the RFC 2136 TSIG key, the NetBox token, the SMTP password — and a filter script has no business reading them.
2. Zombie prevention (kill_on_drop): execution is wrapped in a Tokio timeout with kill_on_drop(true). A timeout alone only drops the future, so without this a hung script would outlive its deadline and leak a process per request.
3. Cost: the connection hook runs on every non-exempt request, including newNonce. A script doing network I/O there will dominate your latency; prefer the identifiers hook when the policy only concerns names.

IPAM

An IPAM backend answers one question: which names does this address own?

acme-proxy asks it through the ipam filter, which turns the answer into a decision — may this client have a certificate for the names it is asking for? The two halves are deliberately separate. The inventory reports what it holds; the filter alone decides what to do about that, and it decides the same way whichever product answered.

Renamed at this release. This used to be a filter called netbox, with its settings under [filter.netbox]. Both moved. See Migrating from filter.netbox below — the old spelling is refused by name at startup, with an error naming all three moves, rather than silently ignored.

Backends

One backend per profile. [ipam] is a per-profile section, so two endpoints served by the same process may consult different inventories.

Sources

Each backend that reads an inventory itself takes a sources list naming the places a permitted name may come from. It is validated at startup against that backend’s own vocabulary. custom has no such list at all — the script reads whatever it reads, so there is nothing to declare and no key to set.

Two things the list does not say, and both matter:

• Order is meaningless. The result is a union of sets, unlike filter.rules (evaluation order) or challenge.enabled (offer order).
• device is a fallback, not a union. It is read only when the address object itself carried no value for the custom field. A value set on the address is the more specific statement, and an operator narrowing one address of a machine must not have the machine-wide list quietly widen it again. vip and fhrp are unions.

Empty, or an unknown entry, is a startup error. An inventory trusted for nothing can never permit a name, so it is a filter that refuses everything — and a typo that silently narrows an allowlist is worse than a refusal to boot. A source that exists but belongs to another backend is refused by name too: naming fhrp under [ipam.phpipam] says a check will run that phpIPAM cannot run, and answering that with silence would leave an operator believing it does.

The default for both backends is ["dns_name", "custom_field", "device"] — exactly what the old netbox filter always did. The two service-address sources are off because both widen what a client may certify.

Matching is exact

Case-insensitive and ignoring a trailing dot, but otherwise literal. There is no suffix rule and no wildcard expansion: an entry example.com does not permit a.example.com, and a request for *.example.com requires that exact string in the inventory. Same reasoning as the anchored patterns in Identifiers — a rule that quietly covers more than it says is the bypass an allowlist exists to prevent.

An ip identifier is permitted when it is the connecting address (a machine may always certify the address it is talking from) or when it is listed like any other name. A common name (cn) is skipped, as in identifiers. Any other type is refused: an inventory has nothing to say about an email address or a URI, and a filter whose job is to confirm entitlement must refuse what it cannot confirm.

Denied versus Internal

The most consequential property of the whole subsystem.

“The inventory does not associate this name with this address” is a decision about the client and denies the request (403 rejectedIdentifier). So is “the inventory holds no record of this address at all”, worded differently so an operator can tell the two apart.

“It answered 500”, “the token was refused”, “the lookup timed out” are not decisions about anybody — the server failed to reach one. Those become a 500 the client can retry.

This is enforced by the types, not by care at each call site: the error an Ipam backend can return has no “denied” variant to reach for. An inventory outage therefore stops issuance rather than permitting everything, and never looks like a permanent refusal.

What it costs per request

The lookup runs inline in newOrder and again at finalize, so it is part of those requests’ worst case. timeout_ms is one budget covering the whole lookup however many requests the backend makes to answer it — not one per request — and it must stay below server.request_timeout_ms.

Migrating from filter.netbox

Three changes, and the server refuses the old spelling of each by name: a check still declared type = "netbox" names the first, a [filter.netbox] section the other two:

1. A check declared with type = "netbox" becomes type = "ipam", plus ipam.backend = "netbox".
2. [filter.netbox] becomes [ipam.netbox]. Most keys are unchanged.
3. Three keys moved or changed shape:

Since the default sources is ["dns_name", "custom_field", "device"], a deployment that left both booleans at their defaults needs no sources line at all. Environment variables move from ACME_PROXY_FILTER__NETBOX__* to ACME_PROXY_IPAM__NETBOX__*.

Startup fails on the old filter name rather than aliasing it. The section moved too, so a silent alias would leave [filter.netbox] read by nothing while the server came up looking configured — the same reasoning that made signer.backend = "acme_proxy" a named refusal when it became relay. Both are error messages rather than compatibility paths: nothing reads the old spelling, and the refusals go away at 1.0.0. Renames like this are expected before then and are listed in the changelog.

Configuration

[ipam]
backend = "netbox"
timeout_ms = 5000

[ipam.netbox]
url = "https://netbox.internal.example.com"
token = "..."
sources = ["dns_name", "custom_field", "device"]

[filter]
enabled = ["ipam"]

Reference

backend (String) — Default: "" | Env: ACME_PROXY_IPAM__BACKEND

Which inventory to consult: netbox, phpipam, custom, or empty for none. Anything else is a startup error rather than a silent fallback. Enabling the ipam filter while this is empty is also a startup error.

timeout_ms (Integer) — Default: 5000 | Env: ACME_PROXY_IPAM__TIMEOUT_MS

Budget for one whole lookup, however many requests the backend makes to answer it — or, for custom, however long its script takes. Applied once around all of them, so a wedged inventory cannot pin a request open. Exceeding it is reported as a server error, not a denial.

NetBox

Reads what NetBox associates with the client’s address. Supports every source, including the two that resolve a shared service address.

What NetBox is asked

One lookup always happens:

GET <url>/api/ipam/ip-addresses/?address=<client ip>

Up to four more are made, each gated by a source:

A read-only API token is enough.

Authenticating

NetBox has two generations of API token, and this backend sends whichever it is given: the scheme is derived from the token itself, so there is nothing to configure.

The nbt_ prefix is NetBox’s own marker for a v2 token, and the whole string — key, dot and secret — is displayed once when the token is created, so paste it verbatim. A value starting nbt_ that carries no . is the key half on its own: that is refused at startup, because NetBox would otherwise answer every lookup with a 403, which looks exactly like a token that has been revoked.

Declaring names

Two places, and either or both can be trusted:

• dns_name on the IP address object — the ordinary case, one name per address.
• A custom field (custom_field, by default acme_domains) for the extra names that address may request. Configure it in NetBox as a multi-select or a text field on ipam.ipaddress and — for the device source — on dcim.device and virtualization.virtualmachine. A single string is accepted as well as a list.

With the device source, an address that carries no value of its own falls back to the field on its device or virtual machine, so names can be declared once per machine rather than once per address. It is a fallback and not a union: see Sources.

Shared and service addresses

A VRRP, CARP or keepalived pair answers on an address that belongs to the pair, not to either member — but the client connects from its own member address, so without one of the sources below it is refused a certificate for the service name. Both are unions: the member’s own names and the service address’s names are true at the same time.

Which one an estate needs depends on how it models redundancy in NetBox.

vip — a role on an address of the same device

The classic modelling: the service address is created on one of the members’ interfaces and tagged with a role.

GET <url>/api/ipam/ip-addresses/?device_id=3&role=vip&role=vrrp

vip_roles says which roles count. The role is re-checked on the answer as well as sent as a filter — a filter parameter this server got wrong must never degrade into “every address on the device”, which would widen an allowlist without saying so.

fhrp — membership of an FHRP group

NetBox’s own model for first-hop redundancy: the service address is assigned to an ipam.FHRPGroup, and each member’s interface is recorded as belonging to that group.

client address ─▶ its interface ─▶ fhrp-group-assignments?interface_id=7
                                        └─▶ group ids ─▶ their addresses

The direction of that chain is the membership proof. A group is only ever reached through an assignment naming the client’s own interface. Nothing is ever looked up by group name, by the service address, or by the identifier the client asked for — so there is no query that could reach a group the client is not recorded in, and no way to turn the check into a lookup of “who owns this name?” by choosing a request carefully. An interface in no group contributes nothing and costs one request.

No role filter applies here: an address assigned to an FHRP group is the group’s service address by construction, and applying vip_roles would drop legitimately untagged VIPs.

A client connecting from the service address needs neither source — that address object comes back from the first query with its own names attached.

TLS

Unlike the challenge validators, where the certificate is deliberately not checked because the proof is what matters, NetBox’s certificate is the only thing identifying the service whose answers decide who may have a name certified. The public roots apply, plus any operator-supplied CA. Switching that off is explicit, logged on every start, and meant to be temporary.

Configuration

[ipam]
backend = "netbox"

[ipam.netbox]
url = "https://netbox.internal.example.com"
token = "your_netbox_read_only_token"
custom_field = "acme_domains"
sources = ["dns_name", "custom_field", "device"]

Turning on service addresses:

[ipam.netbox]
sources = ["dns_name", "custom_field", "device", "vip", "fhrp"]
vip_roles = ["vrrp", "carp"]

Reference

url (String) — Default: "" | Env: ACME_PROXY_IPAM__NETBOX__URL

Base URL of the NetBox instance. Any path is kept, so an instance served under a subpath works. Required when ipam.backend is netbox.

token (String) — Default: "" | Env: ACME_PROXY_IPAM__NETBOX__TOKEN

NetBox API token, of either generation — see Authenticating. A secret: prefer the environment variable.

custom_field (String) — Default: "acme_domains" | Env: ACME_PROXY_IPAM__NETBOX__CUSTOM_FIELD

Custom field holding the permitted names, on the address object and on its device or virtual machine. Only read when sources names custom_field or device.

sources (Array) — Default: ["dns_name", "custom_field", "device"] | Env: ACME_PROXY_IPAM__NETBOX__SOURCES

Where a permitted name may come from. All five sources are available here. See Sources.

vip_roles (Array) — Default: ["vip", "vrrp", "hsrp", "glbp", "carp", "anycast"] | Env: ACME_PROXY_IPAM__NETBOX__VIP_ROLES

Which NetBox address roles mark a service address. Read only when sources names vip, so this is which roles rather than whether to look at all.

ca_cert_path (String) — Default: "" | Env: ACME_PROXY_IPAM__NETBOX__CA_CERT_PATH

Extra CA certificates (PEM) to trust on top of the public roots, for a NetBox behind an internal PKI. Ignored when insecure_skip_verify is on.

insecure_skip_verify (Boolean) — Default: false | Env: ACME_PROXY_IPAM__NETBOX__INSECURE_SKIP_VERIFY

Skip verification of NetBox’s TLS certificate entirely. Meant as a temporary way out of an expired NetBox certificate. Startup logs an ipam_netbox_tls_verification_disabled warning for as long as it is set.

phpIPAM

Reads what phpIPAM associates with the client’s address. Supports dns_name, custom_field and device; phpIPAM records no address roles and no redundancy groups, so vip and fhrp are refused by name at startup.

What phpIPAM is asked

One lookup always happens:

GET <url>/api/<app_id>/addresses/search/<client ip>/

One more is made when sources names device:

GET <url>/api/<app_id>/devices/<deviceId>/

Setting up the API application

In phpIPAM, under Administration → API, create an application:

• App id — becomes app_id, and appears in every API path.
• App permissions — Read is enough.
• App security — SSL with App code. The app code becomes token and is sent as a bare token header (phpIPAM’s own scheme, not Authorization).

The alternative SSL with User token scheme — user credentials exchanged for a six-hour session token — is not implemented: it needs a refresh loop and somewhere to keep the token, for no gain over a credential that can be rotated in the environment.

Declaring names

• hostname on the address — the direct analogue of NetBox’s dns_name, read when sources names dns_name.
• A custom column (custom_field, by default custom_acme_domains). phpIPAM prefixes custom columns with custom_, so the default carries that prefix; write whatever your column is actually called. Add it under Administration → Custom fields for IP addresses and — for the device source — for Devices.

A phpIPAM custom field is a plain text column, so several names are written comma-separated:

www.example.com, api.example.com, mail.example.com

The split is on commas and is not configurable — a comma is not legal in a DNS name, so there is no estate it could need to differ for.

With the device source, an address whose column is empty falls back to the same column on the device named by its deviceId. A fallback, not a union: see Sources.

An unknown address is a 404

The one place phpIPAM’s wire behaviour differs in a way worth knowing about. NetBox answers an unknown address with 200 and an empty result list; phpIPAM answers 404 with its own envelope:

{"code": 404, "success": false, "message": "No addresses found"}

That is read as “no such address” — a denial naming the address — rather than as a transport failure, which would turn every request from an unrecorded machine into a retryable 500. Every other non-2xx status is still a failure, so a broken or misconfigured phpIPAM stops issuance rather than reading as “this address owns no names”. See Denied versus Internal.

Configuration

[ipam]
backend = "phpipam"

[ipam.phpipam]
url = "https://ipam.internal.example.com"
app_id = "acme"
token = "your_app_code"
custom_field = "custom_acme_domains"
sources = ["dns_name", "custom_field", "device"]

Reference

url (String) — Default: "" | Env: ACME_PROXY_IPAM__PHPIPAM__URL

Base URL of the phpIPAM instance. Any path is kept, so an instance served under a subpath works. Required when ipam.backend is phpipam.

app_id (String) — Default: "acme" | Env: ACME_PROXY_IPAM__PHPIPAM__APP_ID

The API application’s identifier, which appears in every API path. One path segment: letters, digits, - and _. Anything else is a startup error, since a stray slash would silently retarget the API rather than fail.

token (String) — Default: "" | Env: ACME_PROXY_IPAM__PHPIPAM__TOKEN

The application’s app code, sent as a token header. A secret: prefer the environment variable.

custom_field (String) — Default: "custom_acme_domains" | Env: ACME_PROXY_IPAM__PHPIPAM__CUSTOM_FIELD

Column holding the permitted names, on the address and on its device. Only read when sources names custom_field or device.

sources (Array) — Default: ["dns_name", "custom_field", "device"] | Env: ACME_PROXY_IPAM__PHPIPAM__SOURCES

Where a permitted name may come from. Only these three are available here; naming vip or fhrp is a startup error.

ca_cert_path (String) — Default: "" | Env: ACME_PROXY_IPAM__PHPIPAM__CA_CERT_PATH

Extra CA certificates (PEM) to trust on top of the public roots. Ignored when insecure_skip_verify is on.

insecure_skip_verify (Boolean) — Default: false | Env: ACME_PROXY_IPAM__PHPIPAM__INSECURE_SKIP_VERIFY

Skip verification of phpIPAM’s TLS certificate entirely. Startup logs an ipam_phpipam_tls_verification_disabled warning for as long as it is set.

Custom Script

Runs an operator-supplied script to answer the one question the whole subsystem asks: which names does this address own?

Use it when the inventory of record is something this server carries no client for — a CMDB, a hosts file, an LDAP tree, a spreadsheet exported nightly, a vendor API behind a Python wrapper. It is the same escape hatch the custom filter and the custom signer are for their subsystems, and it runs under the same hardening.

It is also the backend with the least in it. There is no URL, no credential, no TLS setting and no sources list: the script is the inventory, and where it looks is its own business.

The contract

The script is told the client address twice — once in the environment, once in a JSON object on stdin — so neither a four-line shell script nor a Python one has to reach for the channel it finds awkward.

The same on stdin:

{"hook": "names_for", "client_ip": "203.0.113.5"}

A script that exits without reading stdin is fine and is not an error.

The answer

stdout plus an exit code.

Names are compared exactly, but the script need not tidy them: each line is lowercased and stripped of a trailing dot, and a blank line is ignored. So WWW.Example.COM. and www.example.com are the same answer, and printing whatever form the inventory happens to hold is correct.

One name per line rather than a separated list because a newline is the shell idiom, and plain text rather than JSON because there is nothing here a structure would carry that a list of lines does not — a contract needing jq for what echo already does would be paid for by every script ever written against it. The custom signer hands back its certificate chain the same way.

Why 3 is reserved

“Held, and entitled to nothing” and “no record of this address” are different answers — the ipam check words a different refusal for each, so an operator reading a 403 can tell them apart — and once stdout means the names, an exit status is the only channel left to say the second one in. So it gets a code of its own, exactly as the custom signer’s badCSR does.

Every other non-zero exit stays a failure, and that direction is the one that matters. A script that breaks, is missing, or runs past ipam.timeout_ms produces a server error the client can retry, never a refusal — see Denied versus Internal. It is the same guarantee an unreachable NetBox gets, and it is enforced by the types rather than by care here: the error an IPAM backend can return has no denied variant to reach for, so a broken script cannot fail open or look permanent.

An example

#!/bin/sh
case "$ACME_IPAM_CLIENT_IP" in
  203.0.113.5)
    echo www.example.com
    echo api.example.com
    exit 0
    ;;
  203.0.113.6)
    exit 0          # held, entitled to nothing
    ;;
esac
exit 3              # no record of this address

A fuller one, reading a real source, is in Custom Plugins Examples.

No sources

sources exists because NetBox and phpIPAM each read several places and an operator has to say which are trusted. A script reads whatever it reads, so there is nothing here to list and no key to set. The vocabulary is closed and validated per backend, so a sources line under [ipam.custom] is not a source this backend “does not support” — it is a setting that does not exist.

What it costs

One forked process per lookup, inside newOrder and again at finalize. ipam.timeout_ms is the budget, and it is also what kills the child at the deadline; there is deliberately no second timeout here.

Note that acme-proxy filter explain really runs the policy, so it executes this script — as it does the custom filter’s. That is the point of the command, and it is reported in its side-effects list.

Security and process isolation

1. Environment clearing: env_clear() is called. The script inherits a minimal PATH plus the two ACME_IPAM_* variables above — nothing else. The server’s own environment may hold the NetBox token, the SMTP password or the RFC 2136 TSIG key, and an inventory script has no business reading them.
2. Zombie protection: the child runs with kill_on_drop(true) under a tokio::time::timeout. A timeout alone only drops the future, so without this a hung script would outlive its deadline and leak a process per request.
3. Failure reporting: on a non-zero exit other than 3, the first non-empty line of stdout (falling back to stderr) becomes the error detail. It is logged, not sent to the client: an internal error tells the client nothing about why.

Configuration

[ipam]
backend = "custom"
timeout_ms = 5000

[ipam.custom]
script_path = "/etc/acme-proxy/ipam/lookup.sh"
args = []

Reference

script_path (String) — Default: "" | Env: ACME_PROXY_IPAM__CUSTOM__SCRIPT_PATH

Path to the executable answering the lookup. Empty while ipam.backend is custom is a startup error, the same as signer.custom.script_path.

args (Array) — Default: [] | Env: ACME_PROXY_IPAM__CUSTOM__ARGS

Fixed arguments passed before the script is told anything about the request. One script can serve several deployments by branching on them.

There is deliberately no timeout_ms here. ipam.timeout_ms is the budget the whole lookup runs under, and a second one would contradict the rule the other backends follow.

Configuration Reference

This page is the structured reference for every core configuration parameter.

For deep dives into specific subsystems (Signers, Filters, Notifications, EAB), see their dedicated chapters — linked at the bottom, and the place where those sections’ keys are documented.

How configuration is resolved

Sources are layered, lowest precedence first:

1. Built-in defaults — everything documented below has one, so an empty configuration is valid apart from [profiles].
2. A configuration file — config.toml in the working directory, or the path in ACME_PROXY_CONFIG (the extension may be omitted, in which case the format is inferred). A missing file is not an error.
3. ACME_PROXY_* environment variables — __ separates nested keys, a single _ separates the prefix. server.tls.enabled is ACME_PROXY_SERVER__TLS__ENABLED.

config.toml.example in the repository is the annotated companion to this page: it lists every key with its default and its environment variable name in context.

[profiles] is mandatory. Everything else can be left at its default, but the server serves ACME only through profiles and refuses to start without at least one enabled. See [profiles] below.

Every section, and where it is documented

Six sections are large enough to have a chapter of their own, and their keys are documented there rather than restated here. This page stays the complete map: every top-level section acme-proxy reads appears below, whether or not its text lives here. A delegated section’s own sub-tables — [signer.local_ca.subject], [ipam.netbox], [filter.check.<name>] and the rest — are listed in the chapter that owns them.

Overridable marks the sections a [profiles.<name>] block may override. Everything else is process-wide — one setting for the whole server, however many endpoints it mounts.

The criterion for the last six is having a chapter, not being overridable — [order] and [meta] are overridable and documented here, because neither is large enough to be worth a page. That is the whole rule; there is nothing subtler going on.

config.toml.example in the repository carries the same list as a comment header, with every key in context.

[database]

url (String) — Default: "sqlite://sqlite.db" | Env: ACME_PROXY_DATABASE__URL

Database connection URL, for accounts, orders, certificates and everything else this server keeps. The scheme picks the backend, and any other scheme is refused by name at startup:

• sqlite://<path> — a file, created on first use. The default, and what a single-host deployment wants. sqlite:///var/lib/acme-proxy/acme.db is an absolute path (three slashes).
• postgres:// or postgresql:// — a server, which must already exist: creating a database is an operator’s act, not something a server does to a cluster it was pointed at. Run acme-proxy migrate once against it.

PostgreSQL is what a multi-node deployment needs. SQLite across processes is fine on one local disk, and not safe on NFS or across hosts — see Deployment. Nothing else changes with the backend: the same binary, the same configuration and the same ACME behaviour.

A PostgreSQL URL usually carries user:password@. The password is never logged: the startup line and the SIGHUP refusal both print it as postgres://acme:***@host/db. It is still a credential in a configuration file, so give that file the permissions it deserves.

This key cannot be changed by a reload — see Reload.

[server]

bind_address (String) — Default: "[::]:3000" | Env: ACME_PROXY_SERVER__BIND_ADDRESS

Network address the server binds and listens to. SIGHUP moves it without restarting, and an address that cannot be bound refuses the reload rather than taking the running socket down — see Configuration Reload.

base_url (String) — Default: "http://localhost:3000" | Env: ACME_PROXY_SERVER__BASE_URL

Public base URL advertised in the ACME directory, with no trailing slash. It is never derived from the request, and every signed request’s url field is checked against it (RFC 8555 §6.4) — so behind a reverse proxy, or with TLS enabled, this must be set to the public URL or every client is rejected.

max_concurrent_requests (Integer) — Default: 100 | Env: ACME_PROXY_SERVER__MAX_CONCURRENT_REQUESTS

How many ACME requests may be in flight at once before the server sheds load.

admission_wait_ms (Integer) — Default: 50 | Env: ACME_PROXY_SERVER__ADMISSION_WAIT_MS

How long a request may wait for a slot before it is refused. Past the limit a request waits this long and then gets 503 + Retry-After — it is shed, not queued.

request_timeout_ms (Integer) — Default: 60000 | Env: ACME_PROXY_SERVER__REQUEST_TIMEOUT_MS

Whole-request deadline. It must exceed signer.custom.timeout_ms when that backend is installed with its crl or renewal_info hook enabled, since those hooks run inline inside a request; the server refuses to start otherwise. It is deliberately independent of challenge.timeout_ms and of the script’s issue and revoke hooks, which run in the job queue — see Challenge Validation. A relay or custom revocation that a request queues is waited on for this long, less a second.

max_body_bytes (Integer) — Default: 131072 | Env: ACME_PROXY_SERVER__MAX_BODY_BYTES

Largest request body accepted (128 KiB).

These four keys govern the ACME routes only. GET /health is mounted outside all of them.

trusted_proxies and forwarded_header are not [server] keys — they live under [filter]. See Filters.

[server.tls]

Full treatment in TLS Termination.

enabled (Boolean) — Default: false | Env: ACME_PROXY_SERVER__TLS__ENABLED

Serve HTTPS on bind_address instead of cleartext — one listener, not two. base_url is not rewritten for you; set it to https://… yourself or every signed request fails the §6.4 URL check above.

cert_path (String) — Default: "server.pem" | Env: ACME_PROXY_SERVER__TLS__CERT_PATH

PEM certificate chain, leaf first. A self-signed certificate is generated and written when either this or key_path is missing.

key_path (String) — Default: "server.key" | Env: ACME_PROXY_SERVER__TLS__KEY_PATH

Path to the private key.

handshake_timeout_ms (Integer) — Default: 10000 | Env: ACME_PROXY_SERVER__TLS__HANDSHAKE_TIMEOUT_MS

Budget for one TLS handshake. Handshakes run concurrently, off the accept path, so this never delays another client.

[admin]

The web admin interface — a second listener, on its own socket, serving no ACME. Process-wide, so there is no [profiles.<name>].admin: an operator manages every endpoint this process serves. Full treatment in Web Admin.

enabled (Boolean) — Default: false | Env: ACME_PROXY_ADMIN__ENABLED

Off by default: a certificate authority should not grow a management surface because somebody upgraded it. Bootstrap it with acme-proxy admin user create; there is no sign-up page.

bind_address (String) — Default: "127.0.0.1:3001" | Env: ACME_PROXY_ADMIN__BIND_ADDRESS

Loopback on purpose. This listener has no admission control, filters nothing until [admin.filter] names a rule, and — until [admin.tls] is on — has no transport security.

Startup refuses a non-loopback bind while admin.tls.enabled is false. The session cookie is always sent Secure, and a browser silently declines to store one over plain HTTP on anything but localhost; the symptom would be “sign-in works, then I am immediately signed out”, with nothing in any log to explain it. Either enable [admin.tls], or keep the loopback bind and reach it through an SSH tunnel:

$ ssh -N -L 3001:127.0.0.1:3001 ca.example.com

It is also an error for this to equal server.bind_address.

base_url (String) — Default: "http://localhost:3001" | Env: ACME_PROXY_ADMIN__BASE_URL

The origin the panel is reached at. Load-bearing three times over: the CSRF origin check compares against it, a generated self-signed certificate takes its host, and the pages build absolute URLs from it — exactly as server.base_url does for the ACME listener. Through a tunnel this stays localhost. The resolved origin is logged at startup (admin_origin_resolved) so a mismatch is visible before the first refused request.

session_ttl_seconds (Integer) — Default: 43200 (12 h) | Env: ACME_PROXY_ADMIN__SESSION_TTL_SECONDS

Absolute session lifetime. Never extended by activity: past it, the operator signs in again.

session_idle_timeout_seconds (Integer) — Default: 3600 (1 h) | Env: ACME_PROXY_ADMIN__SESSION_IDLE_TIMEOUT_SECONDS

Idle lifetime, advanced on use — at most once a minute, so a polling page is not a stream of database writes. Whichever deadline comes first wins.

login_max_attempts (Integer) / login_window_seconds (Integer) — Defaults: 5 / 300 | Env: ACME_PROXY_ADMIN__LOGIN_MAX_ATTEMPTS, ACME_PROXY_ADMIN__LOGIN_WINDOW_SECONDS

Failed sign-ins allowed from one address per window, then 429 with a Retry-After. The password hash is deliberately expensive (PBKDF2-HMAC-SHA256 at 600 000 iterations), so this is an availability control as much as a credential one: over the limit, the hash is not computed at all.

Keyed on the client address. The forwarded-for header is believed only from a peer listed in admin.filter.trusted_proxies — never from filter.trusted_proxies, which governs the ACME listener. With no trusted proxy listed, the limiter behind a reverse proxy counts the proxy.

require_mfa (Boolean) — Default: false | Env: ACME_PROXY_ADMIN__REQUIRE_MFA

Require a second factor (TOTP) of every operator. What this changes is the operator who has none: with it on, their next sign-in lands on the enrolment page and their session stays half-authenticated until they finish. An operator who already has one is challenged whether this is set or not.

It deliberately does not refuse a password-only sign-in outright: enrolling needs a session and a session would then need a factor, so that would brick the panel including the way in to fix it.

Turning it on does not retroactively end sessions that predate it — acme-proxy admin session revoke --all is the lever that does. While it is on and some operator has no factor, every start logs admin_mfa_enrolment_pending. See Operators and sessions.

max_body_bytes (Integer) — Default: 65536 | Env: ACME_PROXY_ADMIN__MAX_BODY_BYTES

Largest admin request body. An admin body is a small JSON object or a form, never a certificate.

page_size_max (Integer) — Default: 200 | Env: ACME_PROXY_ADMIN__PAGE_SIZE_MAX

Ceiling on ?limit= for the list endpoints; the default page size is 50. A larger request is clamped, not refused.

template_dir (String) — Default: "" | Env: ACME_PROXY_ADMIN__TEMPLATE_DIR

Override individual page templates on disk, mirroring notify.template_dir. Empty means the compiled-in defaults. The override is per file: a directory holding only layout.html restyles the chrome of every page and leaves the other fifty-five at their defaults. Every template is compiled at startup, so a broken override refuses to start rather than serving a 500 later. Applies to the /ui pages only; the JSON API has nothing to template. See Customizing the Panel.

[admin.filter]

Who may reach the admin listener at all — for the deployment that cannot put a host firewall in front of the port, such as a container. The same policy engine and the same keys as the ACME listener’s [filter] (rules, default, trusted_proxies, forwarded_header, [admin.filter.check.<name>], [admin.filter.rule.<name>]), under ACME_PROXY_ADMIN__FILTER__…, with four differences:

• It is its own section. Nothing is inherited from the global [filter], which is the ACME profiles’ base: an edit made for one listener must not open or shut the other.
• Only the connection stage exists here, so only allowed_ip, path, reverse_dns and custom checks are accepted. An identifiers, eab or ipam check, or a rule whose checks were moved to the identifier stage with stages, is refused by name at startup and on reload.
• Empty rules filters nothing, and logs no warning.
• trusted_proxies also keys the login limiter (see admin.login_max_attempts): it is the one list the admin listener believes a forwarded-for header from, and it applies whether or not a rule is written.

Every request is evaluated, /health included. A refusal is 403 — the admin API’s JSON error (access_denied) under /api, the HTML error page elsewhere — and is logged as filter_request_blocked with listener = "admin". See Web Admin — Restricting who can reach it.

[admin.notify]

A whole [notify] section, process-wide, built only while [admin] is enabled. It delivers the admin_sign_in / admin_credential_changed operator security events (ASVS V6.3.5 / V6.3.7). Every key is the one documented for the per-profile [notify] — under ACME_PROXY_ADMIN__NOTIFY__… — with one difference: [admin.notify.email].to may be empty, since each event carries the affected operator’s own contact address as its recipient. See Web Admin — Security notifications.

[admin.tls]

HTTPS on admin.bind_address instead of cleartext — the same one-listener-not-two shape as [server.tls], and the same load-or-generate provisioning.

enabled (Boolean) — Default: false | Env: ACME_PROXY_ADMIN__TLS__ENABLED

Anything but http://localhost needs this on, or the browser will not store the session cookie at all.

cert_path / key_path (String) — Defaults: "admin.pem" / "admin.key" | Env: ACME_PROXY_ADMIN__TLS__CERT_PATH, ACME_PROXY_ADMIN__TLS__KEY_PATH

PEM chain (leaf first) and its private key. When either is missing, a self-signed certificate for the host of admin.base_url is generated and written at startup; the generated key is created 0600. Separate paths from [server.tls] on purpose — the two listeners answer to different names and should not share a certificate by accident.

handshake_timeout_ms (Integer) — Default: 10000 | Env: ACME_PROXY_ADMIN__TLS__HANDSHAKE_TIMEOUT_MS

As [server.tls].

[challenge]

Which challenge types each new authorization offers, whether they are validated at all, and the per-type keys under [challenge.http_01] and [challenge.tls_alpn_01].

Documented in full in Challenge Validation — this section is a per-profile subsystem with its own chapter, so its keys live there rather than being restated here.

[order]

validity_seconds (Integer) — Default: 604800 (7 days) | Env: ACME_PROXY_ORDER__VALIDITY_SECONDS

Lifetime of the ACME order object before it expires. This is housekeeping for the order resource, not the issued certificate’s validity — that is signer.local_ca.leaf_validity_days, or whatever the delegating backend decides.

max_identifiers (Integer) — Default: 100 | Env: ACME_PROXY_ORDER__MAX_IDENTIFIERS

Most identifiers a single newOrder may name. A request naming more is refused with urn:ietf:params:acme:error:malformed.

The only bound before this was server.max_body_bytes (128 KiB), which at roughly thirty bytes per identifier admits some four thousand names in one request. Every one of them becomes an authorization plus a challenge per offered challenge type, all inserted in a single transaction — and SQLite has one writer, so that transaction stalls every other write in the process while it runs. 100 is what Let’s Encrypt allows and is far above what a real client asks for; the point is that there is a ceiling.

Refused as malformed rather than rateLimited deliberately: the order is malformed for this server whenever it is sent, so rateLimited — which tells a client to come back later — would be a lie.

retention_days (Integer) — Default: 30 | Env: ACME_PROXY_ORDER__RETENTION_DAYS

Days an order is kept after it expires, before the daily order_sweep deletes it. The authorizations and challenges beneath it go with it, through the schema’s ON DELETE CASCADE. 0 keeps everything for ever.

A valid order is never swept, whatever its age. Its row is how revokeCert and the CRL resolve a certificate by serial, and what RFC 9773 renewal information is derived from — deleting one would make an issued certificate unrevokable and unrenewable, which is a far worse outcome than a large table. Only orders that ended some other way are eligible: invalid, or an abandoned pending/ready/processing order past its own expires, at which point no client can act on them either.

Nothing pruned orders before this key existed, so the table and its children grew for the life of a deployment — one order plus one authorization per identifier plus one challenge per offered type, on a default configuration where newAccount is open to anyone.

Per-profile like the rest of [order]. The sweep is a single job handler (JobRegistry refuses two handlers for one kind) that applies each mounted profile’s own value to that profile’s rows, emitting one order_reaper_swept line per profile.

[nonce]

ttl_seconds (Integer) — Default: 300 | Env: ACME_PROXY_NONCE__TTL_SECONDS

Freshness window for JWS anti-replay nonces. Expired nonces are swept on an interval for the life of the process.

[audit]

Traceability and the CA’s audit trail. Process-wide, not per-profile — the trail describes the CA, not one of its endpoints, so this section may not appear under [profiles.<name>].

There is deliberately no enabled key. The address columns on accounts and orders, and the audit_log table, are always written: recording who asked the CA to sign something is what a CA does, not a feature to switch on. The only thing here that can be turned off is the reverse lookup.

reverse_dns (Boolean) — Default: true | Env: ACME_PROXY_AUDIT__REVERSE_DNS

Resolve a PTR record for the client’s address and freeze it into the row beside the address. Turn it off on an estate with no usable reverse zone: every lookup would fail, every *_ptr column would end up NULL anyway, and all that would be left is the round trip. Lookups go through dns.resolver like every other DNS query this server makes.

reverse_dns_timeout_ms (Integer) — Default: 2000 | Env: ACME_PROXY_AUDIT__REVERSE_DNS_TIMEOUT_MS

Budget for one PTR lookup. Deliberately small: this runs inside a request that has already done its real work, so a slow nameserver costs a NULL in one column rather than latency on issuance. Every failure is a NULL, never a refused request.

retention_days (Integer) — Default: 0 | Env: ACME_PROXY_AUDIT__RETENTION_DAYS

Delete audit_log rows older than this many days. 0 keeps everything for ever, which is the right default for a trail whose value is that it is complete. Any non-zero value schedules a daily audit_sweep job beside the nonce one, running the same DELETE as acme-proxy audit cleanup --older-than <days>.

See Audit Trail.

[jobs]

The durable background-work queue: the jobs table plus the one runner that drains it. Process-wide, not per-profile — there is one queue and one runner for the process, so this section may not appear under [profiles.<name>].

There is deliberately no enabled key. The queue is how the server finishes work it has already promised a client: an order answered processing is owed a certificate. Switching it off would not disable a feature, it would strand the orders. What is tunable is how hard and how long the server tries.

Most of what the server does after answering a request runs here, so this section’s reach is wider than the name suggests:

• Client-visible work — challenge validation (challenge_validate), issuance (signer_issue, and signer_relay_issue under the relay backend), revocation through a relay or script (signer_revoke), and a local CA’s CRL signing (local_ca_crl_regenerate).
• Deliveries — every notification (notify_deliver) and the expiry digest (notify_expiry_digest).
• Periodic sweeps — expired nonces, orders past order.retention_days, audit.retention_days, expired admin sessions, stale http-01 tokens, the daily CRL refresh (local_ca_crl_sweep), and this queue’s own retention_days.

A runner that is not running is a server that validates, issues, sweeps and notifies nothing — job_runner_started is the line that says it is. With role processes, only a worker process runs one.

poll_interval_ms (Integer) — Default: 1000 | Env: ACME_PROXY_JOBS__POLL_INTERVAL_MS

How often the runner looks for work nobody woke it for. This bounds only scheduled work — a backoff coming due, a periodic sweep firing. Queueing a job wakes the runner directly, so a relay queued by finalize starts immediately whatever this says, which is what keeps a polling ACME client from waiting on a tick.

max_concurrent (Integer) — Default: 8 | Env: ACME_PROXY_JOBS__MAX_CONCURRENT

How many jobs may run at once. A restart after an upstream outage that left a few thousand orders in flight would otherwise become a few thousand concurrent pollers against one CA, which is how a recoverable backlog turns into a rate-limit ban.

max_attempts (Integer) — Default: 5 | Env: ACME_PROXY_JOBS__MAX_ATTEMPTS

How many attempts a job gets before it is retired permanently. Counted when the job is claimed, so one that kills the process still exhausts its budget rather than crash-looping. With the 30-second base below and doubling, five attempts span roughly seven and a half minutes.

Unlike every other key here, this one is frozen onto each row as it is queued rather than read afresh each attempt, so raising it applies to work queued from then on and not to a backlog already waiting.

retry_base_seconds (Integer) — Default: 30 | Env: ACME_PROXY_JOBS__RETRY_BASE_SECONDS

The first retry delay; each subsequent one doubles. Longer than any single upstream round trip, so a retry is not simply the same failure again, and short enough that a blip clears inside one client poll cycle.

retry_max_seconds (Integer) — Default: 3600 | Env: ACME_PROXY_JOBS__RETRY_MAX_SECONDS

Where the doubling stops, and a real ceiling — the jitter applied to each delay only ever subtracts, so no retry is scheduled past this. An hour sits well under the default order lifetime, which keeps a job’s own deadline the binding constraint rather than this.

lease_seconds (Integer) — Default: 300 | Env: ACME_PROXY_JOBS__LEASE_SECONDS

The default budget for one attempt, and therefore how long a claim is held before another runner may take the row. A handler needing a different one says so itself: the relay signer asks for its own signer.relay.poll_timeout_secs.

retention_days (Integer) — Default: 7 | Env: ACME_PROXY_JOBS__RETENTION_DAYS

Delete settled job rows older than this many days. Unlike audit.retention_days this defaults to a non-zero value: a finished job is a receipt, not evidence, and the trail that has to be complete is audit_log’s. 0 keeps everything for ever and stops the sweep being scheduled at all.

[metrics]

The Prometheus exposition, served on a listener of its own — a third socket beside the ACME and admin ones, not a route on either. Process-wide, not per-profile: there is one counter set for the process, and the endpoint is a dimension of it rather than something each endpoint configures for itself.

The separate port is what settles the access question. A scrape carries no session and needs none, because reaching the port at all is the permission — so the control is your firewall, not a credential this server checks. Putting it on the ACME listener would have meant an unauthenticated route on a public socket; putting it on the admin listener would have meant an auth exemption on a listener whose rule is that every route but sign-in needs a session, plus coupling metrics to the panel being enabled.

There is deliberately no path key — /metrics is what every scrape configuration already assumes, and this listener serves nothing else. There is no [metrics.tls] either, unlike [server.tls] and [admin.tls]: those carry a client’s signed requests and an operator’s session cookie, while a scrape carries no credential and the exposition holds no secret.

What is exposed, and how to point Prometheus at it, is in Monitoring.

enabled (Boolean) — Default: false | Env: ACME_PROXY_METRICS__ENABLED

Bind the metrics listener and serve GET /metrics. Off by default, the same posture [admin] takes: a certificate authority should not open a new socket because somebody upgraded it. Off means no socket at all, rather than one answering 404.

bind_address (String) — Default: 127.0.0.1:3002 | Env: ACME_PROXY_METRICS__BIND_ADDRESS

The socket the exposition is served on — beside the other two, server on 3000 and admin on 3001.

Unlike admin.bind_address, a non-loopback value is neither refused nor warned about. The admin listener refuses one without TLS because its cookie is always Secure, which a browser silently declines to store over plain HTTP, so the symptom would be an unexplained sign-out loop. Nothing here has a cookie, and a port reachable from a Prometheus host on another machine is exactly the intended deployment.

A value equal to server.bind_address, or to admin.bind_address while the panel is enabled, is refused — at startup and on a reload alike — since only one of the three could then bind.

Both keys reload: SIGHUP moves this listener, or switches it on and off, without restarting. The new socket is bound before anything is published, so an address that cannot be bound refuses the reload and leaves the running one serving. See Configuration Reload.

[dns]

resolver (String) — Default: unset (system configuration, i.e. /etc/resolv.conf) | Env: ACME_PROXY_DNS__RESOLVER

host:port of the nameserver every DNS lookup this server makes goes through: the dns-01 TXT query, the connect target that http-01/tls-alpn-01 resolve before reaching out, and filter.reverse_dns’s PTR and forward lookups.

The shared resolver is deliberately uncached, so a TXT record published moments before a challenge is triggered is not defeated by a cached negative answer. filter.reverse_dns is the one exception and keeps its own cached resolver.

[proxy]

The forward proxy every outbound HTTP client dials through: the upstream CA the relay signer talks to, the IPAM inventory, the notification webhooks, and the http-01 and tls-alpn-01 challenge validators — the last through a CONNECT tunnel, since it is TLS rather than HTTP.

Not everything outbound. SMTP (notify.email) and the RFC 2136 updates signer.relay.dns01 makes are not HTTP and keep dialling directly; an estate whose egress is proxy-only needs a separate route for those two.

Every key is empty by default, which means no proxy at all. There is no enabled key — the presence of a URL is the switch.

http_url (String) — Default: "" | Env: ACME_PROXY_PROXY__HTTP_URL

Proxy for http:// targets, e.g. http://proxy.example.com:3128. Falls back to $http_proxy when empty. A cleartext target is forwarded rather than tunnelled: the request line carries the whole URL, which is what RFC 9112 §3.2.2’s absolute-form is for.

https_url (String) — Default: "" | Env: ACME_PROXY_PROXY__HTTPS_URL

Proxy for https:// targets, reached by CONNECT. Falls back to $https_proxy, then $HTTPS_PROXY.

Normally the same http://proxy.example.com:3128 as http_url: this key names the proxy used for https targets, not a proxy spoken to over https. An https:// value is a startup error rather than a second TLS layer with no trust anchor configured for it, and so is a socks5:// one.

The two keys are independent on purpose. An estate that proxies only its TLS egress is ordinary, and “it worked for http and silently did nothing for https” is the failure a single key would produce.

no_proxy (Array<String>) — Default: [] | Env: ACME_PROXY_PROXY__NO_PROXY

Targets that bypass the proxy. An entry is * (everything), a domain — which also matches everything under it — a .domain (the same thing), an address, or a CIDR block. Matching is case-insensitive and ignores a trailing root dot.

A network entry is compared only against a target that is already an address literal: a hostname is never resolved to test one, which would mean a DNS lookup on every outbound request and a race with the connect that follows.

An entry carrying a port is a startup error. Matching is on the host, and an entry that silently ignored half of itself is worse than one that is refused.

Loopback and localhost bypass unconditionally, before this list is consulted. That rule exists because of the environment fallback: an operator’s inherited shell http_proxy must not route this server’s own loopback traffic through a corporate proxy, and the failure that would cause carries no signal at all.

Environment fallback

Each key falls back to its conventional variable when left empty:

An empty string counts as unset in both sources, so a ${VAR:-} shell default does not become a proxy at the empty URL.

Uppercase HTTP_PROXY is deliberately not read. Under CGI a client-supplied Proxy: request header lands in the environment under exactly that name (httpoxy, CVE-2016-5385 and its siblings). This server is never a CGI process, so the vector does not reach it — but Go’s net/http dropped the variable for this reason, matching it costs nothing, and honouring a variable purely because everything else does is the kind of decision that is only ever wrong. HTTPS_PROXY has no such history and is honoured.

Credentials

Userinfo in the URL becomes a Proxy-Authorization: Basic header: http://user:password@proxy.example.com:3128. Percent-encode anything unusual — DOMAIN%5Cuser is decoded before the header is built, since a backslash or an @ in a proxy username is entirely ordinary and encoding it verbatim sends the wrong credential.

On a tunnelled connection the credential is spent on the CONNECT and is not repeated inside the tunnel, where the origin server would read it. The configured URL is never logged with its password: every log line and every error message renders it with the password replaced.

When the proxy is down

A configured but unreachable proxy is an error, every time. There is no fallback to a direct connection: dialling around a controlled egress path at exactly the moment the control fails is the opposite of what the setting is for. Errors name the proxy rather than the origin, so a refused connection points at the host that actually refused it.

[meta]

The optional meta members of the directory (§7.1.1). All are empty by default and omitted from the directory when empty — never sent as an empty value.

terms_of_service (String) — Default: "" | Env: ACME_PROXY_META__TERMS_OF_SERVICE

URL of your terms of service. This one has teeth: setting it turns on §7.3.3, so newAccount then refuses any request without termsOfServiceAgreed: true (403 userActionRequired + a Link: rel="terms-of-service" header), and account objects begin reflecting termsOfServiceAgreed.

website (String) — Default: "" | Env: ACME_PROXY_META__WEBSITE

Informational URL about the ACME server. Advertised only.

caa_identities (Array) — Default: [] | Env: ACME_PROXY_META__CAA_IDENTITIES

Hostnames this CA recognizes in CAA records. Advertised only — this server performs no CAA checking.

[logging]

All six keys are validated at startup: an unknown value is a refusal to start with a message naming the key, never a silent fallback — a CA running at a log level or to a destination its operator did not ask for is the worse failure. The same validation runs on a reload, where a bad value refuses the whole thing rather than half-swapping the log stream.

All six also reload on SIGHUP, so raising the level or switching to JSON mid-incident does not cost a restart.

What the resulting records actually contain, and what to alert on, is Monitoring & Observability.

filter (String) — Default: "acme_proxy=info" | Env: ACME_PROXY_LOGGING__FILTER

EnvFilter directive, and the last of three layers to be consulted. The precedence, highest first:

• --log-level, typed on the command line. A flag was asked for here and now, where the other two are ambient — the same reasoning that has --color always outrank NO_COLOR. It sets acme_proxy alone, so it never turns on a dependency’s logging by accident.
• RUST_LOG, when set to a non-empty value. It replaces the whole filter, so a bare RUST_LOG=debug also turns on debug logging for every dependency.
• this key.

That precedence is the same on a reload as at startup, which means editing this key while either of the two outranks it changes nothing; the server logs server_logging_filter_overridden, whose source field names which one, rather than letting the edit pass for applied.

This section describes the server’s log stream. An admin command emits nothing at all unless asked — see the CLI’s --log-level.

json_format (Boolean) — Default: false | Env: ACME_PROXY_LOGGING__JSON_FORMAT

Emit JSON instead of the human-readable format. Set this in production if you ship logs to ELK, Loki, Datadog or similar: the structured fields become first-class keys rather than text to be re-parsed.

target (String) — Default: "stdout" | Env: ACME_PROXY_LOGGING__TARGET

Where records are written: stdout or stderr. Any other value is a startup error.

ansi (Boolean) — Default: true | Env: ACME_PROXY_LOGGING__ANSI

ANSI colour in the human-readable format. Turn it off when the log is piped to a file or a collector that does not strip escape sequences. Ignored when json_format is on.

span_events (String) — Default: "none" | Env: ACME_PROXY_LOGGING__SPAN_EVENTS

Span lifecycle records: none, close or full. Any other value is a startup error. close emits one record as each span ends, carrying the time spent busy and idle inside it — the closest thing to per-operation timing available without a metrics endpoint, and cheap enough to leave on. full adds new/enter/exit and is a debugging tool.

flatten_event (Boolean) — Default: false | Env: ACME_PROXY_LOGGING__FLATTEN_EVENT

JSON only: lift a record’s own fields (event, and everything beside it) to the top level instead of nesting them under fields. What most pipelines want; off by default because a field can then collide with one of the format’s own keys.

[profiles.<name>]

An ACME endpoint is a profile. The server serves ACME only through them, and at least one enabled profile is required — startup fails otherwise, with a copy-pasteable minimal configuration in the error.

# The whole minimum. `enabled` defaults to true, so naming it is enough.
[profiles.default]

enabled (Boolean) — Default: true | Env: ACME_PROXY_PROFILES__<NAME>__ENABLED

Parks a profile without deleting its configuration. It also doubles as the one key an environment-only profile needs: ACME_PROXY_PROFILES__DEFAULT__ENABLED=true defines a working profile with no configuration file at all.

Load-bearing rules:

• The mount path is derived from the name, never configured. [profiles.le] answers at {base_url}/profile/le/directory. Names must match ^[a-z0-9-]+$. The name is public API — it appears in every kid and order URL a client stores — so renaming a profile invalidates every client’s saved account.
• Inheritance is per key, not per section. The global [signer], [filter], [challenge], [eab], [order], [notify] and [meta] sections are the base each profile overlays. A profile that sets only challenge.bypass keeps the global challenge.enabled rather than reverting it to the compiled default. Precedence: profile key > global key > compiled default.
• Arrays replace wholesale, never append. A profile’s filter.rules fully replaces the global one — order is the policy, so it is stated once per profile rather than accumulated from two places.
• Profiles are a database boundary, not just a URL prefix. Accounts and orders carry a profile column, and accounts are keyed UNIQUE(profile, pubkey) — one client key used at two endpoints is two independent ACME accounts.
• Signer backends are shared by configuration. Two profiles with identical [signer] sections share one backend instance. Two profiles sharing a local_ca key path while differing elsewhere is a startup error.

[signer]
backend = "local_ca"

[filter]
rules = ["corp-only"]

[filter.check.corp-net]
type  = "allowed_ip"
allow = ["10.0.0.0/8"]

[filter.rule.corp-only]
when = "corp-net"
then = "allow"

# Inherits everything above, but dry-runs the one rule: `[filter.rule.<name>]`
# is a table, so overriding `mode` keeps `when` and `then` from the global one.
[profiles.dev]
filter.rule.corp-only.mode = "warn"

# Overrides two keys; keeps the whole filter policy.
[profiles.prod]
signer.backend = "relay"
signer.relay.directory_url = "https://acme-v02.api.letsencrypt.org/directory"

See Profiles & Routing.

Environment variable gotchas

These bite in production and produce no error, so they are worth knowing before you configure anything through the environment.

Array-valued keys are parsed from a comma-separated string. That means a value containing a literal comma cannot be expressed. A regex such as ^host\d{2,3}\.example\.com$ is therefore file-only — through the environment, {2,3} splits into two list entries. In a file, write the array form (deny = ["^host\d{2,3}\.example\.com$"]), which is taken exactly as written; a bare string in a file is split on commas too, since by the time the value is read there is nothing left to say where it came from.

Items are trimmed, and an empty item is a startup error. a, b is ["a", "b"], and a,,b or a trailing comma is refused by name rather than silently dropped or kept as an entry that matches nothing.

An array set to the empty string is the empty list. Shell defaults like ACME_PROXY_FILTER__RULES="${RULES:-}" set the variable to "", which the configuration layer cannot distinguish from a deliberate value — so it is read as “no values”, which is what clears a list the file set. Do not expect "" to mean “fall back to the file”.

A numeric-looking value loses its leading zeros. The environment source parses 007 as a number before the list is built, so it arrives as 7. A value whose spelling matters — an argument to a custom signer, say — belongs in the file’s array form.

Unknown keys are ignored, not rejected. A misspelled key, or a key written under the wrong section, is silently dropped. The most common instance of this is trusted_proxies written under [server] when it belongs to [filter] — see Allowed IP.

Sections documented elsewhere

The six sections with a chapter of their own, expanded — see the map above for the rest.

• [signer] — Signers: local_ca and its PKCS#11 keys, relay, custom
• [filter] — Filters: allowed_ip, path, reverse_dns, identifiers, eab, custom
• [ipam] — IPAM: the inventory the ipam check consults — NetBox, phpIPAM, a custom script
• [challenge] — Challenge Validation: http-01, dns-01, tls-alpn-01
• [notify] — Notifications: email, webhook, custom
• [eab] — External Account Binding

Configuration Scenarios

This page outlines complete, practical examples of configuring acme-proxy for different real-world use cases. Each block is a whole config.toml.

All three scenarios below use the relay backend. Starting the server registers an account at directory_url — see Relay. Use a staging endpoint while you are still working the configuration out.

Let’s Encrypt relay with DNS validation

This scenario configures acme-proxy to act as an internal relay. It intercepts ACME clients locally, but ultimately relays the issuance requests to Let’s Encrypt.

The proxy takes the burden of solving Let’s Encrypt’s DNS-01 challenges on behalf of internal users by utilizing an RFC 2136 dynamic DNS provider. Internal clients never see a DNS credential; the single TSIG key lives here.

[server]
base_url = "https://acme.internal.company.com"
bind_address = "[::]:3000"

[signer]
backend = "relay"

[signer.relay]
directory_url = "https://acme-v02.api.letsencrypt.org/directory"
account_key_path = "le_upstream.key"
contact = ["mailto:admin@company.com"]
challenge_strategy = "dns01"
poll_interval_ms = 2000
poll_timeout_secs = 300

[signer.relay.dns01]
provider = "rfc2136"

[signer.relay.dns01.rfc2136]
server = "10.0.0.53:53"
zone = "internal.company.com."
tsig_key_name = "acme-update-key"
# MUST be standard base64 (not base64url). Prefer the environment variable
# ACME_PROXY_SIGNER__RELAY__DNS01__RFC2136__TSIG_KEY_SECRET to a file.
# A non-base64 value here is a startup error, not a runtime one.
tsig_key_secret = "c2VjcmV0LXJlcGxhY2UtbWU="
tsig_algorithm = "hmac-sha256"

[challenge]
# Require local clients to prove control to the proxy via HTTP-01
enabled = ["http-01"]
bypass = false

[profiles.default]
enabled = true

The key above writes only inside internal.company.com.. For names spread over several zones, DNS alias mode points every domain’s challenge at one alias zone instead of needing a profile per zone.

Public CA relay with HTTP validation

The same relay as above, for an operator who has no RFC 2136 write access to the zone but does control the reverse proxy already fronting the names being issued. Instead of publishing a TXT record, acme-proxy serves the upstream’s challenge file itself.

[server]
base_url = "https://acme.internal.company.com"
bind_address = "[::]:3000"

[signer]
backend = "relay"

[signer.relay]
directory_url = "https://acme-v02.api.letsencrypt.org/directory"
account_key_path = "le_upstream.key"
contact = ["mailto:admin@company.com"]
# No [signer.relay.http01] table exists — this line is the whole
# configuration. The responder is a route on this server's own root router;
# acme-proxy does NOT open a second listener or bind port 80.
challenge_strategy = "http01"
poll_interval_ms = 2000
poll_timeout_secs = 300

[challenge]
# Local clients still prove control to the proxy independently.
enabled = ["http-01"]
bypass = false

[profiles.default]
enabled = true

This only works if the upstream CA’s fetch reaches acme-proxy. Add one location to whatever already answers on port 80 for each name being issued:

location /.well-known/acme-challenge/ {
    proxy_pass http://acme-proxy:3000;
    # A `return 301 http://acme-proxy:3000$request_uri;` works equally well —
    # RFC 8555 §8.3 permits following redirects.
}

Note this strategy cannot issue wildcards (nothing answers HTTP on the name *.example.com); those need scenario 1’s dns01. See Relay for Caddy and Traefik equivalents.

Commercial ACME CA with EAB and NetBox filtering

This scenario uses a commercial CA backend. It enforces External Account Binding (EAB) on the internal proxy so only authorized users can register. It additionally uses NetBox, through the ipam filter, to verify if a client’s IP is actually permitted to request a certificate for a specific DNS name.

[server]
base_url = "https://ca.internal.company.com"

[signer]
backend = "relay"

[signer.relay]
directory_url = "https://commercial-ca.example.com/acme/directory"
account_key_path = "commercial_upstream.key"

# The commercial CA already trusts this server's upstream account implicitly,
# so the upstream challenge is bypassed.
challenge_strategy = "bypass"

[eab]
# Require all internal clients to register with an EAB credential generated by the admin
enabled = true

[filter]
# Ask the inventory about every internal request
enabled = ["ipam"]

[ipam]
backend = "netbox"
timeout_ms = 5000

[ipam.netbox]
url = "https://netbox.internal.company.com"
# Store this in ACME_PROXY_IPAM__NETBOX__TOKEN ideally
token = "your_netbox_read_only_token"
custom_field = "acme_domains"
sources = ["dns_name", "custom_field", "device"]

[profiles.default]
enabled = true

Protocol Support

acme-proxy implements RFC 8555 in full, plus the extensions an ACME client in 2026 expects to find. This page is the conformance summary: what a client can call, which RFC section governs it, and what is deliberately not implemented.

Everything here is served per profile, under /profile/<name>/. There is no ACME at the bare root — see Profiles & Routing.

Resources

Every row is reachable at {base_url}/profile/<name><path>. The Advertised column says whether the directory object names it: a client is expected to find advertised resources by reading the directory rather than by constructing paths.

Two paths sit outside every profile, on the root router:

Two further paths are not on this listener at all. GET /metrics has a socket of its own (off by default, [metrics]), so firewalling that port is what controls who can read it — see Monitoring. The web admin’s /ui and /api likewise have their own listener; see Web Admin.

Protocol behaviour worth knowing

Every signed request is checked the same way. The media type (application/jose+json), any crit header, the JWS url against the route actually reached, and the nonce are all verified before a handler runs, so no resource can forget one. jwk and kid are mutually exclusive per §6.2, and the verification algorithm never rests on the client’s alg alone. See Architecture.

Refusals are problem documents. Every rejection is application/problem+json with an RFC 8555 URN type. A multi-identifier order rejected on several names comes back as one compound problem with a subproblems entry per identifier (§6.7.1); a single rejection stays its own type, unwrapped.

A POST always carries a fresh Replay-Nonce, errors included (§6.5). GET /directory, GET /crl, GET /ca.pem and GET /renewalInfo do not mint one — nothing asks them to, and each nonce is a committed database write.

Extensions

Directory metadata

The directory’s meta object carries only what is configured. An unset member is omitted, never sent empty — "website": "" says less than saying nothing.

• externalAccountRequired appears as true when EAB is on for that profile.
• termsOfService, website and caaIdentities come from [meta].

meta.terms_of_service is the one with teeth: setting it turns on §7.3.3, so newAccount then refuses a request without termsOfServiceAgreed: true (403 userActionRequired plus a Link: rel="terms-of-service" header), and the account object starts reflecting the field.

Not implemented

Stated explicitly, because each is something a reader may reasonably expect:

• CAA checking. meta.caa_identities is advertised to clients; this server does no CAA lookup of its own. Where the relay backend is in use, the upstream CA performs its own.
• OCSP. Revocation is published as a CRL at GET /crl. There is no OCSP responder, and no authorityInfoAccess OCSP pointer is ever written into an issued certificate. The local CA does write the caIssuers half of that extension, and a cRLDistributionPoints pointer, once an operator names the URLs — see Local CA.
• Identifier types other than dns. newOrder accepts DNS names, including wildcards; ip identifiers (RFC 8738) and permanent-identifier are not supported.
• Pre-authorization (§7.4.1). The directory does not advertise newAuthz, and it is not routed. Authorizations exist only as part of an order.
• POST to /renewalInfo — RFC 9773 §4.3’s optional client-side renewal signal. The GET half is implemented.

External Account Binding (EAB)

acme-proxy supports enforcing External Account Binding (RFC 8555 §7.3.4). When enabled, any client attempting to register a new account must provide an EAB credential that was minted out-of-band by the server operator.

This is a highly effective security mechanism for internal CA endpoints: it restricts account creation to authorized entities without relying purely on IP filtering.

Solving commercial CA EAB limits

Beyond security, EAB support in acme-proxy solves a significant operational hurdle when using Commercial CAs (like ZeroSSL, Sectigo, or GlobalSign).

When working with external or commercial CAs, organizations are sometimes restricted to a single account or a limited number of EAB credentials validated for specific domains. It is impractical to distribute these scarce upstream credentials to hundreds of individual internal servers.

By placing acme-proxy in front of the commercial CA:

1. The proxy consumes a single upstream EAB credential to register its own master account with the Commercial CA.
2. The proxy then issues its own unlimited local EAB credentials to your internal servers.
3. This effectively multiplexes the upstream account, allowing thousands of internal clients to securely acquire certificates without exhausting your upstream quotas or spreading sensitive upstream secrets across your infrastructure.

Configuration

[eab]
enabled = true

Reference

enabled (Boolean) — Default: false | Env: ACME_PROXY_EAB__ENABLED

When enabled, the newAccount endpoint will refuse any request that doesn’t carry a valid, unused EAB payload. Standard onlyReturnExisting lookups are exempt because they only query existing accounts and never create new ones.

Minting credentials via CLI

You manage EAB credentials with the Admin CLI, because the secret is sensitive and is shown exactly once.

To create a new credential for a client:

acme-proxy eab create --label "DevOps Team"

# Bind it to a single endpoint in a multi-profile deployment:
acme-proxy eab create --label "DevOps Team" --profile prod

The CLI prints a kid (Key Identifier) and an HMAC secret. The secret is printed only once. It is stored but never displayed again, so a lost secret is replaced, not recovered.

--profile matters in a multi-tenant deployment: omitted, the credential is accepted at every profile, which is what an unscoped credential means. Bind it unless you intend that.

A client then uses the credential at registration:

certbot register \
  --server https://acme.internal/profile/default/directory \
  --eab-kid "the-kid" \
  --eab-hmac-key "the-secret"

Credentials are reusable, not single-use

A credential is not consumed by the account it creates. The same kid can bind any number of accounts and keeps working until you explicitly revoke it. There is no used state — only active and revoked.

This is worth being deliberate about. Handing one credential to a team means any number of hosts can register with it, and a leaked credential stays valid until someone notices. If you want one-client-one-credential, mint one per client and revoke it once that client has registered.

(This differs from the upstream credential consumed by acme-proxy upstream register — or, alternatively, signer.relay.eab in configuration. Commercial CAs typically issue single-use EAB credentials, which is precisely why that one is consumed once by registration and then no longer needed at all, unlike the credentials described on this page.)

Revocation

Revoke a credential to prevent any further use:

acme-proxy eab revoke <kid>

This takes effect immediately, with no restart — credentials are read from the live database on every newAccount. Revocation is idempotent.

Revoking does not disturb accounts that already registered with the credential; it only stops new ones from being bound. To shut out an existing account, deactivate it: acme-proxy account deactivate <id>.

A revoked credential keeps its row, so the accounts it registered still resolve to it — its label keeps matching eab filter checks, and require_active can refuse them.

Deleting a credential

Deleting removes the row. What happens to the accounts registered with it is your choice:

acme-proxy account list --eab-kid <kid>             # who registered with it
acme-proxy eab delete <kid>                         # keep the accounts
acme-proxy eab delete <kid> --deactivate-accounts   # retire them
acme-proxy eab delete <kid> --delete-accounts       # remove them

• Keep (the default) leaves the accounts as they are. They still name the deleted kid but resolve to no credential, so every eab filter check refuses them from then on.
• --deactivate-accounts moves them to deactivated: they can request nothing more, and their orders are kept, so every certificate they hold can still be revoked and still appears in the expiry digest until it expires. This is the way to retire a tenant.
• --delete-accounts deletes them with their orders, authorizations and challenges. It is refused while any of those orders holds a live certificate (issued, not revoked, not expired): the order is the only record of the certificate, and without it the certificate could never be revoked. Revoke those certificates or wait for them to expire, or deactivate instead. A refusal changes nothing, not even the credential.

No choice revokes a certificate. The panel’s credential page offers the same three, and the JSON API takes them as DELETE /api/eab/{kid}?accounts=keep|deactivate|delete. Each writes an eab_deleted audit row, plus one account_deactivated or account_deleted row per account it changed.

Inspecting credentials

acme-proxy eab list --json
acme-proxy eab show <kid>

Neither ever renders the secret. eab list is newest first and paged (Admin CLI → Paging); it reads the same query GET /api/eab and the panel’s /ui/eab do, so the three cannot come to describe the credential set differently.

Key Rollover

acme-proxy fully supports Account Key Rollover (RFC 8555 §7.3.5) via the POST /keyChange endpoint.

This allows a client to proactively rotate the cryptographic key-pair associated with their ACME account without needing to register a new account or abandon their existing authorizations and orders.

Cryptographic verification

The key rollover process is highly secure and requires the client to prove possession of both the old and the new key simultaneously to prevent hijacking.

1. Inner JWS: The client constructs a JSON Web Signature (JWS) whose payload names the account and the new key, signed by the new key itself.
2. Outer JWS: That inner JWS becomes the payload of an outer JWS, signed by the old key currently on the account and carrying its kid.
3. acme-proxy unwraps this nested structure and verifies both signatures (ES256 or RS256, via ring). The outer signature proves the request comes from the current account holder; the inner one proves possession of the new key, so a key the requester does not control cannot be installed.
4. Collision check: the proxy checks that the new key does not already belong to another account. If it does, the request is rejected with 409 Conflict plus a Location header naming the account that already holds the key.
5. Update: the account’s stored public key is replaced in a single statement.

Because accounts are keyed UNIQUE(profile, pubkey), the collision check is scoped per profile — the same key legitimately belonging to a different account at a different profile is not a conflict.

Client support

Many modern clients support key rollover natively. For instance, using lego:

lego --server https://acme.internal/profile/default/directory \
     --email "admin@example.com" \
     accounts keyrollover

(Note: Ensure you are using a recent version of the client, as older clients may lack support for the keyChange endpoint).

Renewal Information (ARI)

acme-proxy implements the ACME Renewal Information extension (RFC 9773). ARI allows a CA to signal to ACME clients when they should ideally renew their certificates. This prevents the “stampede” effect where thousands of certificates expire simultaneously, and allows the CA to orchestrate graceful mass-revocations by shortening the renewal window.

GET /renewalInfo/{certID}

This is an unauthenticated endpoint clients use to ask “when should I renew this certificate?”. The response provides a time window (Start and End).

The window is resolved in this order:

1. Revoked certificates win. If the certificate is known to be revoked locally (looked up by its serial), the answer is a window entirely in the past, prompting a compliant client to renew immediately. This is checked before the signer backend is consulted, so a locally revoked certificate is never talked out of renewing by an upstream CA that has not noticed yet.
2. The backend’s own opinion, if it has one. The relay backend relays the upstream CA’s answer verbatim, including RFC 9773 §4.2’s optional explanationURL — so if Let’s Encrypt signals early renewal, that reaches your internal clients unchanged. The custom backend can do the same through its renewal_info hook, but only when signer.custom.supports_renewal_info = true; otherwise the hook is never invoked.
3. A local estimate, when the backend has no opinion — always the case for local_ca. The certificate’s notBefore and notAfter are read by parsing the certificate itself, and the suggested window runs from ⅔ to ¾ of the validity period. For a 90-day certificate that is roughly day 60 to day 67, leaving a comfortable margin before expiry rather than running up to it.

Spreading clients across that window is what prevents the “stampede” effect where a whole fleet renews at the same moment.

The replaces field

During a newOrder request, an ARI-aware client can include a replaces field containing the certID of the certificate it intends to replace.

acme-proxy validates it against all three of RFC 9773 §5’s correspondence rules. The certID is decoded into an Authority Key Identifier and a serial number, the predecessor order is looked up, and then:

1. The AKI must match the predecessor’s issuer — the serial alone is not enough, since serials are only unique per issuer. (A certificate stored before this check existed may have no recorded AKI; that case falls back to matching on serial alone, for backwards compatibility.)
2. The predecessor must belong to the requesting account. You cannot claim to replace someone else’s certificate.
3. The new order must share at least one identifier with the predecessor. A renewal that covers none of the same names is not a replacement.

Failing any of them is malformed; an unknown certID likewise.

Concurrency guard: a client cannot have two orders replacing the same predecessor. A second newOrder naming a replaces value already claimed gets 409 alreadyReplaced. An order that later becomes invalid releases its claim, so a failed attempt does not permanently block a retry.

The accepted replaces value is stored and reflected back on the 201 response and on every subsequent poll of the order.

Reloading the configuration

acme-proxy reloads its configuration on SIGHUP, without restarting:

sudo systemctl reload acme-proxy
# or, directly:
kill -HUP "$(pidof acme-proxy)"

Nothing is dropped. Connections stay open, in-flight ACME orders keep their state, and queued background work keeps its place. What changes is what the server does with the next request — and, if you moved a listener, on which port it answers it.

A reload is a rebuild and a swap, not a patch. Both routers, every profile’s filter chain and challenge registry, the notification backends, the job registry and both TLS acceptors are constructed fresh from the file on disk — and only once every one of them has succeeded is any of it published.

All or nothing

A reload either applies completely or changes nothing at all.

Three things stop one, and each says so in the log:

In the first two cases the server carries on with exactly the configuration it already had. That matters more than it sounds: a reload that applied the half it understood would leave a running server that no file on disk describes, and “what is this thing actually running?” would stop having an answer.

Every success carries a generation — 1 for the configuration the process started with, and one higher for each reload that landed. It is the quickest way to answer “did my SIGHUP take?”:

journalctl -u acme-proxy | grep server_config_reloaded

What a reload cannot change

One key. A refusal names it, what the server is running, and what the file now says:

`database.url` cannot be changed while the server is running
(running with `sqlite://sqlite.db`, the file now says `sqlite://other.db`):
restart to apply it

Everything else reloads. That was not always true, and the four keys that came off this table most recently are worth knowing about because they are the ones an operator is most likely to remember as frozen: the set of enabled profiles, each profile’s [signer] section, dns.resolver and [proxy]. See Adding and removing endpoints below.

What a reload does change

Everything else, including the things operators reach for most:

• Access policy — [filter] rules and checks, and the [ipam] inventory they consult. Tightening a rule takes effect on the next request.
• The set of endpoints, and each one’s [signer] — see below.
• Egress — dns.resolver and [proxy]. Every outbound client is rebuilt, including the signer backends, which used to be the reason these two were frozen.
• Notification backends — a new webhook, a changed template directory, a different events list.
• Challenge settings, order and account policy, [meta], [eab].
• TLS certificates — server.tls.cert_path and key_path (and the admin listener’s own pair) are re-read, so a renewed certificate is served to the next connection while established ones are undisturbed.
• The listeners themselves — see below.
• The panel’s templates — admin.template_dir is recompiled. A template that does not parse fails the reload, so a mistake never reaches a browser.
• Retention — audit.retention_days and jobs.retention_days. A sweep already scheduled keeps its current time and picks the new cutoff up on its next run.
• Background work — every [jobs] key, so slowing a retry storm, widening a lease or raising concurrency mid-incident costs nothing. See below.
• Logging — every [logging] key, so raising the level or switching to JSON mid-incident costs nothing. The swap is the first thing a reload publishes, so the server_config_reloaded line that confirms it is already under the new settings. One caveat: RUST_LOG still outranks logging.filter, exactly as it does at startup, so with it set an edited filter changes nothing — the server says so with server_logging_filter_overridden.

For what each key means, see the configuration reference.

Adding and removing endpoints

Add a [profiles.<name>] section and signal, and that endpoint starts serving:

server_config_reloaded generation=2 profiles=["le", "staging"]
profile_mounted profile=staging directory=https://ca.example/profile/staging/directory

Remove it and signal again, and it stops. Endpoints that were already running are not disturbed either way — no connection is dropped and no in-flight order loses its state, which is the whole reason this is worth doing without a restart.

Three things to know.

profile_mounted fires only for an endpoint that was not there before. It is a lifecycle event, delivered to whichever [notify] backends are configured, so re-firing it for every endpoint on every SIGHUP would make the notification surface noisiest in exactly the config-managed deployments that would least want it.

Unmounting keeps the data. The accounts and orders belonging to that endpoint stay in the database and come back exactly as they were if you mount it again — the profile name is what they are keyed on. Setting enabled = false is the same thing as removing the section.

Drain a relay endpoint before removing it. Unmounting the last profile a relaying backend serves takes its job handler with it, so any issuance still waiting on the upstream has nothing left to finish it. Those rows sit in the queue until the endpoint is mounted again, and the orders behind them expire. Nothing else is affected, and no other backend has background work to lose.

Editing a signer

A profile’s [signer] section reloads, including the one an endpoint is actively issuing with. The obvious worry — that a rebuilt local CA would forget what it had revoked — does not arise: revocations and the CRL live in the database, which the running CA and its replacement both read, so a revocation that lands during the reload is not lost either, and GET /crl answers identically across the swap. A relay serving http-01 keeps its published key authorizations in the database the same way, so an upstream CA fetching one mid-reload still gets it.

A backend whose section did not move is not rebuilt at all. That matters most with key_source = "pkcs11": an ordinary reload does not log in to the token again.

Two edges:

• Changing where the CA material lives is a new CA. Point crl_path at a different file and the endpoint starts from that file’s revocation history, not the old one’s. That is the intended reading of the key, but it is worth saying, because the certificates already issued do not move with it.
• [dns] and [proxy] rebuild every backend. They are not [signer] keys, but an outbound client caches them, so a change to either has to reach the signers to mean anything. Nothing is lost — the same handover applies.

Moving a listener

All seven keys that decide where a socket is, or whether there is one, reload: server.bind_address, server.tls.enabled, admin.enabled, admin.bind_address, admin.tls.enabled, metrics.enabled and metrics.bind_address. A reload that moved one says which:

server_config_reloaded generation=2 listeners_rebound=["acme"]

Three things are worth knowing before you use it.

A bad address refuses the reload; it does not take the socket down. Every new socket is bound before anything is published, so a port already in use, a name that does not resolve or a privileged port you no longer have the capability for is a server_config_reload_failed — with the listener that is already running still answering on the address it always had. Fix the file and signal again.

Established connections are not disturbed. A rebind replaces the socket new connections arrive on; a request already in flight finishes, and a keep-alive connection opened before the move stays usable until its client closes it. The old socket stops accepting immediately, so nothing new arrives there.

Turning TLS on or off does not move the socket at all. The mode is decided per connection, like the certificate: the next client to connect speaks the new protocol on the same port, and listeners_rebound stays empty. Remember to move server.base_url with it, or every signed request fails RFC 8555 §6.4’s URL check — the server warns tls_base_url_mismatch when it can see the two disagree.

One caveat on the panel. Switching admin.enabled off releases the socket and empties its router, so nothing answers on it — but it does not sign anybody out: sessions live in the database and are waiting when you switch it back on. Use acme-proxy admin session revoke --all if that is what you meant. Switching it off and on again does clear the login-attempt lockout, since the limiter goes with the panel.

Retuning the job runner

All seven [jobs] keys reload. These are the knobs you reach for while something is going wrong — an upstream CA rate-limiting you, a backlog draining too slowly — so a restart to apply them would have dropped exactly the in-flight orders you were trying to save.

The runner does not restart; it picks the new values up on its next pass and says so:

job_runner_retuned poll_interval_ms=250 lease_seconds=120 max_concurrent=16

That line is the confirmation worth grepping for. server_config_reloaded means a generation was published; this means the runner is actually running under it. It is only emitted when the pacing really moved, so reloads that touch other sections stay quiet.

Each key lands at its own grain, and the differences are all in the same direction — nothing already in flight is disturbed:

• poll_interval_ms takes effect immediately, without waiting out the old interval first.
• max_concurrent widens at once when raised. Lowered, it takes back the slots that are free and reaches the new figure as running jobs finish; no job is cancelled to get there sooner.
• lease_seconds, retry_base_seconds and retry_max_seconds apply to the next job claimed. One already running keeps the budget and the backoff it started under.
• max_attempts is frozen onto each job when it is queued, so a change applies to work queued from then on. Raising it is not a way to rescue a backlog that is about to give up — those rows keep the budget they were queued with.
• retention_days rebuilds the sweep, including registering it when it goes from 0 to a real value.

Systemd

Add ExecReload to the unit so systemctl reload works:

[Service]
ExecReload=/bin/kill -HUP $MAINPID

See Deployment for the rest of the unit.

Two things to expect

Neither is a problem, but both look odd if you are not expecting them.

Startup warnings repeat. A reload re-emits the advisories that describe the configuration it just applied — challenge_validation_bypassed, filter_disabled, tls_disabled and the rest. That is deliberate: they are written to stay visible for as long as the condition holds.

profile_mounted does not repeat. It is a lifecycle notification meaning “this endpoint came up”, delivered to whichever [notify] backends are configured. Firing it on every reload would make the notification surface noisiest in exactly the config-managed deployments that would least want it.

Reloads a restart still handles better

Two edges, both brief and both identical to what a restart does:

• A request that was already in flight when the reload landed finishes under the old configuration. That includes the notification it may queue.
• For the moment it takes in-flight requests to drain, the old and new admission limits are both in force, so concurrency can briefly reach twice server.max_concurrent_requests.

If a change is important enough that neither is acceptable, restart.

Admin CLI

acme-proxy embeds an administrative command-line interface in the same binary, so a full deployment never needs a separate tool to manage its state: accounts, orders, the audit trail, the job queue, nonces, EAB credentials, the upstream account, the web admin’s operators and sessions, and the database itself (migrate, init, transfer). profile and filter read the configuration back as the server would build it.

Invoking it

serve is the default subcommand, so a bare acme-proxy starts the server. You reach the admin CLI by naming a subcommand:

acme-proxy account list

Every command reads the same configuration as the server — config.toml in the working directory, or ACME_PROXY_CONFIG, plus ACME_PROXY_* environment overrides — so it must be run where the configuration points at the same database. There is no --config flag.

Commands operate directly on the database, SQLite or PostgreSQL. Running them against a live server is safe (SQLite runs in WAL mode; PostgreSQL is built for concurrent writers), but they act immediately and are not transactional across the server’s own in-flight requests.

The schema is applied explicitly

Opening the database does not migrate it. acme-proxy migrate applies any migrations that have not run yet, and a serve running the worker role does the same at startup — so a default single-process acme-proxy serve against a fresh database still just works.

Everything else checks the schema and refuses by name:

database error: the schema is 3 migration(s) behind; run `acme-proxy migrate` first

This used to be a side effect of opening the database, which made every subcommand an upgrade step — acme-proxy audit list from a newer binary silently rewrote the schema — and let two processes starting together race the migration runner, SQLite offering sqlx no lock to serialise them.

acme-proxy migrate is idempotent and safe to run repeatedly; it prints how many migrations it applied, or says the schema is already up to date.

acme-proxy init migrates and then generates whatever first-run material the configuration calls for — the local CA key and certificate, an upstream account for a relay profile, a self-signed TLS certificate. It is the one command that creates key material, so a split deployment runs it once, as the uid that should own those files, before starting anything.

Moving between backends

acme-proxy transfer --to <url> copies every row of the configured database into another one. The scheme of each URL picks its backend, so this is how a SQLite deployment becomes a PostgreSQL one — and the reverse is the same command with the two swapped.

$ acme-proxy transfer --to postgres://acme@db.internal/acme
Copy 14203 row(s) from sqlite://acme.db to postgres://acme:***@db.internal/acme?
The source server must be stopped, or the copy is a torn snapshot.
Continue? [y/N] y
  accounts                 412
  orders                  9881
  audit_log               3910
  …
Copied 14203 row(s) into 15 table(s).

Stop the server first. Nothing can check it: a worker that issues a certificate while the copy is running writes rows the copy has already walked past, and the result looks exactly like a good one. That is the only part of this an operator has to get right unaided.

The target must already exist, be migrated and be empty. Create the database, run acme-proxy migrate against it (this command will not — applying a schema belongs to migrate, init and the worker role, and nothing else), then transfer. A target that already holds rows is refused by name, listing them: a transfer is a copy, not a merge, and there is no flag that makes it one.

Row ids, certificate serials and audit ids all survive, because all three are things something outside the database still refers to — a kid a client stored, a serial the CRL carries, an id an operator typed. A certificate issued before the move is revocable after it.

What does not travel is the schema’s own history: each backend keeps its own migration set and checksums. And --json answers {"tables": [{"table", "rows"}], "total"} — a report of a copy, not a listing, so it has its own shape rather than the paged envelope.

Roles

serve takes --role, a comma-separated list of acme, admin and worker. With no --role it runs all three in one process, which is the default and what every deployment before the flag existed did.

Splitting them puts the process that parses untrusted JWS and CSRs, the process that holds operator sessions, and the process that reaches out to client-chosen hosts in three different places, each able to run under its own uid. See Deployment.

An unknown role is refused with usage before anything is read:

error: invalid value 'wroker' for '--role <ROLES>': unknown role `wroker`
(expected one of: acme, admin, worker)

A process running no worker logs the advisory server_role_no_worker at startup: nothing there drains the queue, so challenge validation, notifications and the periodic sweeps all wait for a process that does.

Global flags

-y, --yes — skip the interactive “Are you sure?” prompt on destructive commands. It is a global flag, so it may be given anywhere on the line. account delete, order delete, eab delete, jobs cancel, audit cleanup, nonce cleanup, transfer, admin user delete and admin user totp reset prompt; nothing else is gated by it.

--json — where supported, emit JSON instead of the human-readable line format. Single-item commands print one JSON object. Every list command prints the same envelope the admin JSON API returns, so a script does not learn one shape for the shell and another for the API:

{ "items": [ … ], "total": 137, "limit": 50, "offset": 0 }

total is what the same filters match unpaged, which is the difference between having read the table and having read a page of it. See Paging. (It is not newline-delimited JSON.)

--color <auto|always|never> — when to colour the human-readable output. Also global. The default is auto: colour when the stream is a terminal and NO_COLOR is unset or empty, which means a piped or redirected run is plain without your having to say so.

• always colours regardless of the stream and regardless of NO_COLOR — it was typed on this command line, so it outranks both. That is what makes acme-proxy audit list --color always | less -R work.
• never never colours, whatever the terminal is.
• An unrecognised value is refused rather than treated as auto.

Colour is decided separately for stdout (the output) and stderr (error messages), since the two are redirected independently. It is semantic, never decorative: statuses (valid, pending, revoked…), audit events that name a refusal, filter explain’s per-check verdicts, and the standing warnings such as eab create’s “shown only this once”. Labels, timestamps and identifiers are never coloured.

--json output never carries colour, at any setting — it is the same bytes a script parses today. So is every human-readable line under --color never.

Note this is not the same switch as logging.ansi, which colours the server’s log stream and is a configuration key rather than a flag; the CLI’s colour is not configurable, on purpose, since the right answer depends on the terminal in front of you rather than on the deployment.

--log-level <off|error|warn|info|debug|trace> — emit log records for this run. Also global.

An admin command prints only its own output by default: no log records at all, on either stream. That is what makes acme-proxy account list --json | jq work — before this flag existed, a db_migration_completed record landed on stdout ahead of the JSON on every invocation, because [logging] was installed for every subcommand and its target defaults to stdout.

• Records go to stderr, whatever logging.target says. stdout is the answer; a diagnostic does not belong in it.
• The level covers acme-proxy alone, so --log-level debug does not also turn on sqlx and hyper. Set RUST_LOG for a directive that reaches further — a non-empty RUST_LOG turns records on by itself, with no flag.
• --log-level off is silence stated explicitly, which is what a script wants when the environment it runs in may carry a RUST_LOG.

It is worth reaching for on filter show, which builds the policy exactly as startup does and so is the cheapest pre-restart check: the refusals are printed either way, but the advisories are log records, so filter show --log-level warn is how you see filter_disabled and filter_check_unused before a restart rather than after it.

On serve the flag outranks both RUST_LOG and logging.filter — a flag was typed where the other two are ambient — and [logging]’s other five keys still decide the format, the target and the rest. It survives a SIGHUP, so an operator who started the server at --log-level debug keeps it across a reload; an edit to logging.filter is then a no-op the server warns about (server_logging_filter_overridden).

--version — print the build’s own version and exit. It is the first thing a bug report asks for, and the answer a checkout cannot give on a host where the binary was copied in. --help is its counterpart and works at every level: acme-proxy audit --help lists that group’s subcommands.

Exit codes

An admin command exits with one of these. A script can branch on the code without parsing stderr; the deciding question between 1 and 3 is whether re-running the identical command is worth it.

serve exits 1 for any startup failure and otherwise runs until it is signalled.

Shell completions

acme-proxy completions <shell> prints a completion script on stdout, for bash, elvish, fish, powershell or zsh. It is generated from the same command tree clap parses, so it covers every subcommand and flag, four levels deep — acme-proxy admin user totp completes to status, reset and recovery-codes. Flag values complete only where the flag has a fixed set clap knows about, which today is --color, --log-level and completions’ own <shell>; --status and --outcome take a string the command refuses by name, so a shell has nothing to offer for them.

The command reads neither the configuration nor the database, so it works anywhere, including in a shell startup file and before a deployment exists.

# bash — system-wide, or ~/.local/share/bash-completion/completions/acme-proxy
acme-proxy completions bash | sudo tee /etc/bash_completion.d/acme-proxy

# zsh — any directory on $fpath; the file must be named _acme-proxy
acme-proxy completions zsh > ~/.zfunc/_acme-proxy

# fish
acme-proxy completions fish > ~/.config/fish/completions/acme-proxy.fish

Regenerate after upgrading: before 1.0.0 the CLI is not frozen, so a script kept from an older binary can go on offering a subcommand that no longer exists. The policy is stated in the changelog.

One limitation is the generator’s rather than this CLI’s: the fish script stops completing at three levels, so acme-proxy admin user totp offers nothing past totp. The other four shells complete the whole tree.

Man page

acme-proxy man prints the roff source of acme-proxy.1 on stdout. Like completions, it reads nothing and is generated from the command tree:

acme-proxy man | sudo tee /usr/share/man/man1/acme-proxy.1 > /dev/null
man acme-proxy

It is one page for the top-level command — the options, every subcommand with its one-line purpose, the environment variables, the configuration file, and a pointer back to this book. The per-flag detail of each subcommand lives in the tables below rather than in the page, which is why SEE ALSO names the book. Read it without installing anything with acme-proxy man | man -l -.

Account management

• account list --profile restricts the listing to one ACME endpoint. Without it, accounts from every profile are listed — the admin CLI is deliberately unscoped by default, unlike the request path, which always scopes by profile. The listing is newest first and paged; see Paging below.
• account list --eab-kid lists the accounts one EAB credential registered — what to look at before eab delete.
• account list shows, per account, the address its key was last seen from and that address’s reverse name (ip (ptr), the address alone when no name resolved, - when neither was recorded). account show prints one field per line and adds where the account was registered from. Nothing in the server ever compares against these — pinning an identity to an address breaks CGNAT and mobile — and none of them reaches an ACME object.
• account deactivate prevents the account from making any further requests. It is the operator-side equivalent of a client deactivating itself.
• account delete cascades: every order, authorization and challenge belonging to the account is destroyed with it. The prompt names what will go.
• account delete and order delete are refused while a live certificate would go with them — one issued, not revoked, and not known to have expired. An order row is the only record of its certificate: without it, revokeCert and order revoke cannot find the certificate, and it drops out of the expiry digest and renewal information. Revoke it first (order revoke), or wait for it to expire. A certificate whose expiry was never recorded counts as live. There is no flag to override this.

Order management

• --status is one of pending, ready, processing, valid and invalid, and is refused by name otherwise.

• --identifier <name> finds the orders that name that identifier exactly (case-insensitive): the answer to “which order covers web.corp.example.com”. It is an exact match on purpose — --identifier example.com will not surface evil-example.com, which is the wrong thing to hand somebody hunting a misissuance. --identifier-contains <text> is the substring form for when only a fragment of the name is remembered; the two are mutually exclusive.

  A wildcard order stores the wildcard form, so --identifier matches *.example.com and not host.example.com — “which order named this?” is not “which certificate covers this?”, and only the first is a question an exact match can answer. --identifier-contains example.com spans both.

• --cert-serial <hex> finds the order whose issued certificate carries that serial — the value an abuse report hands you, and the same one audit list --cert-serial filters on. Case and separators do not matter: what openssl x509 -serial prints (upper case) and what a report quotes (often colon-separated) are both folded to the form the column holds.

• order list --expiring-in <days> asks a different question over a different query: the certificates this CA issued that reach their notAfter inside the window, soonest first, each annotated with whatever has already replaced it. It is the same listing the [notify.expiry] digest mails and the panel shows at /ui/expiring, so the three cannot come to disagree about what “expiring” or “already replaced” means. Add --hide-superseded to drop the rows that have a successor and leave only the ones to act on. Under --json the envelope carries two more members, as GET /api/expiring does: hidden, the rows --hide-superseded dropped from this page, and days, the window asked for.

• --status, --account-id, --identifier, --identifier-contains and --cert-serial are refused with --expiring-in, by name. The expiry listing is issued, unrevoked certificates by definition, has no account predicate and is ordered by expiry, so any of them would silently mean something other than it does elsewhere — the rule --status and audit list --event already follow.

• order show prints one field per line, omitting every field that was not recorded rather than rendering it empty — the shape audit show and account show have. It covers the certificate’s serial and the leaf’s own notAfter beside the requested notAfter the client asked for, and the revocation timestamp and reason, which are deliberately absent from the ACME JSON a client sees — revocation state is admin-visible only.

• order show and order show --json describe the same order, field for field, with one deliberate exception: the issued chain. --json carries it as certificatePem and the web panel offers it as a download; the text rendering does not, a command run to get one’s bearings being the wrong place for several kilobytes of PEM. The three URL members (authorizations, finalize and the ACME certificate URL, which is reachable only by signed POST-as-GET) are likewise --json’s alone — the indented authorization tree is what a terminal reads instead.

• order chain <id> prints that chain and nothing else, so it pipes:

  $ acme-proxy order chain 0198f3b1-... > web.example.com.pem
  

  It is the terminal’s spelling of the panel’s GET /ui/orders/{id}/chain.pem download, and it keeps that route’s rule: an order that never reached issuance is an error, not an empty file, because zero bytes named .pem read as a broken certificate rather than an absent one. There is no --json — the PEM is the output.

• order revoke is the operator-side equivalent of POST /revokeCert, for an out-of-band compromise report a client cannot or will not act on. It never loads a CA key or contacts an upstream itself; the running server does the signing, as Revocation & CRL describes. It is not confirm-gated, because revocation only ever tightens trust.

  --reason is the RFC 5280 reason code: 0–6 or 8–10, since 7 is unused; any other value is refused. Omitted, the revocation carries no reason. For a relay or custom profile the revocation is queued for the running server, and --wait is how many seconds the command waits for it to land before returning (default 30); --wait 0 queues it and returns at once. A local CA’s revocation is recorded immediately and does not wait.

Job queue

The background queue (relayed issuance, notification delivery, the periodic sweeps) is what keeps an order processing through a transient upstream failure instead of failing it. When an order is stuck, this is where to look.

• jobs list is paged like the other listings, newest first. --status is one of ready, running, done, failed, cancelled and is refused by name — passed to SQL an unknown value answers “no rows”, which reads as “nothing is in that state”. --kind is not refused: a job kind is an open set, so a typo simply matches nothing.

• jobs show prints one field per line, and for a relay issuance job (kind = signer_relay_issue) it appends the upstream order it drives — the upstream URLs and the upstream’s own error text. The stored CSR is never shown.

• jobs cancel retires a job (status = cancelled) and is confirm-gated. Two things it will not do:

  • A running job is refused — a runner owns it, and its lease will expire or it will settle. Wait it out, then cancel the resulting ready/failed row.
  • Cancelling a periodic sweep job (nonce_sweep, audit_sweep, order_sweep, …) stops that sweep until the server restarts. The prompt says so.

  Cancelling an in-flight signer_relay_issue job also abandons the ACME order: the local order is marked invalid (so the client stops polling), the upstream mapping is abandoned (so a restart does not resume it), and a certificate_issue_failed audit row is written naming you. This is the operator-side way to stop a relayed issuance that will never complete.

• jobs run-now makes a job eligible immediately — it is picked up within jobs.poll_interval_ms (it does not wake the runner). On a ready job it just pulls run_at forward; on a failed job it grants exactly one more attempt (attempts is set to max_attempts - 1), not a fresh budget, because a full reset is what turns a permanently failing job into an infinite retry loop. It is not confirm-gated.

The web admin has the same surface at /ui/jobs (GET /api/jobs), with cancel and run-now behind an operator-or-higher session.

Audit trail

• audit list is paged like every listing; see Paging.
• An unknown --event or --outcome is refused by name, listing the values this build knows. Passed through to SQL it would answer “no rows”, which reads exactly like “nothing happened”.
• audit show prints one field per line, omitting every field that was not recorded rather than rendering it empty.
• audit cleanup is the only command in this binary that destroys audit history, so it is confirm-gated and its prompt names the row count. audit.retention_days runs the same sweep daily.

The web admin can read this trail but not prune it — see Audit Trail.

Paging

Every listing in this binary is paged. account list, order list (both of its queries), audit list, jobs list, eab list, upstream order list, admin user list and admin session list all take --limit <n> and --offset <n>, defaulting to 50 rows. orders and audit_log each grow a row per issuance for the life of the deployment, so there is deliberately no “everything” spelling and --limit 0 is not a way around it: on a year-old CA that is a terminal full of scrollback and a table loaded into memory. A nonsense window is corrected rather than refused — a --limit 0 becomes one row, a negative --offset becomes zero.

eab list, admin user list and admin session list used to answer a bare JSON array with no window, on the argument that an operator mints those rows by hand a few at a time. That was true of how the tables fill and said nothing about how long they have been filling — and it made a script learn one shape for the shell and another for /api.

Every paged listing ends with a count, always and not only when the page is short:

$ acme-proxy order list --limit 2
...
2 of 1877 row(s).

“42 of 1877” is the difference between having read the table and having read a page of it. Page with --offset; the listings are ordered newest first, tie-broken on the row id, so a row cannot swap between pages and go unseen.

admin user list is the one exception, and is oldest first. The bootstrap operator — created before there was a panel to sign in to — is precisely the row whose position should not move as colleagues are added.

order list --expiring-in adds a third number when --hide-superseded drops rows, because supersession is decided per row and cannot become part of the query — so the total counts the window, not the rows printed under it:

$ acme-proxy order list --expiring-in 30 --hide-superseded --limit 20
...
6 of 8 row(s), 2 superseded hidden.

Under --json every one of them answers the same envelope the admin API returns, member for member (order list --expiring-in adds hidden and days, as its API twin does):

$ acme-proxy eab list --limit 2 --json
{"items":[…],"total":37,"limit":2,"offset":0}

The window is not clamped to admin.page_size_max. That key is a ceiling on what an HTTP caller may ask the server for; this front end already answers to a shell on the host.

Access policy

--profile may be omitted only when exactly one profile exists, the same rule upstream show follows: [filter] is per-profile, so acting on “the policy” without saying which one would be acting on nothing.

filter show prints the resolved policy — every check with its type and the stages it decides at, then every rule in evaluation order with its condition re-parenthesized. That last part is the point: an operator who wrote a or b and c sees a or (b and c) printed back and has their answer about precedence without reading the grammar.

Both commands build the policy rather than reading the file back, so every startup refusal reaches you here too. filter show is therefore the cheapest way to check a policy before restarting the server. Like every command but completions and man, they open the configured database first, so on a fresh host run acme-proxy migrate before them:

$ acme-proxy filter show
profile: default
default: deny (when a rule was applicable and none matched)

checks
  inventory            ipam         identifiers only
  mgmt-net             allowed_ip   connection and identifiers

rules (first match wins)
  mgmt-bypass          mgmt-net -> allow
                         evaluated at: connection and identifiers
  inventory-owned      inventory or mgmt-net -> allow
                         evaluated at: identifiers only

--json prints the same policy as a document, which is what a configuration check in CI reads — and is the shape the web panel renders, so the two front ends cannot come to describe one policy differently:

{
  "profile": "le",
  "active": true,
  "defaultEffect": "deny",
  "warning": null,
  "checks": [
    { "name": "mgmt-net", "type": "allowed_ip", "stages": "connection and identifiers" }
  ],
  "rules": [
    { "name": "inventory-owned", "when": "corp-names and (inventory or mgmt-net)",
      "then": "allow", "mode": "enforce", "stages": "identifiers only" }
  ]
}

checks is name-sorted and rules is evaluation order. An endpoint with no rules answers "active": false and the warning above, with defaultEffect null rather than the configured word: filter.default is consulted only where some rule was applicable, so with no rules it is not a fact about that endpoint at all.

filter explain evaluates it against a hypothetical request and reports all three stages — connection, newOrder and CSR — because every stage must allow, and that is the thing most easily misread. For each it prints every check’s verdict with its reason, which rule matched, and the HTTP answer that stage would produce.

$ acme-proxy filter explain --client-ip 10.0.0.5 --identifier web.corp.example.com

Checks the evaluation never reached are listed as skipped: a short-circuited operand and a passing one look identical in the outcome, so this is the only way the output can answer “why did my inventory check not run”.

This really runs the policy. filter explain executes your custom scripts and issues real IPAM and DNS requests, exactly as a request would, because a stubbed answer would be worse than nothing the first time it disagreed with production. It writes nothing, and it names the checks that reached outside the process at the end of its output (sideEffects under --json).

That is also why explain is a host-only command with no web-admin equivalent: the address and names are chosen by the caller, so behind a session it would be script execution and outbound requests driven from one stolen cookie. show is the opposite case and the panel does serve it — see Web Admin — because it reads an already-built policy and reaches nothing outside the process.

Nonce housekeeping

nonce cleanup deletes expired nonces. The server already sweeps them on an interval for the life of the process, so this is mainly a debugging tool. --ttl-seconds defaults to the configured nonce.ttl_seconds.

nonce count reports the table size and the window a nonce is fresh for — the terminal’s spelling of GET /api/nonces, answering the same {count, ttlSeconds} under --json:

$ acme-proxy nonce count
1284 nonce(s), ttl 300s.

The two numbers are only meaningful together. The count should sit near the request rate times the TTL; one far above that says the reaper is not running. Values are never listed, on either surface: a nonce is a bearer credential until it is consumed, so a listing would put live ones on a screen.

Profiles

The ACME endpoints this configuration mounts, name-sorted, each with the two facts that decide whether it is safe to expose and then its directory URL — last, because it is the only field here with no bounded width, and any column after it would be ragged:

$ acme-proxy profile list
internal              challenges=bypassed   eab=off  https://ca.example.com/profile/internal/directory
le                    challenges=validated  eab=on   https://ca.example.com/profile/le/directory

challenges=bypassed is painted as a warning, because it is one: an endpoint that marks a challenge valid without checking anything is an open CA wherever [filter] is empty. A profile parked with enabled = false is absent, which is the honest answer to “what does this mount”.

Like filter show, this builds the answer the way startup does rather than reading a file back, so a configuration serve would refuse is refused here too — which makes it a pre-restart check as well as a listing. The panel’s GET /api/profiles and /ui/profiles render the identical document from the mounted profiles instead, so between an edit and its SIGHUP the two legitimately disagree, and only this one can be pointed at a configuration the server would not start on.

Upstream account management

Only relevant with signer.backend = "relay".

--profile is required for show/register whenever the configuration defines more than one profile. [signer] is a per-profile section, so acting on “the upstream” without saying which one would be acting on nothing. It may be omitted only when exactly one profile exists. upstream order list takes --profile as an ordinary filter and is cross-profile without it.

upstream register performs this proxy’s own newAccount at the upstream CA and stores the resulting account URL beside account_key_path with a .kid extension. It is the only time the account is registered: serve reads the stored kid and never needs the EAB credential again.

Security note: the EAB HMAC secret is read from --eab-hmac-key-file, or prompted on stdin. It is deliberately not accepted as a command-line argument, because argv is visible to every user on the host via ps. Omit --eab-kid entirely when the upstream requires no External Account Binding.

upstream order list|show reads the upstream_orders table — one row per local order this proxy relayed to its upstream. --status is processing, valid or invalid, refused by name. Each row carries the upstream order/finalize/ certificate URLs, the upstream CA’s own error text for a failed relay, and the finalize request’s request_id; show takes the local order id and cross-links to the relay job. It is read-only — to stop an in-flight relay, use jobs cancel on the signer_relay_issue job (see Job queue), which abandons the local order too. The panel twins are GET /api/upstream-orders and /ui/upstream-orders.

External Account Binding (EAB)

• eab create prints the generated HMAC secret once. It is stored but never shown again, so a lost secret is replaced, not recovered.
• --profile binds the credential to one endpoint. Omitted, the credential is accepted at every profile — which is what an unscoped credential means, and is usually not what you want in a multi-tenant deployment.
• eab revoke takes effect immediately, with no restart: credentials are read from the live database on every newAccount.
• eab delete removes the credential. By default its accounts are kept, but they no longer resolve to any credential, so every eab filter check refuses them. --deactivate-accounts also deactivates them and keeps their orders, so their certificates can still be revoked. --delete-accounts also deletes them and everything under them; like account delete, it is refused while any of their orders holds a live certificate, and then nothing changes. The prompt names how many accounts and orders are involved.
• eab list is newest first and paged; see Paging. It reads the same query GET /api/eab and /ui/eab do, so the three cannot come to describe the credential set differently.

See External Account Binding for the protocol side.

Web admin operators and sessions

The web admin has no sign-up page: the first operator is created here. These commands work whether or not [admin] is enabled, and whether or not the server is running.