-
Notifications
You must be signed in to change notification settings - Fork 27
Home
This wiki documents features of mod_md and offers help in using it. Discussions are best held on the Apache httpd developer mailing list. If you miss a specific feature being covered here, you may also open an issue or, even better, contribute to the content here.
When you have installed mod_md and the patched mod_ssl in your Apache
and configured your_domain to be managed (how, I explain more below), you will
see something like the following in your log file:
[...00.587735] [md:info] ...<your_domain>: setup staging
[...00.588024] [md:info] ...<your_domain>: need certificate
[...07.040614] [md:info] ...<your_domain>: check Terms-of-Service agreement
[...07.040692] [md:info] ...<your_domain>: setup new authorization
[...13.604130] [md:info] ...<your_domain>: setup new challenges
[...19.522348] [md:info] ...<your_domain>: monitoring challenge status
[...25.387469] [md:info] ...<your_domain>: checked all domain authorizations
[...25.387551] [md:info] ...<your_domain>: creating certificate request
[...35.480524] [md:info] ...<your_domain>: received certificate
[...35.480565] [md:info] ...<your_domain>: retrieving certificate chain
[...41.634865] [md:notice] ... 1 Managed Domain has been setup and
changes will be activated on next (graceful) server restart.
when you then restart the server, the new Let's Encrypt certificate is used by your_domain. Before it expires, mod_md will obtain a new one and you will see a similar message in your server log.
Apart from the installation, you need to configure your server to load mod_md and tell it where it should take over your https management. A simple example:
You have a virtual host defined like this:
<VirtualHost *:443>
ServerName www.your_domain.de
ServerAlias your_domain.de
Protocols h2 http/1.1
SSLEngine on
SSLCertificateFile /etc/mycerts/your_domain.de/fullchain.pem
SSLCertificateKeyFile /etc/mycerts/your_domain.de/privkey.pem
...
</VirtualHost>
then you could change it to this:
ManagedDomain your_domain.de www.your_domain.de
<VirtualHost *:443>
ServerName www.your_domain.de
ServerAlias your_domain.de
Protocols h2 http/1.1
SSLEngine on
...
</VirtualHost>
The SSLCertificate* configurations are gone and you added a ManagedDomain with a list of host names (here, there are two, it could be just one or maybe ten).
More examples and other documentation you can find in the usage topics above.
When httpd is started as root user by your system, as most *NIX distribution set it up, it is configured to have its children (the ones doing the actual work) run as a quite restricted user. On Ubuntu, this is commonly www-data. This is good for security, obviously.
mod_md runs the ACME protocol also in these child processes and is therefore also restricted in the damages it can do. Which at the moment, also means it cannot signal the parent process to do a graceful restart. So, you will see a line in the error log that it was forbidden to do that. For now, in such a setup, you have to manually restart httpd for any certificate changes to take effect.
The ACME protocol challenges your server to prove that it has control over the domains. There are several methods available. The http-01 challenge works over port 80 (plain http:) and the tls-sni-01 works on port 443 (https).
Normally, you need to configure mod_ssl with SSLCertificateFile, SSLCertificateKeyFile and SSLCertificateChainFile directive to tell it where to get this information it needs for the TLS protocol. You no longer need to do that now, as mod_md is in charge of these and will tell mod_ssl where to find them.
I have only tested this on MacOS and Linux so far. It would be nice to hear from other platform. Especially Windows. Where someone needs to create a new build system. Sorry. Maybe that makes more sense to do when this code has landed in Apache subversion?