Apache 模块 mod_md

MDActivationDelay 指令

MDBaseServer 指令

控制是否由 mod_md 管理基础服务器（位于所有 VirtualHosts 之外的服务器）。默认情况下，不会管理。因为这可能会产生令人困惑的副作用。建议您为所有托管域设置虚拟主机，不要依赖全局回退服务器配置。

MDCAChallenges 指令

设置证明域所有权时使用的挑战类型（按优先级排序）。模块支持的挑战方法包括“tls-alpn-01”、“dns-01”和“http-01”。模块将查看服务器的整体配置，以确定可以使用哪些方法。

例如，如果服务器监听端口 80，则可以使用“http-01”方法。使用“dns-01”的先决条件是配置了 MDChallengeDns01 命令。“tls-alpn-01”在上面的“https: 挑战”中进行了描述。

这种自动选择适用于大多数设置。但由于 Apache 是一款功能强大的服务器，具有许多配置选项，因此并非所有可能的情况都清晰明了。例如：它可能监听多个 IP 地址，其中一些地址可以通过 `https:` 访问，而另一些则无法访问。

如果直接配置 MDCAChallenges，则会禁用这种自动选择。相反，模块将在与 ACME 服务器通信时使用配置的挑战列表（挑战类型也必须由服务器提供）。这些挑战将按指定的顺序进行检查。

MDCertificateAgreement 指令

当您使用 mod_md 获取证书时，您将成为 CA（例如 Let's Encrypt）的客户。这意味着您需要阅读并同意他们的服务条款，以便了解他们提供的服务以及他们可能排除或要求您做的事情。mod_md 本身无法同意这样的事情。

MDCertificateAuthority 指令

CA 提供服务的 URL。您可以使用“letsencrypt”或“buypass”代替实际的 URL。

如果配置了多个 URL，则在多次失败后，将以循环方式尝试每个 URL。您可以通过 MDRetryDelay 和 MDRetryFailover 指令配置发生这种情况的速度或延迟。默认设置会在尝试大约半天后进行故障转移。

所有其他设置都适用于这些 URL 中的每一个。因此，例如，不可能有两个具有不同 MDExternalAccountBinding 的 URL。

为了测试，CA 通常会提供第二个服务 URL。“test”服务不会颁发在浏览器中有效的证书，但在速率限制方面更为宽松。这允许您在切换到生产服务 URL 之前验证自己的设置。

MDCertificateAuthority https://acme-staging-v02.api.letsencrypt.org/directory

MDCertificateCheck 指令

MDCertificateFile 指令

这在 MDomainSet 中使用，并指定保存托管域证书链的文件。匹配的密钥通过 MDCertificateKeyFile 指定。

<MDomain mydomain.com>
  MDCertificateFile /etc/ssl/my.cert
  MDCertificateKeyFile /etc/ssl/my.key
</MDomain>

这等效于 mod_ssl SSLCertificateFile 指令。它有几种用途。

例如，如果您想将使用静态文件的现有域迁移到自动化的 Let's Encrypt 证书，您可以定义 MDomainSet，在此添加文件，并从您的 VirtualHosts 中删除 SSLCertificateFile。

这将为您提供与以前相同的配置，但配置文件中可能重复的行更少。然后，您可以向其中添加 MDRenewMode 'always'，模块将在文件中的证书过期之前获取新证书。完成此操作后，您可以删除 MDCertificateFile 并重新加载服务器。

另一个用例是，您可以使用其他 ACME 客户端（例如优秀的 certbot）来更新您的 Let's Encrypt 证书。然后让您的 MD 指向 certbot 的文件，并让两者协同工作。

MDCertificateKeyFile 指令

这在 MDomainSet 中使用，并指定保存托管域私钥的文件。匹配的证书通过 MDCertificateFile 指定。

这等效于 mod_ssl SSLCertificateKeyFile 指令。

MDCertificateMonitor 指令

这是“server-status”HTML 用户界面的一部分，与核心功能本身无关。它定义了该页面上提供的链接，用于轻松检查证书监控器。证书的 SHA256 指纹将附加到配置的 URL。

