certbot_renew: true — ProxyAuth's built-in ACME client, from first issuance to wildcards
Was this useful?
0 unique visitors
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_secsis 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 athttps://acme-staging-v02.api.letsencrypt.org/directorywhile 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:
tlsistrueand at least one route anywhere setscertbot_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 torun_user. - What it serves: a known challenge token returns its key
authorization; everything else gets a
301tohttps://. - 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 needsvhost_cert; running it by hand is intent enough,certbot_renewis not required.renew allis stricter: only vhosts that opted into renewal.- Without
--force, a certificate not yet due is left alone and Let’s Encrypt is not contacted. newdoes not acceptall, and needs a restart afterwards if the vhost was only just added.checkis read-only and covers every vhost with avhost_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.