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 Authority currently implementing the ACME protocol - is Let's Encrypt.
+ Its main feature is the use of the ACME protocol + (RFC 8555) + to automate certificate provisioning. Certificates will be renewed + by the module ahead of their expiration to account for disruption in internet + services. There are ways to monitor the status of all Managed Domains + and configurations that will run your own notification commands on renewal, + expiration and errors. + ++ The default ACME Certificate Authority is + Let's Encrypt, but it is possible + to configure another CA that supports the protocol. +
This module is experimental. Its behaviors, directives, and @@ -79,17 +86,17 @@ MDomain example.org
This module requires
- Certificate signup and renewal with Let's Encrypt requires your server to be + Certificate sign-up and renewal with Let's Encrypt requires your server to be reachable on port 80 (http:) from the outside. The alternative method over port 443 (https:) is currently disabled for security reasons (status from 2018-01-14).
The module will select from the methods offered by Let's Encrypt. If LE decides
- at one point in the future, to re-enable it again,
But for now, only the port 80 variant is available (termed "http-01"). Only
- when LE can reach your server on port 80 will
If you do not want to offer any sites on port 80 any more, you may leave it open @@ -99,6 +106,120 @@ MDomain example.org from Let's Encrypt.
+ Wildcard certificates are possible with version 2.x of `mod_md``. But they are + not straight-forward. Let's Encrypt requires the `dns-01` challenge verification + for those. No other is considered good enough. +
+ The difficulty here is that Apache cannot do that on its own. (which is also + a security benefit, since corrupting a web server or the communication path to + it is the scenario `dns-01` protects against). As the name implies, `dns-01` + requires you to show some specific DNS records for your domain that contain + some challenge data. So you need to _write_ your domain's DNS records. +
+ If you know how to do that, you can integrated this with `mod_md`. Let's + say you have a script for that in `/usr/bin/acme-setup-dns` you configure + Apache with: +
++ and Apache will call this script when it needs to setup/teardown a DNS challenge + record for a domain. +
+ Assuming you want a certificate for `*.mydomain.com`, mod_md will call: +
++ and afterwards it will call +
+
+ Apache has a standard module for monitoring:
+ You see all your MDs listed alphabetically, the domain names they contain, + an overall status, expiration times and specific settings. The settings + show your selection of renewal times (or the default), the CA that is used, + etc. +
+ The 'Renewal' column will show activity and error descriptions for certificate + renewals. This should make life easier for people to find out if everything + is all right or what went wrong. +
+ If there is an error with an MD it will be shown here as well. This let's + you assess problems without digging through your server logs. +
+ There is also a new 'md-status' handler available to give you the MD information + from 'server-status' in JSON format. You configure it as +
++ on your server. As with 'server-status' you will want to add + authorization for this. +
+ If you just want to check the JSON status of a specific domain, simply append + that to your status url: +
++ This JSON status also shows a log of activities when domains are renewed: +
++ You will also find this information in the file `job.json` in your staging and, + when activated, domains directory. This allows you to inspect these at + any later point in time as well. +
+ In addition, there is
All the names in the list are managed as one Managed Domain (MD).
-
The second setting,
- 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.
+ This is the directive
+ This allows you to configure an MD that uses another Certificate Authority, + have other renewal requirements, etc.
+ A common use case is to configure https: requirements separately for + your domains. +
+This is a specialized version of
When you use
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.
-
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.
-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, at https://acme-staging.api.letsencrypt.org/directory).
- In order to have
+ Each version has 2 endpoints, as their is a production endpoint and a + "staging" endpoint for testing. The testing endpoint works the same, but will + not give you certificates recognized by browsers. However, it also has + very relaxed rate limits. This allows testing of the service repeatedly + without you blocking yourself.
Specifies the protocol to use. Currently, only ACME is supported.
+ Specifies the protocol to use. Currently, only ACME is supported.
+
In 'auto' mode,
- In 'manual' mode, it is your duty to do all this. The module will provide the existing
- certificate to
- The third mode 'always' is like 'auto', with the difference that
-
This directive exists for backward compatibility as the old name for
+
+ In the default 'auto' mode, the module will do what makes most sense + of each Managed Domain. For a domain without any certificates, it will + obtain them from the Certificate Authority. +
+
+ However, if you have defined an MD that is not used by any of Apache's
+ VirtualHosts, it will not bother. And for MDs with static certificate
+ files (see
+ You can override this default in either way. If you specify 'always', + the module will renew certificates for an MD, irregardless if the + domains are in use or if there are static files. +
++ For the opposite effect, configure 'manual' and no renewal will + be attempted.
Instead of listing all dns names on the same line, you may use
-
@@ -390,16 +538,17 @@ MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.2-November-15-
The configured executable is run when Managed Domains have signed up or
- renewed their certificates. It is given the names of the processed MDs as
- additional arguments (after the parameters specified here). It should
- return status code 0 to indicate that it has run successfully.
+
+ The configured executable is run when a Managed Domain has signed up or
+ renewed its certificate. It is given the name of the processed MD as
+ additional arguments (after the parameters specified here). It should
+ return status code 0 to indicate that it has run successfully.
- The ACME protocol provides two methods 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.
+ The ACME protocol provides two methods to verify domain ownership via
+ HTTP: one that uses 'http:' urls (port 80) and one for 'https:' urls
+ (port 443). If your server is not reachable by at least one
+ of the two, ACME may only work by configuring your DNS server,
+ see
-
- 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
- With
- 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.
+ The above example shows how you can specify that 'http:' requests from
+ the internet will never arrive. In addition it says that 'https:' requests
+ will arrive on local port 8433.
+
+ This is necessary if you have 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 8443 and 8000, but be reached
+ on ports 443 and 80 (from the internet).
- If the validity of the certificate falls below duration,
- Normally, certificates are valid for around 90 days and You can achieve the same with If you set this globally, it applies to all managed domains. If you want
@@ -570,9 +727,9 @@ MDRequireHttps permanent
Sets challenge types and their execution order when proving domain ownership.
The names are protocol specific.
- The current ACME protocol version implemented by Let's Encrypt defines two challenge
- types that are supported by
Controls if the base server, the one outside all VirtualHosts should be managed by
-
+ This is used inside a
+ This is that equivalent of the mod_ssl
+
+ If you want to migrate an existing domain, using static files, to
+ automated Let's Encrypt certificates, for one. You define the
+
+ This will give you the same as before, with maybe less repeating lines
+ in your configuration. Then you can add
+ Another use case is that you renew your Let's Encrypt certificates with + another ACME clients, for example the excellent + certbot. Then let your MDs point + to the files from certbot and have both working together. +
+
+ This is used inside a
+ This is that equivalent of the mod_ssl
+
+ When enabled, a resources is available in Managed Domains at + 'https://domain/.httpd/certificate-status' that returns a JSON + document list key properties of the current and of a renewed + certificate - when available. +
++ Define a program to be called when the `dns-01` challenge needs to be setup/torn down. + The program is given the argument `setup` or `teardown` followed by the domain name. + For `setup` the challenge content is additionally given. +
+ You do not need to specify this, as long as a 'http:' or 'https:' challenge + method is possible. However, Let's Encrypt makes 'dns-01' the only + challenge available for wildcard certificates. If you require + one of those, you need to configure this. +
+ See the section about wildcard certificates above for more details. +
++ This command gets called when one of the following events happen for + a Managed Domain: "renewed", "expiring", "errored". The command may + be invoked for more than these in the future and ignore events + it is not prepared to handle. +
+ This is the more flexible companion to
+ The program should not block, as the module will wait for it to finish. A + return code other than 0 is regarded as an error. +
+ 'errored' is no immediate cause for concern since renewal is attempted + early enough to allow the internet to come back. +
+ 'expiring' should be taken serious. It is issued when the
+
+ See
+ The modules checks the remaining lifetime of certificates and invokes
+
+ It also applies to Managed Domains with static certificate files (
+ see
+ Apaches 'server-status' handler allows you configure a resource to monitor + what is going on. This includes now a section listing all Managed Domains + with the DNS names, renewal status, lifetimes and main properties. +
+ You can switch that off using this directive. +
+