From: Christophe Jaillet Date: Sat, 28 Mar 2020 20:06:39 +0000 (+0000) Subject: Add some compatibility notes for new directives in 2.4.42. X-Git-Tag: 2.5.0-alpha2-ci-test-only~1553 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=47aef00d41cbafdca406274846fce4370e8c86b7;p=thirdparty%2Fapache%2Fhttpd.git Add some compatibility notes for new directives in 2.4.42. Add some missing and to improve navigation and style. Fix the format of some Add some placeholders for the MDCertificateCheck and MDActivationDelay directives. (new in 2.4.42) git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1875818 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_md.xml b/docs/manual/mod/mod_md.xml index 40f1cfc68a1..929dae1c238 100644 --- a/docs/manual/mod/mod_md.xml +++ b/docs/manual/mod/mod_md.xml @@ -249,7 +249,7 @@ MDChallengeDns01 /usr/bin/acme-setup-dns </MDomain>

- and use the 'server-status' and/or MDMessageCmd to see how it operates. You will + and use the 'server-status' and/or MDMessageCmd to see how it operates. You will see if Stapling information is there, how long it is valid, from where it came and when it will be refreshed.

@@ -531,7 +531,7 @@ MDCertificateAuthority https://acme-staging-v02.api.letsencrypt.org/directory server config -

Use a http proxy to connect to the MDCertificateAuthority. Define this +

Use a http proxy to connect to the MDCertificateAuthority. Define this if your webserver can only reach the internet with a forward proxy.

@@ -547,7 +547,7 @@ MDCertificateAuthority https://acme-staging-v02.api.letsencrypt.org/directory

Instead of listing all dns names on the same line, you may use - MDMember to add such names + MDMember to add such names to a managed domain.

Example @@ -803,7 +803,7 @@ MDRequireHttps permanent MDStoreDir Path on the local file system to store the Managed Domains data. - MDStoreDir path + MDStoreDir path MDStoreDir md server config @@ -838,7 +838,7 @@ MDRequireHttps permanent to find out which methods can be used.

If the server listens on port 80, for example, the 'http-01' method is available. - The prerequisite for 'dns-01' is a configured 'MDChallengeDns01' command. + The prerequisite for 'dns-01' is a configured MDChallengeDns01 command. 'tls-alpn-01' is described above in 'https: Challenges'.

This auto selection works for most setups. But since Apache is a very powerful @@ -846,7 +846,7 @@ MDRequireHttps permanent possible cases. For example: it may listen on multiple IP addresses where some are reachable on `https:` and some not.

- If you configure 'MDCAChallenges' directly, this auto selection is disabled. + If you configure MDCAChallenges directly, this auto selection is disabled. Instead, the module will use the configured challenge list when talking to the ACME server (a challenge type must be offered by the server as well). This challenges are examined in the order specified. @@ -875,7 +875,7 @@ MDRequireHttps permanent MDCertificateFile Specify a static certificate file for the MD. - MDCertificateFile path-to-pem-file + MDCertificateFile path-to-pem-file server config @@ -909,7 +909,7 @@ MDRequireHttps permanent in your configuration. Then you can add MDRenewMode 'always' to it and the module will get a new certificate before the one from the file expires. When it has done so, you remove the - MDCertificateFile and reload the server. + MDCertificateFile and reload the server.

Another use case is that you renew your Let's Encrypt certificates with another ACME clients, for example the excellent @@ -922,7 +922,7 @@ MDRequireHttps permanent MDCertificateKeyFile Specify a static private key for for the static cerrtificate. - MDCertificateKeyFile path-to-file + MDCertificateKeyFile path-to-file server config @@ -971,7 +971,7 @@ MDRequireHttps permanent MDChallengeDns01 - MDChallengeDns01 path-to-command + MDChallengeDns01 path-to-command server config @@ -994,7 +994,7 @@ MDRequireHttps permanent MDMessageCmd Handle events for Manage Domains - MDMessageCmd path-to-cmd optional-args + MDMessageCmd path-to-cmd optional-args server config @@ -1008,12 +1008,12 @@ MDRequireHttps permanent This is the more flexible companion to MDNotifyCmd.

Example + MDMessageCmd /etc/apache/md-message + # will be invoked when a new certificate for mydomain.org is available as: /etc/apache/md-message renewed mydomain.com - -

The program should not block, as the module will wait for it to finish. A @@ -1035,7 +1035,7 @@ MDMessageCmd /etc/apache/md-message

