Certbot

Certbot 是电子前沿基金会的 ACME 客户端，它用 Python 编写，并提供了自动 Web 服务器配置和用于 HTTP 挑战的内置 Web 服务器等便利功能。Certbot 被 Let's Encrypt 推荐。

安装

安装 certbot 软件包。

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

可以使用 certbot-nginx 软件包安装 Nginx 插件。
可以使用 certbot-apache 软件包安装 Apache HTTP Server 插件。

配置

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

插件

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

Nginx

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

首次设置服务器块

# certbot --nginx

续订证书

# certbot renew

更改证书而不修改 nginx 配置文件

# certbot --nginx certonly

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

管理 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 Server 提供了自动配置。此插件将尝试检测每个域的配置设置。该插件添加了额外的建议设置，用于安全、证书使用以及 Certbot 证书的路径。有关示例，请参阅 #管理 Apache 虚拟主机。

首次设置虚拟主机

# certbot --apache

续订证书

# certbot renew

更改证书而不修改 Apache 配置文件

# certbot --apache certonly

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

管理 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 Server#TLS。

PKCS#12

插件 python-certbot-pkcs12^AUR 提供了使用 PKCS#12 证书存档的自动安装，这主要由 Kestrel 使用。

以下命令仅将 PKCS#12 存档安装到您的目标位置

# certbot install -i pkcs12 --pkcs12-location /etc/locationToPlaceFile.pfx

与其他命令集成

# certbot some_options --installer pkcs12 --pkcs12-location /path/to/your/pkcs12.p12

这通过将选项写入 certbot 配置来集成安装程序选项与您之前的操作，并在续订时自动应用。

# certbot renew

Webroot

注

Webroot 方法需要 Certbot 能够通过端口 80 上的 HTTP 进行验证。
服务器名称必须与其对应的 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 中讨论）

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

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

# 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 中讨论）

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

# 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 令牌和其他选项的详细信息，请参阅文档。

高级配置

自动续订

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 之前，请检查服务是否正常工作并且没有尝试提示任何内容。请注意，由于自 v0.29.0 起增加了调用 certbot 非交互式命令的延迟，因此该服务可能需要长达 480 秒才能完成。

启用并启动 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 中讨论）

本文章或章节需要扩充。

原因：缺少关于钩子位置、参数和环境变量的文档引用。（在 Talk:Certbot 中讨论）

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

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

/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

参见