From: Stefan Eissing Date: Wed, 9 Aug 2017 15:19:34 +0000 (+0000) Subject: mod_md documentation X-Git-Tag: 2.5.0-alpha~232 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f26217a3bcc53b7ee2115f88194123eccf3e0d89;p=thirdparty%2Fapache%2Fhttpd.git mod_md documentation git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1804542 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_md.xml b/docs/manual/mod/mod_md.xml new file mode 100644 index 00000000000..ed68151172b --- /dev/null +++ b/docs/manual/mod/mod_md.xml @@ -0,0 +1,382 @@ + + + + + + + + + + mod_md + Managing domains across virtual hosts, certificate provisioning + via the ACME protocol + + Extension + mod_md.c + md_module + Available in version 2.5.0 and later + + +

+ This module manages common properties of domains for one or more virtual hosts. + Specifically it can use the ACME protocol (RFC Draft) + to automate certificate provisioning. These will be configured for managed domains and + their virtual hosts automatically. This includes renewal of certificates before they + expire.

+ + Warning +

This module is experimental. Its behaviors, directives, and + defaults are subject to more change from release to + release relative to other standard modules. Users are encouraged to + consult the "CHANGES" file for potential updates.

+ + +

Simple configuration example:

+ + TLS in a VirtualHost context + +ManagedDomain example.org + +<VirtualHost *:443> + ServerName example.org + DocumentRoot htdocs/a + + SSLEngine on + # no certificates specification needed! +</VirtualHost> + +

+ This setup will, on server start, contact Let's Encrypt + to request a certificate for the domain. If Let's Encrypt can verify the ownership + of the domain, the module will retrieve the certificate and its chain, store it + in the local file system and provide it, on next restart, to mod_ssl. +

+ This happens while the server is already running. All other hosts will continue + to work as before. While a certificate is not available, requests for the managed + domain will be answered with a '503 Service Unavailable'. +

+ + + + + + + ManagedDomain + Define list of domain names that belong to one group + ManagedDomain dns-name [ other-dns-name... ] + + server config + + + +

+ All the names in the list are managed as one Managed Domain (MD). + mod_md will request one certificate that is valid for all these names. This + directive uses the global settings (see other MD directives below). If you + need specific settings for one MD, use + the <ManagedDomain. +

