ACME#

提供使用 ACME 协议 自动获取证书的功能。

在 从源代码构建 时，默认不会构建此模块； 需要使用 构建选项 --with-http_acme_module 启用它。 在来自 我们的软件仓库 的包和镜像中， 该模块已包含在构建中。

配置示例#

有关配置示例和设置说明，请参阅 ACME配置 部分。

指令#

acme#

语法

acme 名称;

默认值

—

上下文

server

对于所有引用名为 名称 的 ACME 客户端 的 server 块中的 server_name 指令指定的所有域名， 将获得单个证书； 如果 server_name 配置更改， 证书将更新以反映这些更改。

每次 Angie 启动时，都会为所有缺少有效证书的域名请求新证书。 可能的原因包括证书已过期、 文件丢失或不可读、 证书配置发生更改等。

备注

目前，不支持使用正则表达式指定的域名， 这些域名将被忽略。

通配符域名仅在 acme_client 中设置了 challenge=dns 时才受支持。

此指令可以多次指定以加载不同类型的证书，例如 RSA 和 ECDSA：

server {

    listen 443 ssl;
    server_name example.com www.example.com;

    ssl_certificate $acme_cert_rsa;
    ssl_certificate_key $acme_cert_key_rsa;

    ssl_certificate $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;

    acme rsa;
    acme ecdsa;
}

acme_client#

语法

acme_client 名称 uri [enabled=on | off] [key_type=类型] [key_bits=数字] [email=email] [max_cert_size=数字] [renew_before_expiry=时间] [renew_on_load] [retry_after_error=off|时间] [challenge=dns | http] [account_key=文件];

默认值

—

上下文

http

定义一个全局唯一的名为 名称 的 ACME 客户端。 该名称必须对目录有效， 是一个包含变量的字符串， 并且将被视为不区分大小写。

小技巧

此处指定的客户端名称在 Angie 配置中标识该客户端， 允许将 acme_client、acme 指令 和使用此名称的模块 变量 相互关联； 不要将其与您的域名或服务器名称混淆。

第二个必需参数是 ACME 目录的 uri。 例如，Let's Encrypt ACME 目录的 URI 列出 为 https://acme-v02.api.letsencrypt.org/directory。

备注

ACME 模块会在 client 上下文中添加一个名为 location @acme 的位置， 可用于配置对 ACME 目录的请求； 默认情况下，此 location 包含一个带有目录 uri 的 proxy_pass 指令， 可以向其添加来自 Proxy 模块的其他设置。

为了使此指令生效， 必须在相同上下文中配置 resolver。

备注

出于测试目的， 证书颁发机构通常提供单独的测试环境。 例如，Let's Encrypt 的测试环境 为 https://acme-staging-v02.api.letsencrypt.org/directory。

enabled

启用或禁用客户端证书的更新； 例如，在不从配置中删除客户端的情况下临时暂停时，这很有用。

默认值：on。

key_type

证书的私钥算法类型。 有效值：rsa，ecdsa。

默认值：ecdsa。

key_bits

证书密钥的位数。 默认值：ecdsa 为 256，rsa 为 2048。

email

用于反馈的可选电子邮件地址； 在 CA 服务器上创建账户时使用。

max_cert_size

指定新证书文件的最大允许大小（以字节为单位）， 以在共享内存中为新证书保留空间； 请求的域名越多，需要的空间越大。

如果启动时已存在证书但其大小超过 max_cert_size 值， 则 max_cert_size 值会动态增加以匹配现有证书文件的大小。

如果更新过程中获得的证书大小超过 max_cert_size， 则更新过程将失败并报错。

默认值：8192。

renew_before_expiry

证书到期前应开始更新的 时间。

默认值：30d。

renew_on_load

指定在每次加载配置时强制更新证书。

retry_after_error

在证书获取失败时重试前等待的 时间。 如果设置为 off， 客户端不会在失败后重试获取证书。

