ACME#
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#
In this example, an ACME client named example automatically obtains
and renews a certificate for example.com and www.example.com
using the default HTTP validation:
http {
resolver 127.0.0.53; # Required for the 'acme_client' directive
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80; # Optional if no server listens on the HTTP challenge port
# (see 'acme_http_port' directive)
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
For other validation methods (DNS, ALPN, hook-based) and detailed setup instructions, see the ACME Configuration section.
Directives#
acme#
Specifies the ACME client that obtains a certificate
for the valid certificate identifiers in this server block.
A single certificate covers all valid domain names and IP addresses specified
in the server_name directives of every server block
that references the client with the given name;
if the server_name configuration changes,
the certificate is renewed to reflect the changes.
Each time Angie starts, new certificates are requested for all identifiers 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 valid certificate identifiers
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> variable,
regardless of whether the block contains an acme directive.
Removing acme from a server block
simply excludes that block's 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.
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 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#
Changed in version 1.11.0.
Changed in version 1.12.0.
| |
Default | — |
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.
Each client manages a single certificate; to obtain separate certificates,
configure multiple acme_client blocks (see
Separate Certificates for Different Domains).
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.
Note
For testing purposes, certificate authorities usually provide separate staging environments. For example, the Let's Encrypt staging environment is https://acme-staging-v02.api.letsencrypt.org/directory.
| Enables or disables certificate renewal for the client; this is useful, for example, for temporarily suspending without removing the client from the configuration. Default: |
| The type of private key algorithm for the certificate.
Valid values: Default: |
| Number of bits in the certificate key.
Default: 256 for |
| Optional email address for feedback; used when creating an account on the CA server. |
| Specifies the maximum allowed size of a new certificate file in bytes to reserve space for the new certificate in shared memory; the more domains the certificate is requested for, the more space is required. This parameter does not limit the size of ACME server responses; use acme_max_response_size for that. If the parameter is not set, Angie calculates an approximate size based on the configured domain list and uses it for shared memory allocation. If a certificate already exists at startup but its size exceeds the
If the size of a certificate obtained during renewal
exceeds Default: calculated automatically. |
| Limits the size of the key authorization string
that Angie stores in shared memory for an ACME challenge.
If the ACME server returns a key authorization string
larger than this value, the request fails with an error
that advises raising Although specified on the Default: |
| Time before certificate expiration when renewal should begin. Default: |
| Specifies that the certificate should be forcibly renewed each time the configuration is loaded. |
| Time to wait before retrying
if certificate retrieval failed.
If set to Default: |
| Specifies the verification type for the ACME client.
Valid values: The Default: |
| Requests a specific ACME profile from the certificate authority. A profile is a CA-defined variant of the certificate and validation settings, for example the certificate lifetime or which identifier types may be requested. For instance, Let's Encrypt describes its available profiles in the profiles documentation. The ACME server must advertise this profile in its directory metadata; otherwise the client cannot obtain a certificate. |
| Specifies the full path to a file containing a key in PEM format. This is useful if you want to use an existing account key instead of automatic generation, or if you need to use one key for multiple ACME clients. Supported key types:
When specifying the Note that keys for ACME clients are created in the order the corresponding clients are mentioned in the configuration in acme_client, acme, or acme_hook directives. Therefore, if one client should use a key created for another, that other client must appear earlier in the configuration. Additionally, keys are only created for clients
that have the |
| Configures External Account Binding (EAB), binding the ACME account to an account already registered with the certificate authority (CA). The value has the form
If the CA requires external account binding but the parameter is not set, the client reports an error without creating an ACME account. The EAB credentials are only sent when a new ACME account is registered; an existing ACME account is reused as is. |
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's master process must run with superuser privileges.
acme_dns_ttl#
Added in version 1.12.0.
Sets the TTL, in seconds, of the TXT records the module returns in responses to ACME servers' DNS validation queries. Accepts values from 0 through 2147483647, as per RFC 2181.
acme_hook#
Enables hook-based domain validation
for the 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, proxy_pass,
or any other request handler.
name | The name of the ACME client for which this hook handles domain verification. |
uri | A string with variables; specifies the request URI for hook calls. Default: |
For example, the following configuration passes the values of hook variables to a FastCGI application through the request URI:
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 ...;
acme_http_port#
Added in version 1.11.0.
Changed in version 1.11.1.
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:
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's master process must run with superuser privileges.
acme_max_response_size#
Added in version 1.11.0.
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.
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, alpn.
$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:
Value | Meaning for DNS challenge | Meaning for HTTP challenge |
| The corresponding TXT record must be added to the DNS configuration. | A response to the corresponding HTTP request must be prepared. |
| The TXT record can be removed from the DNS configuration. | This HTTP request is no longer relevant; the previously created file with the authorization string can be removed. |
$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.
Content