Education Center
ACME Clients on Linux
Introduction
The ACME protocol is a network protocol designed to automate the process of domain validation and deliverance of X.509 certificates. The process is set up between an ACME server and an ACME client.
Two popular clients on Linux are Certbot and acme.sh.
Certbot is an open source ACME client made by the Electronic Frontier Foundation (EFF) originally to be used in coordination with their own Certificate Authority service: Let's Encrypt.
The second client, acme.sh, is a client written in Shell (Unix shell) language under the GPLv3 license.
Overview
Certbot and acme.sh are simple CLI-based ACME clients for Linux.
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.
They both fully support the latest ACMEv2 protocol including its main latest feature: wilcard certificates (\*.example.com).
Both clients supports different modes for obtaining a certificate and in some cases automatically installing it.
The following tables lists the different modes for each clients:
Mode | Cert bot | Acme.sh | Notes |
apache | ✔️ | ✔️ | Obtains and automatically install a certificate using the running Apache server.( For acme.sh, this mode will only obtain a certificate without installing it) |
nginx | ✔️ | ✔️ | Obtains and automatically install a certificate using the running NGINX server.( For acme.sh, this mode will only obtain a certificate without installing it) |
webroot | ✔️ | ✔️ | Obtains a certificate by writing to the webroot directory of an already running webserver. |
standalone | ✔️ | ✔️ | Uses a "standalone" web server managed by Certbot or acme.sh. This mode is useful on system with no web servers or if using the running web server is not desired. |
DNS | ✔️ | ✔️ | This mode automates obtaining a certificate by modifying a DNS record to prove the control over a domain. |
tls-alpn | ❌ | ✔️ | Uses a TLS server to validate the control over a domain. |
Certificate request
Both clients must be executed using administrative privileges (sudo), except for acme.sh when using the webroot or DNS modes.
Each client requires only a few parameters to request a certificate by default from Let's Encrypt.
For instance for Certbot:
Parameter | Description |
certonly | Obtain or renew a certificate, but do 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. |
The command would be:
certbot certonly --webroot -w /var/www/example -d www.example.com
On the other hand, the parameters for acme.sh are:
Parameter | Description |
--issue | Obtain or renew a certificate, but do not install it |
-d [VALUE] | The domain(s) to enroll. |
-w [VALUE] | Path of the server's webroot folder |
The command would be:
acme.sh --issue -d example.com -w /var/www/example
There are many more options on both clients to customize the requests to specific needs.
For more information, visit the official web page of Certbot and acme.sh: * [Certbot](https://certbot.eff.org/docs/using.html) * [acme.sh](https://github.com/Neilpang/acme.sh)
Use Cases
By default, Certbot and acme.sh will request a certificate using the Let's Encrypt CA but there are several use cases where one would prefer to request a certificate from another CA.
The following examples will describe how to use some of the different modes of Certbot and acme.sh to request or revoke a certificate from another CA.
Apache mode
Using the Apache mode from Certbot and acme.sh will request a certificate, validate the control over the requested domain using the running the Apache server and then install the certificate to the server (only for Certbot).
The following example details the request used, its parameters and the results of the request using the Apache mode using Certbot.
NGINX mode
Using the NGINX mode from Certbot and acme.sh will request a certificate, validate the control over the requested domain using the running the NGINX server and then install the certificate to the server (only for Certbot).
The following examples detail the requests used, the parameters and the results of the requests using the NGINX mode.
Standalone mode
Using the standalone mode from Certbot and acme.sh will request a certificate, validate the control over the requested domain using a standalone webserver ran by Certbot or acme.sh.
In this use case, the certificate is only obtained and not installed to the running web server. The configuration of the web server must be modified afterward for the certificate to be consumed.
The following examples detail the requests used, the parameters and the results of the requests using the standalone mode.
Revocation
Both clients are also able to revoke the certificates they handle by sending a revoke request with the correct domain name of the certificate to revoke.
The following examples detail the requests used, the parameters and the results of the requests to revoke a certificate using Certbot.