证书监控器提供对证书透明度 (CT) 日志的监控，以跟踪域的证书使用情况。您至少可以看到 Let's Encrypt（或您配置的任何 CA）已将您的证书输入 CTLogs。

警告：证书日志更新和监控器对这些更新的接收存在一些延迟。这在日志和监控器之间有所不同。新的证书不会立即被识别。

MDCertificateProtocol 指令

指定要使用的协议。目前，仅支持 ACME。

MDCertificateStatus 指令

启用后，托管域中将提供一个资源，位于“https://domain/.httpd/certificate-status”，它将返回一个 JSON 文档，其中列出了当前证书和已更新证书（如果可用）的关键属性。

{
  "valid-until": "Thu, 29 Aug 2019 16:06:35 GMT",
  "valid-from": "Fri, 31 May 2019 16:06:35 GMT",
  "serial": "03039C464D454EDE79FCD2CAE859F668F269",
  "sha256-fingerprint": "1ff3bfd2c7c199489ed04df6e29a9b4ea6c015fe8a1b0ce3deb88afc751e352d"
  "renewal" : { ...renewed cert information... }
}

MDChallengeDns01 指令

定义一个程序，当需要设置/拆卸 `dns-01` 挑战时调用该程序。该程序将获得参数 `setup` 或 `teardown`，后跟域名。对于 `setup`，还会提供挑战内容。当 MDChallengeDns01Version 设置为 2 时，`teardown` 也会获得挑战内容作为参数。

只要“http:”或“https:”挑战方法可用，您就不需要指定此参数。但是，Let's Encrypt 使“dns-01”成为通配符证书的唯一可用挑战。如果您需要其中一个，则需要配置此参数。

现在可以在 MDomain 部分中使用此指令，为该域指定特定命令。这允许配置特定于所涉及的特定 DNS 提供商的脚本。

有关更多详细信息，请参阅上面有关通配符证书的部分。

MDChallengeDns01Version 指令

设置调用 MDChallengeDns01 命令的方式，例如参数的数量和类型。有关差异，请参阅 MDChallengeDns01。此设置是全局的，不能按域进行更改。

MDContactEmail 指令

ACME 协议要求您在注册时提供联系 URL。目前，Let's Encrypt 需要一个电子邮件地址（它将使用该地址通知您有关续订或服务条款更改的信息）。mod_md 在您的 Apache 配置中使用 MDContactEmail 指令中的电子邮件，因此请在此处指定正确的地址。如果不存在 MDContactEmail，mod_md 将使用 ServerAdmin 指令。

MDDriveMode 指令

此指令是为了向后兼容而存在的，是 MDRenewMode 的旧名称。

MDExternalAccountBinding 指令

配置 ACME“外部帐户绑定”的值，这是 ACME 标准的一项功能，允许客户端将注册绑定到 ACME 服务器上的现有客户帐户。

Let's Encrypt 不需要这些值，但其他 ACME CA 需要。如果您需要这些值，请咨询您的 ACME CA，了解如何获取这些值。它们是两个字符串，一个密钥标识符和一个 base64 编码的“hmac”值。

您可以全局配置这些值，也可以为特定 MDomain 配置这些值。由于这些值允许任何人使用同一个帐户进行注册，因此建议您为配置文件授予受限权限，例如仅限 root 用户访问。

值也可以从 JSON 文件中获取，以保持服务器配置的更开放权限，并限制该文件的权限。JSON 本身是

{"kid": "kid-1", "hmac": "zWND..."}

如果更改 EAB 值，则在下次证书续订到期时将使用新值。

MDHttpProxy 指令

使用 http 代理连接到 MDCertificateAuthority。如果您的 Web 服务器只能通过正向代理访问互联网，请定义此项。

MDMatchNames 指令

`all` 模式是所有先前版本的行为。检查 ServerName 和 ServerAlias 以找到与虚拟主机匹配的 MDomain。即使您只将其中一个名称添加到 MDomain，这也将自动检测覆盖范围。

