Stefan Eissing edited this page Aug 16, 2018 · 18 revisions

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.




What can I expect?

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.

What is this about Server Restart?

When 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>
    Protocols h2 http/1.1

    SSLEngine on
    SSLCertificateFile /etc/mycerts/
    SSLCertificateKeyFile /etc/mycerts/

then you could change it to this:


<VirtualHost *:443>
    Protocols h2 http/1.1

    SSLEngine on

The 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 root

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.

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 (https).

Need a patched mod_ssl

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.

Other Platforms

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?

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.