ACME client usages

This section details how to use the most common Linux ACME clients.

Linux ACME clients

This section details how to use the acme.sh, certbot and lego ACME clients.

Overview

Certbot is able to run on any recent UNIX-like operating system equipped with Python 2.7 or 3.4+, while acme.sh can also run on any recent Linux distribution running either bash, dash or sh. lego is a self-contained binary written in Go, also available on Windows.

All three fully support the latest ACMEv2 protocol including its main latest feature: wildcard certificates (*.example.com).

All three clients support different modes for obtaining a certificate and in some cases automatically installing it.

The following tables lists the different modes for each clients:

Modes certbot acme.sh lego Notes

apache

Y

Y

N

Obtains and automatically installs a certificate using the running Apache server. (For acme.sh, this mode will only obtain a certificate without installing it)

nginx

Y

Y

N

Obtains and automatically installs a certificate using the running NGINX server. (For acme.sh, this mode will only obtain a certificate without installing it)

webroot

Y

Y

Y

Obtains a certificate by writing to the webroot directory of an already running web server

standalone

Y

Y

Y

Uses a "standalone" web server managed by Certbot, acme.sh or lego. This mode is useful on system with no web servers or if using the running web server is not desired

DNS

Y

Y

Y

This mode automates obtaining a certificate by modifying a DNS record to prove the control over a domain

tls-alpn

N

Y

Y

Uses a TLS server to validate the control over a domain

Requesting a certificate

certbot and acme.sh must be started using administrative privileges (sudo), except for acme.sh when using the webroot or DNS modes. lego only requires them to listen on a privileged port (below 1024) or to write to a protected webroot folder.

Each client requires only a few parameters to request a certificate.

acme.sh parameters:

Parameter Description

--issue

Obtain or renew a certificate, but does not install it

--accountemail [VALUE]

The contact email address

-w [VALUE]

Path of the server’s webroot folder

-d [VALUE]

The domain(s) to enroll.

certbot parameters:

Parameter Description

certonly

Obtain or renew a certificate, but does not install it

--webroot

Place files in a server’s webroot folder for authentication

-w [VALUE]

Path of the server’s webroot folder

-d [VALUE]

The domain(s) to enroll.

Requesting a certificate for Apache using certbot:

(sudo) certbot run --apache --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: apache.evertrust.fr>

Where:

  • --apache: Enables the Apache mode

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name (can be specified several times)

Requesting a certificate for nginx using certbot:

(sudo) certbot run --nginx --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: nginx.evertrust.fr>

Where:

  • --nginx: Enables the nginx mode

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name (can be specified several times)

Requesting a certificate for nginx using acme.sh:

(sudo) acme.sh --issue --nginx --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accountemail <contact email address, example: [email protected]> -d <DNS name, example: nginx.evertrust.fr>

Where:

  • --issue: Specifies that this is a certificate request

  • --nginx: Enables the nginx mode

  • --server: Horizon ACME profile endpoint

  • --accountemail: Contact email address

  • -d: Requested DNS name (can be specified several times)

Requesting a certificate in standalone mode using certbot:

(sudo) certbot certonly --standalone --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: apache.evertrust.fr>

Where:

  • --standalone: Enables the standalone mode, i.e. certbot will start a local web server to serve the response

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name (can be specified several times)

Requesting a certificate in standalone mode using acme.sh:

(sudo) acme.sh --issue --standalone --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accountemail <contact email address, example: [email protected]> -d <DNS name, example: apache.evertrust.fr>

Where:

  • --issue: Specifies that this is a certificate request

  • --standalone: Enables the standalone mode, i.e. acme.sh will start a local web server to serve the response

  • --server: Horizon ACME profile endpoint

  • --accountemail: Contact email address

  • -d: Requested DNS name (can be specified several times)

Requesting a certificate in TLS-ALPN mode using lego:

lego run --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accept-tos --email <contact email address, example: [email protected]> --domains <DNS name, example: nginx.evertrust.fr> --tls --tls.address <port, example :4443>

Where:

  • run: Requests or renews a certificate

  • --server: Horizon ACME profile endpoint

  • --accept-tos: Accepts the CA terms of service

  • --email: Contact email address

  • --domains: Requested DNS name (can be specified several times)

  • --tls: Enables the TLS-ALPN-01 validation mode

  • --tls.address: Address and port the challenge server listens on (default: :443): must match the TLS-ALPN-01 validation port of the ACME profile

If the Horizon endpoint is served with a certificate not trusted by the system running lego, add the --tls-skip-verify option to skip the TLS verification of the ACME server.

Requesting a certificate with an External Account Binding (EAB)

When the Require External Account Binding (EAB) option is enabled on the ACME profile, the ACME client must provide the credentials of an EAB account (MAC Key ID and MAC Key) when registering its ACME account. These credentials are only displayed once, at EAB account creation and at MAC Key renewal (see MAC Key management): copy them when they are displayed.

Requesting a certificate with EAB using certbot:

(sudo) certbot certonly --webroot -w <path of the webroot folder> --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> -d <DNS name, example: apache.evertrust.fr> --eab-kid=<MAC Key ID> --eab-hmac-key=<MAC Key>

