ACME#
Provides automatic certificate retrieval using the ACME protocol.
When building from the source code,
this module isn't built by default;
it should be enabled with the
--with-http_acme_module
build option.
In packages and images from our repos,
the module is included in the build. Examples of configuration and instructions for setup
can be found in the ACME Configuration section. For all domains specified in the server_name directives
of all server blocks that refer to the acme_client called name,
a single certificate will be obtained;
if the Each time Angie starts,
certificates are requested for all domains that are missing a valid certificate.
Possible reasons include expired certificates; missing or unreadable files;
configuration changes for a certificate. Note Currently, domains specified with regular expressions
are not supported and will be ignored. 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 under a globally unique name.
It must be valid for a file directory
and will be treated as case insensitive. The second mandatory parameter is the uri of the ACME directory. For
example, the URI of Let's Encrypt ACME directory is listed
as
https://acme-v02.api.letsencrypt.org/directory. 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, Let's Encrypt staging environment
is currently
https://acme-staging-v02.api.letsencrypt.org/directory. Enables or disables the client;
this is useful, for example, to temporarily disable the client
without removing it 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 a 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 value of If the size of a renewed certificate exceeds Default: Time before the certificate expires
when certificate renewal should start. Default: Time to retry
when a certificate couldn't be obtained.
If set to Default: Specifies the verification type for the ACME client.
Allowed 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 generating one automatically,
or if you need to share a key between ACME clients. Supported key types include: 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. Overrides the path to the directory for storing certificates and keys,
specified at build time with the Sets the port that the module uses to handle DNS queries from the ACME server.
The port number must be between 1 and 65535.
To use a port number of 1024 or lower,
Angie must run with superuser privileges. Specifies the 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 received at least one certificate,
whereas 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 file requested by the ACME server. The name of the hook.
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. The appropriate response to the HTTP request must be prepared,
such as creating a file with the authorization string. The TXT record can be removed from the DNS configuration. This HTTP request is no longer valid;
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:
Configuration Example#
Directives#
acme#
server_name configuration changes,
the certificate is renewed to reflect the updates.challenge=dns
setting 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] [renew_before_expiry=time] [retry_after_error=off|time] [challenge=dns | http] [account_key=file];enabledon.key_typersa, ecdsa.ecdsa.key_bitsecdsa, 2048 for rsa.emailmax_cert_sizemax_cert_size,
the max_cert_size value is dynamically increased
to match the size of the existing certificate file.max_cert_size,
the renewal will fail with an error.8192.renew_before_expiry30d.retry_after_erroroff,
the client won't retry to obtain the certificate after a failure.2h.challengedns, http.http.account_keyacme_client_path#
--http-acme-client-path
build option.acme_dns_port#
acme_hook#
location where requests and data will be proxied
to the external application.
The name identifies the corresponding ACME client.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 the hook)remove (removing the hook)$acme_hook_token#/.well-known/acme-challenge/ + $acme_hook_token.