Ansible 角色: Certbot（用于 Let's Encrypt）

安装和配置 Certbot（用于 Let's Encrypt）。

需求

如果从源代码安装，需要 Git。您可以使用 geerlingguy.git 角色来安装 Git。

通常，从源代码安装（请参阅“从 Git 源代码安装”部分）可以更好地使用 Certbot 和 Let's Encrypt，尤其是在使用较旧的操作系统时。

角色变量

certbot_install_method: package

控制 Certbot 的安装方式。可用的选项有 'package'、'snap' 和 'source'。

certbot_auto_renew: true
certbot_auto_renew_user: "{{ ansible_user | default(lookup('env', 'USER')) }}"
certbot_auto_renew_hour: "3"
certbot_auto_renew_minute: "30"
certbot_auto_renew_options: "--quiet"

默认情况下，此角色配置了一个定时作业，每天在指定的小时和分钟下由提供的用户帐户运行。默认每天在 03:30:00 运行 certbot renew（或 certbot-auto renew）。最好设置一个自定义用户/小时/分钟，以便在流量较低的时段进行续订，并由非 root 用户帐户执行。

自动证书生成

目前支持使用此角色生成新证书的 standalone 和 webroot 方法。

完整示例：请参见 molecule/default/playbook-standalone-nginx-aws.yml 中的完整功能测试剧本。

certbot_create_if_missing: false

将 certbot_create_if_missing 设置为 yes 或 True 以允许此角色生成证书。

certbot_create_method: standalone

使用 certbot_create_method 变量设置生成证书的方法——当前允许的值为 standalone 或 webroot。

certbot_testmode: false

启用测试模式，仅执行测试请求而不实际创建证书。

certbot_hsts: false

在证书生成时启用（HTTP 严格传输安全）设置。

certbot_admin_email: email@example.com

用于同意 Let's Encrypt 的服务条款，并订阅证书相关通知的电子邮件地址。此项应自定义并设置为您或您的组织定期监控的电子邮件地址。

certbot_certs: []
  # - email: [email protected]
  #   webroot: "/var/www/html"
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

应生成证书的域名（和其他数据）列表。您可以在任何列表项中添加 email 键来覆盖 certbot_admin_email。使用 webroot 创建方法时，必须提供 webroot 项，以指定用于身份验证的目录。确保您的 Web 服务器能够正确提供来自该目录的内容。

certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"

certbot_create_command 定义用于生成证书的命令。请查看 defaults/main.yml 中的完整默认命令以获取完整示例，如有需要，您可以使用 certbot_create_extra_args 变量轻松添加默认命令中没有的额外参数。

独立证书生成

certbot_create_standalone_stop_services:
  - nginx

在 certbot 运行其独立服务器（使用 80 和 443 端口）时，应停止的服务。如果您正在运行 Apache，将此项设置为 apache2（Ubuntu），或 httpd（RHEL），或者如果您在 443 端口上运行 Nginx，并且在 80 端口上有其他服务（例如 Varnish、Java 应用程序或其他），请将其添加到列表中，以便在生成证书时被停止。

这些服务只会在首次生成新证书时停止。

Snap 安装

自 2020 年 12 月起，Certbot 维护者决定推荐通过 Snap 安装 Certbot，而不是维护像 certbot-auto 这样的脚本。

设置 certbot_install_method: snap 可配置此角色通过 Snap 安装 Certbot。

此安装方法当前是实验性的，可能在所有 Linux 发行版上都不适用。

Webroot 证书生成

在使用 webroot 创建方法时，必须为每个 certbot_certs 项提供一个 webroot 项，指定用于身份验证的目录。同时，确保您的 Web 服务器能够正确提供该目录的内容。

从 Git 源代码安装

如果需要，您可以使用 certbot_install_method: source 从 Git 源代码库安装 Certbot。这在某些情况下可能有用，特别是当旧发行版没有可用的 Certbot 包时（例如 CentOS < 7、Ubuntu < 16.10 和 Debian < 8）。

certbot_repo: https://github.com/certbot/certbot.git
certbot_version: master
certbot_keep_updated: true

Certbot Git 存储库选项。如果从源代码安装，配置的 certbot_repo 将被克隆，并遵循 certbot_version 设置。如果 certbot_keep_updated 设置为 yes，则每次运行此角色时都会更新存储库。

certbot_dir: /opt/certbot

Certbot 将被克隆到的目录。

通配符证书

Let's Encrypt 支持 生成通配符证书，但生成和使用它们的过程略微复杂。请查看 此拉取请求 中的评论，了解如何使用此角色维护通配符证书。

Michael Porter 也有一篇关于 使用 Ansible 创建 Let's Encrypt 通配符证书 的详细步骤，特别是与 Cloudflare 配合使用。

依赖关系

无。

示例剧本

- hosts: servers

  vars:
    certbot_auto_renew_user: your_username_here
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

请参见 tests/ 目录中的其他示例。

使用 certbot 手动创建证书

注意：您可以让此角色自动生成证书；请参阅上面的“自动证书生成”文档。

您可以使用 certbot（或 certbot-auto）脚本手动创建证书（在 Ubuntu 16.04 上使用 letsencrypt，或者如果从源代码/Git 安装，则使用 /opt/certbot/certbot-auto）。以下是一些使用 Certbot 配置证书的示例命令：

# 自动为所有 Apache 虚拟主机添加证书（请小心使用！）。
certbot --apache

# 生成证书，但不修改 Apache 配置（更安全）。
certbot --apache certonly

如果您希望完全自动化添加新证书的过程，但不想使用此角色的内置功能，您可以使用命令行选项进行注册、接受条款，然后使用独立服务器生成证书：

1. 确保监听 80 和 443 端口的服务（Apache、Nginx、Varnish 等）已停止。
2. 注册，如 certbot register --agree-tos --email [[email protected]]
   • 注意：在未来在同一服务器上生成其他证书时，您无需执行此步骤。
3. 为 DNS 指向此服务器的域生成证书：certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. 重新启动之前在 80 和 443 端口上监听的服务。
5. 更新您的 Web 服务器虚拟主机 TLS 配置，以指向 certbot 刚为您传入的域生成的新证书（fullchain.pem）和私钥（privkey.pem）。
6. 重新加载或重启您的 Web 服务器，以使其使用新生成的 HTTPS 虚拟主机配置。

Certbot 证书自动续订

默认情况下，此角色添加了一个定时作业，每天在您选择的小时和分钟内续订所有已安装的证书。

您可以使用以下命令测试自动续订（而不实际续订证书）：

/opt/certbot/certbot-auto renew --dry-run

请参见 Certbot 网站 上的完整文档和选项。

许可证

MIT / BSD

作者信息

此角色由 Jeff Geerling 于 2016 年创建，他是 Ansible for DevOps 的作者。