utility submits an X509 certificate for domain
and its alternate DNS names altnames
to the “Let's Encrypt” ACME server for automated signing. It can also revoke previously-submitted signatures. It must be run as root. (Why? chroot(2)
By default, it uses /var/www/acme
for responding to challenges (-C
for the public certificate directory (-c
for the domain private key (-k
), and /etc/acme/privkey.pem
for the account private key (-f
). All of these must exist unless you use -n
, which will generate the account and domain private keys, respectively. Its arguments are as follows:
Back up all Certificates in the certificate directory. This will only back up if something will be done to them (remove or replace). The backups are called cert-NNNNN.pem, chain-NNNNN.pem, and fullchain-NNNNN.pem, where
NNNNN is the current UNIX epoch. Any given backup effort will use the same epoch time for all three certificates. If there are no certificates in place, this does nothing.
Allow expanding the domains listed in the certificate. This is a no-op if no certificate exists yet. If a new domain is specified, the certificate will be renewed as if -F were also specified.
Force updating the certificate signature even if it's too soon.
Append domain to all default paths except the challenge path (i.e., those that are overriden by -c, -k, -f). Thus, foo.com as the initial domain would make the default domain private key into /etc/ssl/acme/private/foo.com/privkey.pem. This is useful in setups with multiple domain sets. If the foo.com directory is not found within non-overriden default paths, it will be created automatically.
Create a new 4096-bit RSA account key if one does not already exist.
Create a new 4096-bit RSA domain key if one does not already exist.
Request OCSP stapling for the given domains.
Revoke the X509 certificate found in Certificates.
Use the “Let's Encrypt” staging server instead of the real thing.
Verbose operation. Specify twice to also trace communication and data transfers.
Use an alternative agreement URL. The default uses the current one, but it may be out of date.
Where to register challenges. See Challenges for details. Ignored when -t is specified.
Where to put public certificates. See Certificates for details.
The account private key. This was either made with a previous ACME client or with -n.
The private key for the domain. This may also be created with -N.
If not using the internally-handled “http-01” as a challenge type, specify a challenge for the caller to manage. See the Challenges section for details.
The domain name. The only difference between this and the altnames is that it's put into the certificate's
CN field and that it uses the “main” domain when specifying -m.
Alternative names (“SAN”) for the domain name. The number of SAN entries is limited by ACME servers, usually to 100 or so.
The process by which acme-client
obtains signed certificates is roughly as follows. In this, the “CA” is the ACME server for Let's Encrypt.
Access the CA (unauthenticated) and requests its list of resources.
Optionally create and register a new RSA account key.
Read and process the RSA account key. This is used to authenticate each subsequent communication to the CA.
For each domain name,
submit a challenge for authentication to the CA,
create a challenge response file,
wait until the CA has verified the challenge.
Read and extract the RSA or ECSDA domain key.
Create an X509 request from the domain key for the domain and its alternative names.
Submit a request for signature to the CA.
Download the signed X509 certificate.
Extract the CA issuer from the X509 certificate.
Download the certificate chain from the issuer.
The revocation sequence is similar:
Request list of resources, manage RSA account key as in the case for signing.
Read and extract the X509 certificate (if found).
Create an X509 revocation request.
Submit a request for revocation to the CA.
Remove the certificate, the chain, and the full-chain.
ACME uses challenges to verify that the submitter has access to the registered domains. acme-client
internally implements only the “http-01” challenge type, where a file is created within a directory accessible by a locally-run web server configured for the requested domain. For example, for the domain “foo.com” and alternate “www.foo.com” and the default challenge directory, an Apache configuration snippet might be as follows:
Alias /.well-known/acme-challenge /var/www/acme
Allow from all
This way, the files placed in /var/www/acme
will be properly mapped by the web server when the ACME server responds to a challenge.
An alternate challenge type, however, may be specified with -t
, in which case the caller must create the challenge environment. This may be used for implementing “dns-01” and other system-specific challenges.
When using -t
, each domain (primary and altnames) is authorised over standard output and input between the caller and acme-client
acme-client prints “challenge-type dns-domain token.thumbprint\n” (note the trailing newline) on its standard output.
The caller performs any tasks to implement the challenge's response.
The caller writes the same three-field string and the newline to the standard input of acme-client.
This cycle repeats for each requested domain, then acme-client
Public certificates (domain certificate, chain, and the full-chain) are placed by default in /etc/ssl/acme
, and fullchain.pem
, respectively. These are all created as the root user with mode 444.
An nginx configuration using these might be as follows:
server_name foo.com www.foo.com;
file, if found, is checked for its expiration: if more than 30 days from expiring, acme-client
will not attempt to refresh the signature.
To create and submit a new key for a single domain, assuming that the web server has already been configured to map the challenge directory as in the Challenges
# mkdir /var/www/acme
# mkdir /etc/ssl/acme
# mkdir /etc/ssl/acme/private /etc/acme
# chmod 0700 /etc/ssl/acme/private /etc/acme
# acme-client -vNn foo.com www.foo.com smtp.foo.com
After generating the necessary directories, the above will create all keys and submit them to the server. You'll then probably want to restart your web server to pick up the new certificates.
You can then keep your certificates fresh with a daily cron(8)
invocation running the following:
acme-client foo.com www.foo.com smtp.foo.com
if [ $? -eq 0 ]
You'll need to replace the httpd-reload statement with the correct script to have your web server reload its certificates.