Acme.sh 使用
跳到导航
跳到搜索
关于
通过 acme.sh 脚本,可以申请、自动更新证书。 项目相关地址: 1、acme.sh 项目主页(中文说明) 2、acme.sh/wiki 3、acme.sh/wiki/Options-and-Params 4、acme.sh/wiki/Blogs-and-tutorials#中文
支持的证书:
- ZeroSSL.com CA(default)
- Letsencrypt.org CA
- BuyPass.com CA
- SSL.com CA
- Pebble strict Mode
- Any other RFC8555-compliant CA
支持的模式:(使用场景)
- Webroot mode
- Standalone mode
- Standalone tls-alpn mode
- Apache mode
- Nginx mode
- DNS mode
- DNS alias mode
- Stateless mode
重点关注其 DNS mode 模式的“Automatic DNS API integration”方式。 (目前 acme.sh 支持大多数 dns 提供商,包括 Cloudflare、GoDaddy、Aliyun 等) 官方连接:How to use DNS API
acme.sh
安装、更新、卸载
- 安装:
- 在线安装:
curl https://get.acme.sh | sh # 或者 wget -O - https://get.acme.sh | sh
- 通过 git 安装:
git clone https://github.com/acmesh-official/acme.sh.git cd ./acme.sh ./acme.sh --install
- 安装位置:“~/.acme.sh/”(若 root 用户安装,即:“/root/.acme.sh”);
- 安装好后,会自动为你创建 cronjob(计划任务), 每天 0:00 点自动检测所有的证书, 如果快过期了, 需要更新, 则会自动更新证书。
- 查看已创建的 cronjob:
[root@newjersey ~]# crontab -l 5 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null
- 在线安装:
- 更新:
# 升级 acme.sh 到最新版 : acme.sh --upgrade # 如果你不想手动升级, 可以开启自动升级: acme.sh --upgrade --auto-upgrade # 你也可以随时关闭自动更新: acme.sh --upgrade --auto-upgrade 0
- 卸载:
acme.sh --uninstall
- 并同时卸载 cron 作业;
其他命令
参考:
Usage: acme.sh <command> ... [parameters ...] Commands: -h, --help Show this help message. -v, --version Show version info. --install Install acme.sh to your system. --uninstall Uninstall acme.sh, and uninstall the cron job. --upgrade Upgrade acme.sh to the latest code from https://github.com/acmesh-official/acme.sh. --issue Issue a cert. --deploy Deploy the cert to your server. -i, --install-cert Install the issued cert to apache/nginx or any other server. -r, --renew Renew a cert. --renew-all Renew all the certs. --revoke Revoke a cert. --remove Remove the cert from list of certs known to acme.sh. --list List all the certs. --to-pkcs12 Export the certificate and key to a pfx file. --to-pkcs8 Convert to pkcs8 format. --sign-csr Issue a cert from an existing csr. --show-csr Show the content of a csr. -ccr, --create-csr Create CSR, professional use. --create-domain-key Create an domain private key, professional use. --update-account Update account info. --register-account Register account key. --deactivate-account Deactivate the account. --create-account-key Create an account private key, professional use. --install-cronjob Install the cron job to renew certs, you don't need to call this. The 'install' command can automatically install the cron job. --uninstall-cronjob Uninstall the cron job. The 'uninstall' command can do this automatically. --cron Run cron job to renew all the certs. --set-notify Set the cron notification hook, level or mode. --deactivate Deactivate the domain authz, professional use. --set-default-ca Used with '--server', Set the default CA to use. See: https://github.com/acmesh-official/acme.sh/wiki/Server Parameters: -d, --domain <domain.tld> Specifies a domain, used to issue, renew or revoke etc. --challenge-alias <domain.tld> The challenge domain alias for DNS alias mode. See: https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode --domain-alias <domain.tld> The domain alias for DNS alias mode. See: https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode --preferred-chain <chain> If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used. (default: empty) See: https://github.com/acmesh-official/acme.sh/wiki/Preferred-Chain -f, --force Force install, force cert renewal or override sudo restrictions. --staging, --test Use staging server, for testing. --debug [0|1|2|3] Output debug info. Defaults to 1 if argument is omitted. --output-insecure Output all the sensitive messages. By default all the credentials/sensitive messages are hidden from the output/debug/log for security. -w, --webroot <directory> Specifies the web root folder for web root mode. --standalone Use standalone mode. --alpn Use standalone alpn mode. --stateless Use stateless mode. See: https://github.com/acmesh-official/acme.sh/wiki/Stateless-Mode --apache Use apache mode. --dns [dns_hook] Use dns manual mode or dns api. Defaults to manual mode when argument is omitted. See: https://github.com/acmesh-official/acme.sh/wiki/dnsapi --dnssleep <seconds> The time in seconds to wait for all the txt records to propagate in dns api mode. It's not necessary to use this by default, acme.sh polls dns status by DOH automatically. -k, --keylength <bits> Specifies the domain key length: 2048, 3072, 4096, 8192 or ec-256, ec-384, ec-521. -ak, --accountkeylength <bits> Specifies the account key length: 2048, 3072, 4096 --log [file] Specifies the log file. Defaults to "/root/.acme.sh/acme.sh.log" if argument is omitted. --log-level <1|2> Specifies the log level, default is 1. --syslog <0|3|6|7> Syslog level, 0: disable syslog, 3: error, 6: info, 7: debug. --eab-kid <eab_key_id> Key Identifier for External Account Binding. --eab-hmac-key <eab_hmac_key> HMAC key for External Account Binding. These parameters are to install the cert to nginx/apache or any other server after issue/renew a cert: --cert-file <file> Path to copy the cert file to after issue/renew.. --key-file <file> Path to copy the key file to after issue/renew. --ca-file <file> Path to copy the intermediate cert file to after issue/renew. --fullchain-file <file> Path to copy the fullchain cert file to after issue/renew. --reloadcmd <command> Command to execute after issue/renew to reload the server. --server <server_uri> ACME Directory Resource URI. (default: https://acme.zerossl.com/v2/DV90) See: https://github.com/acmesh-official/acme.sh/wiki/Server --accountconf <file> Specifies a customized account config file. --home <directory> Specifies the home dir for acme.sh. --cert-home <directory> Specifies the home dir to save all the certs, only valid for '--install' command. --config-home <directory> Specifies the home dir to save all the configurations. --useragent <string> Specifies the user agent string. it will be saved for future use too. -m, --email <email> Specifies the account email, only valid for the '--install' and '--update-account' command. --accountkey <file> Specifies the account key path, only valid for the '--install' command. --days <ndays> Specifies the days to renew the cert when using '--issue' command. The default value is 60 days. --httpport <port> Specifies the standalone listening port. Only valid if the server is behind a reverse proxy or load balancer. --tlsport <port> Specifies the standalone tls listening port. Only valid if the server is behind a reverse proxy or load balancer. --local-address <ip> Specifies the standalone/tls server listening address, in case you have multiple ip addresses. --listraw Only used for '--list' command, list the certs in raw format. -se, --stop-renew-on-error Only valid for '--renew-all' command. Stop if one cert has error in renewal. --insecure Do not check the server certificate, in some devices, the api server's certificate may not be trusted. --ca-bundle <file> Specifies the path to the CA certificate bundle to verify api server's certificate. --ca-path <directory> Specifies directory containing CA certificates in PEM format, used by wget or curl. --no-cron Only valid for '--install' command, which means: do not install the default cron job. In this case, the certs will not be renewed automatically. --no-profile Only valid for '--install' command, which means: do not install aliases to user profile. --no-color Do not output color text. --force-color Force output of color text. Useful for non-interactive use with the aha tool for HTML E-Mails. --ecc Specifies to use the ECC cert. Valid for '--install-cert', '--renew', '--revoke', '--to-pkcs12' and '--create-csr' --csr <file> Specifies the input csr. --pre-hook <command> Command to be run before obtaining any certificates. --post-hook <command> Command to be run after attempting to obtain/renew certificates. Runs regardless of whether obtain/renew succeeded or failed. --renew-hook <command> Command to be run after each successfully renewed certificate. --deploy-hook <hookname> The hook file to deploy cert --ocsp, --ocsp-must-staple Generate OCSP-Must-Staple extension. --always-force-new-domain-key Generate new domain key on renewal. Otherwise, the domain key is not changed by default. --auto-upgrade [0|1] Valid for '--upgrade' command, indicating whether to upgrade automatically in future. Defaults to 1 if argument is omitted. --listen-v4 Force standalone/tls server to listen at ipv4. --listen-v6 Force standalone/tls server to listen at ipv6. --openssl-bin <file> Specifies a custom openssl bin location. --use-wget Force to use wget, if you have both curl and wget installed. --yes-I-know-dns-manual-mode-enough-go-ahead-please Force use of dns manual mode. See: https://github.com/acmesh-official/acme.sh/wiki/dns-manual-mode -b, --branch <branch> Only valid for '--upgrade' command, specifies the branch name to upgrade to. --notify-level <0|1|2|3> Set the notification level: Default value is 2. 0: disabled, no notification will be sent. 1: send notifications only when there is an error. 2: send notifications when a cert is successfully renewed, or there is an error. 3: send notifications when a cert is skipped, renewed, or error. --notify-mode <0|1> Set notification mode. Default value is 0. 0: Bulk mode. Send all the domain's notifications in one message(mail). 1: Cert mode. Send a message for every single cert. --notify-hook <hookname> Set the notify hook --revoke-reason <0-10> The reason for revocation, can be used in conjunction with the '--revoke' command. See: https://github.com/acmesh-official/acme.sh/wiki/revokecert --password <password> Add a password to exported pfx file. Use with --to-pkcs12.
证书管理
以下摘抄自项目说明。 参见: 1、acme.sh 项目 2、中文说明 3、More examples:How to issue a cert 4、How to use DNS API 5、DNS manual mode 6、DNS alias mode
证书颁发
以下: 1、除了“安装证书到 Apache/Nginx”、“Apache 模式”、“Nginx 模式”、“自动 DNS API”无需手动配置,其他的证书都生成在“~/.acme.sh/<example.com>/”目录下,需要手动拷贝到需要的位置; 2、除了“DNS 手动模式”,其他都可以自动续订;
acme.sh 有多种证书颁发用法:
- 颁发单个证书:
- 用于一个网站:
acme.sh --issue -d example.com -w /home/wwwroot/example.com # 或者: acme.sh --issue -d example.com -w /home/username/public_html # 或者: acme.sh --issue -d example.com -w /var/www/html
- 参数“/home/wwwroot/example.com”或“/home/username/public_html”或“/var/www/html”是承载网站文件的 web root 文件夹(您必须具有对此文件夹的写入权限);
- 用于多个网站:
acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com
- 必须将所有域名,指向并绑定到同一 webroot 目录(如上的“/home/wwwroot/example.com”);
- 证书将放在:“~/.acme.sh/example.com/”;
- 证书将每60天自动更新一次;
- 用于一个网站:
- 安装证书到 Apache/Nginx 等:(直接将“证书/密钥”,“安装/复制”到 Apache/Nginx 的生产路径)
生成证书后,您可能希望将证书安装/复制到 Apache/Nginx 或其他服务器。您必须使用此命令将证书复制到目标文件,不要使用 ~/.acme.sh/ 文件夹中的证书文件,它们仅供内部使用,文件夹结构可能会在将来更改。
- Apache:
acme.sh --install-cert -d example.com \ --cert-file /path/to/certfile/in/apache/cert.pem \ --key-file /path/to/keyfile/in/apache/key.pem \ --fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \ --reloadcmd "service apache2 force-reload"
- Nginx:
acme.sh --install-cert -d example.com \ --key-file /path/to/keyfile/in/nginx/key.pem \ --fullchain-file /path/to/fullchain/nginx/cert.pem \ --reloadcmd "service nginx force-reload"
- 参数说明:(这里指定的所有参数都会被自动记录下来, 并在将来证书自动更新以后, 被再次自动调用)
- “-d example.com”:指定域名;(此为必须参数,其他参数都是可选)
- “--cert-file”:颁发/续订后,将“证书文件”复制到的路径;
- “--key-file”:颁发/续订后,将“密钥文件”复制到的路径;
- “--fullchain-file”:颁发/续订后,将“fullchain证书文件”复制到的路径;
- “--reloadcmd”:发出/续订后,要“执行的命令”以重新加载服务器;
- 默认情况下,证书将每60天更新一次(可配置)。证书续订后,Apache/Nginx 服务将通过以下命令自动重新加载:“service apache2 force reload”或“service Nginx force reload”;
- 【如果没有正确的“reloadcmd”,证书可能不会刷新到您的服务器,那么您的网站将无法在 60 天内显示续订的证书】
- 使用独立服务器颁发证书:(如果你还没有运行任何 web 服务, 80 端口是空闲的)
acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com
- 要求:root/sudoer,或具有侦听端口 80(TCP)的权限;
- 使用独立 ssl 服务器颁发证书:(如果你还没有运行任何 ssl 服务, 443 端口是空闲的)
acme.sh --issue --alpn -d example.com -d www.example.com -d cp.example.com
- 要求:root/sudoer,或具有侦听端口 443(TCP)的权限;
- 使用 Apache 模式:(如果您正在运行 Web 服务器,且运行的是 Apache 服务器,则推荐使用此模式)
acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com
- 要求:root/sudoer,因为它是与 Apache 服务器交互所必需的;
- 此模式不会将任何文件写入 web roo 文件夹(仅用于颁发证书,而不会更改您的 Apache 配置文件),所以,【需要自行配置网站配置文件以使用证书】;
- 使用 Nginx 模式:(如果您正在运行 Web 服务器,且运行的是 Nginx 服务器,则推荐使用此模式)
acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com
- 要求:root/sudoer,因为它是与 Nginx 服务器交互所必需的;
- 此模式不会将任何文件写入 web root 文件夹(仅用于颁发证书,而不会更改您的 Nginx 配置文件),所以,【需要自行配置网站配置文件以使用证书】;
- 自动 DNS API 集成:(如果您的 DNS 提供商支持 API 访问)
- 【无需任何证书相关的手动配置】
- 见:How to use DNS API;
- 使用 DNS 手动模式:(如果您的 DNS 提供商不支持任何 API 访问,可以手动添加 txt 记录)
- 生成解析记录:
acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com
- 第一次申请在后面加上“--yes-I-know-dns-manual-mode-enough-go-ahead-please”;
acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please
- 然后,acme.sh 会生成相应的解析记录显示出来(如下),你需要在你的域名管理面板中添加这条 TXT 记录:
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.
- 等待解析完成之后,重新生成证书:(请先等待 1 分钟,等待 DNS 条目反映)
acme.sh --renew -d example.com -d www.example.com -d cp.example.com
- 第一次申请在后面加上“--yes-I-know-dns-manual-mode-enough-go-ahead-please”:
acme.sh --renew -d example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please
- 如果您已使用 SHA CSR 颁发了 暂存/生产 证书,则使用“--force”开关覆盖旧 CER 的任何条目并颁发新 CER:
acme.sh --renew -d example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please --force
- 如果您已使用 ECC CSR 颁发了 暂存/生产 证书,则使用“--ECC--force”开关覆盖旧 CER 的任何条目并颁发新 CER:
acme.sh --renew -d example.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please --ecc --force
- 这种方式的好处是,你不需要任何服务器,不需要任何公网 ip,只需要 dns 的解析记录即可完成验证;【一般用于测试,务必谨慎用于生产环境】
- 此模式不能自动续订。当您更新证书时,您必须手动将新的 txt 记录添加到您的域中;
- 见:DNS manual mode;
- 见:DNS alias mode;
- 生成解析记录:
- 颁发 ECC 证书:(Let's Encrypt 现在可以颁发 ECDSA 证书了)
- 单域 ECC 证书:
acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256
- 多域 ECC 证书:
acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256
- 如上,“keylength”参数的有效值:
- ec-256:(prime256v1, "ECDSA P-256")
- ec-384:(secp384r1, "ECDSA P-384")
- ec-521:(secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)
- 单域 ECC 证书:
- 颁发通配符证书:
acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf
证书更新
您不需要手动续订证书。所有证书将每 60 天自动更新一次。
- 强制更新证书:
# 更新指定证书 acme.sh --renew -d example.com --force [--ecc] # 更新所有证书: acme.sh --renew-all
- --ecc:表示 ECC 证书
- 停止证书更新:
acme.sh --remove -d example.com [--ecc]
- 之后手动把目录下的证书移除就行。
吊销证书
如果你的私钥文件泄露或者不再使用,可以选择吊销该证书。
如果要吊销一个证书,使用:
# 列出全部证书 acme.sh --list # 吊销证书: acme.sh --revoke -d example.com # 吊销证书,并指定理由: acme.sh --revoke -d example.com --revoke-reason 0
移除证书
用于从 acme.sh 已知的证书列表中删除证书。(但并不吊销该证书)
如果要删除一个证书,使用:
# 列出全部证书 acme.sh --list # 移除指定证书 acme.sh --remove -d example.com
- 执行证书移除命令后,acme.sh 仅不再参与该证书的工作,但证书文件仍然在“~/acme.sh”文件夹下,需要用户手动删除。
出错怎么办
如果出错, 请添加 debug log:
acme.sh --issue ..... --debug # 或者: acme.sh --issue ..... --debug 2
详解:DNS认证方式(推荐)
这种方式不需要服务器和公网 IP,只需要 DNS 的解析记录即可完成验证,一般主流域名服务商都提供 API 接口。 (目前 acme.sh 支持包括主流的 CloudFlare、DNSPod、Aliyun、Amazon Route53 在内的多达 131 个的域名 API,见:How to use DNS API) 参考: 1、使用acme.sh自动签发和更新证书 2、使用一键脚本轻松给 shadowsocks v2ray插件, v2ray,trojan申请免费证书
- 给 GoDaddy 自动颁发证书:
#(替换 GD_Key 为自己的) export GD_Key="sdfsdfsdfljlbjkljlkjsdfoiwje" #(替换 GD_Secret 为自己的) export GD_Secret="asdfsdafdsfdsfdsfdsfdsafd" #(<example.com> 为自己的域名) acme.sh --issue --dns dns_gd -d <example.com> [-d <example.com>]
- GoDaddy API Key 创建地址:https://developer.godaddy.com/keys/
- 给 CloudFlare 自动颁发证书:
#(替换 CF_Key 为自己的) export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje" #(替换 CF_Email 为自己的 GoDaddy 登录邮箱) export CF_Email="xxxx@sss.com" #(<example.com> 为自己的域名) acme.sh --issue --dns dns_cf -d <example.com> [-d <example.com>]
- CloudFlare API Key 创建地址:https://dash.cloudflare.com/profile。
- 配置步骤,1、先配置 DNS 解析,2、生成 CloudFlare API Key:
- 在 CloudFlare 添加站点(根域名);
- 在“DNS”项,添加记录(“类型”:A;“名称”:子域名的一级域名;“内容”:服务器IP);
- 根据提示,修改域名供应商的 DNS 地址(在“DNS修改”将其 DNS 指定为 CloudFlare 的 DNS 地址);
- 在 CloudFlare 将 SSL/TLS 更改为“完全”(Full);
- 验证配置(ping 一下该域名,得到一个ip,查一查该ip是不是 CloudFlare 的地址)
CloudFlare 可用于“'''DNS 解析'''”和“'''CDN 加速'''”。 (此处只用其 DNS 解析的功能,因为国外的 CDN 反而可能导致降速) (如果 ip 被锁,倒是可以考虑使用其 CDN 功能拯救一下 ip)
FAQ
“-bash: acme.sh: command not found”
如果“acme.sh”命令提示:“-bash: acme.sh: command not found”,则先执行以下命令:
source ~/.bashrc
再继续执行其他命令。
关于使用的 CA 机构
执行时,提示:
[root@newjersey ~]# acme.sh --issue --dns dns_cf -d <example.com> [Tue Nov 30 23:12:51 UTC 2021] Using CA: https://acme.zerossl.com/v2/DV90 [Tue Nov 30 23:12:51 UTC 2021] Create account key ok. [Tue Nov 30 23:12:51 UTC 2021] No EAB credentials found for ZeroSSL, let's get one [Tue Nov 30 23:12:51 UTC 2021] acme.sh is using ZeroSSL as default CA now. [Tue Nov 30 23:12:51 UTC 2021] Please update your account with an email address first. [Tue Nov 30 23:12:51 UTC 2021] acme.sh --register-account -m my@example.com [Tue Nov 30 23:12:51 UTC 2021] See: https://github.com/acmesh-official/acme.sh/wiki/ZeroSSL.com-CA [Tue Nov 30 23:12:51 UTC 2021] Please add '--debug' or '--log' to check more details. [Tue Nov 30 23:12:51 UTC 2021] See: https://github.com/acmesh-official/acme.sh/wiki/How-to-debug-acme.sh
- 即,acme.sh(从2021年8月1日起)默认 CA 换成了 ZeroSSL(需要注册账号才能使用)。
所以如果需要使用其他 CA:(两种方式)
- 签发时指定:
# 本次使用 letsencrypt 机构的证书 acme.sh --issue --dns dns_cf -d <example.com> --server letsencrypt
- 更改默认:
# 指定默认的证书机构为 letsencrypt acme.sh --set-default-ca --server letsencrypt
- 以后就算版本升级也将一直默认使用指定的 CA。
什么是“ECC 证书”?
默认签发的都是基于 RSA 密钥加密的证书,而 ECC (Elliptic Curve Cryptography, 椭圆曲线密码) 密钥的保密性比 RSA 更好,密钥长度更短,更能对抗量子解密等。 目前现代的操作系统和浏览器都支持 ECC 证书了(Windows XP 及其之前的就算了)。 Let's Encrypt 提供了 ECDSA 证书的签发,且 acme.sh 也支持。
设置通知(Set notifications)
参见:acme.sh/wiki/notify