Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
mod_md - because everybody spies
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.
- Simple Scenarios
- Migration from
- Edge Cases
- Name Changes
- CA Setups
- Command Line
- All Directives
What can I expect?
When you have installed
mod_md and the patched
mod_ssl in your Apache
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.
What is this about Server Restart?
mod_md gets new certificates, they are not immediately live. Instead,
mod_ssl - the module using them for your https: connections, picks them up when the server restarts/reloads. (In case you are not ware: the difference between restart and reload is that the later one does not disturb ongoing connections. Apache calls this also a graceful restart.)
For rather technical reasons (also security related ones)
mod_md is unable to make the server restart/reload by itself. Therefore, once you have it all working and your first certificates are there, it is recommended to reload the server at least once a week, so that renewed certificates are then picked up.
(I'd like to add more admin support in this area. If you have ideas about this, just open an issue and make a proposal!)
What do I need to do?
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:
MDomain your_domain.de <VirtualHost *:443> ServerName www.your_domain.de ServerAlias your_domain.de Protocols h2 http/1.1 SSLEngine on ... </VirtualHost>
SSLCertificate* configurations are gone and you added a
MDomain with a host name.
More examples and other documentation you can find in the usage topics above.
No Auto Restart when started as
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.
Need to be reachable on port 80 and/or 443
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 (
Need a patched
Normally, you need to configure
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?