Tweaking the Server 5 Apache Proxy to Handle HTTPS Sites Correctly

Photo of Greg
Photo by powazny - http://flic.kr/p/6L58iP

With version 5 of the Server app for OS X, Apache has problems correctly delivering TLS-enabled sites that use aliases, for example wrongly sending the ‘www’ variant of a site to the server’s default site. Here’s how to fix it.

Under the new proxied architecture introduced in Server 5, it is only the proxy which ever speaks securely to the outside world; internal connections between the proxy itself and the separate Apache instance serving up web pages are not secure (and don’t need to be). This means that any leftover SSL directives in files contained in the main Apache config directory are superfluous, but those in the following two configuration files are crucial:

/Library/Server/Web/Config/Proxy/apache_serviceproxy.conf
/Library/Server/Web/Config/Proxyapache_serviceproxy_customsites.conf

That second file in particular, which is rebuilt with reference to servermgr_serviceproxy_customsites.plist whenever the Server app is used to add or remove an SSL-enabled site, for example, contains a concatenated batch of all the SSL-enabled virtual hosts the proxy will answer for.

In an ordinary virtual host configuration file, we’re accustomed to seeing ServerAlias directives that list any additional names for a given site — such as www.example.com or *.example.com for a site named example.com. These additional aliases let Apache know how to respond to requests for those aliases. Not so for the VirtualHost containers in apache_serviceproxy_customsites.conf: inexplicably, ServerAlias is nowhere to be seen. What that means is that if you’ve configured a TLS site in Server app with the name example.com and the alias www.example.com, the proxy will not direct requests to the correct virtual host — instead, the requests will be directed to the server’s default site.

There are two different ways of tackling the problem, each with advantages and disadvantages. One is to go back and add full site definitions in Server app for every allowable name for each of your sites — for example adding www.example.com as a whole new site in addition to example.com. This ensures the server will respond only to those names you specify, but it is also fiddly and inefficient, and I believe it is liable to create more maintenance work down the line.

The alternative fix is to ensure that all your main site definitions use the root domain, such as example.com, and have any subdomains like www.example.com set as an alias, and then add a new line to the following in servermgr_serviceproxy_customsites.plist:

	<array>
		<string>ServerName ${SERVERNAME}:443</string>
	</array>

These can be modified to include an explicit reference to aliases covering all subdomains for a given domain:

	<array>
		<string>ServerName ${SERVERNAME}:443</string>
		<string>ServerAlias *.${SERVERNAME}</string>
	</array>

This modification will ensure that whenever apache_serviceproxy_customsites.conf gets rebuilt, every example.com site will include a ServerAlias directive telling Apache to respond to all *.example.com requests. The advantage of this method is that a single line of code inserts all the missing ServerAlias directives, but on the other hand you may not want a given domain to respond to all possible subdomains — and the site’s certificate might not cover each of those subdomains. (It’s easy enough to specify www. rather than *., of course, but that only works if your only aliases are of the www. type.)

It’s also possible just to add the relevant ServerAlias directives directly to apache_serviceproxy_customsites.conf and then restart the proxy with the following:

sudo /Applications/Server.app/Contents/ServerRoot/usr/sbin/serviceproxyctl restart

Keep mind, however, that changes made directly to the configuration file itself, as distinct from the .plist, will be overwritten the next time the file is rebuilt.

Finally, it’s worth mentioning that it’s even more important than usual with the Apache proxy to avoid making typos when editing files like apache_serviceproxy_customsites.conf. A single typo can take down the proxy and either prevent it from restarting at all or send it into a loop which persists even after the typo has been fixed. If it happens that your proxy .plist has been returned to working order after a typo, but the proxy is still stuck in a loop, it’s important to check the logs immediately to see exactly what’s going on. If you see repeated messages saying “Pass phrase incorrect for key…” followed by a site name, it may be necessary to run through each site in the Server app individually and re-select that site’s certificate in order to get the proxy up and running correctly again.

All material on this site is carefully reviewed, but its accuracy cannot be guaranteed, and some suggestions offered here might just be silly ideas. For best results, please do your own checking and verifying. This specific article was last reviewed or updated by Greg on .

This site is provided for informational and entertainment purposes only. It is not intended to provide advice of any kind.