Certbot

来自 ArchWiki

Certbot 是 电子前哨基金会 (Electronic Frontier Foundation) 的 ACME 客户端，它使用 Python 编写，并提供诸如自动 Web 服务器配置和用于 HTTP 质询的内置 Web 服务器等便利功能。Certbot 是 Let's Encrypt 推荐的客户端。

安装

安装 certbot 软件包。

插件可用于自动配置和安装 Web 服务器中颁发的证书

配置

有关证书的创建和使用的更多信息，请参阅 Certbot 文档。

插件

警告： 使用插件时，配置文件可能会被重写，以添加 Certbot 证书的设置和路径。建议先创建 备份。

Nginx

插件 certbot-nginx 为 nginx 提供自动配置。此插件将尝试检测每个域的配置设置。该插件添加了安全建议的额外配置、证书使用设置以及 Certbot 证书的路径。有关示例，请参阅 #管理 Nginx 服务器块。

服务器块 的首次设置

# certbot --nginx

续订证书

# certbot renew

在不修改 nginx 配置文件的情况下更改证书

# certbot --nginx certonly

有关更多信息，请参阅 Arch Linux 上的 Certbot-Nginx，并参阅 #自动续订 以保持已安装证书的有效性。

管理 Nginx 服务器块

以下示例可用于管理 服务器块 文件时的所有服务器块

/etc/nginx/sites-available/example
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2; # Listen on IPv6
  ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ..
}

有关更多信息，请参阅 nginx#TLS。

也可以创建一个单独的配置文件，并将其包含在每个服务器块中

/etc/nginx/conf/001-certbot.conf
ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-nginx.conf;
/etc/nginx/sites-available/example
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2; # Listen on IPv6
  include conf/001-certbot.conf;
  ..
}

Apache

插件 certbot-apache 为 Apache HTTP 服务器 提供自动配置。此插件将尝试检测每个域的配置设置。该插件添加了安全建议的额外配置、证书使用设置以及 Certbot 证书的路径。有关示例，请参阅 #管理 Apache 虚拟主机。

虚拟主机 的首次设置

# certbot --apache

续订证书

# certbot renew

在不修改 Apache 配置文件的情况下更改证书

# certbot --apache certonly

有关更多信息，请参阅 Arch Linux 上的 Certbot-Apache，并参阅 #自动续订 以保持已安装证书的有效性。

管理 Apache 虚拟主机

以下示例可用于管理 虚拟主机 文件时的所有虚拟主机

/etc/httpd/conf/extra/001-certbot.conf
<IfModule mod_ssl.c>
<VirtualHost *:443>

Include /etc/letsencrypt/options-ssl-apache.conf
SSLCertificateFile /etc/letsencrypt/live/'domain'/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/'domain'/privkey.pem

</VirtualHost>
</IfModule>

当 VirtualHost 由 certbot-apache 自动生成时，有时 'Include' 行可能会出现在两个 'SSLCertificate' 行之后。在这种情况下，从浏览器使用 http 访问 VirtualHost 将无法正常工作，并出现 SSL_PROTOCOL_ERROR 错误。如果发生这种情况，只需将 Include 行放在两个 SSLCertificates 行之上并重启 httpd 即可。

/etc/httpd/conf/httpd.conf
  <IfModule mod_ssl.c>
  Listen 443
  </IfModule>

  Include conf/extra/001-certbot.conf
  ..

有关更多信息，请参阅 Apache HTTP 服务器#TLS。

Webroot

注意
  • Webroot 方法需要 端口 80 上的 HTTP 才能让 Certbot 进行验证。
  • 服务器名称必须与其对应的 DNS 相匹配。
  • 可能需要更改主机上的权限，以允许读取访问 http://domain.tld/.well-known。

当使用 webroot 方法时，Certbot 客户端将质询响应放置在 /path/to/domain.tld/html/.well-known/acme-challenge/ 中，该路径用于验证。

建议使用此方法而不是手动安装；它提供自动续订和更轻松的证书管理。但是，由于 #插件 允许自动配置和安装，因此可能更受欢迎。

映射 ACME-challenge 请求

本文或本节的事实准确性存在争议。

原因： 在 webroot 方式中，/var/lib/letsencrypt 路径由 certbot 决定。手动创建是不必要的，这适用于 #手动。（在 Talk:Certbot 中讨论）

通过将所有对 .well-known/acme-challenge 的 HTTP 请求映射到单个文件夹（例如 /var/lib/letsencrypt）可以更轻松地进行管理。

