Provides automatic certificate retrieval using the ACME protocol.

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

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

Configuration Example#

In this example, an ACME client named example automatically obtains and renews a certificate for example.com and www.example.com using the default HTTP validation:

http {

    resolver 127.0.0.53; # Required for the 'acme_client' directive

    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    server {

        listen 80; # Optional if no server listens on the HTTP challenge port
                   # (see 'acme_http_port' directive)

        listen 443 ssl;

        server_name example.com www.example.com;
        acme example;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}

For other validation methods (DNS, ALPN, hook-based) and detailed setup instructions, see the ACME Configuration section.

Directives#

acme#

Specifies the ACME client that obtains a certificate for the valid certificate identifiers in this server block. A single certificate covers all valid domain names and IP addresses specified in the server_name directives of every server block that references the client with the given name; if the server_name configuration changes, the certificate is renewed to reflect the changes.

Each time Angie starts, new certificates are requested for all identifiers that are missing a valid certificate. Possible reasons include certificate expiration, missing or unreadable files, and changes in certificate settings.

Note

This directive only controls which valid certificate identifiers are included in certificate requests; it does not affect where the certificate can be used. Any server block can reference the certificate through the $acme_cert_<name> variable, regardless of whether the block contains an acme directive. Removing acme from a server block simply excludes that block's server_name values from future certificate requests, but does not prevent the block from using the certificate.

Note

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

Wildcard domains are supported only with challenge=dns in acme_client.

IPv4 and IPv6 addresses are supported unless the client uses challenge=dns. With DNS validation enabled, IP addresses are skipped.

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#

Changed in version 1.11.0.

Changed in version 1.12.0.

Defines an ACME client with a globally unique name. It must be valid for a directory, is a string with variables, and will be used case-insensitively.

Each client manages a single certificate; to obtain separate certificates, configure multiple acme_client blocks (see Separate Certificates for Different Domains).

Tip

The client name specified here identifies it in the Angie configuration, allowing you to match acme_client, acme directives, and module variables that use this name; don't confuse it with your domain or server name.

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

Note

The ACME module adds a named location @acme to the client context, which can be used to configure requests to the ACME directory; by default, this location contains a proxy_pass directive with the directory uri, to which other settings from the Proxy module can be added.

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

acme_client_path#

Overrides the path to the directory for storing certificates and keys, set during build using the build parameter --http-acme-client-path.

acme_dns_port#

Specifies the port that the module uses to handle DNS queries from the ACME server over UDP. The port number must be in the range from 1 to 65535.

Specifying an IP address along with an optional port is also supported. Both IPv4 addresses in the form ip:port and IPv6 addresses in the form [ip6]:port can be used:

acme_dns_port 8053;
acme_dns_port 127.0.0.1;
acme_dns_port [::1];

To use port number 1024 or lower, Angie's master process must run with superuser privileges.

acme_dns_ttl#

Added in version 1.12.0.

Sets the TTL, in seconds, of the TXT records the module returns in responses to ACME servers' DNS validation queries. Accepts values from 0 through 2147483647, as per RFC 2181.

acme_hook#

Enables hook-based domain validation for the ACME client specified by name. When certificate issuance or renewal requires domain verification, Angie generates an internal request to the named location where this directive is placed. How the request is handled depends entirely on the other directives configured in the same location, such as fastcgi_pass, proxy_pass, or any other request handler.

For example, the following configuration passes the values of hook variables to a FastCGI application through the request URI:

acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_pass ...;

acme_http_port#

Added in version 1.11.0.

Changed in version 1.11.1.

Specifies the port that the module uses to handle HTTP ACME challenge requests. The port number must be in the range from 1 to 65535.

Specifying an IP address along with an optional port is also supported. Both IPv4 addresses in the form ip:port and IPv6 addresses in the form [ip6]:port can be used:

acme_http_port 8080;
acme_http_port 127.0.0.1;
acme_http_port [::1];

If no server is configured to listen on the specified address and port, the module creates a dedicated listener for HTTP challenges.

To use port number 1024 or lower, Angie's master process must run with superuser privileges.

acme_max_response_size#

Added in version 1.11.0.

Limits the maximum size of an ACME server response body. If a response exceeds this limit, the request fails with an error. Increase the value if you see errors like too big subrequest response while sending to 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.

Note

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

$acme_hook_challenge#

The challenge type. Possible values: dns, http, alpn.

$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 challenge, it is used as the value of the TXT record, whose name is formed as _acme-challenge. + $acme_hook_domain + ..

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

$acme_hook_name#

The hook name. For different challenge types, it may have different values and meanings:

$acme_hook_token#

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