Beginner’s Guide to Using acme.sh for Let’s Encrypt SSL Certificates

by

Acme.sh is a straightforward and robust ACME protocol client, written purely in Shell (Unix shell) language. It is compatible with bash, dash, and sh shells, and facilitates the management of SSL certificate installation, renewal, and revocation. It supports both ACME version 1 and ACME version 2 protocols, as well as wildcard certifications via ACME v2. The fact that it is a zero dependencies ACME client enhances its value significantly—you don’t need extensive downloads or installations to get it running. While it doesn’t require root or sudo access, using root is recommended for optimal performance.

Acme.sh supports various validation methods that confirm domain ownership, including:

  • Webroot mode
  • Standalone mode
  • Standalone tls-alpn mode
  • Apache mode
  • Nginx mode
  • DNS mode
  • DNS alias mode
  • Stateless mode

What is Let’s Encrypt?

Let’s Encrypt (LE) is a certificate authority (CA) that provides free and automated SSL/TLS certificates, aiming to encrypt the entire web. If you own a domain and have shell access to your server, you can use Let’s Encrypt to obtain a trusted certificate at no cost. Let’s Encrypt can issue SAN certificates for up to 100 hostnames and wildcard certificates. All certificates are valid for 90 days.

Acme.sh Usage and Basic Commands

Below are some common commands and options for using acme.sh.

Acme.sh Installation

There are multiple ways to install acme.sh:

Install from web via curl or wget:


      curl https://get.acme.sh | sh
      source ~/.bashrc

or


      wget -O - https://get.acme.sh | sh
      source ~/.bashrc

Install from GitHub:


      curl https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 sh

or


      wget -O - https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 sh

Git Clone and Install:


      git clone https://github.com/Neilpang/acme.sh.git
      cd ./acme.sh
      ./acme.sh --install
      source ~/.bashrc

The installer will perform the following actions:

  1. Create and copy acme.sh to your home directory ($HOME): ~/.acme.sh/. All certificates will be placed in this folder as well.
  2. Create an alias for: acme.sh=~/.acme.sh/acme.sh.
  3. Create a daily cron job to check and renew certificates if needed.

Advanced Installation:


      git clone https://github.com/Neilpang/acme.sh.git
      cd acme.sh
      ./acme.sh --install \
                --home ~/myacme \
                --config-home ~/myacme/data \
                --cert-home ~/mycerts \
                --accountemail "hi@acme.sh" \
                --accountkey ~/myaccount.key \
                --accountconf ~/myaccount.conf \
                --useragent "this is my client."

You don’t need to set all options—only those you care about.

Options explained:

  • --home: A customized directory to install acme.sh in. By default, it installs into ~/.acme.sh.
  • --config-home: A writable folder where acme.sh writes all files (including certs/keys, configs). By default, it’s in --home.
  • --cert-home: A customized directory to save issued certificates. By default, it’s saved in --config-home.
  • --accountemail: The email used to register the account with Let’s Encrypt, receive renewal notice emails here. Default is empty.
  • --accountkey: A file that saves your account private key. By default, it’s saved in --config-home.
  • --useragent: The user-agent header value sent to Let’s Encrypt.

After installation is complete, verify it by checking the acme.sh version:

acme.sh --version # v2.8.1

The program has many commands and parameters for use. To get help, run:

acme.sh --help

Issue an SSL Certificate

If a web server is already running, use webroot mode. You need write access to the web root folder. Here are some example commands:

Single domain + Webroot mode:

acme.sh --issue -d example.com --webroot /var/www/example.com

Multiple domains + Webroot mode:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --webroot /var/www/example.com

Single domain ECC/ECDSA cert + Webroot mode:

acme.sh --issue -d example.com --webroot /var/www/example.com --keylength ec-256

Multiple domains ECC/ECDSA cert + Webroot mode:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --webroot /var/www/example.com --keylength ec-256

Valid values for --keylength are: 2048 (default), 3072, 4096, 8192 or ec-256, ec-384.

If you’re without a web server and port 80 is free, use standalone mode. Install socat tools first.

Single domain + Standalone mode:

acme.sh --issue -d example.com --standalone

