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 source the module is not built by default; it must be enabled with the build parameter --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

For all domains specified in server_name directives in all server blocks that reference an ACME client from the HTTP module with the given name, a single certificate will be obtained; if the server_name configuration changes, the certificate will be updated to account for the changes.

On each Angie startup, new certificates are requested for all domains 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.

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.