ACME#
提供使用 ACME 协议 自动获取证书的功能。
当 从源代码构建 时，该模块默认不会被构建；必须通过
构建选项 --with-http_acme_module 启用它。
在来自 我们的软件仓库 的包和镜像中，该模块已包含在 构建中。
配置示例#
在此示例中，名为 example 的 ACME 客户端使用默认的 HTTP 验证，为 example.com 和 www.example.com 自动获取并续期证书：
http {
acme_client example https://acme-v02.api.letsencrypt.org/directory;
server {
listen 80; # 如果没有服务器监听 HTTP 挑战端口,则可选
# (参见 'acme_http_port' 指令)
listen 443 ssl;
server_name example.com www.example.com;
acme example;
ssl_certificate $acme_cert_example;
ssl_certificate_key $acme_cert_key_example;
}
}
其他验证方法（DNS、ALPN、基于钩子）以及详细的设置说明，请参阅 ACME 配置 部分。
指令#
acme#
指定为此 server 块中的有效证书标识符获取证书的 ACME 客户端。
单个证书覆盖所有引用该 名称 客户端的 server 块的 server_name 指令指定的所有有效域名和 IP 地址;
如果 server_name 配置更改,
证书将更新以反映这些更改。
每次 Angie 启动或重新加载配置时,都会为所有缺少有效证书的标识符请求新证书。 可能的原因包括证书已过期、 文件丢失或不可读、 证书配置发生更改, 或先前的请求以错误结束。
备注
该指令仅控制证书请求中包含哪些有效证书标识符,
并不影响证书可在何处使用。
任何 server 块都可以通过
$acme_cert_<name> 变量
引用该证书,
无论该块是否包含 acme 指令。
从 server 块中移除 acme
仅会将该块的 server_name 值
排除在后续的证书请求之外,
但不会阻止该块使用证书。
备注
目前,不支持使用正则表达式指定的域名, 这些域名将被忽略。
通配符域名仅在 acme_client 中设置了 challenge=dns 时才受支持。
除非客户端使用 challenge=dns,否则支持 IPv4 和 IPv6 地址。
启用 DNS 验证后,IP 地址将被跳过。
此指令可以多次指定以加载不同类型的证书,例如 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#
| |
默认值 | — |
http |
定义一个全局唯一的名为 名称 的 ACME 客户端。 该名称必须对目录有效, 是一个包含变量的字符串, 并且将被视为不区分大小写。
每个客户端只管理一张证书;如需获取多张独立证书,
请配置多个 acme_client 块
（参见 为不同域名申请独立证书）。
第二个必需参数是 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 解析目录主机名,
该解析器默认查询 /etc/resolv.conf 中列出的 DNS 服务器。
备注
出于测试目的, 证书颁发机构通常提供单独的测试环境。 例如, Let's Encrypt 的测试环境 为 https://acme-staging-v02.api.letsencrypt.org/directory。
| 启用或禁用客户端证书的更新; 例如,在不从配置中删除客户端的情况下临时暂停时,这很有用。 默认值： |
| 证书的私钥算法类型。
有效值： 默认值： |
| 证书密钥的位数。
默认值： |
| 用于反馈的可选电子邮件地址; 在 CA 服务器上创建账户时使用。 |
| 指定新证书文件的最大允许大小,
以在共享内存中为新证书保留空间;
请求的域名越多,需要的空间越大。
该大小以字节为单位指定;
如果未设置该参数,Angie 会根据配置的域名列表计算大致大小, 并将其用于共享内存分配。 如果启动时已存在证书但其大小超过 如果更新过程中获得的证书大小超过 默认值:自动计算。 |
| 限制 Angie 为 ACME 验证存储在共享内存中的密钥授权字符串的大小。
如果 ACME 服务器返回的密钥授权字符串超过此值,
请求将失败并报错,提示增大 虽然在 默认值： |
| 证书到期前应开始更新的 时间。 默认值： |
| 指定在每次加载配置时强制更新证书。 |
| 在证书获取失败时重试前等待的 时间。
如果设置为 默认值： 此延迟在 Angie 运行期间生效; 重新加载配置会立即重新请求证书。 |
| 指定 ACME 客户端的验证类型。
有效值：
默认值： |
| 向证书颁发机构请求特定的 ACME 配置档案(profile)。 配置档案是 CA 定义的证书和验证设置的变体, 例如证书的有效期, 或可请求的标识符类型。 例如,Let's Encrypt 在其 配置档案文档 中介绍了可用的配置档案。 ACME 服务器必须在其目录元数据中公布此配置档案, 否则客户端将无法获取证书。 |
| 指定包含 PEM 格式密钥的文件的完整路径。 如果您想使用现有账户密钥而不是自动生成一个, 或者需要为多个 ACME 客户端使用同一个密钥,这很有用。 支持的密钥类型:
指定 请注意,ACME 客户端的密钥是按照它们在配置中 通过 acme_client、acme 或 acme_hook 指令提及的顺序创建的。 因此,如果一个客户端应该使用为另一个客户端创建的密钥, 那么另一个客户端必须在配置中更早出现。 此外,密钥仅为设置了 |
| 配置 外部账户绑定 (EAB), 将 ACME 账户绑定到已在证书颁发机构(CA)注册的账户。 其值的形式为
如果 CA 要求外部账户绑定但未设置该参数, 客户端将报错且不会创建 ACME 账户。 EAB 凭据仅在注册新的 ACME 账户时发送; 现有的 ACME 账户将按原样重用。 |
acme_client_path#
覆盖用于存储证书和密钥的目录的 路径,
该路径在构建时由 构建参数 --http-acme-client-path 设置。
acme_dns_port#
指定模块通过 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_dns_ttl#
Added in version 1.12.0.
设置模块在响应 ACME 服务器的 DNS 验证 查询时返回的 TXT 记录的 TTL(以秒为单位)。 根据 RFC 2181 的规定,取值范围为 0 到 2147483647。
如果验证始终无法完成,请调高该值:部分 DNS 提供商会过滤掉 TTL 低至默认值的响应。
acme_hook#
为由 名称 指定的 ACME 客户端
启用基于钩子的域名验证。
当证书签发或续订需要进行域名验证时,
Angie 会向放置该指令的命名 location
生成一个内部请求。
请求的处理方式完全取决于同一 location
中配置的其他指令,
例如 fastcgi_pass、proxy_pass,
或任何其他请求处理程序。
名称 | 由该钩子处理域名验证的 ACME 客户端 的名称。 |
uri | 包含变量的字符串; 指定钩子调用的请求 URI。 默认值： |
例如,以下配置将 hook 变量 的值 通过请求 URI 传递给 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_http_port#
Added in version 1.11.0.
指定模块用于处理 HTTP ACME 验证请求的端口。 端口号必须在 1 到 65535 之间。
也支持同时指定 IP 地址和可选端口。
可以使用 ip:端口 格式的 IPv4 地址
和 [ip6]:端口 格式的 IPv6 地址:
acme_http_port 8080;
acme_http_port 127.0.0.1;
acme_http_port [::1];
如果没有服务器配置为监听指定的地址和端口, 模块会为 HTTP 验证创建专用监听器。
要使用 1024 或更低的端口号, Angie 的主进程必须以超级用户权限运行。
acme_max_response_size#
Added in version 1.11.0.
限制 ACME 服务器响应正文的最大大小。如果响应超过此限制,请求将失败并报错。
如果您看到类似 too big subrequest response while sending to client 的错误,请增加该值。
内置变量#
$acme_cert_<名称>#
由此 名称 的客户端获得的最后一个证书文件(如果有)的内容。
$acme_cert_key_<名称>#
此 名称 的客户端使用的证书密钥文件的内容。
备注
证书文件仅在 ACME 客户端获得至少一个证书后可用, 而密钥文件在启动后立即可用。
$acme_hook_challenge#
验证类型。可能的值：dns, http, alpn。
$acme_hook_client#
发起请求的 ACME 客户端的名称。
$acme_hook_domain#
被验证的域名。
如果是通配符域名,将不带 *. 前缀传递。
$acme_hook_keyauth#
授权字符串:
在 DNS 验证中,用作 TXT 记录的值, 记录名称格式为
_acme-challenge. + $acme_hook_domain + .。在 HTTP 验证中,此字符串应用作 ACME 服务器请求的响应内容。
$acme_hook_name#
钩子名称。对于不同类型的验证,它可能有不同的值和含义:
值 | DNS 验证中的含义 | HTTP 验证中的含义 |
| 需要在 DNS 配置中添加相应的 TXT 记录。 | 需要准备对相应 HTTP 请求的响应。 |
| 可以从 DNS 配置中删除 TXT 记录。 | 此 HTTP 请求不再相关; 可以删除先前创建的包含授权字符串的文件。 |
$acme_hook_token#
验证令牌。
在 HTTP 验证中,用作请求的文件名:
/.well-known/acme-challenge/ + $acme_hook_token。
目录