Mac OS X Server Tips: Apache and Virtual Hosts

Both Mac OS X client and Mac OS X Server include the Apache Web Server. Apache on various platforms includes virtual hosting capabilities — the ability to have several distinct web sites on a single host with a single IP address — and the following discusses how to set up and troubleshoot and manage Apache virtual hosting on Mac OS X Server.

This article discusses Mac OS X Server. Here is a discussion of Apache on OpenVMS.

The example directory paths shown in the text of article are from 10.6. You'll need to adjust those for your particular OS X Server environment, whether on 10.6 or later. If you're using more current OS X Server software and Server.app from (for instance) 10.9 Mavericks, then the Apache web site directories will usually be located under the /Library/Server/Web/Sites/Data directory.

Setting up the Virtual Host

Use Server Admin to set up the reference to the virtual host directory; to the appropriate local directory.

Start with the virtual host directory to your same particular disk directory for the working Apache host. This configuration should allow you to have two host names landing in one virtual directory; two different hosts having the same files.

If you have a wildcard host specified within Server Admin, you'll (usually) want to disable that, and add explicit host names. (The wildcard host captures everything that misses the other arriving host names.) Different hosts referencing the same web directories are permissible; alias names are allowed.

If you're using a different directory area entirely, you will have to carefully review the protections; both to allow Apache access into the area, and to prevent Apache from reaching further than minimally necessary. This to reduce the exposures should Apache or one of your components (local code written in php, Python, Perl, Ruby, Lua, Java or otherwise) becomes breached. It's best to stay underneath the default web directory /library/webserver/documents when you're just getting going.

Verifying File and Directory Ownership

On Mac OS X Server, the Apache Web Server runs under one of the various “hidden” users present in Mac OS X and Mac OS X Server, and specifically under the www user. This (and the other “hidden” users) will not be visible in the default Workgroup Manager (WGM) and System Preferences > Accounts displays, but are visible to Unix-level users and the Terminal.app environment.

The Apache web directory is usually in or somewhere underneath /library/webserver/documents directory. (By default, Apache will not allow access to random parts of your volume structure, nor should you override this and allow access. It is best to keep to specific directories, as that can contain the scope of damage that an Apache web server breach can produce.)

To create a new web, use the mkdir command, and usually a command sequence akin to the following:

$ cd /library/webserver/documents
$ sudo mkdir NewSiteFolder

Once the NewSiteFolder directory is created, the security configuration of your web directory is key both to the operation of and the security of Apache on OpenVMS, and to virtual hosting.

The usual ownership for files avoids having anything (beyond what is strictly necessary) writable by the web server; the default directories should not be writable by Apache. On Mac OS X Server, the Apache user is usually represented by the www or _www user identifier.

To list the protection and ownership of the files in your existing web directory, launch Terminal.app and issue the following bash commands:

$ cd /library/webserver/documents/
$ ls -al 

or

$ cd /library/webserver/documents/{yourwebdirectory}
$ ls -al 

Look for the file owner and group setting, and at the file and directory and volume protections. Yes, these are a little cryptic; I tend to use the Unix interfaces. (If you prefer, you can use the Get Info stuff at the GUI here to change the settings; check the help text for Mac OS X here.)

Changing File and Directory Ownership

To change the file ownership and file protections settings, move to your new directory, and change the ownerships to match the existing web directories. The commands are akin to the following:

cd /library/webserver/documents/{yourotherwebdirectory}
sudo chown owner:user file
sudo chmod -R u=rwx,go= file

With the use of sudo, you'll have to specify a root password. If you're working with a whole bunch of files in a directory, you can use the recursive option to change everything. First make sure your "aim" is correct with la -alR (adjust the target specification until you see only the files you want changed), then the recursive chown and chmod commands to reset everything:

ls -alR fileordir
sudo chown -R owner:user fileordir
sudo chmod -R u=rwx,go= fileordir

You might see something akin to:

sudo chown root:www file

To set the ownership to the root user, and www to the group. This to prevent the www user from modifying or deleting the file.

You'll want to change the ownership on the parent directory for your web directory to match, too.

Why Protections and Ownerships?

Here's some related reading on getting hacked, and how you can reduce the chances of that by having your file ownerships and file protections set appropriately. Having the web server able to write to (most of) the web directories is usually a bad idea. You'll want to restrict ownership and write access, as described in the article. One option here is ownership by root, and web (www, _www) group membership.

DNS and Virtual Hosts

DNS is not relevant to virtual hosts. This is a bit tricky when you first encounter it, so I'll provide a few details on the sequence of events here. Assume that a web browser is asked to view, say, foo.example.com, so the web browser and the client operating system underneath the browser will ask the client-configured DNS server to translate foo.example.com into an IP address. Some DNS server and usually one located at the provider you've contracted DNS services with translates that name into an IP address (authoritatively), and returns it to the client. The browser and the client then route the web traffic to that IP address without further regard to the IP host name. At the level of the network traffic, there is no IP host name. Just the IP host address.

Now for the tricky part: within the http design (within the web protocol itself), the web browser client also passes along the name of the target web server. In the http traffic. In parallel. This means that the packet and the web traffic arrives at the target host by the DNS IP address translation and the host address, but the web server can look into the http traffic and see which was the target host name selected. Which means the web server and its virtual hosting capabilities are entirely unrelated to the DNS stuff. If the web client asked for foo.example.net and got back the same IP address as the previous case, the connection would work the same, though the web server would receive a different target host name in the http traffic, and could process it as a separate virtual host.

Confusing? Yes. But the web server gets a text string, and uses that to figure out which virtual host it should serve up to the request. Which means that DNS is not involved in the particular implementation of Apache virtual hosting. Verstehen Sie?

http 403 forbidden errors

An http 403 error means you're getting somewhere, and getting a "forbidden" response back from that web server. Check the Apache server logs on your web server, and see if you find matching arriving web traffic; see if the traffic is landing on your own web server. Then confirm that the files, directories and disk volumes are accessible.

The default path for the web directory for the default configuration is usually:

$ ls -al /library/webserver/documents/

And if you have a couple of web sites beyond the default, you might have (say) two directories:

ls -al /library/webserver/documents/this
ls -al /library/webserver/documents/that

For More Information

The Apple Web Technologies manual is a part of the Mac OS X Server documentation set and is a reasonable introduction to the configuration sequence.

For details on modules such as mod_rewrite or mod_security and other modules, and on Apache in general, see the Apache web site.

For assistance with configuring and operating Apache, contact HoffmanLabs.