Managing SSL certificates can get tedious, especially with a bunch of domains or constant renewals. acme.sh SSL is a lightweight shell script that automates getting, installing, and renewing acme.sh SSL certificates from free certificate authorities like Let’s Encrypt and ZeroSSL.
Unlike some other tools, acme.sh doesn’t need Python or other programming languages. It runs across pretty much any Unix-based system out there.
The tool takes care of everything—from the first certificate issuance to automatic renewals every 30 days. You don’t have to do it by hand. It works with several validation methods: webroot, standalone, DNS, and even plugs directly into popular web servers like Apache and Nginx.
Big names like FreeBSD.org and Proxmox rely on this script for their cert management. That says something about its reliability.
Whether you’re running one site or juggling a stack of domains, acme.sh makes things pretty straightforward. Most DNS providers are supported via API integration. It only takes a few minutes to install and, in most cases, you don’t even need root access.
Key Takeaways
- acme.sh automates SSL certificate issuance and renewal from free certificate authorities using a simple shell script
- The tool supports multiple validation methods and integrates directly with web servers and DNS providers for hands-free operation
- Certificates automatically renew every 30 days and can be deployed to production servers with configurable reload commands
Core Concepts of acme.sh SSL Certs Management
acme.sh works as a lightweight ACME client, connecting to certificate authorities to grab and manage SSL/TLS certificates. It supports several certificate authorities and lets you pick from different certificate types and key options to fit your security needs.
How acme.sh Implements the ACME Protocol
The ACME protocol automates the back-and-forth between certificate authorities and servers. This acme.sh client is written entirely in bash shell script, so it’s portable across almost any Unix-based OS.
acme.sh follows RFC 8555 standards to talk with ACME v2 compatible authorities. When you request a certificate, acme.sh creates an account with the CA and submits a signing request. The CA then gives you a challenge to prove domain ownership before issuing the certificate.
Certificate issuance, renewal, and revocation all happen through automated API calls. The script manages the certificate lifecycle, so you don’t have to step in manually. Most of the time, you can run acme.sh without root privileges.
Supported Certificate Authorities and Compatibility
acme.sh isn’t limited to just one certificate authority. By default, it works with Let’s Encrypt, but you can also use ZeroSSL, Buypass, and SSL.com.
Each CA has its own quirks and rate limits. Let’s Encrypt lets you issue up to 50 certificates per domain each week. ZeroSSL needs an account, but otherwise offers similar free certs.
If one CA goes down, the script can switch to another automatically. You can pick your preferred CA with a simple command-line option. DNS challenge validation is supported and is especially handy for wildcard certs or tricky network setups.
Certificate Types and Key Options
acme.sh can generate different certificate types depending on what you need. Single-domain certificates protect just one domain, while wildcard certs cover a domain and all its subdomains.
Available key algorithms:
- RSA 2048-bit
- RSA 3072-bit
- RSA 4096-bit
- ECC 256-bit
- ECC 384-bit
By default, you get RSA 2048-bit, which is a solid balance between security and compatibility. ECC options offer stronger security with smaller key sizes and faster performance. You can pick the key length and algorithm when you issue the certificate.
Certificates are stored in PEM format by default, but you can export them in other formats if your web server or app needs something different.
Installing and Setting Up acme.sh
acme.sh doesn’t need much to get started. Installation is flexible and works across various Linux distributions. Setting up directories and permissions right from the beginning helps keep things running smoothly.
Installation Methods and Requirements
The acme.sh installation only needs a few basic packages. You’ll want git, socat, and cron. Just grab them from your package manager.
The standard way is to clone the repo: git clone https://github.com/acmesh-official/acme.sh.git to a temp folder. Then run the install script with the –accountemail flag to register your contact info.
acme.sh –install has several parameters. –home sets where the script lives, –config-home is for config files, and –cert-home is where certs get stored.
By default, acme.sh installs to ~/.acme.sh. If you’re doing a server-wide install, it’s common to put files in places like /usr/local/sbin/acme. The installer adds a cron job for renewals automatically.
Initial Configuration and Directory Structure
It’s best to keep things tidy by separating config files, raw certs, and live certs into their own directories. That way, you know where everything is.
Here’s what an install command might look like:
./acme.sh --install \
--home /usr/local/sbin/acme \
--config-home /etc/acme/config \
--cert-home /etc/acme/certs \
--accountemail "[email protected]"
This setup keeps your CSR and private keys organized by domain. After installing, check your setup with acme.sh --info. It’ll show you where everything lives and what email is set.
Some folks like to use a wrapper script to make sure acme.sh always uses the right config-home path. Saves some typing, honestly.
Recommended Practices for Secure Setup
File permissions are a big deal for security. Private keys need restrictive permissions—think 600 or 640—to keep them safe. Cert directories should be owned by root, but give group access if a service needs it.
It’s usually a good idea to set Let’s Encrypt as your default CA for better reliability. Just run acme.sh --set-default-ca --server letsencrypt. Turning on automatic upgrades keeps you patched against vulnerabilities.
Schedule the cron job for off-peak hours, like midnight or early morning, to avoid bogging down your system. Renewal only happens when certs are within 30 days of expiring, so it won’t run unnecessarily.
Security checklist:
- Set proper ownership on
/etc/acmedirectories - Restrict private key access to root only
- Use strong file permissions (600 for keys, 644 for certs)
- Enable automatic upgrades for security patches
- Configure email notifications for renewal failures
Issuing and Deploying Certificates with acme.sh
acme.sh supports several validation methods and handles both single and multi-domain certificates, including wildcards. You can use webroot, standalone, DNS, or web server-specific modes depending on your setup.
Certificate Issuance Workflow
To get started, use acme.sh --issue. This command connects to the CA, validates your domain, and generates the SSL cert files.
The issuance process needs you to specify the domain and validation method. Once validation is a go, acme.sh generates the private key, CSR, and gets the signed cert back.
You can set the key length and algorithm right when you issue the cert. By default, it uses RSA, but you can pick ECC for stronger security with smaller keys. The keylength parameter takes values like ec-256, ec-384, or ec-521 for ECDSA certs.
acme.sh drops the domain cert, intermediate certs, private key, and full chain cert into a folder named after your domain in the install directory.
Selecting Validation Methods and Modes
Webroot mode works by placing a file in your web server’s document root. No downtime, and it’s perfect for live sites.
Standalone mode fires up a temporary web server on port 80 for validation. You’ll need to stop your main web server briefly for this. Standalone tls-alpn mode uses port 443 and the ALPN protocol instead.
nginx mode and apache mode handle validation for those servers automatically. These modes sniff out your server config and add temporary rules as needed.
DNS mode uses a DNS TXT record to prove domain ownership. DNS API integration covers over 150 DNS providers with scripts. For example, dns_cf does Cloudflare DNS for you.
DNS alias mode lets you validate a domain using DNS records from another domain. Handy if your main DNS provider doesn’t have an API. Stateless mode finishes validation without saving challenge tokens on disk, which is great for sensitive environments.
Handling Multiple Domains and Wildcard Certificates
The acme.sh client can generate certificates for multiple domains at once using subject alternative name entries. You just add more domains with the -d flag after your primary domain.
A wildcard certificate lets you cover all subdomains under a domain using the *.example.com format. Wildcard certificates always need DNS validation, since HTTP-based methods can’t verify wildcard ownership.
You can mix wildcard and specific domains in a single command. This way, you get a certificate that works for *.example.com, example.com, and any others you list.
Multiple domains from different root domains can go into one certificate. You’ll need to validate each domain separately, but it does cut down on the number of certificates to track.
Integration with Web Servers and Certificate Deployment
After you get SSL certificates with acme.sh, you have to deploy them to your web servers and set up automatic reloading. The steps are a bit different for NGINX and Apache, but both need you to point to the right certificate files and set up reload commands so changes apply without downtime.
Using acme.sh with NGINX
Deploying SSL certificates to NGINX means copying the certificate files over and updating your server config. You run the --install-cert command with parameters to put certificates in the right places.
The command includes the domain, key-file path, fullchain-file path, and a reloadcmd. Here’s a typical example:
acme.sh --install-cert -d example.com \
--key-file /etc/ssl/certs/example.com.key \
--fullchain-file /etc/ssl/certs/example.com.fullchain.cer \
--reloadcmd "systemctl reload nginx"
Your nginx config file needs to reference these certificate paths. Edit your server block to include ssl_certificate and ssl_certificate_key directives that point to the installed files.
When you run systemctl reload nginx, it applies your new config without dropping active connections. NGINX will start serving HTTPS traffic as soon as the config points to the right certificates and the service reloads cleanly.
Using acme.sh with Apache
Apache works much like NGINX here, though the service commands are different. The acme.sh deployment to Apache servers involves creating a directory for certificates and updating your virtual hosts.
Make a directory like /etc/ssl/certs to hold your Apache certificates. Then, run the install command with the right certificate locations and reload command:
acme.sh --install-cert -d example.com \
--cert-file /etc/ssl/certs/example.com.cert \
--key-file /etc/ssl/certs/example.com.key \
--fullchain-file /etc/ssl/certs/example.com.fullchain.cer \
--reloadcmd "systemctl reload apache2"
Update your Apache virtual host files so SSLCertificateFile and SSLCertificateKeyFile point to these certificates. Run systemctl reload apache2 to apply the changes without interrupting service.
Automation and Reload Hooks
The reloadcmd parameter lets you automate server reloads after certificate renewal. With this, renewed certificates take effect without you having to do anything manually.
acme.sh stores your reload command and runs it every time a certificate renews. You can use any shell command here, but most people go with systemctl reload nginx or systemctl reload apache2 depending on their setup.
The webroot method works well for automation. It drops validation files in the web server’s document root during renewal, so you don’t have to stop the web server. Just specify the webroot path the first time, and acme.sh remembers it for renewals later.
Need different reload commands for different domains? Just run separate acme.sh --install-cert commands for each one. That flexibility helps in mixed environments where you might have both NGINX and Apache servers running.
Certificate Renewal, Revocation, and Lifecycle Management
The acme.sh tool takes care of certificate renewal automatically with scheduled tasks, but you can also force renewals or remove certificates manually. If a certificate gets compromised, you can revoke it, and there’s a built-in upgrade command to keep acme.sh current.
Automatic and Manual Renewal Strategies
acme.sh sets up automatic renewal by default using a cron job. The installer adds a crontab entry that runs twice daily to check if any certificates need renewal.
Certificates usually get renewed automatically 60 days after they’re issued, leaving about 30 days before they expire. If you want, you can force a manual renewal at any time with acme.sh --renew and the right domain flag. That’s handy for testing or when you’ve changed something in your config.
You can set up renewal hooks to run custom scripts before or after renewal. These hooks might deploy renewed certificates to servers, restart services, or trigger other automated tasks. The automated certificate management process helps you avoid outages from expired certificates.
Managing Revocation and Removal
Sometimes, you have to revoke a certificate—maybe a private key got leaked, or you just need to invalidate it right away. The acme.sh --revoke command tells the certificate authority to mark it untrusted, so browsers and clients won’t accept it anymore.
You’ll need the original certificate files and account credentials for revocation. After that, you should request a new certificate with fresh keys.
Use acme.sh --remove to delete certificate files and related config from your system. This also removes the certificate from certificate lifecycle management tracking and stops future renewal attempts for that domain.
Upgrading acme.sh and Maintaining the Environment
acme.sh has a built-in upgrade tool—just run acme.sh --upgrade to grab the latest version from the official repo. It updates the install but keeps your certificates and config settings intact.
Run acme.sh --version to see what version you’re using. Staying updated gives you new features, security fixes, and better compatibility with various certificate authorities.
The upgrade process keeps your existing certificates and cron jobs working. Still, it’s smart to check the release notes before upgrading production systems, just to catch any changes that might affect your setup.
Advanced Use Cases and Ecosystem Integration
Acme.sh does more than basic certificates. With DNS API integrations, ACME v2 features, and deployment options for all sorts of infrastructure, you can automate certificate provisioning for complex networks, wildcard domains, and even enterprise setups.
DNS API and Cloud Provider Integrations
acme.sh works with over 150 DNS provider APIs for automated domain validation. With DNS API integration, you don’t have to mess with web server configs during issuance.
It connects directly to DNS providers like Cloudflare, AWS Route53, and Google Cloud DNS. You authenticate using API tokens or credentials in config files, and the script handles creating and deleting TXT records for validation.
DNS manual mode is there if you can’t use an API. It shows you the TXT record values you need to add manually in your DNS panel. You’ll need to add those records before moving forward with validation.
Wildcard certificates can only use DNS validation. The DNS-01 challenge proves you own the domain by creating TXT records at _acme-challenge.domain.com. This works for both public and private domains.
External Account Binding and ACME v2 Features
External account binding lets acme.sh work with commercial certificate authorities that want account verification. This ACME v2 feature ties your client account to an existing customer account using EAB credentials.
Authorities give you a key identifier and an HMAC key. Register your account by passing these during setup. This way, only authorized folks can request certificates from those providers.
Stateless mode lets HAProxy handle HTTP challenges without saving challenge files. The load balancer returns responses using account thumbprints—pretty handy for high-availability setups.
TLS-ALPN mode validates domains over TLS on port 443. It’s useful if you can’t use port 80 or HTTP validation. The protocol uses a special ALPN identifier in the TLS handshake.
If you’re testing, Pebble is a small ACME server for development. Pebble strict mode enforces all the protocol rules, so you can catch issues before going live.
Deployment in Complex Environments
acme.sh hooks and API connections let you integrate with all sorts of platforms. Each environment needs its own approach, though.
Proxmox users can deploy certificates through the web UI or command line. The script updates node certificates and the web GUI automatically, but you do need root access to place the files.
On pfSense firewalls, acme.sh comes as a package you can install from the package manager. Configure domains and validation in the web UI, and the package handles renewals and restarts for you.
cPanel hosting platforms can use acme.sh as an alternative to AutoSSL. The script plugs into cPanel’s certificate store with API calls, managing certificates for multiple domains and subdomains across accounts.
Cert-manager in Kubernetes clusters can work with acme.sh for hybrid setups. Cert-manager handles pod certificates, while acme.sh can provide certificates for external load balancers or infrastructure components.
For Windows, win-acme is a native option, but acme.sh runs just fine under WSL. Both tools use the ACME protocol, but they have different deployment and scripting styles.
Frequently Asked Questions
People often ask how to install acme.sh with shell scripts, how automatic renewals work, and how it compares to Certbot when it comes to requirements or customization.
How can I install acme.sh to manage SSL certificates on my server?
Installing acme.sh is pretty simple—just run a shell command that downloads and sets up the client. You can use curl or wget to pull the script from the official repo and get started.
The installer makes a dedicated directory in your home folder for acme.sh files and configs. After it’s installed, it automatically adds a cron job to handle renewals.
Before you start, make sure you’ve got DNS access or control over your web server. acme.sh works with bash, dash, and sh shells on Unix-based systems.
What steps are required to renew an SSL certificate with acme.sh?
Certificate renewal in acme.sh usually runs on autopilot. When you set it up, it drops a cron job into your system.
That job checks your certificates every day and kicks off renewal when they’re close to expiring. You don’t really have to think about it most of the time.
If you want to renew a certificate yourself, just run the renewal command and pass in your domain. Acme.sh takes care of validation and puts the new certificate right where the old one lived.
Let’s Encrypt certificates get renewed about 60 days after they’re issued. This approach keeps downtime to a minimum, and honestly, it saves you from having to remember renewal dates.
How does acme.sh store and handle SSL certificate files on the system?
The tool keeps certificate files neatly sorted in its install directory. Each domain gets its own folder, holding the certificate, private key, intermediates, and the full chain.
It’s not a great idea to point your web server directly at the files in acme.sh’s folder. Instead, use the deployment hooks or install commands to put certificates where your server expects them.
Acme.sh hangs on to backup copies of older certificates, so you can roll back if something goes sideways. It also handles file permissions for you, locking down private keys against prying eyes.
Can you provide a brief overview of the ACME protocol and its role in SSL certificate management?
The Automatic Certificate Management Environment (ACME) protocol takes care of verifying, issuing, and renewing digital certificates. Thanks to ACME, you don’t have to wrangle certificates by hand, which is always a relief.
Clients like acme.sh talk to certificate authorities and prove you control your domain through different challenges. Once validation works, the CA hands over a signed SSL certificate.
ACME covers both v1 and v2. The second version brought in wildcard certificates and better security, which is pretty handy if you ask me.
How does acme.sh differ from other ACME clients like Certbot?
Acme.sh is lighter than Certbot because it’s just shell scripts—no extra dependencies to mess with. That makes it perfect for barebones servers or even quirky embedded gear.
The hook system and deployment options give you more ways to customize things. If you need to work with different DNS providers or cloud platforms, acme.sh gives you a lot of flexibility.
Certbot feels friendlier for beginners, with its interactive prompts. Acme.sh, though, is better for folks who like command-line tools and want to automate everything with scripts.
Where can I find a tutorial for setting up and configuring acme.sh for SSL certificate management?
Plenty of solid guides are out there for implementing SSL with acme.sh on Ubuntu and other flavors of Linux. Most of them walk you through installation, domain verification, and deploying certificates to web servers like Nginx or Apache.
The official acme.sh GitHub repository has documentation that digs into supported features and configuration options. You’ll find examples for different validation methods and deployment setups there, which is pretty handy if you’re not sure where to start.
If you want to just get going, getting started guides break down the basics, from installing acme.sh to snagging your first certificate. They toss in troubleshooting tips and some best practices for production too—which, honestly, can save a lot of headaches down the line.