但是，这种自动操作在更复杂的设置中存在缺点。如果将此指令设置为 `servernames`，则仅使用虚拟主机的 ServerName 进行匹配。然后，ServerAlias 将被忽略，用于匹配。别名仍将添加到获得的证书中，除非您还运行 `MDMembers manual`。

`servernames` 的另一个优点是它为您提供了更多关于子域和通配符的灵活性。您可以使用通配符定义一个 MDomain，并为特定子域名称定义其他 MDomain。

MDMember 指令

您可以使用 MDMember 将托管域中的所有 DNS 名称添加到托管域中，而不是在同一行上列出所有 DNS 名称。

<MDomain example.org>
    MDMember www.example.org
    MDMember mail.example.org
</MDomain>

如果您在全局上下文中使用它，而不是在特定 MD 中使用它，则只能指定一个值，'auto' 或 'manual' 作为所有其他 MD 的默认值。有关这些特殊值的描述，请参见 MDomain。

MDMembers 指令

定义是否将虚拟主机的 ServerName 和 ServerAlias 值自动添加到托管域的成员中。

MDMessageCmd 指令

当托管域发生以下事件之一时，将调用此命令："renewed"、"installed"、"expiring"、"errored"。将来可能会为这些事件调用该命令，并忽略它未准备处理的事件。

这是 MDNotifyCmd 的更灵活的伴侣。

MDMessageCmd /etc/apache/md-message

该程序不应阻塞，因为模块将等待它完成。非 0 的返回值被视为错误。

'errored' 不是立即引起关注的原因，因为续订尝试得足够早，以允许互联网恢复。每小时最多报告一次。

'expiring' 应该认真对待。当达到 MDWarnWindow 时，将发出它。默认情况下，这是证书生命周期的 10%，因此对于 Let's Encrypt，目前这意味着在证书过期前 9 天。警告最多每天重复一次。

'renewed' 表示已获得新证书，并存储在 MD 存储区的“暂存”区域中。它将在下次服务器重启/重新加载时激活。

'installed' 在将新证书从暂存区转移到 MD 存储区的域位置时触发。这发生在服务器启动/重新加载时。与所有其他调用不同，MDMessageCmd 以 root 权限（在 *nix 系统上）运行，并可以访问证书文件（和密钥）。可以在此事件上处理其他应用程序或不同格式所需的证书。

'renewing' 事件在开始为托管域续订过程之前触发。如果命令为此返回 != 0，则续订将中止并在下次循环中重复。一些集群设置使用此功能来允许续订仅在单个节点上运行。

'challenge-setup:type:domain' 事件在创建域的挑战数据时触发。在告诉 ACME 服务器检查它之前调用它。类型是 ACME 挑战类型之一。它将为 MDomain 中的每个 DNS 名称调用。集群设置可以使用此事件将挑战文件分发到集群中的所有节点。

ocsp-errored 发生在为域启用 MDStapling 时，这表示在从证书颁发机构检索 OCSP 响应时遇到错误。mod_md 将继续尝试。

MDMustStaple 指令

定义是否应将新请求的证书设置为 OCSP Must Staple 标志。如果证书具有此标志，则服务器需要向每个客户端发送 OCSP 钉扎响应。这仅在您配置 mod_ssl 以生成此响应时有效（请参见 SSLUseStapling 及其朋友）。

MDNotifyCmd 指令

当托管域注册或续订其证书时，将运行配置的可执行文件。它将处理的 MD 的名称作为附加参数（在您在此处指定的参数之后）传递给它。它应该返回状态码 0 以指示它已成功运行。

MDomain 指令

列表中的所有名称都作为单个托管域 (MD) 进行管理。mod_md 将请求一个对所有这些名称有效的单个证书。此指令使用全局设置（请参见下面的其他 MD 指令）。如果您需要一个 MD 的特定设置，请使用 <MDomainSet>。

