# acme.sh **Repository Path**: bely/acme.sh ## Basic Information - **Project Name**: acme.sh - **Description**: acme.sh 实现了 acme 协议, 可以从 letsencrypt 生成免费的证书. - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 3 - **Created**: 2024-10-16 - **Last Updated**: 2024-10-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README **acme.sh** 实现了 `acme` 协议, 可以从 letsencrypt 生成免费的证书. 主要步骤: 1. 安装 **acme.sh** 1. 生成证书 1. copy 证书到 nginx/apache 或者其他服务 1. 更新证书 1. 更新 **acme.sh** 1. 出错怎么办, 如何调试 下面详细介绍. # 1. 安装 **acme.sh** 安装很简单, 一个命令: ``` curl https://get.acme.sh | sh -s email=my@example.com #拉取代码 git clone https://gitee.com/pcboy/acme.sh.git cd acme.sh #安装 ./acme.sh --install -m 328754147@qq.com #使命令生效 cd ~ source ~/.bashrc #设置证书主 acme.sh --set-default-ca --server letsencrypt #开启自动更新 acme.sh --upgrade --auto-upgrade #设置阿里云DNS密钥 export Ali_Key="xxx" export Ali_Secret="xxx" #dns生成证书 acme.sh --issue --dns dns_ali -d <域名> #查看证书信息 acme.sh --info -d <域名> #检查修改nginx配置路径后安装证书 acme.sh --install-cert -d <域名> \ --key-file <路径>/key.pem \ --fullchain-file <路径>/cert.pem \ --reloadcmd "service nginx force-reload" #最后不要忘记修改定时任务执行时间 crontab -e ``` 普通用户和 root 用户都可以安装使用. 安装过程进行了以下几步: 1) 把 acme.sh 安装到你的 **home** 目录下: ``` ~/.acme.sh/ ``` 并创建 一个 shell 的 alias, 例如 .bashrc，方便你的使用: `alias acme.sh=~/.acme.sh/acme.sh` 2) 自动为你创建 cronjob, 每天 0:00 点自动检测所有的证书, 如果快过期了, 需要更新, 则会自动更新证书. 更高级的安装选项请参考: https://github.com/Neilpang/acme.sh/wiki/How-to-install **安装过程不会污染已有的系统任何功能和文件**, 所有的修改都限制在安装目录中: `~/.acme.sh/` # 2. 生成证书 **acme.sh** 实现了 **acme** 协议支持的所有验证协议. 一般有两种方式验证: http 和 dns 验证. ### 1. http 方式需要在你的网站根目录下放置一个文件, 来验证你的域名所有权,完成验证. 然后就可以生成证书了. ``` acme.sh --issue -d mydomain.com -d www.mydomain.com --webroot /home/wwwroot/mydomain.com/ ``` 只需要指定域名, 并指定域名所在的网站根目录. **acme.sh** 会全自动的生成验证文件, 并放到网站的根目录, 然后自动完成验证. 最后会聪明的删除验证文件. 整个过程没有任何副作用. 如果你用的 **apache**服务器, **acme.sh** 还可以智能的从 **apache**的配置中自动完成验证, 你不需要指定网站根目录: ``` acme.sh --issue -d mydomain.com --apache ``` 如果你用的 **nginx**服务器, 或者反代, **acme.sh** 还可以智能的从 **nginx**的配置中自动完成验证, 你不需要指定网站根目录: ``` acme.sh --issue -d mydomain.com --nginx ``` **注意, 无论是 apache 还是 nginx 模式, acme.sh在完成验证之后, 会恢复到之前的状态, 都不会私自更改你本身的配置. 好处是你不用担心配置被搞坏, 也有一个缺点, 你需要自己配置 ssl 的配置, 否则只能成功生成证书, 你的网站还是无法访问https. 但是为了安全, 你还是自己手动改配置吧.** 如果你还没有运行任何 web 服务, **80** 端口是空闲的, 那么 **acme.sh** 还能假装自己是一个webserver, 临时听在**80** 端口, 完成验证: ``` acme.sh --issue -d mydomain.com --standalone ``` acme.sh脚本默认ca服务器是zerossl，经常出错，会导致获取证书的时候一直出现：Pending, The CA is processing your order, please just wait. 只需要把ca服务器改成letsencrypt 即可，虽然更改以后还是有概率出现pending，但基本2-3次即可成功 ``` acme.sh --set-default-ca --server letsencrypt ``` 更高级的用法请参考: https://github.com/Neilpang/acme.sh/wiki/How-to-issue-a-cert ### 2. 手动 dns 方式, 手动在域名上添加一条 txt 解析记录, 验证域名所有权. 这种方式的好处是, 你不需要任何服务器, 不需要任何公网 ip, 只需要 dns 的解析记录即可完成验证. 坏处是，如果不同时配置 Automatic DNS API，使用这种方式 acme.sh 将无法自动更新证书，每次都需要手动再次重新解析验证域名所有权。 ``` acme.sh --issue --dns -d mydomain.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please ``` 然后, **acme.sh** 会生成相应的解析记录显示出来, 你只需要在你的域名管理面板中添加这条 txt 记录即可. 等待解析完成之后, 重新生成证书: ``` acme.sh --renew -d mydomain.com \ --yes-I-know-dns-manual-mode-enough-go-ahead-please ``` 注意第二次这里用的是 `--renew` dns 方式的真正强大之处在于可以使用域名解析商提供的 api 自动添加 txt 记录完成验证. **acme.sh** 目前支持 cloudflare, dnspod, cloudxns, godaddy 以及 ovh 等数十种解析商的自动集成. 以 dnspod 为例, 你需要先登录到 dnspod 账号, 生成你的 api id 和 api key, 都是免费的. 然后: ``` export DP_Id="1234" export DP_Key="sADDsdasdgdsf" acme.sh --issue --dns dns_dp -d aa.com -d www.aa.com ``` 证书就会自动生成了. 这里给出的 api id 和 api key 会被自动记录下来, 将来你在使用 dnspod api 的时候, 就不需要再次指定了. 直接生成就好了: ``` acme.sh --issue -d mydomain2.com --dns dns_dp ``` 更详细的 api 用法: https://github.com/Neilpang/acme.sh/blob/master/dnsapi/README.md # 3. copy/安装 证书 前面证书生成以后, 接下来需要把证书 copy 到真正需要用它的地方. 注意, 默认生成的证书都放在安装目录下: `~/.acme.sh/`, 请不要直接使用此目录下的文件, 例如: 不要直接让 nginx/apache 的配置文件使用这下面的文件. 这里面的文件都是内部使用, 而且目录结构可能会变化. 正确的使用方法是使用 `--install-cert` 命令,并指定目标位置, 然后证书文件会被copy到相应的位置, 例如: ## Apache example: ``` 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 example: ``` 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" ``` (一个小提醒, 这里用的是 `service nginx force-reload`, 不是 `service nginx reload`, 据测试, `reload` 并不会重新加载证书, 所以用的 `force-reload`) Nginx 的配置 `ssl_certificate` 使用 `/etc/nginx/ssl/fullchain.cer` ，而非 `/etc/nginx/ssl/.cer` ，否则 [SSL Labs](https://www.ssllabs.com/ssltest/) 的测试会报 `Chain issues Incomplete` 错误。 `--install-cert`命令可以携带很多参数, 来指定目标文件. 并且可以指定 reloadcmd, 当证书更新以后, reloadcmd会被自动调用,让服务器生效. 详细参数请参考: https://github.com/Neilpang/acme.sh#3-install-the-issued-cert-to-apachenginx-etc 值得注意的是, 这里指定的所有参数都会被自动记录下来, 并在将来证书自动更新以后, 被再次自动调用. # 4. 查看已安装证书信息 ``` acme.sh --info -d example.com # 会输出如下内容： DOMAIN_CONF=/root/.acme.sh/example.com/example.com.conf Le_Domain=example.com Le_Alt=no Le_Webroot=dns_ali Le_PreHook= Le_PostHook= Le_RenewHook= Le_API=https://acme-v02.api.letsencrypt.org/directory Le_Keylength= Le_OrderFinalize=https://acme-v02.api.letsencrypt.org/acme/finalize/23xxxx150/781xxxx4310 Le_LinkOrder=https://acme-v02.api.letsencrypt.org/acme/order/233xxx150/781xxxx4310 Le_LinkCert=https://acme-v02.api.letsencrypt.org/acme/cert/04cbd28xxxxxx349ecaea8d07 Le_CertCreateTime=1649358725 Le_CertCreateTimeStr=Thu Apr 7 19:12:05 UTC 2022 Le_NextRenewTimeStr=Mon Jun 6 19:12:05 UTC 2022 Le_NextRenewTime=1654456325 Le_RealCertPath= Le_RealCACertPath= Le_RealKeyPath=/etc/acme/example.com/privkey.pem Le_ReloadCmd=service nginx force-reload Le_RealFullChainPath=/etc/acme/example.com/chain.pem ``` # 5. 更新证书 目前证书在 60 天以后会自动更新, 你无需任何操作. 今后有可能会缩短这个时间, 不过都是自动的, 你不用关心. 请确保 cronjob 正确安装, 看起来是类似这样的: ``` crontab -l 56 * * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null ``` # 6. 关于修改ReloadCmd 目前修改`ReloadCmd`没有专门的命令，可以通过重新安装证书来实现修改`reloadCmd`的目的。 此外，安装证书后，相关信息是保存在`~/.acme.sh/example.com/example.conf`文件下的，内容就是`acme.sh --info -d example.com`输出的信息，不过`ReloadCmd`在文件中使用了Base64编码。理论上可以通过直接修改该文件来修改`ReloadCmd`，且修改时，无需Base64编码，直接写命令原文`acme.sh`也可以识别。 不过，`example.conf`文件的位置和内容格式以后可能会改变！`example.conf`一直都是内部使用, 后面有可能会改为用 sqlite 或者mysql 格式存储. 所以一般不建议自己修改。 # 7. 更新 acme.sh 目前由于 acme 协议和 letsencrypt CA 都在频繁的更新, 因此 acme.sh 也经常更新以保持同步. 升级 acme.sh 到最新版 : ``` acme.sh --upgrade ``` 如果你不想手动升级, 可以开启自动升级: ``` acme.sh --upgrade --auto-upgrade ``` 之后, acme.sh 就会自动保持更新了. 你也可以随时关闭自动更新: ``` acme.sh --upgrade --auto-upgrade 0 ``` # 8. 出错怎么办： 如果出错, 请添加 debug log： ``` acme.sh --issue ..... --debug ``` 或者： ``` acme.sh --issue ..... --debug 2 ``` 请参考： https://github.com/Neilpang/acme.sh/wiki/How-to-debug-acme.sh 在DNS验证模式下如果debug中出现诸如"timed out"等字样可能是因为GFW拦截了相应请求，需要添加http(s) proxy环境变量。（请按照自己实际设定修改） ``` export http_proxy="socks5h://localhost:1081" && export https_proxy="socks5h://localhost:1081" ``` 如果是使用docker则完整示例配置如下： ``` docker run --rm -it \ -v "/etc/acme":/acme.sh \ -e "CF_Token=[填入自己的信息]" \ -e "CF_Account_ID=[填入自己的信息]" \ -e "CF_Zone_ID=[填入自己的信息]" \ -e http_proxy="socks5h://[代理A]:1234" \ -e https_proxy="socks5h://[代理A]:1234" \ --network container:[代理A]\ neilpang/acme.sh \ --issue -d example.com --dns dns_cf --debug ``` 上述例子中使用cloudflare的DNS来签发证书，并通过把acme.sh链接到容器[代理A]，来转发curl请求（请按照自己实际设定修改） 最后, 本文并非完全的使用说明, 还有很多高级的功能, 更高级的用法请参看其他 wiki 页面. https://github.com/Neilpang/acme.sh/wiki # An ACME Shell script: acme.sh [![FreeBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/FreeBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/FreeBSD.yml) [![OpenBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/OpenBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/OpenBSD.yml) [![NetBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/NetBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/NetBSD.yml) [![MacOS](https://github.com/acmesh-official/acme.sh/actions/workflows/MacOS.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/MacOS.yml) [![Ubuntu](https://github.com/acmesh-official/acme.sh/actions/workflows/Ubuntu.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Ubuntu.yml) [![Windows](https://github.com/acmesh-official/acme.sh/actions/workflows/Windows.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Windows.yml) [![Solaris](https://github.com/acmesh-official/acme.sh/actions/workflows/Solaris.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Solaris.yml) [![DragonFlyBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/DragonFlyBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/DragonFlyBSD.yml) [![Omnios](https://github.com/acmesh-official/acme.sh/actions/workflows/Omnios.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Omnios.yml) ![Shellcheck](https://github.com/acmesh-official/acme.sh/workflows/Shellcheck/badge.svg) ![PebbleStrict](https://github.com/acmesh-official/acme.sh/workflows/PebbleStrict/badge.svg) ![DockerHub](https://github.com/acmesh-official/acme.sh/workflows/Build%20DockerHub/badge.svg) [![Join the chat at https://gitter.im/acme-sh/Lobby](https://badges.gitter.im/acme-sh/Lobby.svg)](https://gitter.im/acme-sh/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Docker stars](https://img.shields.io/docker/stars/neilpang/acme.sh.svg)](https://hub.docker.com/r/neilpang/acme.sh "Click to view the image on Docker Hub") [![Docker pulls](https://img.shields.io/docker/pulls/neilpang/acme.sh.svg)](https://hub.docker.com/r/neilpang/acme.sh "Click to view the image on Docker Hub") - An ACME protocol client written purely in Shell (Unix shell) language. - Full ACME protocol implementation. - Support ECDSA certs - Support SAN and wildcard certs - Simple, powerful and very easy to use. You only need 3 minutes to learn it. - Bash, dash and sh compatible. - Purely written in Shell with no dependencies on python. - Just one script to issue, renew and install your certificates automatically. - DOES NOT require `root/sudoer` access. - Docker ready - IPv6 ready - Cron job notifications for renewal or error etc. It's probably the `easiest & smartest` shell script to automatically issue & renew the free certificates. Wiki: https://github.com/acmesh-official/acme.sh/wiki For Docker Fans: [acme.sh :two_hearts: Docker ](https://github.com/acmesh-official/acme.sh/wiki/Run-acme.sh-in-docker) Twitter: [@neilpangxa](https://twitter.com/neilpangxa) # [中文说明](https://github.com/acmesh-official/acme.sh/wiki/%E8%AF%B4%E6%98%8E) # Who: - [FreeBSD.org](https://blog.crashed.org/letsencrypt-in-freebsd-org/) - [ruby-china.org](https://ruby-china.org/topics/31983) - [Proxmox](https://pve.proxmox.com/wiki/Certificate_Management) - [pfsense](https://github.com/pfsense/FreeBSD-ports/pull/89) - [Loadbalancer.org](https://www.loadbalancer.org/blog/loadbalancer-org-with-lets-encrypt-quick-and-dirty) - [discourse.org](https://meta.discourse.org/t/setting-up-lets-encrypt/40709) - [Centminmod](https://centminmod.com/letsencrypt-acmetool-https.html) - [splynx](https://forum.splynx.com/t/free-ssl-cert-for-splynx-lets-encrypt/297) - [opnsense.org](https://github.com/opnsense/plugins/tree/master/security/acme-client/src/opnsense/scripts/OPNsense/AcmeClient) - [CentOS Web Panel](https://control-webpanel.com) - [lnmp.org](https://lnmp.org/) - [more...](https://github.com/acmesh-official/acme.sh/wiki/Blogs-and-tutorials) # Tested OS | NO | Status| Platform| |----|-------|---------| |1|[![MacOS](https://github.com/acmesh-official/acme.sh/actions/workflows/MacOS.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/MacOS.yml)|Mac OSX |2|[![Windows](https://github.com/acmesh-official/acme.sh/actions/workflows/Windows.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Windows.yml)|Windows (cygwin with curl, openssl and crontab included) |3|[![FreeBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/FreeBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/FreeBSD.yml)|FreeBSD |4|[![Solaris](https://github.com/acmesh-official/acme.sh/actions/workflows/Solaris.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Solaris.yml)|Solaris |5|[![Ubuntu](https://github.com/acmesh-official/acme.sh/actions/workflows/Ubuntu.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Ubuntu.yml)| Ubuntu |6|NA|pfsense |7|[![OpenBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/OpenBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/OpenBSD.yml)|OpenBSD |8|[![NetBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/NetBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/NetBSD.yml)|NetBSD |9|[![DragonFlyBSD](https://github.com/acmesh-official/acme.sh/actions/workflows/DragonFlyBSD.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/DragonFlyBSD.yml)|DragonFlyBSD |10|[![Omnios](https://github.com/acmesh-official/acme.sh/actions/workflows/Omnios.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Omnios.yml)|Omnios |11|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)| Debian |12|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|CentOS |13|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|openSUSE |14|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|Alpine Linux (with curl) |15|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|Archlinux |16|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|fedora |17|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|Kali Linux |18|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|Oracle Linux |19|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|Mageia |10|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|Gentoo Linux |11|[![Linux](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml/badge.svg)](https://github.com/acmesh-official/acme.sh/actions/workflows/Linux.yml)|ClearLinux |22|-----| Cloud Linux https://github.com/acmesh-official/acme.sh/issues/111 |23|-----| OpenWRT: Tested and working. See [wiki page](https://github.com/acmesh-official/acme.sh/wiki/How-to-run-on-OpenWRT) |24|[![](https://acmesh-official.github.io/acmetest/status/proxmox.svg)](https://github.com/acmesh-official/letest#here-are-the-latest-status)| Proxmox: See Proxmox VE Wiki. Version [4.x, 5.0, 5.1](https://pve.proxmox.com/wiki/HTTPS_Certificate_Configuration_(Version_4.x,_5.0_and_5.1)#Let.27s_Encrypt_using_acme.sh), version [5.2 and up](https://pve.proxmox.com/wiki/Certificate_Management) Check our [testing project](https://github.com/acmesh-official/acmetest): https://github.com/acmesh-official/acmetest # Supported CA - [ZeroSSL.com CA](https://github.com/acmesh-official/acme.sh/wiki/ZeroSSL.com-CA)(default) - Letsencrypt.org CA - [BuyPass.com CA](https://github.com/acmesh-official/acme.sh/wiki/BuyPass.com-CA) - [SSL.com CA](https://github.com/acmesh-official/acme.sh/wiki/SSL.com-CA) - [Google.com Public CA](https://github.com/acmesh-official/acme.sh/wiki/Google-Public-CA) - [Pebble strict Mode](https://github.com/letsencrypt/pebble) - Any other [RFC8555](https://tools.ietf.org/html/rfc8555)-compliant CA # Supported modes - Webroot mode - Standalone mode - Standalone tls-alpn mode - Apache mode - Nginx mode - DNS mode - [DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode) - [Stateless mode](https://github.com/acmesh-official/acme.sh/wiki/Stateless-Mode) # 1. How to install ### 1. Install online Check this project: https://github.com/acmesh-official/get.acme.sh ```bash curl https://get.acme.sh | sh -s email=my@example.com ``` Or: ```bash wget -O - https://get.acme.sh | sh -s email=my@example.com ``` ### 2. Or, Install from git Clone this project and launch installation: ```bash git clone https://github.com/acmesh-official/acme.sh.git cd ./acme.sh ./acme.sh --install -m my@example.com ``` You `don't have to be root` then, although `it is recommended`. Advanced Installation: https://github.com/acmesh-official/acme.sh/wiki/How-to-install The installer will perform 3 actions: 1. Create and copy `acme.sh` to your home dir (`$HOME`): `~/.acme.sh/`. All certs will be placed in this folder too. 2. Create alias for: `acme.sh=~/.acme.sh/acme.sh`. 3. Create daily cron job to check and renew the certs if needed. Cron entry example: ```bash 0 0 * * * "/home/user/.acme.sh"/acme.sh --cron --home "/home/user/.acme.sh" > /dev/null ``` After the installation, you must close the current terminal and reopen it to make the alias take effect. Ok, you are ready to issue certs now. Show help message: ```sh root@v1:~# acme.sh -h ``` # 2. Just issue a cert **Example 1:** Single domain. ```bash acme.sh --issue -d example.com -w /home/wwwroot/example.com ``` or: ```bash acme.sh --issue -d example.com -w /home/username/public_html ``` or: ```bash acme.sh --issue -d example.com -w /var/www/html ``` **Example 2:** Multiple domains in the same cert. ```bash acme.sh --issue -d example.com -d www.example.com -d cp.example.com -w /home/wwwroot/example.com ``` The parameter `/home/wwwroot/example.com` or `/home/username/public_html` or `/var/www/html` is the web root folder where you host your website files. You **MUST** have `write access` to this folder. Second argument **"example.com"** is the main domain you want to issue the cert for. You must have at least one domain there. You must point and bind all the domains to the same webroot dir: `/home/wwwroot/example.com`. The certs will be placed in `~/.acme.sh/example.com/` The certs will be renewed automatically every **60** days. More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert # 3. Install the cert to Apache/Nginx etc. After the cert is generated, you probably want to install/copy the cert to your Apache/Nginx or other servers. You **MUST** use this command to copy the certs to the target files, **DO NOT** use the certs files in **~/.acme.sh/** folder, they are for internal use only, the folder structure may change in the future. **Apache** example: ```bash 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** example: ```bash 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" ``` Only the domain is required, all the other parameters are optional. The ownership and permission info of existing files are preserved. You can pre-create the files to define the ownership and permission. Install/copy the cert/key to the production Apache or Nginx path. The cert will be renewed every **60** days by default (which is configurable). Once the cert is renewed, the Apache/Nginx service will be reloaded automatically by the command: `service apache2 force-reload` or `service nginx force-reload`. **Please take care: The reloadcmd is very important. The cert can be automatically renewed, but, without a correct 'reloadcmd' the cert may not be flushed to your server(like nginx or apache), then your website will not be able to show renewed cert in 60 days.** # 4. Use Standalone server to issue cert **(requires you to be root/sudoer or have permission to listen on port 80 (TCP))** Port `80` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again. ```bash acme.sh --issue --standalone -d example.com -d www.example.com -d cp.example.com ``` More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert # 5. Use Standalone ssl server to issue cert **(requires you to be root/sudoer or have permission to listen on port 443 (TCP))** Port `443` (TCP) **MUST** be free to listen on, otherwise you will be prompted to free it and try again. ```bash acme.sh --issue --alpn -d example.com -d www.example.com -d cp.example.com ``` More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert # 6. Use Apache mode **(requires you to be root/sudoer, since it is required to interact with Apache server)** If you are running a web server, it is recommended to use the `Webroot mode`. Particularly, if you are running an Apache server, you can use Apache mode instead. This mode doesn't write any files to your web root folder. Just set string "apache" as the second argument and it will force use of apache plugin automatically. ```sh acme.sh --issue --apache -d example.com -d www.example.com -d cp.example.com ``` **This apache mode is only to issue the cert, it will not change your apache config files. You will need to configure your website config files to use the cert by yourself. We don't want to mess with your apache server, don't worry.** More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert # 7. Use Nginx mode **(requires you to be root/sudoer, since it is required to interact with Nginx server)** If you are running a web server, it is recommended to use the `Webroot mode`. Particularly, if you are running an nginx server, you can use nginx mode instead. This mode doesn't write any files to your web root folder. Just set string "nginx" as the second argument. It will configure nginx server automatically to verify the domain and then restore the nginx config to the original version. So, the config is not changed. ```sh acme.sh --issue --nginx -d example.com -d www.example.com -d cp.example.com ``` **This nginx mode is only to issue the cert, it will not change your nginx config files. You will need to configure your website config files to use the cert by yourself. We don't want to mess with your nginx server, don't worry.** More examples: https://github.com/acmesh-official/acme.sh/wiki/How-to-issue-a-cert # 8. Automatic DNS API integration If your DNS provider supports API access, we can use that API to automatically issue the certs. You don't have to do anything manually! ### Currently acme.sh supports most of the dns providers: https://github.com/acmesh-official/acme.sh/wiki/dnsapi # 9. Use DNS manual mode: See: https://github.com/acmesh-official/acme.sh/wiki/dns-manual-mode first. If your dns provider doesn't support any api access, you can add the txt record by hand. ```bash acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com ``` You should get an output like below: ```sh 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 just rerun with `renew` argument: ```bash acme.sh --renew -d example.com ``` Ok, it's done. **Take care, this is dns manual mode, it can not be renewed automatically. you will have to add a new txt record to your domain by your hand when you renew your cert.** **Please use dns api mode instead.** # 10. Issue ECC certificates Just set the `keylength` parameter with a prefix `ec-`. For example: ### Single domain ECC certificate ```bash acme.sh --issue -w /home/wwwroot/example.com -d example.com --keylength ec-256 ``` ### SAN multi domain ECC certificate ```bash acme.sh --issue -w /home/wwwroot/example.com -d example.com -d www.example.com --keylength ec-256 ``` Please look at the `keylength` parameter above. Valid values are: 1. **ec-256 (prime256v1, "ECDSA P-256", which is the default key type)** 2. **ec-384 (secp384r1, "ECDSA P-384")** 3. **ec-521 (secp521r1, "ECDSA P-521", which is not supported by Let's Encrypt yet.)** 4. **2048 (RSA2048)** 5. **3072 (RSA3072)** 6. **4096 (RSA4096)** # 11. 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 ``` # 12. How to renew the certs No, you don't need to renew the certs manually. All the certs will be renewed automatically every **60** days. However, you can also force to renew a cert: ```sh acme.sh --renew -d example.com --force ``` or, for ECC cert: ```sh acme.sh --renew -d example.com --force --ecc ``` # 13. How to stop cert 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`) by yourself. # 14. How to upgrade `acme.sh` acme.sh is in constant development, so it's strongly recommended to use the latest code. You can update acme.sh to the latest code: ```sh acme.sh --upgrade ``` You can also enable auto upgrade: ```sh acme.sh --upgrade --auto-upgrade ``` Then **acme.sh** will be kept up to date automatically. Disable auto upgrade: ```sh acme.sh --upgrade --auto-upgrade 0 ``` # 15. Issue a cert from an existing CSR https://github.com/acmesh-official/acme.sh/wiki/Issue-a-cert-from-existing-CSR # 16. Send notifications in cronjob https://github.com/acmesh-official/acme.sh/wiki/notify # 17. Under the Hood Speak ACME language using shell, directly to "Let's Encrypt". TODO: # 18. Acknowledgments 1. Acme-tiny: https://github.com/diafygi/acme-tiny 2. 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)] # 19. License & Others License is GPLv3 Please Star and Fork me. [Issues](https://github.com/acmesh-official/acme.sh/issues) and [pull requests](https://github.com/acmesh-official/acme.sh/pulls) are welcome. # 20. Donate Your donation makes **acme.sh** better: 1. PayPal/Alipay(支付宝)/Wechat(微信): [https://donate.acme.sh/](https://donate.acme.sh/) [Donate List](https://github.com/acmesh-official/acme.sh/wiki/Donate-list)