acme.sh

acme.sh
Name	acme.sh
Title	acme.sh
Released	2015
Programming language	Shell (POSIX sh)
Operating system	Unix-like
License	MIT License

acme.sh acme.sh is a lightweight, pure POSIX shell implementation of the ACME protocol designed to obtain and renew Transport Layer Security certificates from Let's Encrypt and other certificate authorities. It emphasizes minimal dependencies, broad portability across Linux, FreeBSD, OpenBSD, and NetBSD, and scriptable hooks for integration with web servers and DNS providers. The project has been referenced in discussions around TLS automation, DevOps toolchains used by organizations such as Google and Mozilla, and system administration practices widely adopted by administrators of Apache HTTP Server and NGINX.

Overview

acme.sh implements the Automated Certificate Management Environment protocol first standardized by the Internet Security Research Group and adopted by certificate authorities including Let's Encrypt and Buypass. The tool operates as a single-file shell script that delegates validation challenges (HTTP-01, DNS-01, TLS-ALPN-01) to platform-specific hooks compatible with systemd, OpenRC, crond, and container platforms such as Docker and Kubernetes. Its minimalist design philosophy aligns it with other Unix utilities used in production environments like BusyBox and s6, and it is often paired with configuration management systems such as Ansible, Puppet, and Chef.

Features

acme.sh provides automated certificate issuance, renewal, and installation workflows supporting multiple challenge types and certificate authorities. Key features include: - Challenge automation via hooks for DNS providers including Cloudflare, AWS, Alibaba Cloud, Google Cloud Platform, and DigitalOcean so it integrates with cloud platforms used by Amazon Web Services and Microsoft Azure deployments. - Support for ACME v2 endpoints and wildcard certificates, facilitating use with content delivery networks like Cloudflare and load balancers from F5 Networks. - Zero-dependency operation using only POSIX shell and standard Unix utilities, enhancing compatibility with minimalist systems such as Alpine Linux and embedded devices running OpenWrt. - Integration hooks for web servers and reverse proxies including NGINX, Apache HTTP Server, HAProxy, and TLS terminators used by Envoy (software). - Scriptable storage backends and PKI operations compatible with hardware security modules from vendors like Yubico and Thales Group, as well as software keystores used by OpenSSL and GnuTLS.

Installation and usage

Installation is typically performed by fetching the single shell script and installing it into system paths managed by Filesystem Hierarchy Standard conventions on distributions such as Debian GNU/Linux, Ubuntu, CentOS, and Fedora. acme.sh offers command-line subcommands for registering accounts with ACME providers, issuing certificates, and performing staged renewals compatible with CI/CD pipelines orchestrated by Jenkins, GitLab CI, and GitHub Actions. Usage examples demonstrate obtaining certificates for web services hosted on Heroku or virtual machines provisioned via Proxmox VE, and automating renewals with cron jobs similar to strategies used for OpenVPN and Postfix. Administrators integrate acme.sh with monitoring systems like Prometheus and alerting stacks such as Alertmanager to track certificate expiry.

Supported ACME providers and integrations

acme.sh supports a broad range of ACME-compatible certificate authorities and DNS providers through built-in and community-contributed plugins. Notable supported services include Let's Encrypt, Buypass, and ACME endpoints provided by commercial CAs used by enterprises such as DigiCert and Entrust. DNS provider integrations cover major cloud DNS services—Amazon Route 53, Cloudflare, Google Cloud DNS—and telecom operators' DNS platforms used by domain registrars like GoDaddy and Namecheap. The extensible hook system allows connections to orchestration platforms and services including Kubernetes ExternalDNS, Traefik, Caddy (web server), and certificate distribution systems used in service meshes created with Istio.

Security and design

Security in acme.sh centers on minimal attack surface, reproducible behavior across POSIX environments, and explicit hook execution privileges. The design avoids linking against language runtimes by using POSIX sh, reducing dependencies that have historically introduced vulnerabilities in projects like OpenSSL Heartbleed era discussions involving OpenSSL and GnuTLS. It supports storing private keys in protected file systems with permissions aligned to POSIX semantics and can integrate with key-management appliances and HSM devices following practices from standards bodies like the Internet Engineering Task Force. The project includes safeguards for rate limits imposed by Let's Encrypt and operational guidelines echoed in security advisories from organizations such as CERT Coordination Center.

Development and community

acme.sh is developed as an open-source project under the MIT License, with contributions from independent maintainers and operators in the web infrastructure community including participants who also contribute to Let's Encrypt client ecosystems and Unix tooling projects such as Debian packaging teams. The community discusses development, feature requests, and integration recipes on issue trackers and forums frequented by system administrators and developers from companies like Facebook, LinkedIn, and Red Hat. Documentation and examples have been translated and republished in materials used by training organizations and conferences including FOSDEM, KubeCon, and DevOpsDays.

Category:Free software Category:SSL/TLS Category:Public-key infrastructure