mod_md
is by far the simplest way to add LetsEncrypt signed certificates to your Apache httpd server. Just add one line of configuration and you're done!
The Mozilla Open Source Support project commissioned Stefan Eissing (@icing) to create an integrated module for Apache's httpd server to make using TLS even easier. We already know Stefan Eissing as the creator of the HTTP/2 module for Apache httpd.
Even though issuing a certificate with mod_md
is a breeze, the module itself not yet readily available for Apache version 2.4. It is already part of the upcoming Apache version 2.5.
This is still an experimental module
It works for me, but your mileage may vary!
Full transparency: I am the maintainer of the www/mod_md-devel
port on FreeBSD
Give me that mod_md module!
Since mod_md
takes over the complete key and certificate directives, it needs integration with mod_ssl
. What we need to do is add a patch to Apache httpd, rebuild and reinstall it before mod_md
can issue and register certificates. @icing's GitHub repo hosts the required patches for mod_ssl
as well (in the patches
directory, doh!).
Rebuild/install Apache httpd
With FreeBSD ports that would be done like this (make sure you get the most recent patch!):
cd /usr/ports/www/apache24
fetch -o files/patch-mod_ssl-for-mod_md https://github.com/icing/mod_md/raw/master/patches/mod_ssl_md-2.4.x-v4.diff
make clean package
pkg add -f work/pkg/apache24-2.4.27.tar.xz
or, in a more manual style, like so:
cd /usr/ports/www/apache24
fetch https://github.com/icing/mod_md/raw/master/patches/mod_ssl_md-2.4.x-v4.diff
make clean patch
cd work/httpd-2.4.27
patch -p0 < ../../mod_ssl_md-2.4.x-v4.diff
cd ../..
make clean package
pkg add -f work/pkg/apache24-2.4.27.tar.xz
Build/install mod_md
With the patched Apache 2.4 installed, we can now build and install mod_md
.
The releases are ready-to-go tarballs that can easily be compiled.
Check the Latest Release page to download the most current one.
fetch https://github.com/icing/mod_md/releases/download/v0.9.2/mod_md-0.9.2.tar.gz
tar xf mod_md-0.9.2.tar.gz
./configure --apxs=/usr/local/sbin/apxs
make && make install
The module can now be configured.
Using FreeBSD ports
On FreeBSD this can be simplified, there's a www/mod_md-devel
port that is ready for use.
First of all you'll have to rebuild apache with an extra patch.
To do so add to your make.conf
(default location /etc/make.conf
)
.if ${.CURDIR:M*/www/apache24}
EXTRA_PATCHES+=../mod_md-devel/files/extra-patch-mod_ssl
.endif
this will add the up-to-date patch to the apache build.
Now rebuild/install www/apache24
.
This works in poudriere or other setups as well.
Now you can build the www/mod_md-devel
port and install it.
Using mod_md
To use mod_md
you need disturbingly little configuration.
There's only 2 things you must do, the rest is optional.
First and foremost you must accept the terms of service of LetsEncrypt, secondly you add the domains that mod_md
will manage.
MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
ManagedDomains www.example.org
With all the other settings left as default, this will issue a certificate for the Virtual Host ServerName www.example.org
with Subject Alternative Names for all ServerAlias
es.
Tips
Your system will be registered with the ServerAdmin
email address. This is where expiry notifications will be sent to.
By default, it will use 2048-bit keys and certificates. This behaviour can be changed using
MDPrivateKeys RSA 4096
mod_md
creates one (SAN) certificate for every ManagedDomain entry you have.
If you have multiple domains, you can steer the behaviour by adding multiple ManagedDomain directives
ManagedDomain www.example.org www.example.net
ManagedDomain www.example.com
would create 2 certificates (NB you need separate VirtualHost blocks to use them!).