然后，该路径必须对 Cerbot 和 Web 服务器（例如，以用户 http 身份运行的 nginx 或 Apache HTTP 服务器）可写

# mkdir -p /var/lib/letsencrypt/.well-known
# chgrp http /var/lib/letsencrypt
# chmod g+s /var/lib/letsencrypt
nginx

创建一个包含 location 块的文件，并将其包含在服务器块内

/etc/nginx/conf.d/letsencrypt.conf
location ^~ /.well-known/acme-challenge/ {
  allow all;
  root /var/lib/letsencrypt/;
  default_type "text/plain";
  try_files $uri =404;
}

服务器配置示例

/etc/nginx/servers-available/domain.conf
server {
  server_name domain.tld
   ..
  include conf.d/letsencrypt.conf;
}
Apache

创建文件 /etc/httpd/conf/extra/httpd-acme.conf

/etc/httpd/conf/extra/httpd-acme.conf
Alias /.well-known/acme-challenge/ "/var/lib/letsencrypt/.well-known/acme-challenge/"
<Directory "/var/lib/letsencrypt/">
    AllowOverride None
    Options MultiViews SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS
</Directory>

将其包含在 /etc/httpd/conf/httpd.conf 中

/etc/httpd/conf/httpd.conf
Include conf/extra/httpd-acme.conf

获取证书

本文或本节需要扩充。

原因： 缺乏成功完成所教任务的细节（在 Talk:Certbot#accuracy_flag 中讨论）

使用 /var/lib/letsencrypt/ 作为公共可访问路径，为 domain.tld 请求证书

# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld

要添加（子）域，请包含当前设置中使用的所有注册域

# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld,sub.domain.tld

续订（所有）当前证书

# certbot renew
注意： 不要忘记将 Let's Encrypt 配置文件包含在所有相关的服务器块中，包括处理 HTTP 流量的服务器块以及处理 HTTPS 流量的服务器块，尤其是在使用 - 推荐的 - HSTS（HTTP 严格传输安全）时。这可能导致顺利获取证书，并在设置完成后，阻止续订。

另请参阅作为替代方法的 #自动续订。

手动

如果您的 Web 服务器没有插件，请使用以下命令

# certbot certonly --manual

当希望使用 DNS 挑战（TXT 记录）时，请使用

# certbot certonly --manual --preferred-challenges dns

这将自动验证您的域并创建私钥和证书对。它们放置在 /etc/letsencrypt/archive/your.domain/ 中，并从 /etc/letsencrypt/live/your.domain/ 符号链接。

然后，您可以手动配置您的 Web 服务器以引用符号链接目录中的私钥、证书和完整证书链。

注意： 多次运行此命令或续订证书将在 /etc/letsencrypt/archive/your.domain/ 中创建多个带尾号的文件集。Certbot 会自动更新 /etc/letsencrypt/live/your.domain/ 中的符号链接，以指向文件的最新实例，因此无需更新您的 Web 服务器以指向新的密钥材料。

DNS 挑战

对于未暴露于公共互联网的服务器，可以使用 DNS-01 挑战 来验证域所有权

安装 适用于您的 DNS 提供商的 certbot 插件 certbot-dns-*。以下示例展示了使用 certbot-dns-cloudflare 的 cloudflare。

创建凭据文件

/etc/certbot-cloudflare.creds.ini
dns_cloudflare_api_token = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

获取证书。

# chmod 600 /etc/certbot-cloudflare.creds.ini
# certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/certbot-cloudflare.creds.ini -d domain.tld

certbot-renew.service 将使用上述凭据文件 #自动续订 自动续订。有关获取 api 令牌和其他选项，请参阅 docs。

高级配置

自动续订

systemd

certbot 附带一个 systemd certbot-renew.service，它尝试续订在不到 30 天内过期的证书。如果所有证书都未到期续订，则此服务不执行任何操作。

如果您不使用插件来自动管理 Web 服务器配置，则必须手动重新加载 Web 服务器才能在每次续订证书时重新加载证书。这可以通过将 --post-hook "systemctl reload nginx.service" 添加到 ExecStart 命令 [1] 来完成。当然，如果适用，请使用 httpd.service 而不是 nginx.service。可以根据需要将其他服务添加到 systemctl 命令，例如 systemctl reload httpd dovecot postfix。

