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

# ACME

Provides automatic certificate retrieval using the [ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555).

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), the module isn't built by default;
it must be enabled with the [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--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.

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

## Configuration Example

Examples of configuration and setup instructions can be found in the [ACME Configuration](https://en.angie.software//angie/docs/configuration/acme.md#acme-config) section.

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

## Directives

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

<a id="id1"></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 the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) directives
in all [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) blocks
that reference the [ACME client](#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
This directive only controls which domain names
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>](#v-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](https://en.angie.software//angie/docs/configuration/modules/http/index.md#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`.

This directive can be specified multiple times
to load certificates of different types, for example RSA and ECDSA:

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

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

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

### acme_client

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `acme_client` name uri [`enabled=``on` | `off`] [`key_type=`type] [`key_bits=`number] [`email=`email] [`max_cert_size=`number] [`renew_before_expiry=`time] [`renew_on_load`] [`retry_after_error=`off|time] [`challenge=``dns` | `http` | `alpn`] [`account_key=`file];   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                          |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                                                                                                                                                                                                                                       |

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.

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

#### NOTE
The ACME module adds a named `location @acme`
to the [client](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client) context,
which can be used to configure requests to the ACME directory;
by default, this `location`
contains a [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive with the directory uri,
to which other settings from the [Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module can be added.

For this directive to work,
a [resolver](https://en.angie.software//angie/docs/configuration/modules/http/index.md#resolver) must be configured in the same context.

#### NOTE
For testing purposes,
certificate authorities usually provide separate staging environments.
For example, the [Let's Encrypt staging environment](https://letsencrypt.org/docs/staging-environment/)
is
[https://acme-staging-v02.api.letsencrypt.org/directory](https://acme-staging-v02.api.letsencrypt.org/directory).

| `enabled`             | Enables or disables certificate renewal for the client;<br/>this is useful, for example, for temporarily suspending<br/>without removing the client from the configuration.<br/><br/>Default: `on`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `key_type`            | The type of private key algorithm for the certificate.<br/>Valid values: `rsa`, `ecdsa`.<br/><br/>Default: `ecdsa`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `key_bits`            | Number of bits in the certificate key.<br/>Default: 256 for `ecdsa`, 2048 for `rsa`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `email`               | Optional email address for feedback;<br/>used when creating an account on the CA server.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `max_cert_size`       | Specifies the maximum allowed size of a new certificate file in bytes<br/>to reserve space for the new certificate in shared memory;<br/>the more domains the certificate is requested for,<br/>the more space is required.<br/>This parameter does not limit the size of ACME server responses;<br/>use [acme_max_response_size](#acme-max-response-size) for that.<br/><br/>If the parameter is not set, Angie calculates an approximate size<br/>based on the configured domain list and uses it for shared memory<br/>allocation.<br/><br/>If a certificate already exists at startup but its size exceeds the<br/>`max_cert_size` value, the `max_cert_size` value is<br/>dynamically increased to match the size of the existing certificate<br/>file.<br/><br/>If the size of a certificate obtained during renewal<br/>exceeds `max_cert_size`,<br/>the renewal process will fail with an error.<br/><br/>Default: calculated automatically.                                                                                                                                   |
| `renew_before_expiry` | [Time](https://en.angie.software//angie/docs/configuration/configfile.md#syntax) before certificate expiration<br/>when renewal should begin.<br/><br/>Default: `30d`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `renew_on_load`       | Specifies that the certificate should be forcibly renewed<br/>each time the configuration is loaded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `retry_after_error`   | [Time](https://en.angie.software//angie/docs/configuration/configfile.md#syntax) to wait before retrying<br/>if certificate retrieval failed.<br/>If set to `off`,<br/>the client will not retry to obtain the certificate after an error.<br/><br/>Default: `2h`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `challenge`           | Specifies the verification type for the ACME client.<br/>Valid values: `dns`, `http`, `alpn`.<br/><br/>The `alpn` value enables [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) validation and requires<br/>Angie to be built with OpenSSL that supports ALPN<br/>(not supported with BoringSSL or AWS-LC builds).<br/><br/>Default: `http`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `account_key`         | Specifies the full path to a file containing a key in PEM format.<br/>This is useful if you want to use an existing account key<br/>instead of automatic generation,<br/>or if you need to use one key for multiple ACME clients.<br/><br/>Supported key types:<br/><br/>- RSA keys with lengths that are multiples of 8, ranging from 2048 to 8192 bits.<br/>- ECDSA keys with lengths of 256, 384, or 521 bits.<br/><br/>When specifying the `account_key` parameter,<br/>ensure that the key file actually exists.<br/>If the file is missing,<br/>Angie will attempt to create it at the specified path.<br/><br/>Note that keys for ACME clients are created in the order<br/>the corresponding clients are mentioned in the configuration<br/>in [acme_client](#acme-client), [acme](#id1), or [acme_hook](#acme-hook) directives.<br/>Therefore, if one client should use a key<br/>created for another,<br/>that other client must appear earlier in the configuration.<br/><br/>Additionally, keys are only created for clients<br/>that have the `enabled=on` parameter set. |

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

<a id="acme-max-response-size"></a>

### acme_max_response_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `acme_max_response_size` size;   |
|------------------------------------------------------------------------------------------|----------------------------------|
| Default                                                                                  | `acme_max_response_size 32k;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                             |

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

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

<a id="acme-client-path"></a>

### acme_client_path

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

Overrides the path to the directory for storing certificates and keys,
set during build using the [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure)
`--http-acme-client-path`.

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

<a id="acme-dns-port"></a>

### acme_dns_port

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `acme_dns_port` port | ip[:port] | [ip6][:port];   |
|------------------------------------------------------------------------------------------|----------------------------------------------------|
| Default                                                                                  | `acme_dns_port 53;`                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                               |

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:

```nginx
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](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges.

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

<a id="acme-http-port"></a>

### acme_http_port

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `acme_http_port` port | ip[:port] | [ip6][:port];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------|
| Default                                                                                  | `acme_http_port 80;`                                |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                                |

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:

```nginx
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 must run with [superuser](https://en.angie.software//angie/docs/configuration/modules/core.md#user) privileges.

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

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

### acme_hook

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

Enables hook-based domain validation
for the [ACME client](#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](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),
or any other request handler.

| name   | The name of the [ACME client](#acme-client)<br/>for which this hook handles domain verification.   |
|--------|----------------------------------------------------------------------------------------------------|
| uri    | A string with variables;<br/>specifies the request URI for hook calls.<br/><br/>Default: `/`.      |

For example, the following configuration passes the values of [hook variables](#http-acme-variables)
to a FastCGI application through the request URI:

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

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

## Built-in Variables

<a id="v-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-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,
but the key file is available immediately after startup.

<a id="v-acme-hook-challenge"></a>

### `$acme_hook_challenge`

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

<a id="v-acme-hook-client"></a>

### `$acme_hook_client`

The name of the ACME client initiating the request.

<a id="v-acme-hook-domain"></a>

### `$acme_hook_domain`

The domain being verified.
If it is a wildcard domain, it will be passed without the `*.` prefix.

<a id="v-acme-hook-keyauth"></a>

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

<a id="v-acme-hook-name"></a>

### `$acme_hook_name`

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

| Value                    | Meaning for DNS challenge                                            | Meaning for HTTP challenge                                                                                             |
|--------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `add` (adding hook)      | The corresponding TXT record must be added to the DNS configuration. | A response to the corresponding HTTP request must be prepared.                                                         |
| `remove` (removing hook) | The TXT record can be removed from the DNS configuration.            | This HTTP request is no longer relevant;<br/>the previously created file with the authorization string can be removed. |

<a id="v-acme-hook-token"></a>

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