http-autocert #
Quick start — set and forget
Source: our fork on GitHub
Directives
autocert #
syntax: autocert 1 arg; · context: http, server
nginx-autocert-module is an ACME client that lives inside NGINX.
autocert_ca #
syntax: autocert_ca 1 arg (string); · context: http, server
Repeatable; sole-leading-label form only. | | autocert_ca <url> | http, server | LE production https://acme-v02.api.letsencrypt.org/directory | ACME directory URL to issue against.
autocert_ca_trusted_certificate #
syntax: autocert_ca_trusted_certificate 1 arg (string); · context: http, server
Mutually exclusive with autocert_ca. | | autocert_ca_trusted_certificate <file> | http, server | (none) | PEM trust bundle verifying a private CA's TLS endpoint.
autocert_challenge #
syntax: autocert_challenge 1 arg; · context: http
Behind such a layer, use http-01 or dns-01 instead. - It's instance-wide, not per-vhost. autocert_challenge lives in http{} — one challenge type for the whole NGINX instance.
autocert_contact #
syntax: autocert_contact 1 arg; · context: http, server
A server{}-level autocert on is what seeds the empty cert arrays so a cert-less vhost still builds an SSL_CTX. | | autocert_contact <email> | http, server | (none) | ACME account contact email (one @, non-empty both sides).
autocert_dns_hook_add #
syntax: autocert_dns_hook_add 1 arg (string); · context: http
Same address[:port] valid= ipv6= syntax as core resolver. | | autocert_resolver_timeout <time> | http | 30s | Timeout for that DNS resolution. | | autocert_dns_hook_add <path> | http | (none) | Absolute path to the executable that publishes the dns-01 TXT record.
autocert_dns_hook_remove #
syntax: autocert_dns_hook_remove 1 arg (string); · context: http
Required when challenge is dns-01. | | autocert_dns_hook_remove <path> | http | (none) | Absolute path to the executable that removes the TXT record after validation.
autocert_dns_hook_timeout #
syntax: autocert_dns_hook_timeout 1 arg (duration in seconds); · context: http
0 = no wait. | | autocert_dns_hook_timeout <time> | http | 30s | Per-hook exec timeout before SIGKILL.
autocert_dns_propagation_delay #
syntax: autocert_dns_propagation_delay 1 arg (duration in seconds); · context: http
Required when challenge is dns-01. | | autocert_dns_propagation_delay <time> | http | 10s | Wait after the add-hook returns before asking the CA to validate.
autocert_eab_hmac_key #
syntax: autocert_eab_hmac_key 1 arg (string); · context: http, server
CA-bound. | | autocert_eab_hmac_key <b64url> | http, server | (none) | EAB HMAC key (base64url).
autocert_eab_kid #
syntax: autocert_eab_kid 1 arg (string); · context: http, server
Made absolute against the nginx prefix. | | autocert_eab_kid <key-id> | http, server | (none) | EAB key identifier (RFC 8555 §7.3.4) for CAs requiring External Account Binding.
autocert_key_type #
syntax: autocert_key_type 1+ args; · context: http
Nothing to install alongside, nothing to schedule. - Three challenge types: http-01 (default), tls-alpn-01 (RFC 8737), and dns-01. - ECDSA, RSA, or both. autocert_key_type selects the leaf key — P-384 (default), P-256, RSA-2048/3072/4096, or a dual EC+RSA pair (one of each).
autocert_renew_before #
syntax: autocert_renew_before 1 arg (duration in seconds); · context: http
dns-01 is required for wildcards and requires both DNS hooks. | | autocert_renew_before <time> | http | 7d | Renew this long before a cert's notAfter. | | autocert_resolver <addr> [addr…] | http | falls back to core resolver | DNS resolver(s) used to reach the CA host.
autocert_resolver #
syntax: autocert_resolver 1+ args; · context: http
dns-01 is required for wildcards and requires both DNS hooks. | | autocert_renew_before <time> | http | 7d | Renew this long before a cert's notAfter. | | autocert_resolver <addr> [addr…] | http | falls back to core resolver | DNS resolver(s) used to reach the CA host.
autocert_resolver_timeout #
syntax: autocert_resolver_timeout 1 arg (duration in seconds); · context: http
Same address[:port] valid= ipv6= syntax as core resolver. | | autocert_resolver_timeout <time> | http | 30s | Timeout for that DNS resolution. | | autocert_dns_hook_add <path> | http | (none) | Absolute path to the executable that publishes the dns-01 TXT record.
autocert_staging #
syntax: autocert_staging on | off (on/off flag); · context: http, server
Mutually exclusive with autocert_staging. | | autocert_staging on\|off | http, server | off | Shorthand for the LE staging directory (https://acme-staging-v02.api.letsencrypt.org/directory).
autocert_store_layout #
syntax: autocert_store_layout 1 arg; · context: http
Relative paths resolve against the nginx prefix, not the CWD. | | autocert_store_layout default\|certbot | http | default | On-disk layout: the module's own hardened layout, or a certbot-compatible live/ layout.
autocert_store_path #
syntax: autocert_store_path 1 arg (string); · context: http
CA-bound. | | autocert_store_path <path> | http | autocert (→ <prefix>/autocert) | Root of the cert / account-key store.
autocert_wildcard #
syntax: autocert_wildcard 1+ args; · context: http, server
(Was the optional 2nd arg of autocert on.) | | autocert_wildcard .rest [.rest …] | http, server | (none) | Declare wildcard SAN(s) for this scope without putting *. in server_name (which would also make the vhost a subdomain catch-all).
Example
http {
resolver 127.0.0.1 [::1] valid=300s; # core nginx; autocert falls back to this if autocert_resolver is unset
# ---- instance-wide defaults (folded into every server) ----
autocert on; # http,server | default: off
autocert_contact admin@example.com; # http,server | ACME account email (optional)
autocert_ca https://acme-v02.api.letsencrypt.org/directory;
# http,server | default: LE production (mutually exclusive with autocert_staging)
autocert_staging off; # http,server | default: off (on = LE staging directory)
autocert_store_path /var/lib/autocert; # http only | default: autocert (relative → resolved against nginx prefix)
autocert_store_layout default; # http only | default: default (default | certbot)
autocert_key_type p384; # http only | default: p384 (p384 | p256 | rsa2048 | rsa3072(=rsa) | rsa4096; list up to one EC + one RSA for a dual cert)
autocert_challenge http-01; # http only | default: http-01 (http-01 | tls-alpn-01 | dns-01)
autocert_renew_before 7d; # http only | default: 7d (renew this long before notAfter)
# ---- resolver used to REACH the CA (not for dns-01 validation) ----
autocert_resolver 127.0.0.1 [::1]; # http only | default: falls back to core `resolver` above
autocert_resolver_timeout 30s; # http only | default: 30s
# =====================================================================
# 1) Plain HTTP-01 vhost. Needs `listen 80;`. CA fetches the token
# over plain HTTP from /.well-known/acme-challenge/<token>.
# =====================================================================
server {
listen 80;
listen 443 ssl;
server_name www.example.com example.com;
autocert on; # http,server | default: off (server-level `autocert on` is what seeds the empty cert arrays)
# no ssl_certificate / ssl_certificate_key — autocert supplies them
}
# =====================================================================
# 2) DNS-01 wildcard vhost. Requires dns-01 + both hooks (below).
…