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 位址，其中某些 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。

為了進行測試，CA 通常會提供一個第二個服務 URL。「測試」服務不會提供瀏覽器中有效的憑證，但會放寬速率限制。這允許您驗證自己的設定，再轉換為建置服務 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 指紋會附加到所組態的網址中。

憑證記錄監視器提供憑證透明度 (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 協定要求您在註冊時提供聯絡網址。目前 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 設定這些內容。由於這些參數允許任何人於相同的帳戶中註冊，因此建議給予設定檔受限的權限，例如僅根目錄。

此參數也可以從 JSON 檔案讀取，以保留較開放的伺服器設定權限，並限制該檔案的權限。JSON 本身為

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

如果您變更 EAB 參數，下一次更新憑證時會使用新的參數。

MDHttpProxy 指令

使用 http 代理伺服器連線到 MDCertificateAuthority。如果您的網路伺服器只能透過轉發代理伺服器連線至網際網路時定義這個指令。

MDMatchNames 指令

模式「all」是所有先前版本的行為方式。伺服器名稱和伺服器別名都會被檢查，找出符合虛擬主機的 MDomain。這個模式會自動偵測涵蓋範圍，即使您只將一個名稱新增至 MDomain。

但是，這個自動化功能在更複雜的設定中會有缺點。如果您將這個指令設定為「servernames」，只有虛擬主機的伺服器名稱會用於配對。如此一來，配對時伺服器別名將被忽略。別名仍會新增到取得的憑證中，除非您同時也執行「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 指令

定義 VirtualHost 的 ServerName 和 ServerAlias 值是否自動新增到 Managed Domain 的成員。

MDMessageCmd 指令

在 Managed Domain 發生以下事件之一時，呼叫這個指令：「已更新」、「已安裝」、「快到期」、「發生錯誤」。指令可能會在未來呼叫，並忽略未準備處理的事件。

這個指令是 MDNotifyCmd 的較為靈活的伴侶。

MDMessageCmd /etc/apache/md-message

程式不應阻擋，因為模組會等候程式完成。回傳碼不為 0 則視為發生錯誤。

'已發生錯誤' 並非立即可引起注意，因為已提早嘗試更新，以便讓網路恢復。每小時至多報告一次。

'快到期' 應視為嚴重事項。當達到 MDWarnWindow 時，發出這個事項。預設為憑證使用壽命的 10%，因此對於 Let's Encrypt，目前表示快到期前 9 天。警告至多每天重複發布一次。

'已更新' 表示已取得新憑證，並儲存在 MD 儲存空間的「暫存」區域。『下次伺服器重新啟動/重新載入時，憑證將會啟動。

當新的憑證已從 MD 儲存空間的暫存區域傳送至域位置時，會觸發 '已安裝'。這會在伺服器啟動/重新載入時發生。不同於其他呼叫，MDMessageCmd 會以 root 權限執行（在*nix 系統上），並有權存取憑證檔案（和金鑰）。可在這個事件處理其他應用程式或不同格式所需的憑證。

Managed Domain 開始更新程序之前，會觸發 '正在更新' 事件。如果指令回傳 != 0，更新將會取消，並在下一個週期重複。有些叢集設定會使用這個設定，只在單一節點上執行更新。

當域的挑戰資料已建立時，會觸發 'challenge-setup:type:domain' 事件。在通知 ACME 伺服器檢查之前，會呼叫這個事件。類型為 ACME 挑戰類型之一。MDomain 中的每個 DNS 名稱都會呼叫這個事件。叢集設定可以使用這個事件，將挑戰檔案散布到叢集中的所有節點。

當 MDStapling 對網域啟用時，就會發生 ocsp-errored，這表示從憑證授權機構中擷取 OCSP 回應時遇到錯誤。mod_md 將持續嘗試。

MDMustStaple 指令

定義新要求的憑證是否應該設定 OCSP 必備旗標。如果憑證有這個旗標，伺服器必須對每個客戶端傳送 OCSP 主訂固定回應。這僅在您設定 mod_ssl 來產生此資訊時才有效 (請參閱 SSLUseStapling 和相關部分)。

MDNotifyCmd 指令

當管理網域已註冊或更新其憑證時，會執行設定的可執行檔。它將取得處理過的 MD 名稱，做為額外的引數 (在這裡指定的參數之後)。它應該傳回狀態碼 0 來表示已成功執行。

MDomain 指令

清單中的所有名稱做為一個管理網域 (MD) 管理。mod_md 會要求一個對所有這些名稱都有效的單一憑證。這個指令使用全域設定 (請參閱下方其他 MD 指令)。如果您需要針對一個 MD 指定特定設定，請使用 <MDomainSet>。

管理網域有 2 個必要的附加設定：一個聯絡人電子郵件地址 (經由 MDContactEmail 或 ServerAdmin) 和 MDCertificateAgreement。ServerAdmin 的郵件地址用於在 CA (預設為 Let's Encrypt) 中註冊。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'。這決定管理網域應具有的名稱清單是否完全和設定的一樣 ('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:' 網址 (埠口 80)，一個使用 'https:' 網址 (埠口 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。而「讓我們加密」所支援的曲線包括「secp256r1」和「secp384r1」。

每個金鑰和憑證類型都儲存在 MD 儲存空間中自己的檔案裡。金鑰類型是檔案名稱的一部分，以及部分向下相容的 RSA 憑證命名。如此一來，你就可以繼續將這些檔案與其他應用程式共用。

請注意，此設定只會影響新的金鑰。任何你現有的私人金鑰都會維持不受影響。此外，這只會影響為憑證所產生的私人金鑰。ACME 帳戶金鑰不受此影響。

MDRenewMode 指令

在預設的「auto」模式中，模組將為每個受管網域採取最適合的行動。對於任何沒有憑證的網域，它會向憑證授權機構取得這些憑證。

然而，如果你已定義未被任何 Apache VirtualHosts 所使用的 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 指令

這是一個方便的指令，可讓 Managed Domain 的 http: 輕鬆遷移至 https：使用

MDRequireHttps temporary

指派您目前想要將所有透過 http: URL 的流量重新導向至 https:，這很安全，您可以隨時移除它。

會產生以下結果：若您要用戶不再使用 http: URL，請設定

MDRequireHttps permanent

此執行方法包含兩件事

1. 使用狀態碼 301 將所有對 http: 資源的要求重新導向至具有 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 天。

這也適用於使用靜態憑證檔案的 Managed Domain（參閱 MDCertificateFile）。