<!-- review: finished -->

<a id="stream-acme"></a>

# ACME

Allows automatic certificate acquisition
using the [ACME](https://datatracker.ietf.org/doc/html/rfc8555) protocol
for servers defined in the `stream` context.

When [building from source](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild)
the module is not built by default; it must be
enabled with the [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--with-stream_acme_module`
(also requires `--with-http_acme_module`).
In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages)
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.

<a id="configuration-example-57"></a>

## Configuration Example

For configuration examples and setup instructions, see the
[ACME in the Stream Module](https://en.angie.software//angie/docs/configuration/acme.md#acme-config-stream) section.

<a id="directives-66"></a>

## Directives

<a id="index-0"></a>

<a id="s-acme"></a>

### acme

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `acme` name;   |
|------------------------------------------------------------------------------------------|----------------|
| Default                                                                                  | —              |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server         |

For all domains specified in [server_name](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server-name) directives
in all [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) blocks
that reference an [ACME client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#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:

```nginx
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;
}
```

<a id="stream-acme-variables"></a>

## Embedded Variables

<a id="v-s-acme-cert-name"></a>

### `$acme_cert_<name>`

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

<a id="v-s-acme-cert-key-name"></a>

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