注意： 在启用 certbot-renew.timer 之前，请检查该服务是否正常工作且未尝试提示任何内容。请注意，该服务可能需要长达 480 秒才能完成，因为自 v0.29.0 以来，在非交互式调用 certbot 时添加了延迟。

启用 并 启动 certbot-renew.timer 以每天两次检查证书续订，包括随机延迟，以便将所有人的续订请求分散到一天中，以减轻 Let's Encrypt 服务器负载 [2]。

通配符证书的自动续订

该过程非常简单。要颁发通配符证书，您必须通过 DNS 质询请求，使用 ACMEv2 协议 来完成。

虽然手动颁发证书很容易，但对于自动化来说并不直接。DNS 质询表示由 certbot 给出的 TXT 记录，必须在域区域文件中手动设置。

您需要在每次续订时更新区域文件。为避免手动执行此操作，您可以使用 RFC 2136，certbot 为此在 certbot-dns-rfc2136 中打包了一个插件。您还需要配置您的 DNS 服务器以允许对 TXT 记录进行动态更新。

为 rfc2136 配置 BIND

生成 TSIG 密钥

$ tsig-keygen -a HMAC-SHA512 example-key

并将其添加到配置文件中

/etc/named.conf
...
zone "domain.ltd" IN {
        ...
        // this is for certbot
        update-policy {
                grant example-key name _acme-challenge.domain.ltd. txt;
        };
        ...
};

key "example-key" {
        algorithm hmac-sha512;
        secret "a_secret_key";
};
...

重启 named.service。

为 rfc2136 配置 certbot

安装 certbot-dns-rfc2136，然后为其创建一个配置文件。

/etc/letsencrypt/rfc2136.ini
dns_rfc2136_server = IP.ADD.RE.SS
dns_rfc2136_name = example-key
dns_rfc2136_secret = INSERT_KEY_WITHOUT_QUOTES
dns_rfc2136_algorithm = HMAC-SHA512

由于该文件包含密钥的副本，请使用 chmod 删除组和其他人的权限来保护它。

测试我们所做的

# certbot certonly --dns-rfc2136 --force-renewal --dns-rfc2136-credentials /etc/letsencrypt/rfc2136.ini --server https://acme-v02.api.letsencrypt.org/directory --email example@domain.ltd --agree-tos --no-eff-email -d 'domain.ltd' -d '*.domain.ltd'

如果您成功通过验证并收到证书，那么您就可以自动化 certbot 了。否则，某些地方出了问题，您需要调试您的设置。从现在开始，基本上可以归结为运行 certbot renew，请参阅 #自动续订。

将证书部署到应用程序

本文或本节的事实准确性存在争议。

原因： 在大多数情况下，只需执行类似 chmod g+r 和 chgrp ssl-cert 的操作而无需脚本就足够了（请参阅 官方文档）。（在 Talk:Certbot 中讨论）

本文或本节需要扩充。

原因： 缺少有关 hook 位置、参数和环境变量的文档参考。（在 Talk:Certbot 中讨论）

certbot 将证书保存在 /etc/letsencrypt/live 下。此目录只能由 root 用户读取。可以使用部署 hook 脚本在续订证书时将证书复制到应用程序目录。

将证书复制到应用程序状态目录并设置正确权限并重启应用程序服务的示例脚本。使用可执行权限创建以下脚本。

/etc/letsencrypt/renewal-hooks/deploy/myapp_cert_copy.sh

#!/bin/sh
set -eu

if [ "$RENEWED_DOMAINS" = "myapp.mydomain.com" ]
then
	app=myapp
	appuser=$app
	certpath="/var/lib/$app/certs"

	mkdir -p "$certpath"
	chmod 750 "$certpath"

	chown $appuser:$appuser "$certpath"
	install -o "$appuser" -g "$appuser" -m 444 "$RENEWED_LINEAGE/fullchain.pem" -t "$certpath"
	install -o "$appuser" -g "$appuser" -m 400 "$RENEWED_LINEAGE/privkey.pem" -t "$certpath"

	systemctl restart $app.service
	echo "$(date) Renewed and deployed certificates for $app" >> /var/log/cert-renew.log
fi

如果已生成证书，则可以使用此命令运行部署脚本以复制证书，而无需重新生成新证书

$ certbot certonly -d myapp.mydomain.com --run-deploy-hooks --dry-run

参见

Retrieved from "https://wiki.archlinux.org.cn/index.php?title=Certbot&oldid=820485"