ACME

Added in version 1.10.0.

Allows automatic certificate acquisition using the ACME protocol for servers defined in the stream context.

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

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

Note

For correct operation, the stream block must be located after the http block. This is because the stream module uses client definitions created during HTTP configuration parsing.

Configuration Example

In this example, certificates obtained by the example ACME client (declared in the http block) secure a TCP server using the default HTTP validation:

# HTTP part
http {

    resolver 127.0.0.53;

    # ACME client for the stream part
    acme_client example https://acme-v02.api.letsencrypt.org/directory;

    # Server for HTTP validation
    server {

        listen 80;
        return 444;
    }
}

# Stream part
stream {

    server {

        listen 12345 ssl;
        proxy_pass backend_upstream;

        ssl_certificate $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;

        server_name example.com www.example.com;
        acme example; # reference to the ACME client defined in the HTTP part
    }

    upstream backend_upstream {

        server 127.0.0.1:54321;
    }
}

For configuration examples and setup instructions, including DNS validation, see the ACME in the Stream Module section.

Directives

acme

Syntax	acme name;
Default	—
Context	server

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

On each Angie startup or configuration reload, new certificates are requested for all identifiers that lack a valid certificate. Possible reasons include certificate expiration, missing files or inability to read them, and changes in certificate settings.

Note

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

Wildcard domains are supported only in challenge=dns mode 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 12345 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;
}

Embedded 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, while the key file is available immediately after startup.