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
Examples of configuration and setup instructions can be found in the ACME Configuration section. For all domains specified in the server_name directives
in all server blocks
that reference the ACME client with the given name,
a single certificate will be obtained;
if the 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 Currently, domains specified with regular expressions
are not supported and will be skipped. Wildcard domains are supported only with This directive can be specified multiple times
to load certificates of different types, for example RSA and ECDSA: 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. Tip The client name specified here identifies it in the Angie configuration,
allowing you to match 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 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. If a certificate already exists at startup
but its size exceeds the If the size of a certificate obtained during renewal
exceeds 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: Default: 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: RSA keys with lengths that are multiples of 8, ranging from 2048 to 8192 bits. ECDSA keys with lengths of 256, 384, or 521 bits. 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 Overrides the path to the directory for storing certificates and keys,
specified at build time with the build option
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 To use port number 1024 or lower,
Angie must run with superuser privileges. The directive links the server to the specified ACME client.
Handler (hook) calls implemented by an external service
are made through the name Specifies the corresponding ACME client. uri A string with variables;
specifies the request string for handler calls. Default: For example, the following configuration passes the values of hook variables
to a FastCGI application through the request string: Contents of the last certificate file (if any)
obtained by the client with this name. Contents of the certificate key file
used by the client with this name. Important 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. The verification type. Possible values: The name of the ACME client initiating the request. The domain being verified.
If it is a wildcard domain, it will be passed without the The authorization string: For DNS verification, it is used as the value of the TXT record,
whose name is formed as
For HTTP verification, this string must be used
as the content of the response requested by the ACME server. The hook name. For different verification types, it may have different values and meanings: Value Meaning for DNS verification Meaning for HTTP verification 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. The verification token.
For HTTP verification, it is used as the name of the requested file:
--with-http_acme_module.
In packages and images from
our repositories,
the module is included in the build.Configuration Example#
Directives#
acme#
server_name configuration changes,
the certificate will be renewed to reflect the changes.challenge=dns
in acme_client.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#
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] [account_key=file];acme_client, acme directives,
and module variables that use this name;
don't confuse it with your domain or server name.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.enabledon.key_typersa, ecdsa.ecdsa.key_bitsecdsa, 2048 for rsa.emailmax_cert_sizemax_cert_size value,
the max_cert_size value is dynamically increased
to match the size of the existing certificate file.max_cert_size,
the renewal process will fail with an error.8192.renew_before_expiry30d.renew_on_loadretry_after_erroroff,
the client will not retry to obtain the certificate after an error.2h.challengedns, http.http.account_keyaccount_key parameter,
ensure that the key file actually exists.
If the file is missing,
Angie will attempt to create it at the specified path.enabled=on parameter set.acme_client_path#
--http-acme-client-path.acme_dns_port#
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];
acme_hook#
location context where it is located./.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 ...;
Built-in Variables#
$acme_cert_<name>#$acme_cert_key_<name>#$acme_hook_challenge#dns, http.$acme_hook_client#$acme_hook_domain#*. prefix.$acme_hook_keyauth#_acme-challenge. + $acme_hook_domain + ..$acme_hook_name#add (adding hook)remove (removing hook)$acme_hook_token#/.well-known/acme-challenge/ + $acme_hook_token.
Content