Apache模块mod_md

MDActivationDelay 指令

MDBaseServer 指令

控制基本服务器（所有VirtualHost外部的服务器）是否应由mod_md管理。默认情况下不会。由于它可能具有令人困惑的副作用的原因。建议您为所有托管域拥有虚拟主机，并且不要依赖于全局的回退服务器配置。

MDCAC挑战 指令

在证明域所有权时设置挑战类型（按优先顺序）。该模块支持挑战方法“ tls-alpn-01”，“ dns-01”和“ http-01”。该模块将查看服务器的整体配置，以找出可以使用的方法。

例如，如果服务器在端口80上侦听，则'http-01'方法可用。“ dns-01”的前提条件是已配置的 MDChallengeDns01命令。上面的“ https：挑战”中介绍了“ tls-alpn-01”。

此自动选择适用于大多数设置。但是，由于Apache是​​具有许多配置选项的功能非常强大的服务器，因此并非在所有可能的情况下情况都如此。例如：它可以侦听多个IP地址，其中某些IP地址可以在“ https：”上访问，而有些IP地址则无法访问。

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

MDCertificateAgreement 指令

当您使用mod_md获得证书时，您将成为CA的客户（例如，让我们加密）。这意味着您需要阅读并同意他们的服务条款，以便了解他们提供的服务以及他们可能从您的服务中排除或要求的内容。mod_md本身不能同意这样的事情。

MDCertificateAuthority 指令

CA提供服务的URL。

现在让我们加密提供四个此类URL。两个用于ACME协议自己的旧版，通常称为ACMEv1。还有两个用于RFC 8555版本的名称为ACMEv2。

每个版本都有2个端点，因为它们是生产端点和用于测试的“临时”端点。测试端点的工作原理相同，但不会提供浏览器可以识别的证书。但是，它也有非常宽松的速率限制。这样就可以重复测试服务，而不会阻塞自己。

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

MDCertificateCheck 指令

MDCertificateFile 指令

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

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

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

如果要使用静态文件将现有域迁移到一个自动的“我们加密”证书中。您定义 MDomainSet，在此处添加文件，然后SSLCertificateFile从VirtualHosts中删除。

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

另一个用例是您与其他ACME客户端（例如优秀的certbot）续订“加密加密”证书 。然后，让您的MD指向certbot中的文件，并使它们一起工作。

MDCertificateKeyFile 指令

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

这等效于mod_ssl SSLCertificateKeyFile指令。

MDCertificateMonitor 指令

这是“服务器状态” 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”，后跟域名。对于“设置”，还提供了挑战内容。

只要可以使用'http：'或'https：'质询方法，就无需指定此选项。但是，“让我们加密”使“ dns-01”成为通配符证书可用的唯一挑战。如果需要其中之一，则需要进行配置。

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

MDContactEmail 指令

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

MDDriveMode 指令

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

MDHttpProxy 指令

使用http代理连接到MDCertificateAuthority。如果您的网络服务器只能通过转发代理访问Internet，请定义此选项。

MDMember 指令

您可以使用MDMember将这样的名称添加到托管域中来代替在同一行上列出所有DNS名称 。

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

如果在特定MD之外的全局上下文中使用它，则只能将一个值“ auto”或“ manual”指定为所有其他MD的默认值。有关MDomain这些特殊值的说明，请参见 。

MDMembers 指令

定义是否将VirtualHost 的ServerName和 ServerAlias值自动添加到托管域的成员。

MDMessageCmd 指令

当受管域发生以下事件之一时，将调用此命令：“更新”，“安装”，“到期”，“错误”。将来可能会调用更多命令，并忽略不准备处理的事件。

这是的更灵活的伴侣MDNotifyCmd。

MDMessageCmd /etc/apache/md-message

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

“错误”并不是引起关注的直接原因，因为更新已尽早尝试以使互联网恢复正常。每小时最多报告一次。

“到期”应当真。MDWarnWindow到达时发出 。默认情况下，这是证书寿命的10％，因此，对于“让我们加密”来说，当前意味着证书到期前9天。该警告每天最多重复一次。

