From: Stefan Eissing Date: Wed, 13 Sep 2017 14:19:40 +0000 (+0000) Subject: added new mod_md directives X-Git-Tag: 2.5.0-alpha~129 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=84989f7456d9f9091d77c49424a4d109e89ebb4e;p=apache added new mod_md directives git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1808242 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_md.xml b/docs/manual/mod/mod_md.xml index 9cb8200498..227e83ad09 100644 --- a/docs/manual/mod/mod_md.xml +++ b/docs/manual/mod/mod_md.xml @@ -220,7 +220,7 @@ ManagedDomain example.org www.example.org mail.example.org The URL where the CA offers its service.

Let's Encrypt offers, right now, two such URLs. One for the real certificates and - one for testing (their staging area, athttps://acme-staging.api.letsencrypt.org/directory). + one for testing (their staging area, at https://acme-staging.api.letsencrypt.org/directory). In order to have mod_md use this testing service, configure your server like this:

@@ -273,6 +273,20 @@ MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2 + + MDHttpProxy + Define a proxy for outgoing connections. + MDHttpProxy url + + server config + + +

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

+ + + MDMember Additional hostname for the managed domain. @@ -319,6 +333,24 @@ MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2 + + MDMustStaple + Control if new certificates carry the OCSP Must Staple flag. + MDMustStaple on|off + MDMustStaple off + + server config + + +

Defines if newly requested certificate should have the OCSP Must Staple flag + set or not. If a certificate has this flag, the server is required to send a + OCSP stapling response to every client. This only works if you configure + mod_ssl to generate this (see SSLUseStapling + and friends). +

+ + + MDPortMap Map external to internal ports for domain ownership verification. @@ -395,23 +427,83 @@ MDPrivateKeys RSA 3072 MDRenewWindow Control when a certificate will be renewed. MDRenewWindow duration - MDRenewWindow 14d + MDRenewWindow 33% server config

- Tells mod_md when to renew a certificate. The default means 14 days before a - certificate actually expires. If you configure this too short, a CA might - not be reachable in time and your server will show an invalid certificate. If - you do it too long, the CA might think you are a bother and block your requests. - Let's Encrypt has a certificate expiration of 90 days. So, if you configure the - renew window to 89 days, mod_md will renew the certificate - every day and Let's Encrypt will block you. + If the validity of the certificate falls below duration, mod_md will get a + new signed certificate. +

+ Normally, certificates are valid for around 90 days and mod_md will renew + them the earliest 33% of their complete lifetime before they expire (so for + 90 days validity, 30 days before it expires). If you think this is not what + you need, you can specify either the exact time, as in: +

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

When in auto drive mode, the module will check every 12 hours at least + what the status of the managed domains is and if it needs to do something. + On errors, for example when the CA is unreachable, it will initially retry + after some seconds. Should that continue to fail, it will back off to a + maximum interval of hourly checks.

+ + MDRequireHttps + Redirects http: traffic to https: for Managed Domains. + MDRequireHttps off|temporary|permanent + MDRequireHttps off + + server config + + +

This is a convenience directive to ease http: to https: migration of + your Managed Domains. With: +

+ Example + +MDRequireHttps temporary + + +

you announce that you want all traffic via http: URLs to be redirected + to the https: ones, for now. If you want client to no longer use the + http: URLs, configure: +

+ Example + +MDRequireHttps permanent + + +

You can achieve the same with mod_alias and some Redirect configuration, + basically. If you do it yourself, please make sure to exclude the paths + /.well-known/* from your redirection, otherwise mod_md might have trouble + signing on new certificates. +

+

If you set this globally, it applies to all managed domains. If you want + it for a specific domain only, use: +

+ Example + +<ManagedDomain xxx.yyy> + MDRequireHttps permanent +</ManagedDomain> + + + + + MDStoreDir Path on the local file system to store the Managed Domains data. @@ -453,17 +545,4 @@ MDPrivateKeys RSA 3072 - - MDHttpProxy - The URL of the HTTP proxy to use. - MDHttpProxy url - MDHttpProxy - - server config - - -

Use a HTTP proxy to connect to the MDCertificateAuthority url.

- - -