ProxyAuth / Configuration

certbot_renew: true — ProxyAuth's built-in ACME client, from first issuance to wildcards

ProxyAuthTLS / ACME / Let's EncryptUpdated on 2026-09-18

certbot_renew: true does not call the certbot program. There is no subprocess and no dependency on it being installed. The name is familiar vocabulary; what it enables is an ACME client built into ProxyAuth, talking to Let’s Encrypt directly.

Turning it on

Per vhost, in routes.yml:

vhosts:
  - vhost: ["app.example.com"]
    vhost_cert:
      cert: "/etc/proxyauth/cert/app.example.com/fullchain.pem"
      key: "/etc/proxyauth/cert/app.example.com/privkey.pem"
    certbot_renew: true
    routes:
      - prefix: "/"
        target: "http://127.0.0.1:8000"

The paths in vhost_cert are where ProxyAuth will write the certificate; they do not need to exist yet. A vhost_cert without certbot_renew is treated as managed elsewhere: served, watched for changes, never touched.

Once for the instance, in config.json:

{
  "tls": true,
  "host": ["0.0.0.0", "::"],
  "port": 443,
  "letsencrypt": {
    "check_interval_secs": 3600,
    "renew_before_days": 30,
    "directory_url": "https://acme-v02.api.letsencrypt.org/directory",
    "contact_email": "ops@example.com",
    "account_credentials_path": "/etc/proxyauth/acme/account.json"
  }
}

(acme is still accepted as an alias of letsencrypt.)

  • check_interval_secs is how often certificates are checked. Most checks find nothing due and do nothing.
  • renew_before_days — renew at 30 days left or fewer. Certificates last 90 days, so that leaves room for several failed attempts.
  • directory_url — point it at https://acme-staging-v02.api.letsencrypt.org/directory while testing. Production allows only a handful of certificates per registered domain per week; staging runs the identical code path.
  • account_credentials_path — the ACME account key, persisted so restarts reuse the same account instead of registering again.

First issuance, then automatic

proxyauth certbot new app.example.com
proxyauth certbot check app.example.com
systemctl enable --now proxyauth

Renewal is automatic from then on; the first issuance is the one explicit step.

Port 80 is handled for you

Let’s Encrypt always fetches http://{vhost}/.well-known/acme-challenge/{token} over plain HTTP on port 80. A TLS-only deployment would never complete a renewal without something answering there, so ProxyAuth binds it itself:

  • When: tls is true and at least one route anywhere sets certbot_renew. Setting it on one route opens port 80 for the whole instance.
  • Where: one listener per address in host, bound during the privileged phase before privileges drop to run_user.
  • What it serves: a known challenge token returns its key authorization; everything else gets a 301 to https://.
  • If the port is taken: the address is logged and skipped, and startup continues normally.

Look for one of these lines at startup:

ACME: HTTP-01 challenge listener bound on 0.0.0.0:80
ACME: failed to bind the HTTP-01 challenge listener on …

Because the challenge listener answers on its own, validation is independent of the routing rules on 443. An allow_ips restriction or a maintenance gate on the vhost has no effect on what Let’s Encrypt sees.

Why the challenge store is LMDB

Two different processes can start a renewal: the periodic scan inside the running server, and a short-lived proxyauth certbot invocation. They share no memory. The challenge is therefore exchanged through an LMDB store at /opt/proxyauth/db/acme_challenges: whoever starts the order publishes the expected response there, and the listener reads it when Let’s Encrypt calls. An unknown or expired token returns a plain 404.

What a renewal does

The standard HTTP-01 flow: create an order, get the authorization, publish the challenge response, signal readiness, wait for validation. A fresh key pair and CSR are generated for each renewal; a previous private key is never reused.

Renewal is atomic. If any step fails, nothing is written, the existing certificate keeps being served, and the next scheduled check tries again.

One certificate per file, not per name

A group listing several names shares one vhost_cert, and the file defines the certificate. Every name pointing at the same fullchain.pem is issued together, as SANs of one certificate:

- vhost: ["example.com", "www.example.com"]
  certbot_renew: true
  vhost_cert:
    cert: "/etc/proxyauth/cert/example.com/fullchain.pem"
    key: "/etc/proxyauth/cert/example.com/privkey.pem"

Naming one member — certbot renew www.example.com — renews the whole group and says so. Reissuing one name alone would overwrite the shared file with a certificate that no longer covers its siblings. certbot check lists the SANs actually present.

Reload without restart

Renewal does not trigger a reload; it does not need to. At startup, ProxyAuth watches the directory containing each vhost_cert, not the file. A file-level watch dies the moment a renewal replaces the file’s inode — which is exactly what an atomic rename, or certbot’s symlink swap, does. A directory’s inode survives, so the watch keeps working through every renewal.

One consequence: watchers are created from the paths present at startup. A vhost added to a running server needs one restart to be watched. After that, every renewal is picked up live.

Wildcards: DNS-01, by hand

Let’s Encrypt issues wildcard certificates only through DNS-01: you prove control by publishing a TXT record. ProxyAuth does not integrate with DNS provider APIs, so this part is manual.

DNS-01 is selected automatically when any name in the group starts with *.:

proxyauth certbot new example.com      # prints the TXT records, waits
dig +short TXT _acme-challenge.example.com  # confirm before continuing

Three things to know:

  • Excluded from automatic renewal. A group with a wildcard is skipped by the periodic scan with a warning — a prompt nobody watches is not a renewal. Renew by hand before expiry, and set a reminder.
  • Two values at one name. An apex plus its wildcard both validate under _acme-challenge.example.com, producing two different TXT values that must exist at the same time. Many DNS interfaces replace the first with the second. Add them as two separate records.
  • Rehearse on staging. A first manual DNS-01 often needs a second try, and staging’s limits are much wider.

certbot renew on a wildcard group prompts, so it needs a terminal.

The commands

proxyauth certbot new <vhost>            # issue now, unconditionally
proxyauth certbot renew <vhost> [--force]
proxyauth certbot renew all [--force]
proxyauth certbot check <vhost|all>
  • renew <vhost> only needs vhost_cert; running it by hand is intent enough, certbot_renew is not required.
  • renew all is stricter: only vhosts that opted into renewal.
  • Without --force, a certificate not yet due is left alone and Let’s Encrypt is not contacted.
  • new does not accept all, and needs a restart afterwards if the vhost was only just added.
  • check is read-only and covers every vhost with a vhost_cert, ACME-managed or not: subject, issuer, validity, days remaining, serial, SANs.

Maintenance never blocks renewal

ACME challenge handling sits ahead of redirect_protect in the request lifecycle, and the port 80 listener is independent of routing anyway. A vhost can stay in maintenance for weeks and its certificate still renews.

A native client, its own port 80, one certificate per file, atomic renewals and a directory watch that survives them. Automatic for everything except wildcards — and for those, a clear prompt and a reminder beat a silent failure.