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

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

需求

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

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

角色变量

变量 certbot_install_from_source 控制是否从 Git 或软件包管理系统安装 Certbot。后者是默认设置，因此该变量默认为 no。

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 --no-self-upgrade"

默认情况下，此角色配置一个 cron 任务，在指定的用户账户下每天在指定的小时和分钟运行。默认设置是由您在 Ansible playbook 中使用的用户在每天 03:30:00 运行 certbot renew（或 certbot-auto renew）。建议您设置自定义用户/小时/分钟，以便在低流量时段进行续期，并由非 root 用户账户完成。

自动证书生成

目前，通过此角色生成新证书的内置方法为：standalone。未来可能会添加其他方法（例如使用 nginx 或 apache 和网页根目录）。

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

certbot_create_if_missing: false
certbot_create_method: standalone

将 certbot_create_if_missing 设置为 yes 或 True 以允许此角色生成证书。使用 certbot_create_method 变量设置生成证书的方法——当前允许的值包括：standalone。

certbot_admin_email: email@example.com

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

certbot_certs: []
  # - email: [email protected]
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

需要生成证书的域名（以及其他数据）列表。您可以在任何列表项中添加一个 email 键来覆盖 certbot_admin_email。

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 定义用于生成证书的命令。

独立证书生成

certbot_create_standalone_stop_services:
  - nginx

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

这些服务仅在生成新证书的第一次时停止。

从 Git 源代码安装

如果需要，您可以从 Git 源代码库安装 Certbot。这可能在多种情况下很有用，特别是在旧版本的发行版没有可用的 Certbot 软件包时（例如，CentOS < 7、Ubuntu < 16.10 和 Debian < 8）。

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

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

certbot_dir: /opt/certbot

Certbot 将要克隆的目录。

通配符证书

Let's Encrypt 支持 生成通配符证书，但生成和使用它们的过程稍微复杂一些。请参阅 这个拉取请求 中的评论，了解如何使用此角色维护通配符证书的示例。

Michael Porter 还提供了一个关于 使用 Ansible 创建 Let's Encrypt 通配符证书 的详细步骤，特别是在与 Cloudflare 一起使用时。

依赖关系

无。

示例 Playbook

- 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）。以下是一些配置证书的示例命令：

# 自动为所有 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 刚为您传入的 certbot 命令生成的新证书（fullchain.pem）和私钥（privkey.pem）。
6. 重新加载或重启您的 Web 服务器，以使其使用新的 HTTPS 虚拟主机配置。

Certbot 证书自动续期

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

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

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

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

许可证

MIT / BSD

作者信息

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