Apache Module mod_md

Available Languages: en

+ + + + +

Description:	Managing domains across virtual hosts, certificate provisioning + via the ACME protocol +
Status:	Extension
Module Identifier:	md_module
Source File:	mod_md.c
Compatibility:	Available in version 2.5.0 and later

Summary

+ +

+ 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. The most famous Certificate Autority currently implementing the ACME protocol + is Let's Encrypt.

+ +

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 (see MDStoreDir) + 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'. +

+ +

Bugfix checklist

ManagedDomain Directive

+ + + + + + +

Description:	Define list of domain names that belong to one group
Syntax:	`ManagedDomain dns-name [ other-dns-name... ]`
Context:	server config
Status:	Extension
Module:	mod_md

+ All the names in the list are managed as one Managed Domain (MD). + mod_md will request one single 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>

+ There are two special names that you may use in this directive: 'manual' + and 'auto'. This determines if a Managed Domain shall have exactly the + name list as is configured ('manual') or offer more convenince. With 'auto' + all names of a virtual host are added to a MD. +

Example

ManagedDomain example.org
+
+<VirtualHost *:443>
+    ServerName example.org
+    ServerAlias www.example.org
+    DocumentRoot htdocs/root
+
+    SSLEngine on
+</VirtualHost>

+ In this example, the domain 'www.example.org' is automatically added to + the MD 'example.org'. And when you add more ServerAlias names to this + virtual host, they will be added as well. +

+ If this is too much automagic for you, define 'manual' mode. + mod_md will then complain if the names do not match. +

+ +

<ManagedDomain> Directive

+ + + + + + +

Description:	Container for directives applied to the same managed domains
Syntax:	`<ManagedDomain dns-name [ other-dns-name... ]>...</ManagedDomain>`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ +

MDCAChallenges Directive

+ + + + + + + +

Description:
Syntax:	`MDCAChallenges name [ name ... ]`
Default:	`MDCAChallenges tls-sni-01 http-01`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ +

MDCertificateAgreement Directive

+ + + + + + +

Description:	The URL of the Terms-of-Service document, that the CA server requires you to accept.
Syntax:	`MDCertificateAgreement url-of-terms-of-service`
Context:	server config
Status:	Extension
Module:	mod_md

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 Directive

+ + + + + + + +

Description:	The URL of the ACME CA service
Syntax:	`MDCertificateAuthority url`
Default:	`MDCertificateAuthority https://acme-v01.api.letsencrypt.org/directory`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ + + + + + + +

Description:	The protocol to use with the CA
Syntax:	`MDCertificateProtocol protocol`
Default:	`MDCertificateProtocol ACME`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ +

MDDriveMode Directive

+ + + + + + + +

Description:	Controls when `mod_md` will try to obtain/renew certificates.
Syntax:	`MDDriveMode always\|auto\|manual`
Default:	`MDDriveMode auto`
Context:	server config
Status:	Extension
Module:	mod_md

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 Directive

+ + + + + + +

Description:	Additional hostname for the managed domain
Syntax:	`MDMember hostname`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ + + + + + + +

Description:
Syntax:	`MDPortMap map1 [ map2 ]`
Default:	`MDPortMap 80:80 443:443`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ + + + + + + +

Description:
Syntax:	`MDRenewWindow duration`
Default:	`MDRenewWindow 14d`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ + + + + + + +

Description:
Syntax:	`MDStoreDir path`
Default:	`MDStoreDir md`
Context:	server config
Status:	Extension
Module:	mod_md

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

+ +

Apache Module mod_md

Summary

Warning

TLS in a VirtualHost context

Directives

Bugfix checklist

See also

ManagedDomain Directive

Example

Example

<ManagedDomain> Directive

Example

MDCAChallenges Directive

MDCertificateAgreement Directive

Example

MDCertificateAuthority Directive

LE Staging Setup

MDCertificateProtocol Directive

MDDriveMode Directive

MDMember Directive

Example

MDPortMap Directive

Example

MDRenewWindow Directive

MDStoreDir Directive

Comments