托管域需要两个附加设置：联系电子邮件地址（通过 MDContactEmail 或 ServerAdmin）和 MDCertificateAgreement。 ServerAdmin 的邮件地址用于在 CA（默认情况下为 Let's Encrypt）注册。CA 可能会使用它来通知您其服务中的更改或证书的状态。

第二个设置 MDCertificateAgreement 应具有值“accepted”。通过指定此值，您确认您接受 CA 的服务条款。

MDContactEmail [email protected]
MDCertificateAgreement accepted
MDomain example.org www.example.org

<VirtualHost *:443>
    ServerName example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName www.example.org
    DocumentRoot htdocs/www

    SSLEngine on
</VirtualHost>

您可以在此指令中使用两个特殊名称：“manual” 和“auto”。这决定了托管域是否应具有与配置的名称列表完全相同（'manual'）或提供更多便利。使用 'auto'，虚拟主机的所有名称都将添加到 MD 中。方便的是，'auto' 也是默认值。

MDomain example.org

<VirtualHost *:443>
    ServerName example.org
    ServerAlias www.example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

MDomain example2.org auto

<VirtualHost *:443>
    ServerName example2.org
    ServerAlias www.example2.org
    ...
</VirtualHost>

在此示例中，域 'www.example.org' 将自动添加到 MD 'example.org' 中。类似地，对于 'example2.org'，其中显式配置了 'auto'。每当您向此虚拟主机添加更多 ServerAlias 名称时，它们也将添加到托管域中。

如果您希望显式声明所有域名称，请使用 'manual' 模式。如果名称与预期名称不匹配，将记录错误。

<MDomainSet> 指令

这是指令 MDomain，它增加了为该 MD 添加设置的可能性。实际上，您也可以使用“<MDomain ..>”作为快捷方式。

这允许您配置使用另一个证书颁发机构的 MD，具有其他续订要求等。

<MDomain sandbox.example.org>
    MDCertificateAuthority   https://someotherca.com/ACME
</MDomain>

一个常见的用例是分别配置域的 https: 要求。

<MDomain example.org>
    MDRequireHttps temporary
</MDomain>

MDPortMap 指令

ACME 协议提供两种通过 HTTP 验证域所有权的方法：一种使用 'http:' url（端口 80），另一种使用 'https:' url（端口 443）。如果您的服务器无法通过至少两种方法中的其中一种访问，则 ACME 可能只能通过配置您的 DNS 服务器来工作，请参见 MDChallengeDns01。

在大多数面向公众的服务器上，'http:' 抵达端口 80，'https:' 抵达端口 443。该模块检查您的 Apache 服务器正在监听的端口，并假设这些端口可用。这意味着当您的服务器没有监听端口 80 时，它会假设来自互联网的 'http:' 请求将无法正常工作。

这是一个很好的猜测，但可能是错误的。例如，您的 Apache 可能会监听端口 80，但您的防火墙可能会阻止它。'http:' 仅在您的内联网中可用。因此，该模块将错误地假设 Let's Encrypt 可以使用您的服务器的 'http:' 挑战。这将失败，因为您的防火墙会丢弃这些挑战。

MDPortMap http:- https:8433

上面的示例显示了如何指定来自互联网的 'http:' 请求永远不会到达。此外，它还表示 'https:' 请求将到达本地端口 8433。

如果您的服务器上启用了端口转发，则您的服务器可能可以通过端口 443 从互联网访问，但 httpd 使用的本地端口是另一个端口。您的服务器可能只监听端口 8443 和 8000，但可以通过端口 443 和 80（从互联网）访问。

MDPrivateKeys 指令

定义为托管域生成哪种私钥以及使用哪些参数。您可以配置多个私钥类型，该模块将为每个密钥获取证书。

例如，您可以配置一个 RSA 密钥和一个椭圆曲线 (EC) 密钥，以便为一个域创建 2 个证书。在客户端连接中，将使用客户端支持的第一个证书。

由于 EC 密钥和证书更小，因此您可能希望首先为所有兼容（现代）客户端提供它们。这可以实现更快的握手。添加 RSA 密钥类型以支持旧版客户端。

