nginx-acme is an NGINX module with the implementation of the automatic certificate management (ACMEv2) protocol.

The module implements following specifications:

• RFC8555 (Automatic Certificate Management Environment) with limitations:
  • Only HTTP-01 challenge type is supported

• Regular NGINX build dependencies: C compiler, make, PCRE2, Zlib
• System-wide installation of OpenSSL 1.1.1 or later
• Rust toolchain (1.81.0 or later)
• libclang for rust-bindgen

One way to build the module is to export a path to a configured NGINX source tree and run cargo.

# checkout, configure and build NGINX at ../nginx cd nginx-acme export NGINX_BUILD_DIR=$(realpath ../nginx/objs) cargo build --release

The result will be located at target/release/libnginx_acme.so.

Another way is to use the provided config script:

# in the NGINX source directory auto/configure \ --with-compat \ --with-http_ssl_module \ --add-[dynamic-]module=/path/to/nginx-acme

The result will be located at objs/ngx_http_acme_module.so.

Currently this method produces a slightly larger library, as we don't instruct the linker to perform LTO and remove unused code.

As there is no mechanism to add third-party module configuration options to auto/configure, all the module build-time options are set via environment variables passed to the cargo build or make commands. Currently accepted options are:

• NGX_ACME_STATE_PREFIX: sets a default prefix for per-issuer state paths. If unset, state paths are created relative to the NGINX prefix directory. The prefix directory should exist and be readable to the worker processes.

Example:

export NGX_ACME_STATE_PREFIX=/var/cache/nginx auto/configure \ ... \ --with-compat \ --with-http_ssl_module \ --add-dynamic-module=/path/to/nginx-acme make

The repository contains an integration test suite based on the nginx-tests. The following command will build the module and run the tests:

# Path to the nginx source checkout, defaults to ../nginx if not specified. export NGINX_SOURCE_DIR=$(realpath ../nginx) # Path to the nginx-tests checkout; defaults to ../nginx/tests if not specified. export NGINX_TESTS_DIR=$(realpath ../nginx-tests) make test

Most of the tests require pebble test server binary in the path, or in a location specified via TEST_NGINX_PEBBLE_BINARY environment variable.

Add the module to the NGINX configuration and configure as described below. Note that this module requires a resolver configuration in the http block.

resolver 127.0.0.1:53; acme_issuer example { uri https://acme.example.com/directory;  # contact admin@example.test; state_path /var/cache/nginx/acme-example; accept_terms_of_service; } acme_shared_zone zone=ngx_acme_shared:1M; server { listen 443 ssl; server_name .example.test; acme_certificate example; ssl_certificate $acme_certificate; ssl_certificate_key $acme_certificate_key;  # do not parse the certificate on each request ssl_certificate_cache max=2; } server {  # listener on port 80 is required to process ACME HTTP-01 challenges listen 80; location / { return 404; } }

Syntax: acme_issuer name { ... }

Default: -

Context: http

Defines an ACME certificate issuer object.

Syntax: uri uri

Default: -

Context: acme_issuer

The directory URL of the ACME server. This is the only mandatory directive in the acme_issuer block.

Syntax: account_key alg[:size] | file

Default: -

Context: acme_issuer

The account's private key used for request authentication.

Accepted values:

• ecdsa:256/384/521 for ES256, ES384 or ES512 JSON Web Signature algorithms
• rsa:2048/3072/4096 for RS256.
• File path for an existing key, using one of the algorithms above.

The generated account keys are preserved across reloads, but will be lost on restart unless state_path is configured.

Syntax: contact url

Default: -

Context: acme_issuer

Sets an array of URLs that the ACME server can use to contact the client regarding account issues. The mailto: scheme will be assumed unless specified explicitly.

Syntax: external_account_key kid file

Default: -

Context: acme_issuer

A key identifier and a file with the MAC key for external account authorization (RFC8555 § 7.3.4).

The value data:key can be specified instead of the file to load the key directly from the configuration without using intermediate files.

In both cases, the key is expected to be encoded as base64url.

Syntax: ssl_trusted_certificate file

Default: system CA bundle

Context: acme_issuer

Specifies a file with trusted CA certificates in the PEM format used to verify the certificate of the ACME server.

Syntax: ssl_verify on | off

Default: on

Context: acme_issuer

Enables or disables verification of the ACME server certificate.

Syntax: state_path path | off

Default: acme_name or $NGX_ACME_STATE_PREFIX/acme_name

Context: acme_issuer

Defines a directory for storing the module data that can be persisted across restarts. This can significantly improve the time until the server is ready and help with rate-limiting ACME servers.

The directory contains sensitive content, such as the account key, issued certificates, and private keys.

Syntax: accept_terms_of_service

Default: -

Context: acme_issuer

Agrees to the terms of service under which the ACME server will be used. Some servers require accepting the terms of service before account registration. The terms are usually available on the ACME server's website and the URL will be printed to the error log if necessary.

Syntax: acme_shared_zone zone = name:size

Default: ngx_acme_shared:256k

Context: http

Allows increasing the size of in-memory storage of the module. The shared memory zone will be used to store the issued certificates, keys and challenge data for all the configured certificate issuers.

The default zone size is sufficient to hold ~50 ECDSA prime256v1 keys or ~35 RSA 2048 keys.

Syntax: acme_certificate issuer [identifier ...] [ key = alg[:size] ]

Default: -

Context: server

Defines a certificate with the list of identifiers requested from issuer issuer.

The explicit list of identifiers can be omitted. In this case, the identifiers will be taken from the server_name directive in the same server block. Not all values accepted in the server_name are valid certificate identifiers: regular expressions and wildcards are not supported.

The key parameter sets the type of a generated private key. Supported key algorithms and sizes: ecdsa:256 (default), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

The ngx_http_acme_module module defines following embedded variables, valid in the server block with the acme_certificate directive:

SSL certificate that can be passed to the ssl_certificate.

SSL certificate private key that can be passed to the ssl_certificate_key.

Please see the contributing guide for guidelines on how to best contribute to this project.

Apache License, Version 2.0

© F5, Inc. 2025