Automatic Let’s Encrypt certificates in Apache with mod_md

Since 2.4.30, Apache comes with experimental support for ACME certificates (Let’s Encrypt et al.) in the form of mod_md (short for “managed domains”). It’s kind of a pain but it’s still better than what I had before, i.e. a mess of shell and Perl scripts based on Crypt::LE, and if your use case is limited to Apache, it appears to be simpler than Certbot as well. Unfortunately for me, it’s not very well documented and I wasted a considerable amount of time figuring out how to use it. Fortunately for you, I then decided to blog about it so you don’t have to repeat my mistakes.

Edit: the author of mod_md, Stefan Eissing, got in touch and pointed me to his own documentation, which is far superior to the one available from Apache.

My starting point is a freshly installed FreeBSD 13.0 server with Apache 2.4, but this isn’t really OS dependent.

First, you will need mod_ssl (of course) and a session cache, and you will need to tweak the TLS parameters, as the defaults are far from fine.

LoadModule ssl_module libexec/apache24/mod_ssl.so
SSLProtocol +TLSv1.3 +TLSv1.2
SSLCipherSuite TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
SSLHonorCipherOrder off
SSLCompression off

LoadModule socache_dbm_module libexec/apache24/mod_socache_dbm.so
SSLSessionCache dbm:/var/db/httpd_ssl_cache.db

You will also need to load mod_md, of course, and mod_watchdog, which mod_md needs to function.

LoadModule watchdog_module libexec/apache24/mod_watchdog.so
LoadModule md_module libexec/apache24/mod_md.so
MDCertificateAgreement accepted
MDContactEmail acme@example.com

The MDCertificateAgreement directive indicates that you have read and accepted Let’s Encrypt’s subscriber agreement, while MDContactEmail is the email address that you used to sign up to Let’s Encrypt.

You will also need mod_rewrite to redirect HTTP requests to HTTPS and mod_headers for HSTS.

LoadModule rewrite_module libexec/apache24/mod_rewrite.so
LoadModule headers_module libexec/apache24/mod_headers.so

By default, Apache only listens on port 80, so you’ll need an extra Listen directive for port 443.

Listen 443

And as always with Apache, you should probably set ServerName and ServerAdmin to sensible values.

ServerName server.example.com
ServerAdmin www@example.com

Next, set up an HTTP-only virtual host that you can use to check the status of mod_md.

<VirtualHost *:80>
  ServerName localhost
  <Location />
    Require ip 127.0.0.1/8 ::1
  </Location>
  <Location "/md-status">
    SetHandler md-status
  </Location>
</VirtualHost>

(Once Apache is running, you will be able to query it at any time as http://localhost/md-status.)

On to the actual website. First, you need to tell mod_md to manage certificates for it.

MDomain site.example.com

Next, set up a redirect from HTTP to HTTPS for everything except ACME challenge tokens.

<VirtualHost localhost:80>
  ServerName site.example.com
  RewriteEngine on
  RewriteRule "^/(?!.well-known/acme-challenge)(.*)" https://site.example.com/$1 [R=301,L]
  ErrorLog /www/site.example.com/logs/http-error.log
  CustomLog /www/site.example.com/logs/http-access.log combined
</VirtualHost>

And finally, the site itself, including HSTS and strict SNI:

<VirtualHost *:443>
  ServerName site.example.com
  SSLEngine on
  SSLStrictSNIVHostCheck On
  Header always set Strict-Transport-Security "max-age=15552000; includeSubdomains;"
  DocumentRoot /www/site.example.com/data
  IncludeOptional /www/site.example.com/etc/*.conf
  ErrorLog /www/site.example.com/logs/https-error.log
  CustomLog /www/site.example.com/logs/https-access.log combined
</VirtualHost>

Now start Apache and monitor the error log. You should see something like this pretty quickly:

[Sun Oct 10 16:15:27.450401 2021] [md:notice] [pid 12345] AH10059: The Managed Domain site.example.com has been setup and changes will be activated on next (graceful) server restart.

Once you do as it says (apachectl graceful), your site will be up and running and you can head over to the Qualys SSL Server Test and admire your solid A+.

Download the sample configuration and try it out yourself.

Leave a Reply

Your email address will not be published. Required fields are marked *

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax

 

This site uses Akismet to reduce spam. Learn how your comment data is processed.