ACME#

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

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

配置示例#

在此示例中，名为 example 的 ACME 客户端使用默认的 HTTP 验证，为 example.com 和 www.example.com 自动获取并续期证书：

http {

    resolver 127.0.0.53; # 'acme_client' 指令所需

    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#

在 1.9.0 版本发生变更: 仅当在引用 ACME 客户端的 server 块中未找到任何有效（即符合 ACME 规范）的域名时，才会发出 "no valid domain name defined for ACME client" 错误。

语法	`acme` 名称;
默认值	—
上下文	server

指定为此 server 块中的域名获取证书的 ACME 客户端。单个证书覆盖所有引用该名称客户端的 server 块的 server_name 指令指定的所有域名; 如果 server_name 配置更改, 证书将更新以反映这些更改。

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

备注

该指令仅控制证书请求中包含的域名, 并不影响证书可在何处使用。任何 server 块都可以通过 $acme_cert_<name> 变量引用该证书, 无论该块是否包含 acme 指令。从 server 块中移除 acme 仅会将该块的 server_name 值排除在后续的证书请求之外, 但不会阻止该块使用证书。

备注

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

通配符域名仅在 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#

在 1.9.0 版本发生变更.

在 1.11.0 版本发生变更.

语法	`acme_client` 名称 uri [`enabled=on` \| `off`] [`key_type=`类型] [`key_bits=`数字] [`email=`email] [`max_cert_size=`数字] [`max_key_auth_size=`大小] [`renew_before_expiry=`时间] [`renew_on_load`] [`retry_after_error=`off\|时间] [`challenge=dns` \| `http` \| `alpn`] [`account_key=`文件];
默认值	—
上下文	http

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

每个客户端只管理一张证书;如需获取多张独立证书, 请配置多个 acme_client 块（参见为不同域名申请独立证书）。

小技巧

此处指定的客户端名称在 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 指令, 可以向其添加来自代理模块的其他设置。

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

备注

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

`enabled`	启用或禁用客户端证书的更新; 例如,在不从配置中删除客户端的情况下临时暂停时,这很有用。默认值:`on`。
`key_type`	证书的私钥算法类型。有效值:`rsa`,:samp:ecdsa。默认值:`ecdsa`。
`key_bits`	证书密钥的位数。默认值:`ecdsa` 为 256,:samp:rsa 为 2048。
`email`	用于反馈的可选电子邮件地址; 在 CA 服务器上创建账户时使用。
`max_cert_size`	指定新证书文件的最大允许大小(以字节为单位), 以在共享内存中为新证书保留空间; 请求的域名越多,需要的空间越大。此参数不限制 ACME 服务器响应的大小; 请使用 acme_max_response_size 来限制响应大小。如果未设置该参数,Angie 会根据配置的域名列表计算大致大小, 并将其用于共享内存分配。如果启动时已存在证书但其大小超过 `max_cert_size` 值, 则 `max_cert_size` 值会动态增加以匹配现有证书文件的大小。如果更新过程中获得的证书大小超过 `max_cert_size`, 则更新过程将失败并报错。默认值:自动计算。
`max_key_auth_size`	限制 Angie 为 ACME 验证存储在共享内存中的密钥授权字符串的大小。如果 ACME 服务器返回的密钥授权字符串超过此值, 请求将失败并报错,提示增大 `max_key_auth_size`。虽然在 `acme_client` 行中指定, 但这是 `http` 块中所有客户端共享的单一设置。默认值:`2k`。
`renew_before_expiry`	证书到期前应开始更新的时间。默认值:`30d`。
`renew_on_load`	指定在每次加载配置时强制更新证书。
`retry_after_error`	在证书获取失败时重试前等待的时间。如果设置为 `off`, 客户端不会在失败后重试获取证书。默认值:`2h`。
`challenge`	指定 ACME 客户端的验证类型。有效值:`dns`,:samp:http,:samp:alpn。 `alpn` 值启用 TLS-ALPN-01 验证,需要 Angie 使用支持 ALPN 的 OpenSSL 构建 (不支持 BoringSSL 或 AWS-LC 构建)。默认值:`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_max_response_size#

Added in version 1.11.0.

语法	`acme_max_response_size` 大小;
默认值	`acme_max_response_size 32k;`
上下文	http

限制 ACME 服务器响应正文的最大大小。如果响应超过此限制,请求将失败并报错。如果您看到类似 too big subrequest response while sending to client 的错误,请增加该值。

acme_client_path#

语法	`acme_client_path` 路径;
默认值	—
上下文	http

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

acme_dns_port#

在 1.9.1 版本发生变更.

语法	`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_http_port#

Added in version 1.11.0.

在 1.11.1 版本发生变更.

语法	`acme_http_port` 端口 \| ip[:端口] \| [ip6][:端口];
默认值	`acme_http_port 80;`
上下文	http

指定模块用于处理 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_hook#

在 1.9.0 版本发生变更.

语法	`acme_hook` 名称 [uri];
默认值	—
上下文	location

为由名称指定的 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_cert_<名称>`#

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

`$acme_cert_key_<名称>`#

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

备注

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

`$acme_hook_challenge`#

验证类型。可能的值:dns,:samp:http,:samp: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 验证中的含义
`add` (添加钩子)	需要在 DNS 配置中添加相应的 TXT 记录。	需要准备对相应 HTTP 请求的响应。
`remove` (移除钩子)	可以从 DNS 配置中删除 TXT 记录。	此 HTTP 请求不再相关; 可以删除先前创建的包含授权字符串的文件。

`$acme_hook_token`#

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