MDPrivateKeys secp256r1 rsa3072

支持的 EC 类型取决于您使用的 CA。对于 Let's encrypt，支持的曲线包括 'secp256r1' 和 'secp384r1'。

每个密钥和证书类型都存储在 MD 存储区中的单独文件中。密钥类型是文件名的一部分，对于 RSA 证书，它具有向后兼容的命名方式。因此，您可以继续与其他应用程序共享这些文件。

请注意，此设置仅对新密钥有效。您拥有的任何现有私钥都将保持不变。此外，这仅影响为证书生成的私钥。ACME 帐户密钥不受此影响。

MDRenewMode 指令

在默认的 'auto' 模式下，该模块将对每个托管域执行最合理的动作。对于没有证书的域，它将从证书颁发机构获取证书。

但是，如果您定义了一个未被任何 Apache 虚拟主机使用的 MD，它将不会理会。对于具有静态证书文件的 MD（请参阅 MDCertificateFile），它假设您有自己的来源，也不会续订它们。

您可以通过以下两种方式覆盖此默认设置。如果您指定“always”，模块将续订 MD 的证书，无论域是否正在使用或是否存在静态文件。

相反，配置“manual”，将不会尝试续订。

MDRenewWindow 指令

如果证书的有效期低于持续时间，mod_md 将获取一个新的已签署证书。

通常，证书的有效期约为 90 天，mod_md 将在证书到期前最早 33% 的完整生命周期内续订它们（因此对于 90 天的有效期，在到期前 30 天）。如果您认为这并非您所需，您可以指定确切的时间，如

# 21 days before expiry
MDRenewWindow 21d 
# 30 seconds (might be close)
MDRenewWindow 30s
# 10% of the cert lifetime
MDRenewWindow 10%

在自动驾驶模式下，模块将至少每 12 小时检查一次托管域的状态，以及是否需要执行任何操作。在出现错误时，例如 CA 不可访问时，它将最初在几秒钟后重试。如果继续失败，它将退回到每小时检查一次的最大间隔。

MDRequireHttps 指令

这是一个方便的指令，可以简化托管域的 http: 到 https: 的迁移。使用

MDRequireHttps temporary

您宣布您希望所有通过 http: URL 的流量都重定向到 https: URL，暂时如此。这是安全的，您可以随时将其删除。

以下有影响：如果您希望客户端不再使用 http: URL，请配置

MDRequireHttps permanent

这将执行两项操作

1. 对http: 资源的所有请求都将使用301 状态代码重定向到具有https: 方案的相同 url。这告诉客户端这是永久性的，他们应该相应地更新所有链接。
2. 对https: 请求的所有答案都将携带Strict-Transport-Security 标头，其生命周期为半年。这告诉浏览器它永远（半年）不应在与该域名通信时使用http:。浏览器在看到此信息后，将拒绝联系您的未加密站点。这可以防止恶意中间件降级连接并监听/操纵流量。这是好事。但您不能简单地将其收回。

