LinuxCommandLibrary

acme.sh

Obtain and renew Let's Encrypt certificates

TLDR

Issue a certificate using webroot mode

$ acme.sh --issue [[-d|--domain]] [example.com] [[-w|--webroot]] [/path/to/webroot]
copy

Issue a certificate for multiple domains using standalone mode using port 80
$ acme.sh --issue --standalone [[-d|--domain]] [example.com] [[-d|--domain]] [www.example.com]
copy

Issue a certificate using standalone TLS mode using port 443
$ acme.sh --issue --alpn [[-d|--domain]] [example.com]
copy

Issue a certificate using a working Nginx configuration
$ acme.sh --issue --nginx [[-d|--domain]] [example.com]
copy

Issue a certificate using a working Apache configuration
$ acme.sh --issue --apache [[-d|--domain]] [example.com]
copy

Issue a wildcard (\*) certificate using an automatic DNS API mode
$ acme.sh --issue --dns [dns_cf] [[-d|--domain]] [*.example.com]
copy

Install certificate files into the specified locations (useful for automatic certificate renewal)
$ acme.sh [[-i|--install-cert]] [[-d|--domain]] [example.com] --key-file [/path/to/example.com.key] --fullchain-file [/path/to/example.com.cer] --reloadcmd "[systemctl force-reload nginx]"
copy

SYNOPSIS

acme.sh [options] --issue [domain] ...

PARAMETERS

--issue --domain domain.com
    Issue a certificate for the specified domain.

--issue --dns dns_provider
    Use DNS validation with the specified DNS provider to issue a wildcard certificate. It will read environment variables of the dns provider.

--installcert --domain domain.com --certpath /path/to/cert.pem --keypath /path/to/key.pem --fullchainpath /path/to/fullchain.pem --reloadcmd "service nginx force-reload"
    Install the certificate to the specified locations and reload the server.

--renew --domain domain.com
    Renew the certificate for the specified domain.

--revoke --domain domain.com
    Revoke the certificate for the specified domain.

--uninstall
    Uninstall acme.sh completely.

--upgrade
    Upgrade acme.sh to the latest version.

--help
    Display help message.

--version
    Show the version of acme.sh.

DESCRIPTION

acme.sh is a pure Unix shell script implementing the ACME client protocol. It's designed to be simple, easy to use, and require no external dependencies beyond a basic Unix environment and standard tools like curl or wget. It allows you to obtain free certificates from Let's Encrypt and other ACME compliant Certificate Authorities (CAs). The primary goal of acme.sh is to automate the process of requesting, renewing, and installing certificates, making it easy to secure your web servers. It supports various DNS providers for automatic DNS challenges, allowing you to issue wildcard certificates even when you don't have direct access to the webserver. It supports a number of webservers like apache, nginx. It is very light and doesn't have dependencies like python.
The script handles the entire certificate lifecycle, including automatic renewal, ensuring that your certificates remain valid. It prioritizes security and reliability, implementing best practices for certificate management. It also attempts to be user-friendly, providing informative output and clear error messages.

CAVEATS

acme.sh requires a working internet connection to communicate with the ACME server. Ensure proper permissions are set to avoid security vulnerabilities. Some DNS providers may require specific environment variables to be set. acme.sh stores certificates in its own directory, typically ~/.acme.sh/.

INSTALLATION

To install acme.sh, simply run the following command: curl https://get.acme.sh | sh. This will download and install the script, creating a cron job for automatic certificate renewal.

AUTOMATIC RENEWAL

acme.sh automatically renews certificates every 60 days by default, ensuring that your certificates remain valid. The renewal process is handled by a cron job created during installation.

DNS API

To use DNS API to verify domain ownership, set the needed environment variables.
Example for Cloudflare:
export CF_Key="xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export CF_Email="your_cloudflare_email"
acme.sh --issue --dns dns_cf -d example.com -d "*.example.com"

HISTORY

acme.sh was developed to provide a simple, dependency-free ACME client for Unix systems. It gained popularity due to its ease of use and minimal requirements, making it suitable for environments where installing complex software packages is not feasible. The project has seen active development and community contributions, adding support for various DNS providers and improving its reliability.

SEE ALSO

openssl(1), certbot(1)

Copied to clipboard