the codingmerc llc

application programming expert for hire

.well-known directory access prevented by Mac OS X Server Proxy update

The .well-known directory is part of several conventions for web services. I recently updated my 10.9 Mac OS X server version 4 to 10.11 version 5 and a whole lot of things changed under the hood. One of which is that now there are 2 apache instances running. One serves as a proxy to sites and services delivered by the second apache process or other process.

Let’s Encrypt

Using Let’s Encrypt to acquire widely accepted SSL certificates for my hosted sites and services before it was enough to just run

/letsencrypt-auto certonly --webroot

to validate access. Under the hood, the toolchain would create an acme challenge file in a directory called .well-known located in the servers web root directory. With the servers new proxy however traffic would be redirected to the calendar service who serves up a different content than our web root and in turn the tool would fail to verify access to the domains.

Fixing .well-known access

The fix is fairly robust: If we look at the last line of the proxy configuration file /Library/Server/Web/Config/Proxy/apache_serviceproxy.conf it looks something like this:

# *customsites*
IncludeOptional /Library/Server/Web/Config/Proxy/apache_serviceproxy_customsites*.conf

That means that we can create custom configurations that would not get overwritten every time we use the to change any configuration!

I created the following file


and it contains the following content:

ProxyPass /.well-known/acme-challenge
ProxyPassReverse /.well-known/acme-challenge

This should let the proxy server instance pass all access to the acme-challenge folder to the apache instance hosting my websites where access to the .well-known folder still redirects to the calendar server.

Restart Proxy Server

The proxy server is not exposed through the UI and doesn’t restart together with the Webserver instance. One can restart the proxy through the command line though by issuing the following commands:

sudo launchctl stop
sudo launchctl start

Now Let’s encrypt should be able to access the acme-challenge folder in the .well-known directory and the calendar service should still be able to rely on his portion of said folder functionality. 

© 2023 the codingmerc llc