🔐 acme.sh

An ACME Protocol Client Written Purely in Shell

📚 Wiki • 🐳 Docker Guide • 🐦 Twitter

` | Pick the CA (default is your configured default). The account is registered automatically if you have not used this CA before. | | `--dns-persist-wildcard` | Adds `policy=wildcard` to the record so it also authorizes wildcard / subdomain certs. | | `--dns-persist-ca-name ` | Use a specific CA identity domain (e.g. `sectigo.com`). If omitted, identities are read from the ACME directory's `caaIdentities` field and one record per identity is printed — you only need to add **any one** of them. | | `--dns-persist-days ` | Adds `persistUntil=` to the record, set to N days from now. The CA will refuse new validations against the record after that time. Omit for a record with no expiry. | You should get an output like: ```sh TXT persist domain:_validation-persist.example.com TXT persist value :"letsencrypt.org; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/123456789" ``` #### ✍️ Step 2: Add the TXT record to your DNS Add the printed `TXT persist domain` / `TXT persist value` pair as a TXT record at your DNS provider, then wait for it to propagate. #### 📜 Step 3: Issue the certificate ```bash acme.sh --issue -d example.com --dns-persist ``` ✅ **Done!** No challenge token is provisioned during issuance — the CA reads the persistent TXT record directly. > 🔄 Renewals just work: `acme.sh --renew -d example.com` (or the cron job) reuses the same TXT record automatically — no further DNS edits needed. --- ### 1️⃣1️⃣ Issue Certificates of Different Key Types (ECC or RSA) Just set the `keylength` to a valid, supported value. **Valid values for the `keylength` parameter:** | Key Length | Description | |------------|-------------| | `ec-256` | prime256v1, "ECDSA P-256" ⭐ **Default** | | `ec-384` | secp384r1, "ECDSA P-384" | | `ec-521` | secp521r1, "ECDSA P-521" ⚠️ Not supported by Let's Encrypt yet | | `2048` | RSA 2048-bit | | `3072` | RSA 3072-bit | | `4096` | RSA 4096-bit | **Examples:** #### Single domain with ECDSA P-384 certificate ```bash acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-384 ``` #### SAN multi domain with RSA4096 certificate ```bash acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength 4096 ``` --- ### 1️⃣2️⃣ Issue Wildcard Certificates It's simple! Just give a wildcard domain as the `-d` parameter: ```sh acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf ``` --- ### 1️⃣3️⃣ How to Renew Certificates > 🔄 No need to renew manually! All certs will be renewed automatically every **30** days, **or earlier when the CA's ARI says so** (see below). However, you can force a renewal: ```sh acme.sh --renew -d example.com --force ``` **For ECC cert:** ```sh acme.sh --renew -d example.com --force --ecc ``` #### 📡 ACME Renewal Information (ARI) — RFC 9773 📖 Wiki: https://github.com/acmesh-official/acme.sh/wiki/ARI If the CA exposes a `renewalInfo` endpoint in its ACME directory (Let's Encrypt, ZeroSSL, etc.), `acme.sh` follows [RFC 9773](https://www.rfc-editor.org/rfc/rfc9773.html) automatically — **no flag needed, no opt-in**: | What | When | Why | |------|------|-----| | 🔍 **Polls `suggestedWindow`** | Every cron run, before deciding to skip | Lets the CA shift the renewal time forward in case of an incident (key compromise, mass revocation, etc.) | | 🎯 **Picks a random renewal time** inside the window | Right after a successful issuance/renewal | Disperses renewals across the network so all clients don't hit the CA at the same instant | | 🔗 **Sends `replaces=`** in `newOrder` | On renewal | Lets the CA correlate the new order with the certificate it supersedes (RFC 9773 §5) | | ↩️ **Retries without `replaces`** | If the CA rejects with `alreadyReplaced` or an ARI validation error | Robust against edge cases (e.g. switching CAs, retired issuers) | **Renewal trigger logic:** the cert is renewed if **any one** of the following becomes true: 1. `--force` is given 2. The CA's **ARI `suggestedWindow` has started** 3. The cached `Le_NextRenewTime` has passed (default fallback for CAs without ARI) You can see the resulting next renewal time (already ARI-picked when applicable) in: ```sh acme.sh --info -d example.com # Look for: Le_NextRenewTimeStr=... ``` For the live ARI window the CA is currently advertising, run with `--debug 2`: ```sh acme.sh --renew -d example.com --debug 2 2>&1 | grep -i 'ARI suggestedWindow' ``` > 💡 If your CA does not advertise `renewalInfo`, `acme.sh` falls back to the classic 30-day rule — no behavior change. --- ### 1️⃣4️⃣ How to Stop Certificate Renewal To stop renewal of a cert, you can execute the following to remove the cert from the renewal list: ```sh acme.sh --remove -d example.com [--ecc] ``` The cert/key file is not removed from the disk. > 💡 You can remove the respective directory (e.g. `~/.acme.sh/example.com`) manually. --- ### 1️⃣5️⃣ How to Upgrade acme.sh > 🚀 acme.sh is in constant development — it's strongly recommended to use the latest code. **Update to latest:** ```sh acme.sh --upgrade ``` **Enable auto upgrade:** ```sh acme.sh --upgrade --auto-upgrade ``` **Disable auto upgrade:** ```sh acme.sh --upgrade --auto-upgrade 0 ``` --- ### 1️⃣6️⃣ Issue a Certificate from an Existing CSR 📚 https://github.com/acmesh-official/acme.sh/wiki/Issue-a-cert-from-existing-CSR --- ### 1️⃣7️⃣ Send Notifications in Cronjob 📚 https://github.com/acmesh-official/acme.sh/wiki/notify --- ### 1️⃣8️⃣ Under the Hood > 🔧 Speak ACME language using shell, directly to "Let's Encrypt". --- ### 1️⃣9️⃣ Acknowledgments | Project | Link | |---------|------| | 🙏 Acme-tiny | https://github.com/diafygi/acme-tiny | | 📜 ACME protocol | https://github.com/ietf-wg-acme/acme | --- ## 👥 Contributors ### 💻 Code Contributors This project exists thanks to all the people who contribute. ### 💰 Financial Contributors Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/acmesh/contribute)] #### 👤 Individuals #### 🏢 Organizations Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/acmesh/contribute)] --- ### 2️⃣0️⃣ License & Others 📄 **License:** GPLv3 ⭐ Please **Star** and **Fork** this project! 🐛 [Issues](https://github.com/acmesh-official/acme.sh/issues) and 🔀 [Pull Requests](https://github.com/acmesh-official/acme.sh/pulls) are welcome. --- ### 2️⃣1️⃣ Donate > 💝 Your donation makes **acme.sh** better! | Method | Link | |--------|------| | PayPal / Alipay(支付宝) / Wechat(微信) | [https://donate.acme.sh/](https://donate.acme.sh/) | 📜 [Donate List](https://github.com/acmesh-official/acme.sh/wiki/Donate-list) --- ### 2️⃣2️⃣ About This Repository > [!NOTE] > This repository is officially maintained by ZeroSSL as part of our commitment to providing secure and reliable SSL/TLS solutions. We welcome contributions and feedback from the community! > For more information about our services, including free and paid SSL/TLS certificates, visit https://zerossl.com. > > All donations made through this repository go directly to the original independent maintainer (Neil Pang), not to ZeroSSL.