R V Williams
27 Redshots Close

R V Williams - Everything 4 IT


Sep 28, 2017

A Peek Inside Apple's MacOS Server 5 Websites

A quick look at the configuration of the Apache server software as implemented by Apple's MacOS Server 5 app.

Posted by:

Apple includes a basic web server with standard MacOS 10.  However this is overridden when Websites is enabled in the MacOS Server app.  This article takes a brief look at some of the aspects of the configuration of Websites.

With each new version of the MacOS Server app, Apple has provided us with fewer and fewer Websites configuration options.  To make any significant configuration changes we need to use the Terminal app.

Use of the Terminal app can cause huge problems if not used with care. Even seasoned professionals who have learnt its mystic arts can be caught out.  Be sure to have a full backup and always make individual backup copies of any files you intend to change.

Apple makes use of two products in the implementation of the webserver.  The first is Apache HTTP Server as used in very many web server implementations.  The second is mod_proxy, an optional module within HTTP Server and allows the HTTP server to act as a proxy.

So what do we mean by a proxy?  There are two distinct meanings, that is forward proxy and reverse proxy.  To quote from the Apache documentation:
"An ordinary forward proxy is an intermediate server that sits between the client and the origin server. In order to get content from the origin server, the client sends a request to the proxy naming the origin server as the target. The proxy then requests the content from the origin server and returns it to the client. The client must be specially configured to use the forward proxy to access other sites."
"A reverse proxy (or gateway), by contrast, appears to the client just like an ordinary web server. No special configuration on the client is necessary. The client makes ordinary requests for content in the namespace of the reverse proxy. The reverse proxy then decides where to send those requests and returns the content as if it were itself the origin."

A forward proxy is often used to overcome certain obstacles such as censorship or to be anonymous.  This latter is different from 'private browsing' that is well documented elsewhere.

Apple uses mod_proxy as a  reverse proxy as a means of implementing Calendar and Profiles which also use the HTTP protocol.

A good place to start delving into the configuration details is the ReadMe.txt file.  Quite often these contain just a few lines; in this case it runs to eight pages and is full of information about the uses of the various configuration files and the way that Apple has implemented the service.

I recommend copying the ReadMe.txt file into your own user folder , where you can read it more easily or print it out.  To do this, open Terminal in the Utilities folder and type the following commands:

cd /Library/Server/web/Config/Apache2/sites
cp ReadMe.txt /Users/yourusername/Desktop/

 The ReadMe.txt file should now be on your Desktop, where you can open it with your favourite word processing app.  Take your time to go through it.

The very many configuration files are present to allow the web server to be used for serving up additional services such as Calendar.

 The sites folder is where all of the websites on this server are defined. If a site is set to use either port 80 or port 443, the site will be automatically included in the proxy server settings as well.  However, if a site is set to use a different port, for example 81, it won't be added to the proxy server settings.  This can have advantages if you don't want the proxy server settings for timeouts and the like to apply.  If you do use a different port, you may have to update the port forwarding settings on your router or firewall.

You may need to add additional configuration statements for your website to operate correctly.  It is perfectly possible to edit your website configuration in the sites folder using your favourite command line editor.  This has a major disadvantage: your additions are very likely to be overridden whenever the Server app is updated.  A more pemanent method of adding configuration statements is through a simple webapp.

A simple webapp consists of two parts.  The first is a file containing the configuration statements you need to add.  The second is a plist file that defines your webapp.

The file of configuration statements may be put anywhere that the web server can access them.  You can put it in /Library/Server/Web/Config/apache2.  Apple suggests using the name httpd.myinclude.conf but you can use any name, preferably ending in .conf.  Another location would be  a folder of your choice in /usr/local/.

There is no choice for the location of the PLIST file.  This must go in /Library/Server/Web/Config/apache2/webapps.  This folder does contain an example (com.example.mywebapp.plist) showing all the options.  An example of a simple plist file might be

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">
	<string>Mysite Updates</string>	
	<key>sslPolicy</key>	<!-- Determines webapp SSL behavior -->
	<integer>0</integer>	<!-- 0: default, UseSSLWhenEnabled -->
			<!-- 1:	UseSSLAlways -->
			<!-- 2:	UseSSLOnlyWhenCertificateIsTrustable -->
			<!-- 3:	UseSSLNever -->
			<!-- 4:	UseSSLAndNonSSL -->

The includeFiles string defines the location of the file of configuration statements you want to add.  My example requires PHP 5.0 but this key and string can be omitted if you don't have any specific module requirements.  The installationIndicatorFilePath defines the file that has to be present for the webapp to appear in the list of webapps available.

Once your webapp is defined, it will show in the Websites section of Server app.  Edit your site details, click Edit Advance Settings and tick the box for your webapp.  Your file of configuration statements will be included after the other generated configuration statements.

Note that if you need to change any of the proxy settings, for example Proxytimeout,  then webapps don't help.  I've found the best solution is to change the port and keep the site out of the proxy server.  If you are reluctant to do this, it is possible to change the proxy settings.  These are located in /Library/Server/Web/config/proxy/apache_serviceproxy.conf.  You'll need to use Terminal and your favourite text editor (pico?) to change this.

Apple calls any sites you add 'custom sites' and 2 Macros are used for all these: one for port 80 and one for port 443.  Search for <Macro to find the definitions for the custom sites and add your changes as appropriate.  Remember to save the file again.  Now to put your changes into action you have to retart the proxy server.  Restarting the Web service doesn't do this.  Instead you need to restart it using Terminal by typing

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

One big drawback to changing the proxy server settings is that this has to be done each time the Server app is updated by Apple.