nginx-acme

Automatic TLS certificates via the ACME protocol

compiled inApache-2.0source docs

Overview

nginx-acme implements the ACMEv2 protocol (RFC 8555) inside nginx itself. It obtains and renews TLS certificates automatically, so external clients such as certbot and their reload hooks are no longer needed.

Certificates can come from any ACMEv2 authority, including Let's Encrypt. The module answers http-01 or tls-alpn-01 challenges on its own, keeps certificates and keys in a shared memory zone, and can persist state on disk across restarts.

The module is developed by the nginx team at F5, is written in Rust, and is documented on nginx.org alongside the core modules.

Key directives

acme_issuerDefines an ACME certificate authority with its directory URI, account key, contact, and challenge settings.

acme_certificateRequests and renews a certificate for the server's names from the given issuer.

acme_shared_zoneAllocates shared memory for certificates, keys, and challenge data, 256k by default.

$acme_certificate / $acme_certificate_keyVariables that feed the managed certificate and key into ssl_certificate and ssl_certificate_key.

challengeSelects the ACME challenge type, http-01 (default) or tls-alpn-01.

state_pathStores account and certificate data on disk so it survives restarts.

Example

nginx.conf

resolver 1.1.1.1; acme_issuer letsencrypt { uri https://acme-v02.api.letsencrypt.org/directory; contact mailto:admin@example.com; state_path /var/cache/nginx/acme-letsencrypt; accept_terms_of_service; } acme_shared_zone zone=acme_shared:1M; server { listen 443 ssl; server_name example.com; acme_certificate letsencrypt; ssl_certificate $acme_certificate; ssl_certificate_key $acme_certificate_key; }

Availability

Compiled into every n.wtf nginx binary. Install nginx-extras and the directives above work out of the box, no load_module line needed.