acme.sh

Issue a certificate using webroot mode

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

$ acme.sh --issue --standalone [[-d|--domain]] [example.com] [[-d|--domain]] [www.example.com]

$ acme.sh --issue --alpn [[-d|--domain]] [example.com]

$ acme.sh --issue --nginx [[-d|--domain]] [example.com]

$ acme.sh --issue --apache [[-d|--domain]] [example.com]

$ acme.sh --issue --dns [dns_cf] [[-d|--domain]] [*.example.com]

$ 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]"

acme.sh [command] [options]
acme.sh --issue [domain_options] [validation_method] [other_options]
acme.sh --renew [-d domain] [other_options]
acme.sh --install-cert [-d domain] --key-file path --fullchain-file path [--reloadcmd service_cmd]
acme.sh --uninstall [-d domain]
acme.sh --cron

--issue
    Issue a new certificate.

-d, --domain
    Specify domain name(s). Can be used multiple times for SAN certificates.

--dns dns_api_name
    Use DNS-01 validation. Specify the DNS provider API (e.g., `dns_cf` for Cloudflare).

--webroot /path/to/webroot
    Use HTTP-01 validation with a webroot directory.

--standalone
    Use HTTP-01 validation by spinning up a temporary standalone web server on port 80/443.

--renew
    Renew a certificate. This command is automatically run by the cron job.

--install-cert
    Install certificate files to a specified location for use by services like web servers.

--install-ssl
    An alias for --install-cert, provided for compatibility.

--reloadcmd "service_cmd"
    Command to execute after certificate installation/renewal (e.g., `systemctl reload nginx`).

--uninstall
    Uninstall a certificate and remove its configuration from acme.sh.

--home /path/to/acme.sh
    Specify the `acme.sh` working directory (default: `~/.acme.sh`).

--cert-home /path/to/certs
    Specify the directory where certificates are stored (default: `~/.acme.sh/`).

--server ca_url
    Specify an ACME server URL (e.g., staging server, custom CA).

--force
    Force renewal or issuance, even if the certificate is not due. Use with caution.

--cron
    Run the daily cron job for certificate renewal checks. This is typically automated.

--debug
    Enable debug output for troubleshooting.

--log-level level
    Set the log level (e.g., `1` for info, `2` for debug).

--upgrade
    Upgrade `acme.sh` to the latest version from its git repository.

--set-default-dns dns_api_name
    Set a default DNS API to be used for future certificate issues, avoiding repeated `--dns` options.

acme.sh is a pure Unix shell script that automates the process of issuing and renewing SSL/TLS certificates from ACME providers like Let's Encrypt. It's designed to be lightweight and simple, requiring no external dependencies beyond a standard Unix environment (curl, grep, sed, openssl, awk).

It supports various domain validation methods, including HTTP-01 (webroot, standalone server) and DNS-01. For DNS-01, it offers extensive support for numerous DNS providers through their APIs, allowing fully automated wildcard certificate issuance and renewal.

Its primary purpose is to simplify certificate management for web servers, mail servers, and other services, providing an easy way to keep certificates up-to-date with automatic renewal capabilities integrated into a cron job.

acme.sh requires root or sudo privileges for certain operations like binding to port 80/443 for standalone mode, or installing certificates to system-protected directories (e.g., `/etc/nginx/ssl`). When using DNS-01 validation, ensure the necessary API keys/tokens are correctly set as environment variables as per the documentation for your specific DNS provider. Be mindful of Let's Encrypt rate limits, especially during testing; use the staging server (`--server https://acme-staging-v02.api.letsencrypt.org/directory`) for testing to avoid hitting production limits. As a shell script, its execution speed might be slightly slower than compiled clients, but this is negligible for certificate management tasks.

To issue a wildcard certificate using DNS-01 validation (e.g., with Cloudflare DNS):

First, set up your DNS API credentials (replace with your actual API key/token and email):
`export CF_Key="sdfsdfsdfljlbjkljkljlkjlkjsdfs"`
`export CF_Email="xxxx@gmail.com"`

Then, issue the certificate:
`acme.sh --issue -d example.com -d *.example.com --dns dns_cf`

After issuance, configure your web server (e.g., Nginx) to use the generated certificates. `acme.sh` provides the --install-cert command to copy the certificates to a desired location and reload the service.

Once a certificate is issued, `acme.sh` stores it in its own directory (typically `~/.acme.sh/example.com/`). For web servers, you typically install them to a more conventional location:

`acme.sh --install-cert -d example.com \`
` --key-file /etc/nginx/ssl/example.com.key \`
` --fullchain-file /etc/nginx/ssl/example.com_fullchain.cer \`
` --reloadcmd "systemctl reload nginx"`

`acme.sh` automatically creates a cron job (or adds to an existing one) to run the --cron command twice a day. This command checks for certificates due for renewal and executes the --install-cert command again if renewal is successful, ensuring your certificates are always up-to-date without manual intervention.

acme.sh emerged as a lightweight, pure shell script alternative to more complex ACME clients like `certbot`. Its design philosophy prioritizes simplicity and minimal dependencies, making it suitable for a wide range of Unix-like systems, including embedded devices or environments where Python or other language runtimes might not be readily available or desired. It quickly gained popularity for its extensive support for DNS API integrations, enabling fully automated wildcard certificate management well before `certbot` offered similar robust support. It has continuously evolved to support new ACME features and protocols, including ACME v2 and external account binding, maintaining its status as a highly capable and versatile ACME client.

certbot(1): Another popular ACME client, typically Python-based., openssl(1): Cryptographic toolkit used by acme.sh for key generation and certificate operations., curl(1): Used for communication with ACME servers and DNS APIs., nginx(8): Common web server often configured with certificates issued by acme.sh., apache2(8): Another common web server., cron(8): Used to schedule automatic certificate renewals by acme.sh.