Where:

  • --webroot: Enables the webroot mode, i.e. certbot will place the challenge response in the server’s webroot folder

  • -w: Path of the server’s webroot folder

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • -d: Requested DNS name (can be specified several times)

  • --eab-kid: MAC Key ID of the EAB account

  • --eab-hmac-key: MAC Key of the EAB account

The --eab-kid and --eab-hmac-key options must be passed with the = form: a base64url value starting with a - would otherwise be interpreted by certbot as another option.

Requesting a certificate with EAB using acme.sh:

(sudo) acme.sh --issue -w <path of the webroot folder> --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accountemail <contact email address, example: [email protected]> -d <DNS name, example: apache.evertrust.fr> --eab-kid <MAC Key ID> --eab-hmac-key <MAC Key>

Where:

  • --issue: Specifies that this is a certificate request

  • -w: Path of the server’s webroot folder

  • --server: Horizon ACME profile endpoint

  • --accountemail: Contact email address

  • -d: Requested DNS name (can be specified several times)

  • --eab-kid: MAC Key ID of the EAB account

  • --eab-hmac-key: MAC Key of the EAB account

Requesting a certificate with EAB using lego:

lego run --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accept-tos --email <contact email address, example: [email protected]> --domains <DNS name, example: nginx.evertrust.fr> --tls --tls.address <port, example :4443> --eab --eab.kid <MAC Key ID> --eab.hmac <MAC Key>

Where:

  • run: Requests or renews a certificate

  • --server: Horizon ACME profile endpoint

  • --accept-tos: Accepts the CA terms of service

  • --email: Contact email address

  • --domains: Requested DNS name (can be specified several times)

  • --tls: Enables the TLS-ALPN-01 validation mode

  • --tls.address: Address and port the challenge server listens on (default: :443): must match the TLS-ALPN-01 validation port of the ACME profile

  • --eab: Use External Account Binding for account registration

  • --eab.kid: MAC Key ID of the EAB account

  • --eab.hmac: MAC Key of the EAB account

Requesting a certificate for an IP address

An ACME client can request an IP identifier instead of, or alongside, a DNS name: the identifier type is defined by the ACME client when placing its order. Optionally, the IP identifier constraint of the ACME profile can restrict the IP addresses accepted (see ACME profile).

Requesting a certificate for an IP address using acme.sh:

(sudo) acme.sh --issue -w <path of the webroot folder> --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accountemail <contact email address, example: [email protected]> -d <IP address, example: 192.0.2.1>

Where:

  • --issue: Specifies that this is a certificate request

  • -w: Path of the webroot folder

  • --server: Horizon ACME profile endpoint

  • --accountemail: Contact email address

  • -d: Requested IP address

Requesting a certificate for an IP address using certbot:

(sudo) certbot certonly --webroot -w <path of the webroot folder> --no-eff-email --agree-tos --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> -m <contact email address, example: [email protected]> --domain <DNS name, example: apache.evertrust.fr> --ip-address <IP address, example: 192.0.2.1>

Where:

  • --webroot: Enables the webroot mode

  • -w: Path of the webroot folder

  • --no-eff-email: Does not share your email address with EFF

  • --agree-tos: Explicitly agrees to the terms of service

  • --server: Horizon ACME profile endpoint

  • -m: Contact email address

  • --domain: Requested DNS name

  • --ip-address: Requested IP address, added to the certificate as a SAN alongside the DNS name

Requesting a certificate for an IP address using lego:

lego run --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --accept-tos --email <contact email address, example: [email protected]> --domains <IP address, example: 192.0.2.1> --tls --tls.address <port, example :4443>

Where:

  • run: Requests or renews a certificate

  • --server: Horizon ACME profile endpoint

  • --accept-tos: Accepts the CA terms of service

  • --email: Contact email address

  • --domains: Requested IP address

  • --tls: Enables the TLS-ALPN-01 validation mode

  • --tls.address: Address and port the challenge server listens on (default: :443): must match the TLS-ALPN-01 validation port of the ACME profile

Revoking a certificate

Revoking a certificate using certbot:

(sudo) certbot revoke --cert-path <path of the certificate to revoke> --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory>

Where:

  • --cert-path: Specifies the path of the certificate to revoke

  • --server: Horizon ACME profile endpoint

Revoking a certificate using acme.sh:

(sudo) acme.sh --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --revoke -d <DNS name, example: apache.evertrust.fr>

Where:

  • --server: Horizon ACME profile endpoint

  • -d: DNS name of the certificate to revoke

Revoking a certificate using lego:

lego certificates revoke --server <Horizon ACME endpoint, example: https://horizon.evertrust.fr/acme/profile1/directory> --email <contact email address, example: [email protected]> --cert.name <DNS name, example: apache.evertrust.fr>

Where:

  • certificates revoke: Revokes the certificate identified by its name

  • --server: Horizon ACME profile endpoint

  • --email: Contact email address used to register the account

  • --cert.name: Name of the certificate to revoke (the first domain name by default)