“更新”表示已获取新证书，并将其存储在MD存储区的“登台”区域中。它将在下次服务器重新启动/重新加载时被激活。

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

MDMustStaple 指令

定义新请求的证书是否应设置“ OCSP必须装订”标志。如果证书具有此标志，则要求服务器向每个客户端发送OCSP装订响应。仅当您配置mod_ssl为生成此代码时，此方法才有效 （请参阅SSLUseStapling 和朋友）。

MDNotifyCmd 指令

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

MDomain 指令

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

受管域还需要进行2个其他设置：联系人电子邮件地址（通过MDContactEmail或ServerAdmin）和MDCertificateAgreement。的邮件地址ServerAdmin 用于在CA进行注册（默认情况下为“让我们加密”）。CA可能会使用它来通知您有关其服务或证书状态的更改。

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

MDContactEmail admin@example.org
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”。这决定了受管域是否应具有已配置（“手动”）的名称列表，还是提供更多便利。通过“自动”，虚拟主机的所有名称都将添加到MD。方便地，“自动”也是默认设置。

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名称时，它们也将被添加到托管域中。

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

<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上侦听时，它将假定来自Internet的“ http：”请求将不起作用。

这是一个很好的猜测，但可能是错误的。例如，您的Apache可能监听80端口，但是您的防火墙可能阻止了它。“ http：”仅在您的Intranet中可用。因此，该模块将错误地认为Let's Encrypt可以在服务器上使用“ http：”挑战。然后这将失败，因为您的防火墙将丢弃那些防火墙。

MDPortMap http:- https:8433

上面的示例显示了如何指定来自Internet的“ http：”请求永远不会到达。此外，它还说“ https：”请求将到达本地端口8433。

如果有适当的端口转发，这是必要的，则可以从Internet上的端口443访问服务器，但是httpd使用的本地端口是另一个。您的服务器可能仅侦听端口8443和8000，但可以侦听端口443和80（来自Internet）。

MDPrivateKeys 指令

定义为托管域生成哪种私钥以及使用什么参数。现在唯一受支持的类型是“ RSA”，并且它采用的唯一参数是密钥所使用的位数。

当前（2017年）建议至少为2048位，此处不接受较小的建议。较高的数字可提供更长的安全性，但计算上更昂贵，例如，增加服务器的负载。这可能对您来说不是问题。

其他密钥类型将在以后定义。

MDPrivateKeys RSA 3072

请注意，此设置仅对新键有效。您拥有的任何现有私钥均不会受到影响。同样，这仅影响为证书生成的私钥。ACME帐户密钥不受此影响。

MDRenewMode 指令

在默认的“自动”模式下，该模块将执行每个受管域最有意义的操作。对于没有证书的域，它将从证书颁发机构获得证书。

但是，如果您定义的MD未被Apache的任何VirtualHost使用，则它不会打扰。对于带有静态证书文件的MD（请参阅参考资料MDCertificateFile），它假定您拥有自己的源，也不会更新它们。

您可以通过两种方式覆盖此默认设置。如果指定“ always”（始终），则该模块将续签MD的证书，而不管域是否正在使用或是否有静态文件。

为了达到相反的效果，请配置“手动”，并且不会尝试进行任何更新。

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:。这是安全的，您可以随时再次将其删除。

结果如下：如果希望客户端不再使用http：URL，请配置：

MDRequireHttps permanent

这有两件事：

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

基本上，您可以通过mod_alias和一些 Redirect配置来实现相同的目的。如果您自己执行此操作，请确保从重定向中排除路径/.well-known/*，否则mod_md可能无法在新证书上签名。

如果全局设置，则它适用于所有托管域。如果只希望将其用于特定域，请使用：

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

MDServerStatus 指令

Apache的“服务器状态”处理程序允许您配置资源以监视正在发生的事情。现在，该部分列出了所有托管域，其中包括DNS名称，续订状态，生存期和主要属性。

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

MDStapleOthers 指令

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