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#

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

Directives#

acme#

For all domains specified in the server_name directives in all server blocks that reference the ACME client with the given name, a single certificate will be obtained; if the server_name configuration changes, the certificate will be renewed to reflect the changes.

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

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.

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#

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.

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 must run with superuser privileges.

acme_hook#

The directive links the server to the specified ACME client. Handler (hook) calls implemented by an external service are made through the location context where it is located.

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

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 ...;

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.

$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.