Multiple domains + Standalone mode:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --standalone

If port 443 is free on a non-web server, use standalone TLS ALPN mode. Acme.sh’s built-in TLS web server listens on port 443 to issue certs.

Single domain + Standalone TLS ALPN mode:

acme.sh --issue -d example.com --alpn

Multiple domains + Standalone TLS ALPN mode:

acme.sh --issue -d example.com -d www.example.com --alpn

Automatic DNS API Integration

If your DNS provider offers an API, acme.sh can automatically add the DNS TXT record for you, facilitating the automatic issuance and renewal of certificates. Configure your API keys and email before requesting certificates. Acme.sh integrates automatically with about 60 DNS providers and can utilize the Lexicon tool for unsupported ones.

Single domain + CloudFlare DNS API mode:


      export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje"
      export CF_Email="xx@ddd.com"
      acme.sh --issue -d example.com --dns dns_cf

Wildcard cert + CloudFlare DNS API mode:


      export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje"
      export CF_Email="xx@ddd.com"
      acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf

If your DNS provider doesn’t offer API access, add the TXT record manually:

acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com

You should see an output like below:

    Add the following txt record:
    Domain:_acme-challenge.example.com
    Txt value:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c
    
    Add the following txt record:
    Domain:_acme-challenge.www.example.com
    Txt value:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    
    Please add those txt records to the domains. Waiting for the DNS to take effect.

Then rerun with the renew argument:

acme.sh --renew -d example.com

Note: DNS manual mode cannot auto-renew certificates. You must add a new TXT record to your domain during certificate renewal. Use DNS API mode for automation.

Install Let’s Encrypt SSL Certificate

Post generation, install/copy issued certificates to the correct disk location. Avoid using cert files in the ~/.acme.sh/ folder—they’re for internal use, and folder structures may change. Create a directory for certificates storage like /etc/letsencrypt, /etc/nginx/ssl, or /etc/apache2/ssl, based on your server software and SSL storage preferences.

Example for Apache:


      acme.sh --install-cert \
              --domain example.com \
              --cert-file /path/to/cert/cert.pem \
              --key-file /path/to/keyfile/key.pem \
              --fullchain-file /path/to/fullchain/fullchain.pem \
              --reloadcmd "sudo systemctl reload apache2.service"

Example for Nginx:


      acme.sh --install-cert \
              --domain example.com \
              --cert-file /path/to/cert/cert.pem \
              --key-file /path/to/keyfile/key.pem \
              --fullchain-file /path/to/fullchain/fullchain.pem \
              --reloadcmd "sudo systemctl reload nginx.service"

Parameters are stored in the .acme.sh configuration file and should be correctly set, as this file is referenced during cron job renewal runs. The “reloadcmd” depends on your operating system and init system.

Renewing Let’s Encrypt SSL Certificates

Manual certificate renewal isn’t necessary since all certificates automatically renew every 60 days. However, you can force renew a certificate:

acme.sh --renew -d example.com --force

or, for ECC cert:

acme.sh --renew -d example.com --force --ecc

How to Upgrade acme.sh

Update acme.sh to the latest code with:

acme.sh --upgrade

Enable auto-upgrade with:

acme.sh --upgrade --auto-upgrade

This keeps acme.sh updated automatically.

For more assistance, visit the acme.sh wiki page at https://github.com/Neilpang/acme.sh/wiki.

Links

Frequently Asked Questions (FAQ)

  • Do I need to be a root user to install acme.sh?
    No, root or sudo access is not required but recommended for the installation and management of certificates.
  • How often do I need to renew SSL certificates issued by acme.sh?
    Certificates are automatically renewed every 60 days, well before the 90-day expiration period.
  • Can I use acme.sh for wildcard certificates?
    Yes, acme.sh supports issuing wildcard certificates with the ACME v2 protocol.
  • How can I update acme.sh?
    You can update acme.sh with the acme.sh --upgrade command or enable auto-upgrade.
  • What should I do if my DNS provider doesn’t support API for automatic DNS challenge?
    You can manually add the DNS TXT records as instructed by the output, however, it’s recommended to use DNS providers with API support for automation.