默认值：2h。

challenge

指定 ACME 客户端的验证类型。 有效值：dns，http。

默认值：http。

account_key

指定包含 PEM 格式密钥的文件的完整路径。 如果您想使用现有账户密钥而不是自动生成一个， 或者需要为多个 ACME 客户端使用同一个密钥，这很有用。

支持的密钥类型：

  • RSA 密钥，长度为 8 的倍数，范围从 2048 到 8192 位。

  • ECDSA 密钥，长度为 256、384 或 521 位。

指定 account_key 参数时， 应确保密钥文件确实存在。 如果文件不存在， Angie 将尝试在指定路径创建它。

请注意，ACME 客户端的密钥是按照它们在配置中 通过 acme_client、acme 或 acme_hook 指令提及的顺序创建的。 因此，如果一个客户端应该使用为另一个客户端创建的密钥， 那么另一个客户端必须在配置中更早出现。

此外，密钥仅为设置了 enabled=on 参数的客户端创建。

acme_client_path#

语法

acme_client_path 路径;

默认值

—

上下文

http

覆盖用于存储证书和密钥的目录的 路径， 该路径在构建时由 构建参数 --http-acme-client-path 设置。

acme_dns_port#

语法

acme_dns_port 端口 | ip[:端口] | [ip6][:端口];

默认值

acme_dns_port 53;

上下文

http

指定模块通过 UDP 处理来自 ACME 服务器的 DNS 查询所使用的端口。 端口号必须在 1 到 65535 之间。

也支持同时指定 IP 地址和可选端口。 可以使用 ip:端口 格式的 IPv4 地址 和 [ip6]:端口 格式的 IPv6 地址：

acme_dns_port 8053;
acme_dns_port 127.0.0.1;
acme_dns_port [::1];

要使用 1024 或更低的端口号， Angie 必须以 超级用户 权限运行。

acme_hook#

语法

acme_hook 名称 [uri];

默认值

—

上下文

location

该指令将服务器与指定的 ACME 客户端关联起来。 通过定义该指令的 location 上下文， 调用由外部服务实现的处理程序（hook）。

名称

指定对应的 ACME 客户端。

uri

包含变量的字符串； 指定调用处理程序的请求字符串。

默认值：/。

例如，以下配置将 hook 变量 的值 通过请求字符串传递给 FastCGI 应用程序：

acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_pass ...;

内置变量#

$acme_cert_<名称>#

由此 名称 的客户端获得的最后一个证书文件（如果有）的内容。

$acme_cert_key_<名称>#

此 名称 的客户端使用的证书密钥文件的内容。

备注

证书文件仅在 ACME 客户端获得至少一个证书后可用， 而密钥文件在启动后立即可用。

$acme_hook_challenge#

验证类型。可能的值：dns，http。

$acme_hook_client#

发起请求的 ACME 客户端的名称。

$acme_hook_domain#

被验证的域名。 如果是通配符域名，将不带 *. 前缀传递。

$acme_hook_keyauth#

授权字符串：

  • 在 DNS 验证中，用作 TXT 记录的值， 记录名称格式为 _acme-challenge. + $acme_hook_domain + .。

  • 在 HTTP 验证中，此字符串应用作 ACME 服务器请求的响应内容。

$acme_hook_name#

钩子名称。对于不同类型的验证，它可能有不同的值和含义：

值

DNS 验证中的含义

HTTP 验证中的含义

add (添加钩子)

需要在 DNS 配置中添加相应的 TXT 记录。

需要准备对相应 HTTP 请求的响应。

remove (移除钩子)

可以从 DNS 配置中删除 TXT 记录。

此 HTTP 请求不再相关； 可以删除先前创建的包含授权字符串的文件。

$acme_hook_token#

验证令牌。 在 HTTP 验证中，用作请求的文件名： /.well-known/acme-challenge/ + $acme_hook_token。