+ There are 2 additional settings that are necessary for a Managed Domain: ServerAdmin + and MDCertificateAgreement. The mail address of + ServerAdmin is used to register + at the CA (Let's Encrypt by default). The CA may use it to notify you about + changes in its service or status of your certificates. +

+ The second setting, MDCertificateAgreement, + is the URL of the Terms of Service of the CA. When you configure the URL, + you confirm that you have read and agree to the terms described in the linked + document. Before you do that, the CA will not hand out certificates to you. +

+ Example + +ServerAdmin mailto:admin@example.org +MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf +ManagedDomain 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> + + + + + + + <ManagedDomain + Define a group of domains with common properties + <ManagedDomain dns-name>...</ManagedDomain> + + server config + + + +

+ This directive allows you to define a Managed Domain (MD) with specific + settings, different from the global MD* ones. For example, you can have + such an MD use another CA then Let's Encrypt, have its unique renewal duration + etc. +

+ Example + +<ManagedDomain sandbox.example.org> + MDDriveMode manual + MDCertificateAuthority https://someotherca.com/ACME + MDCertificateAgreement https://someotherca.com/terms/v_1.02.pdf +</ManagedDomain example.org> + + + + + + + MDCertificateAgreement + The URL of the Terms-of-Service document, that the CA server requires you to accept. + MDCertificateAgreement url-of-terms-of-service + + server config + managed domain + + +

When you use mod_md to obtain a certificate, you become a customer of the CA (e.g. Let's Encrypt). That means you need to read and agree to their Terms of Service, + so that you understand what they offer and what they might exclude or require from you. + mod_md cannot, by itself, agree to such a thing. +

+

In case of Let's Encrypt, their current Terms of Service are here. + Those terms might (and probably will) change over time. So, the certificate renewal might require you to update this agreement URL.

+ Example + +MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf +ManagedDomain example.org www.example.org mail.example.org + + + + + + + MDCertificateAuthority + The URL of the ACME CA service + MDCertificateAuthority url + MDCertificateAuthority https://acme-v01.api.letsencrypt.org/directory + + server config + managed domain + + +

+ 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). + In order to have mod_md use this testing service, configure your + server like this: +

+ LE Staging Setup + + MDCertificateAuthority https://acme-staging.api.letsencrypt.org/directory + MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf + + + + + + + MDCertificateProtocol + The protocol to use with the CA + MDCertificateProtocol protocol + MDCertificateProtocol ACME + + server config + managed domain + + +

Specifies the protocol to use. Currently, only ACME is supported.

+ + + + + MDDriveMode + Controls when mod_md will try to obtain/renew certificates. + MDDriveMode always|auto|manual + MDDriveMode auto + + server config + managed domain + + +

In 'auto' mode, mod_md will drive a Managed Domain's + properties (e.g. certicate management) whenever necessary. When a MD is not used + in any virtual host, the module will do nothing. When a certificate is missing, it + will try to get one. When a certificate expires soon (see + MDRenewWindow), it will + renew it. +

+ In 'manual' mode, it is your duty to do all this. The module will provide existing + ceriticate to mod_ssl, if available. But it will not contact the CA for signup/renewal. + This can be useful in clustered setups where you want just one node to perform + the driving. +

+ The third mode 'always' is like 'auto' only that mod_md will not + check if the MD is actually used somewhere. +

+ + + + + MDMember + Additional hostname for the managed domain + MDMember hostname + + server config + managed domain + + +

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

+ Example + +<ManagedDomain example.org> + MDMember www.example.org + MDMember mail.example.org +</ManagedDomain example.org> + + +

+ If you use it in the global context, outside a specific MD, you can only + specify one value, 'auto' or 'manual' as the default for all other MDs. See + ManagedDomain for a + description of these special values. +

+ + + + + MDPortMap + + MDPortMap map1 [ map2 ] + MDPortMap 80:80 443:443 + + server config + + +

+ The ACME protocol provides two method to verify domain ownership: one that uses + port 80 and one for port 443. If your server is not reachable by at least one + of the two, ACME will not work for you. +

+ mod_md will look at your server configuration and try to figure + out which of those are available. Then it can select the proper ACME challenge + to create a certificate for your site. +

+ However if you have some fancy port forwarding in place, your server may be + reachable from the Internet on port 443, but the local port that httpd uses is + another one. Your server might only listen on ports 5001 and 5002, but be reached + on ports 443 and 80. How should mod_md figure that one out? +

+ With MDPortMap you can tell it which 'Internet port' corresponds to which local + port. +

+ Example + +MDPortMap 80:- 443:5002 + + +

+ This example says that the server is not reachable on port 80 from the outside, but + local port 5002 is the one responding to https: requests. +

+ + + + + MDRenewWindow + + MDRenewWindow duration + MDRenewWindow 14d + + server config + managed domain + + +

+ 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. +

+ + + + + MDStoreDir + + MDStoreDir path + MDStoreDir md + + server config + + +

+ Defines where on the local file system the Managed Domain data is stored. This is + an absolute path or interpreted relative to the server root. The default will create + a directory 'md' in your server root. +

+ If you move this and have already data, be sure to move/copy the data first to + the new location, reconfigure and then restart the server. If you reconfigure + and restart first, the server will try to get new certificates that it thinks + are missing. +

+ + + + + MDCAChallenges + + MDCAChallenges name [ name ... ] + MDCAChallenges tls-sni-01 http-01 + + server config + managed domain + + +

+ This tells mod_md which challenge types it shall use in + which order when proving domain ownership. The names are protocol specific. The + current ACME protocol version that Let's Encrypt speaks defines two challenge + types that are supported by mod_md. By default, it will try + the one on port 443 when available. +

+ + + + diff --git a/docs/manual/mod/mod_md.xml.meta b/docs/manual/mod/mod_md.xml.meta new file mode 100644 index 00000000000..29abbf4ff2e --- /dev/null +++ b/docs/manual/mod/mod_md.xml.meta @@ -0,0 +1,12 @@ + + + + + mod_md + /mod/ + .. + + + en + +