ACME

Provides automatic certificate retrieval using the ACME protocol.

When building from the source code, this module isn't built by default; it should be enabled with the --with-http_acme_module build option.

In packages and images from our repos, the module is included in the build.

Configuration Example

Examples of configuration and instructions for setup can be found in the ACME Configuration section.

Directives

acme

Syntax	acme name;
Default	—
Context	server

For all domains specified in the server_name directives of all server blocks that refer to the acme_client called name, a single certificate will be obtained; if the server_name configuration changes, the certificate is renewed to account for the updates.

Note

Currently, wildcard domains and domains specified with regular expressions are not supported and will be ignored.

This directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

server {

    listen 443 ssl;
    server_name example.com www.example.com;

    ssl_certificate $acme_cert_rsa;
    ssl_certificate_key $acme_cert_key_rsa;

    ssl_certificate $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;

    acme rsa;
    acme ecdsa;
}

acme_client

Syntax	acme_client name uri [enabled=on | off] [key_type=type] [key_bits=number] [email=email] [renew_before_expiry=time] [retry_after_error=off|time] [challenge=dns | http] [account_key=file];
Default	—
Context	http

Defines an ACME client under a globally unique name. It must be valid for a file directory and will be treated as case insensitive.

The second mandatory parameter is the uri of the ACME directory. For example, the URI of Let's Encrypt ACME directory is listed as https://acme-v02.api.letsencrypt.org/directory.

For this directive to work, a resolver must be configured in the same context.

Note

For testing purposes, certificate authorities usually provide separate staging environments. For example, Let's Encrypt staging environment is currently https://acme-staging-v02.api.letsencrypt.org/directory.

enabled	Enables or disables the client; this is useful, for example, to temporarily disable the client without removing it from the configuration. Default: on.
key_type	The type of private key algorithm for the certificate. Valid values: rsa, ecdsa. Default: ecdsa.
key_bits	Number of bits in the certificate key. Default: 256 for ecdsa, 2048 for rsa.
email	Optional email address for feedback; used when creating an account on the CA server.
max_cert_size	Specifies the maximum allowed size of a new certificate file in bytes to reserve space for a new certificate in shared memory. The more domains the certificate is requested for, the more space is required. If a certificate already exists at startup but its size exceeds the value of max_cert_size, the max_cert_size value is dynamically increased to match the size of the existing certificate file. If the size of a renewed certificate exceeds max_cert_size, the renewal will fail with an error. Default: 8192.
renew_before_expiry	Time before the certificate expires when certificate renewal should start. Default: 30d.
retry_after_error	Time to retry when a certificate couldn't be obtained. If set to off, the client won't retry to obtain the certificate after a failure. Default: 2h.
challenge	Specifies the verification type for the ACME client. Allowed values: dns, http. Default: http.
account_key	Specifies the full path to a file containing a key in PEM format. This is useful if you want to use an existing account key instead of generating one automatically, or if you need to share a key between ACME clients. Supported key types include: RSA keys with lengths that are multiples of 8, ranging from 2048 to 8192 bits. ECDSA keys with lengths of 256, 384, or 521 bits.

acme_client_path

Syntax	acme_client_path path;
Default	—
Context	http

Overrides the path to the directory for storing certificates and keys, specified at build time with the --http-acme-client-path build option.

acme_dns_port

Syntax	acme_dns_port number;
Default	acme_dns_port 53;
Context	http

Sets the port that the module uses to handle DNS queries from the ACME server. The port number must be between 1 and 65535. To use a port number of 1024 or lower, Angie must run with superuser privileges.

acme_hook

Syntax	acme_hook name;
Default	—
Context	location

Specifies the location where requests and data will be proxied to the external application. The name identifies the corresponding ACME client.

Built-in Variables

$acme_cert_<name>

Contents of the last certificate file (if any) obtained by the client with this name.

$acme_cert_key_<name>

Contents of the certificate key file used by the client with this name.

Important

The certificate file is available only if the ACME client has received at least one certificate, whereas the key file is available immediately after startup.

$acme_hook_challenge

The verification type. Possible values: dns, http.

$acme_hook_client

The name of the ACME client initiating the request.

$acme_hook_domain

The domain being verified. If it is a wildcard domain, it will be passed without the *. prefix.

$acme_hook_keyauth

The authorization string:

• For DNS verification, it is used as the value of the TXT record, whose name is formed as _acme-challenge. + $acme_hook_domain + ..

• For HTTP verification, this string must be used as the content of the file requested by the ACME server.

$acme_hook_name

The name of the hook. For different verification types, it may have different values and meanings:

Value	Meaning for DNS verification	Meaning for HTTP verification
add (adding the hook)	The corresponding TXT record must be added to the DNS configuration.	The appropriate response to the HTTP request must be prepared, such as creating a file with the authorization string.
remove (removing the hook)	The TXT record can be removed from the DNS configuration.	This HTTP request is no longer valid; the previously created file with the authorization string can be removed.

$acme_hook_token

The verification token. For HTTP verification, it is used as the name of the requested file: /.well-known/acme-challenge/ + $acme_hook_token.