您可以使用 mod_alias 和一些 Redirect 配置来实现相同的效果，基本上如此。如果您自己动手，请确保将路径 /.well-known/* 从重定向中排除，否则 mod_md 可能会在签署新证书时遇到问题。

如果您在全局范围内设置此项，它将应用于所有托管域。如果您只想将其用于特定域，请使用

<MDomain xxx.yyy>
  MDRequireHttps temporary
</MDomain>

MDRetryDelay 指令

在错误后等待的时间长度，然后再尝试再次续订证书。此持续时间在每次连续错误后加倍，最大为 24 小时。

它针对每个证书续订保持独立。这意味着一个 MDomain 上的错误不会延迟其他域的续订。

MDRetryFailover 指令

续订证书之前连续出现的错误次数，才会选择另一个 CA。这仅适用于具有多个 MDCertificateAuthority 指定的配置。

MDServerStatus 指令

Apache 的“server-status”处理程序允许您配置一个资源来监控正在发生的事情。这现在包括一个部分，列出了所有托管域，以及 DNS 名称、续订状态、生命周期和主要属性。

您可以使用此指令将其关闭。

MDStapleOthers 指令

此设置仅在启用 MDStapling 时生效。它控制 mod_md 是否也应为不受其直接控制的证书提供装订信息，例如通过 ACME CA 续订的证书。

MDStapling 指令

mod_md 提供了一个用于提供 OCSP 装订信息的实现。这是 mod_ssl 提供的实现的替代方案。为了向后兼容，默认情况下禁用此功能。

可以为服务器上的所有证书或单个 MDomain 打开装订。这将替换 mod_ssl 中针对这些主机的任何装订配置。禁用后，mod_ssl 装订将执行工作（当然，如果它本身已启用）。这允许从一个实现逐步过渡到另一个实现。

mod_md 的装订也适用于证书不受此模块管理的域（请参阅 MDStapleOthers，了解如何控制此功能）。这允许使用新的装订，而无需使用任何 ACME 证书管理。

MDStaplingKeepResponse 指令

此时间窗口指定何时应从存储中再次删除装订中使用的 OCSP 响应数据。在服务器重新启动/重新加载时，将删除比 7 天（默认值）旧的响应信息。这可以防止在频繁续订/重新配置证书时存储不断增长。

MDStaplingRenewWindow 指令

如果装订中使用的 OCSP 响应的有效期低于 持续时间，mod_md 将获取一个新的 OCSP 响应。

颁发证书的 CA 通常也运营 OCSP 响应者服务，并确定其关于证书有效性的已签署响应本身的有效期。响应的有效期越长，它就可以缓存的时间越长，这意味着对所有人的整体性能都会更好。生命周期越短，证书撤销传播到客户端的速度就越快。此外，服务可靠性也是一个考虑因素。

通过调整装订续订窗口，您可以自己控制这部分内容。如果您将续订时间缩短（例如，在当前信息到期前不久），您将获得最大的缓存时间。但是，服务中断（例如，停机维护）会影响您。如果您在到期前很长时间续订，更新将更加频繁，导致 CA 服务器基础设施的负载增加，以及服务器子进程之间的协调增加。

默认值为 33%，这意味着当响应生命周期的三分之一剩余时开始续订。对于颁发生命周期为 3 天的 OCSP 响应的 CA，这意味着 2 天的缓存和 1 天的续订尝试。服务中断必须持续整整 24 小时才能影响您的域。

也可以设置绝对续订窗口，例如 `2d`（2 天）。

MDStoreDir 指令

定义在本地文件系统上的哪个位置存储托管域数据。这是一个绝对路径，或者相对于服务器根目录进行解释。默认情况下将在服务器根目录中创建一个名为“md”的目录。

如果您移动此目录并且已经存在数据，请确保首先将数据移动/复制到新位置，然后重新配置并重新启动服务器。如果您先重新配置并重新启动，服务器将尝试获取它认为丢失的新证书。

MDStoreLocks 指令

启用此功能以在服务器启动时使用锁定文件，此时 MDStoreDir 与服务器配置同步，并且续订的证书被激活。

锁定旨在用于在集群中具有共享文件系统用于 MDStoreDir 的设置。它将在集群节点同时重新启动/重新加载时保护续订证书的激活。前提是共享文件系统支持文件锁定。

获取锁的默认持续时间为 5 秒。如果无法获取日志，将记录错误，服务器启动将继续。这可能导致集群节点随后仍然使用之前的证书。

更高的超时将降低这种可能性，但可能会延迟服务器启动/重新加载，以防在底层文件系统中没有正确处理锁定。锁定应该只由 httpd 实例保持很短的时间。

MDWarnWindow 指令

请参阅 MDRenewWindow，了解如何指定时间的说明。

模块检查证书的剩余生命周期，并在剩余时间少于警告窗口时调用 MDMessageCmd。使用默认设置，这意味着对于 Let's Encrypt 的证书来说是 9 天。

它也适用于具有静态证书文件的托管域（请参阅 MDCertificateFile）。