letsencrypt证书-管理工具certbot
目录
1. 安装certbot
申请证书的工具：官方是certbot，可以根据你服务器的类型来选择安装教程。地址：certbot
你也可以直接使用certbot-auto(包含certbot，命令和certbot一样)，
user@webserver:~$ wget https://dl.eff.org/certbot-auto
user@webserver:~$ chmod a+x ./certbot-auto
user@webserver:~$ ./certbot-auto --help
官方建议：除非你有特别的需求，否则最好使用certbot来自动管理的你的证书。
2. certbot 介绍
Certbot 现在需要运行在安装了Python （2.7 or 3.4）的类unix系统上，内存大于512MB（如果小于的话，官方解决方案），默认是需要root权限的，比如写证书操作需要root权限。
Certbot客户机支持获取和安装证书的两种插件:auth和install，当使用certonly参数的时候，只会获取证书，并不会安装证，获取的证书位于/etc/letsencrypt目录下
主要插件的介绍：
Plugin| Auth| Install| Notes| Challenge types (and port)
---|---|---|---|---|---
apache | Y| Y| 自动化获取并安装证书| tls-sni-01 (443)
webroot | Y| N| 已经有运行的服务，通过验证webroot目录来获取证书 |http-01 (80)
nginx | Y| Y| 使用nginx自动获取和安装证书 | tls-sni-01 (443)
standalone | Y| N| 建立一个standalone WEB服务，需要80或者443端口可用，如果你没有类似nginx和apache等服务，这很有用 |http-01 (80) or tls-sni-01 (443)
DNS plugins| Y| N| 通过修改dns服务器的text记录，来获取证书，野卡证书只能通过此方式获取 |dns-01 (53)
manual | Y| N| 通过自己给指令获取证书，支持添加定制脚本来完成任务 |http-01 (80), dns-01 (53) or tls-sni-01 (443)
解析：
- 如果你使用standalone插件，那么需要使用80和443端口，因为要建一个监听这些端口的服务，如果你有别的服务使用了该端口，那么就会出问题了。
- webroot方式，如果你使用了nginx，那么你需要更改一些nginx配置，确保能验证你对该域名的所有权限
3. 插件的具体使用
这里讲解下部分插件的使用方法
3.1 webroot
一般需要使用的参数
certonly #只获取证书，不安装
--webroot #定义使用的插件方法是webroot
--webroot-path # 简写：-w 目录位置
-d # 域名
类似下面的命令
certbot certonly --webroot -w /var/www/example -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net
-w和-d配合使用，域名将使用最近的path，比如上面 /var/www/example 对应 前两个域名，/var/www/other对应后两个域名
验证的机制：
验证的时候会自动向${webroot-path}/.well-known/acme-challenge目录下写一个临时文件，然后会发送一个请求，去验证是否可以正常访问，访问的请求类似下面
66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"
所以我们本身有服务的情况下，比如使用的是nginx，那么我们需要添加如下配置
server {
server_name www.yoursite.com yoursite.com;
# 需要添加的配置
location ^~ /.well-known/acme-challenge/ {
alias /home/xxx/www/challenges/;
try_files $uri =404;
}
# ... 其它配置
}
3.2 standalone
该插件会启动一个web服务器，使用--preferred-challenges http参数的话，对应使用80端口，使用--preferred-challenges tls-sni参数对应使用443端口，所以如果你有占用这两个端口的服务，请根据你的实际使用端口，停用占用端口的程序，同样配合certonly使用。
使用方法：
sudo certbot certonly --standalone -d example.com -d www.example.com
3.3 DNS plugins
如果你想去的一个野卡证书，那么只能使用dns验证的方式（即使你是使用manual参数，根本上还是使用dns验证方式）。
默认的certbot是不包含dns插件的，如果你要使用此方式的话，需要下载相应的插件：插件地址，具体的使用方法，请点击你对应的dns服务商链接，然后按照相应的方法获取证书，官方提供的基本上是国外的dns服务区上，国内的服务商暂时没有，不过可以使用manual方法。
3.4 manual
该方法允许你通过交互的方式获取证书，可以在其它服务器上运行，可以选择http，dns和tls-sni方式中的任意一种。
比如使用dns的方式，会要求你在验证过程中手动填写txt dns的记录，然后继续，验证成功后会获取证书。
举例：
使用manual方式，选择dns验证，申请野卡证书的方法（添加--server https://acme-v02.api.letsencrypt.org/directory参数）
./certbot-auto certonly -d *.archerwong.cn -d archerwong.cn --manual --preferred-challenges dns --server https://acme-v02.api.letsencrypt.org/directory
上面是手动的方式申请，中间需要人工干预，去dns服务商填写text记录。
你还可以使用脚本帮助你完成一些验证，可以使用--manual-auth-hook 和 --manual-cleanup-hook参数，关于钩子的使用：参考地址
正是因为这个钩子，可以编写一个 Shell 脚本，让脚本调用 DNS 服务商的 API 接口，动态添加 TXT 记录，这样就无需人工干预了。
推荐下 ：申请dns证书的脚本
4. 证书管理
4.1 查看已经申请的证书
$ ./certbot-auto certificates
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Found the following certs:
Certificate Name: archerwong.cn-0001
Domains: *.archerwong.cn archerwong.cn
Expiry Date: 2019-03-17 13:24:57+00:00 (VALID: 89 days)
Certificate Path: /etc/letsencrypt/live/archerwong.cn-0001/fullchain.pem
Private Key Path: /etc/letsencrypt/live/archerwong.cn-0001/privkey.pem
Certificate Name: archerwong.cn
Domains: *.archerwong.cn
Expiry Date: 2019-03-17 12:34:52+00:00 (VALID: 89 days)
Certificate Path: /etc/letsencrypt/live/archerwong.cn/fullchain.pem
Private Key Path: /etc/letsencrypt/live/archerwong.cn/privkey.pem
Certificate Name是一个重要标识，可以具体指定哪一个证书，可以配合 run, certonly, certificates, renew，和 delete等命令一起使用，比如：
certbot certonly --cert-name archerwong.cn
4.2 重新创建和更新证书
可以使用certonly或run命令来创建一个新证书，即使已经存在具有该域名的证书，也没有关系，那么certbot会更新该证书，否则会创建一个新证书，一句话存在就更新，不存在就创建
run 和 certonly的区别：
- run 默认的方式，获取，并安装一个证书
- certonly 是创建或者更新一个证书，但是不安装该证书
在recreate证书的时候，可以指定具体行为，可以使用--force-renewal, --duplicate, --expand来限定操作，如果你没有具体指定，certbot可能会问你具体意图。
--force-renewal当请求一个已经存在并有相同域名的证书时，需要把每一个域名通过-d来指定，不管过期与否，强制更新证书。--duplicate告诉certbot不管有没有旧证书，都创建一个独立的新证书--expand告诉certbot更新一个已经存在的证书，需要使用-d参数包含所有旧的域名，并添加新的域名。
expand 举例
可以将域名使用逗号分隔
certbot --expand -d existing.com,example.com,newdomain.com
也可以单独写
certbot --expand -d existing.com -d example.com -d newdomain.com
当我们需要扩展一个证书的时候，上面是通过expand方式，并且是通过-d参数来判定是哪个证书的，但是官方鼓励使用--cert-name来指明是哪个证书，不建议使用expand。
4.3 改变证书的域名
同样可以通过指定--cert-name的方式来更改证书的域名，形式如下
certbot certonly --cert-name example.com -d example.com
certbot certonly --cert-name example.com -d example.org,www.example.org
4.4 撤销证书（revoking certificates）
如果你的证书秘钥已经被泄露，那么可以选择撤销证书，使用revoke命令，注意这里配合使用的参数是证书路径（以cert.pem结尾），不是证书名称或者域名
certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem
同时可以指定原因，可以使用的原因包括 unspecified（默认）， keycompromise, affiliationchanged, superseded, 和 cessationofoperation
certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem --reason keycompromise
如果证书是使用 --staging 或 --test-cert 参数，那么当revoke证书的时候需要带着测试参数 --staging 或 --test-cert
因为证书申请是有数目限制的，所以后面我加上了测试用的参数，可以看下申请出的证书过期时间是和正式证书不同的
$ ./certbot-auto certificates
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Found the following certs:
Certificate Name: archerwong.cn-0001
Domains: *.archerwong.cn archerwong.cn
Expiry Date: 2019-03-17 13:24:57+00:00 (VALID: 89 days)
Certificate Path: /etc/letsencrypt/live/archerwong.cn-0001/fullchain.pem
Private Key Path: /etc/letsencrypt/live/archerwong.cn-0001/privkey.pem
Certificate Name: test.archerwong.cn-0001
Domains: test.archerwong.cn
Expiry Date: 2019-03-18 05:36:23+00:00 (INVALID: TEST_CERT)
Certificate Path: /etc/letsencrypt/live/test.archerwong.cn-0001/fullchain.pem
Private Key Path: /etc/letsencrypt/live/test.archerwong.cn-0001/privkey.pem
Certificate Name: archerwong.cn
Domains: *.archerwong.cn
Expiry Date: 2019-03-17 12:34:52+00:00 (VALID: 89 days)
Certificate Path: /etc/letsencrypt/live/archerwong.cn/fullchain.pem
Private Key Path: /etc/letsencrypt/live/archerwong.cn/privkey.pem
Certificate Name: test.archerwong.cn
Domains: test.archerwong.cn blog.archerwong.cn
Expiry Date: 2019-03-18 05:32:07+00:00 (INVALID: TEST_CERT)
Certificate Path: /etc/letsencrypt/live/test.archerwong.cn/fullchain.pem
Private Key Path: /etc/letsencrypt/live/test.archerwong.cn/privkey.pem
如果申请的时候有测试参数，但是revoke的时候不加，那么就会出现问题
$ ./certbot-auto revoke --cert-path /etc/letsencrypt/live/test.archerwong.cn/cert.pem
Saving debug log to /var/log/letsencrypt/letsencrypt.log
An unexpected error occurred:
The request message was malformed :: No such certificate
Please see the logfiles in /var/log/letsencrypt for more details.
一旦证书被revoke后，可以使用delete命令删除证书。
certbot delete --cert-name example.com
注意：如果你revoke一个证书，那么如果不delete的话，当renew的时候该证书仍然会被更新。
下面演示如何删除一个证书
$ ./certbot-auto revoke --cert-path /etc/letsencrypt/live/test.archerwong.cn-0001/cert.pem --staging --reason keycompromise
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you like to delete the cert(s) you just revoked?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es (recommended)/(N)o: n
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully revoked the certificate that was located
at /etc/letsencrypt/live/test.archerwong.cn-0001/cert.pem
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IMPORTANT NOTES:
- Not deleting revoked certs.
中间会询问你是否删除revoke的证书，为了演示，这里我选择不删除证书。发现状态又变化了，有了revoked标志
$ ./certbot-auto certificates
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Found the following certs:
...
Certificate Name: test.archerwong.cn-0001
Domains: blog.archerwong.cn
Expiry Date: 2019-03-18 05:45:31+00:00 (INVALID: TEST_CERT, REVOKED)
Certificate Path: /etc/letsencrypt/live/test.archerwong.cn-0001/fullchain.pem
Private Key Path: /etc/letsencrypt/live/test.archerwong.cn-0001/privkey.pem
...
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
继续删除证书
$ ./certbot-auto delete --cert-name test.archerwong.cn-0001
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Deleted all files relating to certificate test.archerwong.cn-0001.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
此时证书已经被删除了，查看发现文件夹（test.archerwong.cn-0001）已经被删除
$ tree /etc/letsencrypt/live
/etc/letsencrypt/live
├── archerwong.cn
│ ├── cert.pem -> ../../archive/archerwong.cn/cert1.pem
│ ├── chain.pem -> ../../archive/archerwong.cn/chain1.pem
│ ├── fullchain.pem -> ../../archive/archerwong.cn/fullchain1.pem
│ ├── privkey.pem -> ../../archive/archerwong.cn/privkey1.pem
│ └── README
├── archerwong.cn-0001
│ ├── cert.pem -> ../../archive/archerwong.cn-0001/cert1.pem
│ ├── chain.pem -> ../../archive/archerwong.cn-0001/chain1.pem
│ ├── fullchain.pem -> ../../archive/archerwong.cn-0001/fullchain1.pem
│ ├── privkey.pem -> ../../archive/archerwong.cn-0001/privkey1.pem
│ └── README
├── README
└── test.archerwong.cn
├── cert.pem -> ../../archive/test.archerwong.cn/cert2.pem
├── chain.pem -> ../../archive/test.archerwong.cn/chain2.pem
├── fullchain.pem -> ../../archive/test.archerwong.cn/fullchain2.pem
├── privkey.pem -> ../../archive/test.archerwong.cn/privkey2.pem
└── README
3 directories, 16 files
4.5 更新证书
处于安全等因素的考虑，letsencrypt证书只支持90天的有效期，所以我们需要在临近过期的时间再次更新证书，certbot上可以方便的进行更新操作,使用renew命令
certbot renew
类似于下面的情形，因为我都是新申请的证书，所以没有更新
$ ./certbot-auto renew
Saving debug log to /var/log/letsencrypt/letsencrypt.log
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/letsencrypt/renewal/archerwong.cn-0001.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Cert not yet due for renewal
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/letsencrypt/renewal/archerwong.cn.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Cert not yet due for renewal
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/letsencrypt/renewal/test.archerwong.cn.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Cert not yet due for renewal
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
The following certs are not due for renewal yet:
/etc/letsencrypt/live/archerwong.cn-0001/fullchain.pem expires on 2019-03-17 (skipped)
/etc/letsencrypt/live/archerwong.cn/fullchain.pem expires on 2019-03-17 (skipped)
/etc/letsencrypt/live/test.archerwong.cn/fullchain.pem expires on 2019-03-18 (skipped)
No renewals were attempted.
该命令会尝试更新所有的证书，查找到期天数低于30天的证书，然后更新
，正式因为上面的特性，当没有需要更新的证书的时候，就不会采取任何操作，所以这特别适合自动部署，你可以频繁的进行renew操作，不用担心产生太多副作用。
这里还有个强大的功能就是可以使用钩子，比如你使用的是standalone方式验证证书，同时你又时刻运行着自己的nginx服务器，那么当验证的时候就需要关闭nginx服务，这时候就可以使用钩子来自动化完成这个操作，当有证书需要更新的时候才会触发钩子，不是每运行一次更新操作就运行一次钩子，所以不用太担心会频繁关闭启动nginx服务。
certbot renew --pre-hook "service nginx stop" --post-hook "service nginx start"
--pre-hook 和 --post-hook 钩子运行在尝试更新和更新证书之后，如果你想要只运行在一次成功更新证书之后，那么可以使用--deploy-hook
certbot renew --deploy-hook /path/to/deploy-hook-script
比如，你有一个守护进程需要读取证书内容但是不是使用root用户，下面的脚本可以复制一份证书，并更改证书的权限。
#!/bin/sh
set -e
for domain in $RENEWED_DOMAINS; do
case $domain in
example.com)
daemon_cert_root=/etc/some-daemon/certs
# Make sure the certificate and private key files are
# never world readable, even just for an instant while
# we're copying them into daemon_cert_root.
umask 077
cp "$RENEWED_LINEAGE/fullchain.pem" "$daemon_cert_root/$domain.cert"
cp "$RENEWED_LINEAGE/privkey.pem" "$daemon_cert_root/$domain.key"
# Apply the proper file ownership and permissions for
# the daemon to read its certificate and key.
chown some-daemon "$daemon_cert_root/$domain.cert" \
"$daemon_cert_root/$domain.key"
chmod 400 "$daemon_cert_root/$domain.cert" \
"$daemon_cert_root/$domain.key"
service some-daemon restart >/dev/null
;;
esac
done
你可以直接将钩子文件放到指定目录 /etc/letsencrypt/renewal-hooks/pre, /etc/letsencrypt/renewal-hooks/deploy, /etc/letsencrypt/renewal-hooks/post，那么这三个文件夹里的文件会按照，pre，deply，post类型的钩子运行。同一个文件夹下有多个文件，那么这些文件的运行时按照文件名字母的排序先后运行的。你可以指定不使用这些文件夹下的钩子文件，需要在使用命令的时候添加 --no-directory-hooks 参数
如果在更新证书的过程中不需要人工干预，那么可以将命令添加到crontab，这样定期自动更新证书。
如果你在手动更新证书，并且向忽略过期时间的限制，那么可以使用 --force-renewal 参数，但是这样做要注意，你可能很快就超过官方申请频率的限制。
如果你不想在申请过程中有任何输入，那么可以使用--noninteractive (简写：-n)来表名不想输入，这时客户端会尝试帮你填写需要的选项。
如果快到期的时候你还没有更新证书，那么CA会给你发邮件提醒你，这很人性化啊。。。，所以邮箱还是要认真填写的。
5. 其它问题
野卡证书
默认的，certbot的CA是使用 https://acme-v01.api.letsencrypt.org/，但是如果你想申请通配符证书，那么你需要指定letsencrypt的新的ACMEV2服务，需要加下面的参数--server https://acme-v02.api.letsencrypt.org/directory，这样certbot就可以选择正确的协议帮你申请野卡证书了。
野卡证书支持dns的验证方式，具体如何操作，我会单独写一篇文章。
命令 certbot --help all
可以通过help来查看命令怎么用，这里就贴一下官方的文档，有一篇文章翻译了部分，大家可以看下： Certbot命令行工具使用说明
usage:
certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...
Certbot can obtain and install HTTPS/TLS/SSL certificates. By default,
it will attempt to use a webserver both for obtaining and installing the
certificate. The most common SUBCOMMANDS and flags are:
obtain, install, and renew certificates:
(default) run Obtain & install a certificate in your current webserver
certonly Obtain or renew a certificate, but do not install it
renew Renew all previously obtained certificates that are near expiry
enhance Add security enhancements to your existing configuration
-d DOMAINS Comma-separated list of domains to obtain a certificate for
--apache Use the Apache plugin for authentication & installation
--standalone Run a standalone webserver for authentication
--nginx Use the Nginx plugin for authentication & installation
--webroot Place files in a server's webroot folder for authentication
--manual Obtain certificates interactively, or using shell script hooks
-n Run non-interactively
--test-cert Obtain a test certificate from a staging server
--dry-run Test "renew" or "certonly" without saving any certificates to disk
manage certificates:
certificates Display information about certificates you have from Certbot
revoke Revoke a certificate (supply --cert-path or --cert-name)
delete Delete a certificate
manage your account with Let's Encrypt:
register Create a Let's Encrypt ACME account
--agree-tos Agree to the ACME server's Subscriber Agreement
-m EMAIL Email address for important account notifications
optional arguments:
-h, --help show this help message and exit
-c CONFIG_FILE, --config CONFIG_FILE
path to config file (default: /etc/letsencrypt/cli.ini
and ~/.config/letsencrypt/cli.ini)
-v, --verbose This flag can be used multiple times to incrementally
increase the verbosity of output, e.g. -vvv. (default:
-2)
--max-log-backups MAX_LOG_BACKUPS
Specifies the maximum number of backup logs that
should be kept by Certbot's built in log rotation.
Setting this flag to 0 disables log rotation entirely,
causing Certbot to always append to the same log file.
(default: 1000)
-n, --non-interactive, --noninteractive
Run without ever asking for user input. This may
require additional command line flags; the client will
try to explain which ones are required if it finds one
missing (default: False)
--force-interactive Force Certbot to be interactive even if it detects
it's not being run in a terminal. This flag cannot be
used with the renew subcommand. (default: False)
-d DOMAIN, --domains DOMAIN, --domain DOMAIN
Domain names to apply. For multiple domains you can
use multiple -d flags or enter a comma separated list
of domains as a parameter. The first domain provided
will be the subject CN of the certificate, and all
domains will be Subject Alternative Names on the
certificate. The first domain will also be used in
some software user interfaces and as the file paths
for the certificate and related material unless
otherwise specified or you already have a certificate
with the same name. In the case of a name collision it
will append a number like 0001 to the file path name.
(default: Ask)
--cert-name CERTNAME Certificate name to apply. This name is used by
Certbot for housekeeping and in file paths; it doesn't
affect the content of the certificate itself. To see
certificate names, run 'certbot certificates'. When
creating a new certificate, specifies the new
certificate's name. (default: the first provided
domain or the name of an existing certificate on your
system for the same domains)
--dry-run Perform a test run of the client, obtaining test
(invalid) certificates but not saving them to disk.
This can currently only be used with the 'certonly'
and 'renew' subcommands. Note: Although --dry-run
tries to avoid making any persistent changes on a
system, it is not completely side-effect free: if used
with webserver authenticator plugins like apache and
nginx, it makes and then reverts temporary config
changes in order to obtain test certificates, and
reloads webservers to deploy and then roll back those
changes. It also calls --pre-hook and --post-hook
commands if they are defined because they may be
necessary to accurately simulate renewal. --deploy-
hook commands are not called. (default: False)
--debug-challenges After setting up challenges, wait for user input
before submitting to CA (default: False)
--preferred-challenges PREF_CHALLS
A sorted, comma delimited list of the preferred
challenge to use during authorization with the most
preferred challenge listed first (Eg, "dns" or "tls-
sni-01,http,dns"). Not all plugins support all
challenges. See
https://certbot.eff.org/docs/using.html#plugins for
details. ACME Challenges are versioned, but if you
pick "http" rather than "http-01", Certbot will select
the latest version automatically. (default: [])
--user-agent USER_AGENT
Set a custom user agent string for the client. User
agent strings allow the CA to collect high level
statistics about success rates by OS, plugin and use
case, and to know when to deprecate support for past
Python versions and flags. If you wish to hide this
information from the Let's Encrypt server, set this to
"". (default: CertbotACMEClient/0.28.0
(certbot(-auto); OS_NAME OS_VERSION) Authenticator/XXX
Installer/YYY (SUBCOMMAND; flags: FLAGS)
Py/major.minor.patchlevel). The flags encoded in the
user agent are: --duplicate, --force-renew, --allow-
subset-of-names, -n, and whether any hooks are set.
--user-agent-comment USER_AGENT_COMMENT
Add a comment to the default user agent string. May be
used when repackaging Certbot or calling it from
another tool to allow additional statistical data to
be collected. Ignored if --user-agent is set.
(Example: Foo-Wrapper/1.0) (default: None)
automation:
Flags for automating execution & other tweaks
--keep-until-expiring, --keep, --reinstall
If the requested certificate matches an existing
certificate, always keep the existing one until it is
due for renewal (for the 'run' subcommand this means
reinstall the existing certificate). (default: Ask)
--expand If an existing certificate is a strict subset of the
requested names, always expand and replace it with the
additional names. (default: Ask)
--version show program's version number and exit
--force-renewal, --renew-by-default
If a certificate already exists for the requested
domains, renew it now, regardless of whether it is
near expiry. (Often --keep-until-expiring is more
appropriate). Also implies --expand. (default: False)
--renew-with-new-domains
If a certificate already exists for the requested
certificate name but does not match the requested
domains, renew it now, regardless of whether it is
near expiry. (default: False)
--reuse-key When renewing, use the same private key as the
existing certificate. (default: False)
--allow-subset-of-names
When performing domain validation, do not consider it
a failure if authorizations can not be obtained for a
strict subset of the requested domains. This may be
useful for allowing renewals for multiple domains to
succeed even if some domains no longer point at this
system. This option cannot be used with --csr.
(default: False)
--agree-tos Agree to the ACME Subscriber Agreement (default: Ask)
--duplicate Allow making a certificate lineage that duplicates an
existing one (both can be renewed in parallel)
(default: False)
--os-packages-only (certbot-auto only) install OS package dependencies
and then stop (default: False)
--no-self-upgrade (certbot-auto only) prevent the certbot-auto script
from upgrading itself to newer released versions
(default: Upgrade automatically)
--no-bootstrap (certbot-auto only) prevent the certbot-auto script
from installing OS-level dependencies (default: Prompt
to install OS-wide dependencies, but exit if the user
says 'No')
-q, --quiet Silence all output except errors. Useful for
automation via cron. Implies --non-interactive.
(default: False)
security:
Security parameters & server settings
--rsa-key-size N Size of the RSA key. (default: 2048)
--must-staple Adds the OCSP Must Staple extension to the
certificate. Autoconfigures OCSP Stapling for
supported setups (Apache version >= 2.3.3 ). (default:
False)
--redirect Automatically redirect all HTTP traffic to HTTPS for
the newly authenticated vhost. (default: Ask)
--no-redirect Do not automatically redirect all HTTP traffic to
HTTPS for the newly authenticated vhost. (default:
Ask)
--hsts Add the Strict-Transport-Security header to every HTTP
response. Forcing browser to always use SSL for the
domain. Defends against SSL Stripping. (default: None)
--uir Add the "Content-Security-Policy: upgrade-insecure-
requests" header to every HTTP response. Forcing the
browser to use https:// for every http:// resource.
(default: None)
--staple-ocsp Enables OCSP Stapling. A valid OCSP response is
stapled to the certificate that the server offers
during TLS. (default: None)
--strict-permissions Require that all configuration files are owned by the
current user; only needed if your config is somewhere
unsafe like /tmp/ (default: False)
--auto-hsts Gradually increasing max-age value for HTTP Strict
Transport Security security header (default: False)
testing:
The following flags are meant for testing and integration purposes only.
--test-cert, --staging
Use the staging server to obtain or revoke test
(invalid) certificates; equivalent to --server https
://acme-staging-v02.api.letsencrypt.org/directory
(default: False)
--debug Show tracebacks in case of errors, and allow certbot-
auto execution on experimental platforms (default:
False)
--no-verify-ssl Disable verification of the ACME server's certificate.
(default: False)
--tls-sni-01-port TLS_SNI_01_PORT
Port used during tls-sni-01 challenge. This only
affects the port Certbot listens on. A conforming ACME
server will still attempt to connect on port 443.
(default: 443)
--tls-sni-01-address TLS_SNI_01_ADDRESS
The address the server listens to during tls-sni-01
challenge. (default: )
--http-01-port HTTP01_PORT
Port used in the http-01 challenge. This only affects
the port Certbot listens on. A conforming ACME server
will still attempt to connect on port 80. (default:
80)
--http-01-address HTTP01_ADDRESS
The address the server listens to during http-01
challenge. (default: )
--break-my-certs Be willing to replace or renew valid certificates with
invalid (testing/staging) certificates (default:
False)
paths:
Flags for changing execution paths & servers
--cert-path CERT_PATH
Path to where certificate is saved (with auth --csr),
installed from, or revoked. (default: None)
--key-path KEY_PATH Path to private key for certificate installation or
revocation (if account key is missing) (default: None)
--fullchain-path FULLCHAIN_PATH
Accompanying path to a full certificate chain
(certificate plus chain). (default: None)
--chain-path CHAIN_PATH
Accompanying path to a certificate chain. (default:
None)
--config-dir CONFIG_DIR
Configuration directory. (default: /etc/letsencrypt)
--work-dir WORK_DIR Working directory. (default: /var/lib/letsencrypt)
--logs-dir LOGS_DIR Logs directory. (default: /var/log/letsencrypt)
--server SERVER ACME Directory Resource URI. (default:
https://acme-v02.api.letsencrypt.org/directory)
manage:
Various subcommands and flags are available for managing your
certificates:
certificates List certificates managed by Certbot
delete Clean up all files related to a certificate
renew Renew all certificates (or one specified with --cert-
name)
revoke Revoke a certificate specified with --cert-path or
--cert-name
update_symlinks Recreate symlinks in your /etc/letsencrypt/live/
directory
run:
Options for obtaining & installing certificates
certonly:
Options for modifying how a certificate is obtained
--csr CSR Path to a Certificate Signing Request (CSR) in DER or
PEM format. Currently --csr only works with the
'certonly' subcommand. (default: None)
renew:
The 'renew' subcommand will attempt to renew all certificates (or more
precisely, certificate lineages) you have previously obtained if they are
close to expiry, and print a summary of the results. By default, 'renew'
will reuse the options used to create obtain or most recently successfully
renew each certificate lineage. You can try it with `--dry-run` first. For
more fine-grained control, you can renew individual lineages with the
`certonly` subcommand. Hooks are available to run commands before and
after renewal; see https://certbot.eff.org/docs/using.html#renewal for
more information on these.
--pre-hook PRE_HOOK Command to be run in a shell before obtaining any
certificates. Intended primarily for renewal, where it
can be used to temporarily shut down a webserver that
might conflict with the standalone plugin. This will
only be called if a certificate is actually to be
obtained/renewed. When renewing several certificates
that have identical pre-hooks, only the first will be
executed. (default: None)
--post-hook POST_HOOK
Command to be run in a shell after attempting to
obtain/renew certificates. Can be used to deploy
renewed certificates, or to restart any servers that
were stopped by --pre-hook. This is only run if an
attempt was made to obtain/renew a certificate. If
multiple renewed certificates have identical post-
hooks, only one will be run. (default: None)
--deploy-hook DEPLOY_HOOK
Command to be run in a shell once for each
successfully issued certificate. For this command, the
shell variable $RENEWED_LINEAGE will point to the
config live subdirectory (for example,
"/etc/letsencrypt/live/example.com") containing the
new certificates and keys; the shell variable
$RENEWED_DOMAINS will contain a space-delimited list
of renewed certificate domains (for example,
"example.com www.example.com" (default: None)
--disable-hook-validation
Ordinarily the commands specified for --pre-hook
/--post-hook/--deploy-hook will be checked for
validity, to see if the programs being run are in the
$PATH, so that mistakes can be caught early, even when
the hooks aren't being run just yet. The validation is
rather simplistic and fails if you use more advanced
shell constructs, so you can use this switch to
disable it. (default: False)
--no-directory-hooks Disable running executables found in Certbot's hook
directories during renewal. (default: False)
--disable-renew-updates
Disable automatic updates to your server configuration
that would otherwise be done by the selected installer
plugin, and triggered when the user executes "certbot
renew", regardless of if the certificate is renewed.
This setting does not apply to important TLS
configuration updates. (default: False)
--no-autorenew Disable auto renewal of certificates. (default: True)
certificates:
List certificates managed by Certbot
delete:
Options for deleting a certificate
revoke:
Options for revocation of certificates
--reason {unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation}
Specify reason for revoking certificate. (default:
unspecified)
--delete-after-revoke
Delete certificates after revoking them. (default:
None)
--no-delete-after-revoke
Do not delete certificates after revoking them. This
option should be used with caution because the 'renew'
subcommand will attempt to renew undeleted revoked
certificates. (default: None)
register:
Options for account registration & modification
--register-unsafely-without-email
Specifying this flag enables registering an account
with no email address. This is strongly discouraged,
because in the event of key loss or account compromise
you will irrevocably lose access to your account. You
will also be unable to receive notice about impending
expiration or revocation of your certificates. Updates
to the Subscriber Agreement will still affect you, and
will be effective 14 days after posting an update to
the web site. (default: False)
--update-registration
With the register verb, indicates that details
associated with an existing registration, such as the
e-mail address, should be updated, rather than
registering a new account. (default: False)
-m EMAIL, --email EMAIL
Email used for registration and recovery contact. Use
comma to register multiple emails, ex:
u1@example.com,u2@example.com. (default: Ask).
--eff-email Share your e-mail address with EFF (default: None)
--no-eff-email Don't share your e-mail address with EFF (default:
None)
unregister:
Options for account deactivation.
--account ACCOUNT_ID Account ID to use (default: None)
install:
Options for modifying how a certificate is deployed
config_changes:
Options for controlling which changes are displayed
--num NUM How many past revisions you want to be displayed
(default: None)
rollback:
Options for rolling back server configuration changes
--checkpoints N Revert configuration N number of checkpoints.
(default: 1)
plugins:
Options for for the "plugins" subcommand
--init Initialize plugins. (default: False)
--prepare Initialize and prepare plugins. (default: False)
--authenticators Limit to authenticator plugins only. (default: None)
--installers Limit to installer plugins only. (default: None)
update_symlinks:
Recreates certificate and key symlinks in /etc/letsencrypt/live, if you
changed them by hand or edited a renewal configuration file
enhance:
Helps to harden the TLS configuration by adding security enhancements to
already existing configuration.
plugins:
Plugin Selection: Certbot client supports an extensible plugins
architecture. See 'certbot plugins' for a list of all installed plugins
and their names. You can force a particular plugin by setting options
provided below. Running --help <plugin_name> will list flags specific to
that plugin.
--configurator CONFIGURATOR
Name of the plugin that is both an authenticator and
an installer. Should not be used together with
--authenticator or --installer. (default: Ask)
-a AUTHENTICATOR, --authenticator AUTHENTICATOR
Authenticator plugin name. (default: None)
-i INSTALLER, --installer INSTALLER
Installer plugin name (also used to find domains).
(default: None)
--apache Obtain and install certificates using Apache (default:
False)
--nginx Obtain and install certificates using Nginx (default:
False)
--standalone Obtain certificates using a "standalone" webserver.
(default: False)
--manual Provide laborious manual instructions for obtaining a
certificate (default: False)
--webroot Obtain certificates by placing files in a webroot
directory. (default: False)
--dns-cloudflare Obtain certificates using a DNS TXT record (if you are
using Cloudflare for DNS). (default: False)
--dns-cloudxns Obtain certificates using a DNS TXT record (if you are
using CloudXNS for DNS). (default: False)
--dns-digitalocean Obtain certificates using a DNS TXT record (if you are
using DigitalOcean for DNS). (default: False)
--dns-dnsimple Obtain certificates using a DNS TXT record (if you are
using DNSimple for DNS). (default: False)
--dns-dnsmadeeasy Obtain certificates using a DNS TXT record (if you
areusing DNS Made Easy for DNS). (default: False)
--dns-gehirn Obtain certificates using a DNS TXT record (if you are
using Gehirn Infrastracture Service for DNS).
(default: False)
--dns-google Obtain certificates using a DNS TXT record (if you are
using Google Cloud DNS). (default: False)
--dns-linode Obtain certificates using a DNS TXT record (if you are
using Linode for DNS). (default: False)
--dns-luadns Obtain certificates using a DNS TXT record (if you are
using LuaDNS for DNS). (default: False)
--dns-nsone Obtain certificates using a DNS TXT record (if you are
using NS1 for DNS). (default: False)
--dns-ovh Obtain certificates using a DNS TXT record (if you are
using OVH for DNS). (default: False)
--dns-rfc2136 Obtain certificates using a DNS TXT record (if you are
using BIND for DNS). (default: False)
--dns-route53 Obtain certificates using a DNS TXT record (if you are
using Route53 for DNS). (default: False)
--dns-sakuracloud Obtain certificates using a DNS TXT record (if you are
using Sakura Cloud for DNS). (default: False)
apache:
Apache Web Server plugin - Beta
--apache-enmod APACHE_ENMOD
Path to the Apache 'a2enmod' binary (default: None)
--apache-dismod APACHE_DISMOD
Path to the Apache 'a2dismod' binary (default: None)
--apache-le-vhost-ext APACHE_LE_VHOST_EXT
SSL vhost configuration extension (default: -le-
ssl.conf)
--apache-server-root APACHE_SERVER_ROOT
Apache server root directory (default: /etc/apache2)
--apache-vhost-root APACHE_VHOST_ROOT
Apache server VirtualHost configuration root (default:
None)
--apache-logs-root APACHE_LOGS_ROOT
Apache server logs directory (default:
/var/log/apache2)
--apache-challenge-location APACHE_CHALLENGE_LOCATION
Directory path for challenge configuration (default:
/etc/apache2/other)
--apache-handle-modules APACHE_HANDLE_MODULES
Let installer handle enabling required modules for you
(Only Ubuntu/Debian currently) (default: False)
--apache-handle-sites APACHE_HANDLE_SITES
Let installer handle enabling sites for you (Only
Ubuntu/Debian currently) (default: False)
--apache-ctl APACHE_CTL
Full path to Apache control script (default:
apachectl)
certbot-route53:auth:
Obtain certificates using a DNS TXT record (if you are using AWS Route53
for DNS).
--certbot-route53:auth-propagation-seconds CERTBOT_ROUTE53:AUTH_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 10)
dns-cloudflare:
Obtain certificates using a DNS TXT record (if you are using Cloudflare
for DNS).
--dns-cloudflare-propagation-seconds DNS_CLOUDFLARE_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 10)
--dns-cloudflare-credentials DNS_CLOUDFLARE_CREDENTIALS
Cloudflare credentials INI file. (default: None)
dns-cloudxns:
Obtain certificates using a DNS TXT record (if you are using CloudXNS for
DNS).
--dns-cloudxns-propagation-seconds DNS_CLOUDXNS_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 30)
--dns-cloudxns-credentials DNS_CLOUDXNS_CREDENTIALS
CloudXNS credentials INI file. (default: None)
dns-digitalocean:
Obtain certs using a DNS TXT record (if you are using DigitalOcean for
DNS).
--dns-digitalocean-propagation-seconds DNS_DIGITALOCEAN_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 10)
--dns-digitalocean-credentials DNS_DIGITALOCEAN_CREDENTIALS
DigitalOcean credentials INI file. (default: None)
dns-dnsimple:
Obtain certificates using a DNS TXT record (if you are using DNSimple for
DNS).
--dns-dnsimple-propagation-seconds DNS_DNSIMPLE_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 30)
--dns-dnsimple-credentials DNS_DNSIMPLE_CREDENTIALS
DNSimple credentials INI file. (default: None)
dns-dnsmadeeasy:
Obtain certificates using a DNS TXT record (if you are using DNS Made Easy
for DNS).
--dns-dnsmadeeasy-propagation-seconds DNS_DNSMADEEASY_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 60)
--dns-dnsmadeeasy-credentials DNS_DNSMADEEASY_CREDENTIALS
DNS Made Easy credentials INI file. (default: None)
dns-gehirn:
Obtain certificates using a DNS TXT record (if you are using Gehirn
Infrastracture Service for DNS).
--dns-gehirn-propagation-seconds DNS_GEHIRN_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 30)
--dns-gehirn-credentials DNS_GEHIRN_CREDENTIALS
Gehirn Infrastracture Service credentials file.
(default: None)
dns-google:
Obtain certificates using a DNS TXT record (if you are using Google Cloud
DNS for DNS).
--dns-google-propagation-seconds DNS_GOOGLE_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 60)
--dns-google-credentials DNS_GOOGLE_CREDENTIALS
Path to Google Cloud DNS service account JSON file.
(See https://developers.google.com/identity/protocols/
OAuth2ServiceAccount#creatinganaccount forinformation
about creating a service account and
https://cloud.google.com/dns/access-
control#permissions_and_roles for information about
therequired permissions.) (default: None)
dns-linode:
Obtain certs using a DNS TXT record (if you are using Linode for DNS).
--dns-linode-propagation-seconds DNS_LINODE_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 1200)
--dns-linode-credentials DNS_LINODE_CREDENTIALS
Linode credentials INI file. (default: None)
dns-luadns:
Obtain certificates using a DNS TXT record (if you are using LuaDNS for
DNS).
--dns-luadns-propagation-seconds DNS_LUADNS_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 30)
--dns-luadns-credentials DNS_LUADNS_CREDENTIALS
LuaDNS credentials INI file. (default: None)
dns-nsone:
Obtain certificates using a DNS TXT record (if you are using NS1 for DNS).
--dns-nsone-propagation-seconds DNS_NSONE_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 30)
--dns-nsone-credentials DNS_NSONE_CREDENTIALS
NS1 credentials file. (default: None)
dns-ovh:
Obtain certificates using a DNS TXT record (if you are using OVH for DNS).
--dns-ovh-propagation-seconds DNS_OVH_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 30)
--dns-ovh-credentials DNS_OVH_CREDENTIALS
OVH credentials INI file. (default: None)
dns-rfc2136:
Obtain certificates using a DNS TXT record (if you are using BIND for
DNS).
--dns-rfc2136-propagation-seconds DNS_RFC2136_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 60)
--dns-rfc2136-credentials DNS_RFC2136_CREDENTIALS
RFC 2136 credentials INI file. (default: None)
dns-route53:
Obtain certificates using a DNS TXT record (if you are using AWS Route53
for DNS).
--dns-route53-propagation-seconds DNS_ROUTE53_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 10)
dns-sakuracloud:
Obtain certificates using a DNS TXT record (if you are using Sakura Cloud
for DNS).
--dns-sakuracloud-propagation-seconds DNS_SAKURACLOUD_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate
before asking the ACME server to verify the DNS
record. (default: 90)
--dns-sakuracloud-credentials DNS_SAKURACLOUD_CREDENTIALS
Sakura Cloud credentials file. (default: None)
manual:
Authenticate through manual configuration or custom shell scripts. When
using shell scripts, an authenticator script must be provided. The
environment variables available to this script depend on the type of
challenge. $CERTBOT_DOMAIN will always contain the domain being
authenticated. For HTTP-01 and DNS-01, $CERTBOT_VALIDATION is the
validation string, and $CERTBOT_TOKEN is the filename of the resource
requested when performing an HTTP-01 challenge. When performing a TLS-
SNI-01 challenge, $CERTBOT_SNI_DOMAIN will contain the SNI name for which
the ACME server expects to be presented with the self-signed certificate
located at $CERTBOT_CERT_PATH. The secret key needed to complete the TLS
handshake is located at $CERTBOT_KEY_PATH. An additional cleanup script
can also be provided and can use the additional variable
$CERTBOT_AUTH_OUTPUT which contains the stdout output from the auth
script.
--manual-auth-hook MANUAL_AUTH_HOOK
Path or command to execute for the authentication
script (default: None)
--manual-cleanup-hook MANUAL_CLEANUP_HOOK
Path or command to execute for the cleanup script
(default: None)
--manual-public-ip-logging-ok
Automatically allows public IP logging (default: Ask)
nginx:
Nginx Web Server plugin
--nginx-server-root NGINX_SERVER_ROOT
Nginx server root directory. (default: /etc/nginx or
/usr/local/etc/nginx)
--nginx-ctl NGINX_CTL
Path to the 'nginx' binary, used for 'configtest' and
retrieving nginx version number. (default: nginx)
null:
Null Installer
standalone:
Spin up a temporary webserver
webroot:
Place files in webroot directory
--webroot-path WEBROOT_PATH, -w WEBROOT_PATH
public_html / webroot path. This can be specified
multiple times to handle different domains; each
domain will have the webroot path that preceded it.
For instance: `-w /var/www/example -d example.com -d
www.example.com -w /var/www/thing -d thing.net -d
m.thing.net` (default: Ask)
--webroot-map WEBROOT_MAP
JSON dictionary mapping domains to webroot paths; this
implies -d for each entry. You may need to escape this
from your shell. E.g.: --webroot-map
'{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}'
This option is merged with, but takes precedence over,
-w / -d entries. At present, if you put webroot-map in
a config file, it needs to be on a single line, like:
webroot-map = {"example.com":"/var/www"}. (default:
{})