'installed' is triggered when a new certificate has been transferred from staging into the domains location in MD store. This happens at server - startup/reload. Different to all other invocations, MDMessageCmd is run + startup/reload. Different to all other invocations, MDMessageCmd is run with root permissions (on *nix systems) and has access to the certificate files (and keys). Certificates needed for other applications or in different formats can be processed on this event. @@ -1090,7 +1090,7 @@ MDMessageCmd /etc/apache/md-message MDCertificateMonitor The URL of a certificate log monitor. MDCertificateMonitor name url - crt.sh https://crt.sh?q= + MDCertificateMonitor crt.sh https://crt.sh?q= server config @@ -1117,24 +1117,26 @@ MDMessageCmd /etc/apache/md-message MDStapling Enable stapling for all or a particular MDomain. MDStapling on|off - off + MDStapling off server config + Available in version 2.4.42 and later

- mod_md offers an implementation for providing OCSP stapling information. - This is an alternative to the one provided by 'mod_ssl'. For backward + mod_md offers an implementation for providing OCSP stapling information. + This is an alternative to the one provided by mod_ssl. For backward compatibility, this is disabled by default.

The stapling can be switched on for all certificates on the server or - for an individual MDomain. This will replace any stapling configuration - in `mod_ssl` for these hosts. When disabled, the 'mod_ssl' stapling + for an individual MDomain. + This will replace any stapling configuration + in mod_ssl for these hosts. When disabled, the mod_ssl stapling will do the work (if it is itself enabled, of course). This allows for a gradual shift over from one implementation to the other.

- The stapling of `mod_md` will also work for domains where the certificates - are not managed by this module (see MDStapleOthers for how to control this). + The stapling of mod_md will also work for domains where the certificates + are not managed by this module (see MDStapleOthers for how to control this). This allows use of the new stapling without using any ACME certificate management.

@@ -1145,14 +1147,15 @@ MDMessageCmd /etc/apache/md-message MDStapleOthers Enable stapling for certificates not managed by mod_md. MDStapleOthers on|off - on + MDStapleOthers on server config + Available in version 2.4.42 and later

- This setting only takes effect when `MDStapling` is enabled. It controls - if `mod_md` should also provide stapling information for certificates + This setting only takes effect when MDStapling is enabled. It controls + if mod_md should also provide stapling information for certificates that are not directly controlled by it, e.g. renewed via an ACME CA.

@@ -1161,11 +1164,12 @@ MDMessageCmd /etc/apache/md-message MDStaplingKeepResponse Controls when old responses should be removed. - MDStaplingKeepResponse duration - 7d + MDStaplingKeepResponse duration + MDStaplingKeepResponse 7d server config + Available in version 2.4.42 and later

This time window specifies when OCSP response data used in stapling @@ -1180,15 +1184,16 @@ MDMessageCmd /etc/apache/md-message MDStaplingRenewWindow Control when the stapling responses will be renewed. - MDStaplingRenewWindow duration - 33% + MDStaplingRenewWindow duration + MDStaplingRenewWindow 33% server config + Available in version 2.4.42 and later

- If the validity of the OCSP response used in stapling falls below 'duration', - mod_md will obtain a new OCSP response. + If the validity of the OCSP response used in stapling falls below duration, + mod_md will obtain a new OCSP response.

The CA issuing a certificate commonly also operates the OCSP responder service and determines how long its signed response about the validity @@ -1215,11 +1220,40 @@ MDMessageCmd /etc/apache/md-message

- + + + MDCertificateCheck + MDCertificateCheck name url + + + server config + + Available in version 2.4.42 and later + +

+

+ + + + + MDActivationDelay + + MDActivationDelay duration< + + + server config + + Available in version 2.4.42 and later + +

+

+ + + MDContactEmail - MDContactEmail address + MDContactEmail address server config @@ -1227,9 +1261,9 @@ MDMessageCmd /etc/apache/md-message

The ACME protocol requires you to give a contact url when you sign up. Currently, Let's Encrypt wants an email address (and it will use it to inform you about renewals - or changed terms of service). mod_md uses the MDContactEmail directive email in + or changed terms of service). mod_md uses the MDContactEmail directive email in your Apache configuration, so please specify the correct address there. - If MDContactEmail is not present, mod_md will use the + If MDContactEmail is not present, mod_md will use the ServerAdmin directive.