Project92.Configure Apache

Project 92. Configure Apache

"How do I enable Apache to serve the main Web site from my home directory?"

This project shows you how to configure the Apache Web server that is part of a standard Mac OS X install. It describes how to start and stop Apache, and how to change the document root. Project 93 shows you how to enable features such as PHP support, server-side includes (SSI), and CGI (Common Gateway Interface) scripts. This project assumes that you are familiar with the concept of a Web server and are able to write simple HTML files.

Set Up Your Own Web Server

Apache is an open-source Web server (more strictly, an HTTP server) maintained by the Apache Software Foundation (www.apache.org). Apache is supplied as part of Mac OS X, so you can serve Web pages straight out of the box. It's easy to start Apache from System Preferences: Select the Sharing pane, click the Services tab, and check Personal Web Sharing. Use the Computer Name at the top of the Sharing pane in place of computer-name in the examples below.

The default configuration has Apache serving documents from the directory /Library/Webserver/Documents. Users can view the Web site from a Web browser by entering one of the following URLs.

• http://computer-name.local/

• http://localhost/

• http://127.0.0.1/

In addition to the main site, each user account has a personal Web presence. The user saruman, for example (we'll assume this user throughout the rest of the project), maintains a personal Web site at /Users/saruman/Sites (~/Sites), accessible by entering the URL

• http://computer-name.local/~saruman/

Try these example URLs now. If you've enabled Personal Web Sharing, you'll see a placeholder Web site answering to your Mac's IP address or hostname, plus a Web site answering to each user account. Note that the main site looks different from the personal sites; you'll need to remember this for later.

Learn More

Refer to "How to Become the Root User" in Project 2 for more information about the sudo command.

Configuration of Apache from System Preferences is limited to turning Apache on and off. That's a shame, because Apache is a very powerful and highly configurable server. However, and as you might have guessed, we can configure Apache and take full advantage of its many features from the Unix command line. Let's look at a few examples of what we can achieve.

Learn More

Refer to Chapter 4 if you are not familiar with any of the Unix text editors.

The Apache daemon, which runs as httpd, is owned by the root user. The Apache configuration file is also owned by root. For the remainder of this project, we'll assume the status of the root user by issuing the command

$ sudo -s Password: #

Start and Stop Apache

We can enable, start, stop, and restart Apache from the command line. First, let's enable Apache. Once it's enabled, Apache will start automatically every time your Mac boots.

Edit the file /etc/hostconfig, using a Unix text editor such as nano. Look for a line that starts with WEBSERVER, and set it to equal -YES-

WEBSERVER=-YES-

Reboot your Mac, and Apache will start automatically.

To disable Apache at startup, set

WEBSERVER=-NO-

Alternatively, to start Apache at any time, no matter what WEBSERVER is set to, type

# apachectl start

To stop Apache, type

# apachectl stop

Tip

The file /etc/hostconfig enables other services, such as Personal File Sharing and Windows Sharing. As for Personal Web Sharing, these setting are honored when your Mac boots, but changing them during normal operation will have no effect.

Configure Apache

All Apache configuration directives you'll want to change are in a single file called /etc/httpd/httpd.conf. We'll be editing this file throughout the project. Remember to edit it as the root user.

Tip

If you maintain a live Web site and don't want to disrupt the experience of clients who may already have connections, restart Apache gracefully by typing

# apachectl graceful

Change the Document Root

Changing the document root is a common configuration requirement. The document root tells Apache where you've placed the HTML files that make up the main Web site. In a standard configuration, the document root is the directory /Library/WebServer/Documents.

Let's change it to the Sites directory in our home directory. Edit the file /etc/httpd/httpd.conf, and search for the DocumentRoot directive. You'll find it currently naming the default directory root.

DocumentRoot "/Library/WebServer/Documents"

In the examples that follow, we assume the username saruman, but you should type your own username. Replace the line above with the following line.

DocumentRoot "/Users/saruman/Sites"

There's one more change we must make. The document root must be configuredpermissions and options setby a Directory directive. We'll see some examples of changing options in Project 93. For now, locate the current setting that configures the old document root.

<Directory "/Library/WebServer/Documents">

Replace it with this one, which configures the new document root.

<Directory "/Users/saruman/Sites">

Learn More

Projects 7 and 8 cover users, groups, and permissions.

Don't change any of the actual settingsjust the name of the document root specified in the Directory directive. The Directory directive is brought to a close by the following line.

</Directory>

Always ensure that Apache, which runs under the user and group www, has read access to the files it is supposed to serve. This is best achieved by granting read permission (but not write permission) to others.

Tip

Lines in the configuration file that start with the hash ( # ) symbol are comments, and Apache ignores them. When changing the file, you might want to leave the original lines in but comment them out by preceding them with a hash.

Remove Clashing Sites

The last line of the configuration file is

Include /private/etc/httpd/users/*.conf

This line loads several additional configuration files into Apache to configure the document root for each user's personal Web site. The user saruman's personal Web site now clashes with our new main document root (because we just set the main document root to be /Users/saruman/Sites), so we must remove the file /etc/httpd/users/saruman.conf.

Alternatively, we could serve the main site from a different directory, such as ~/MainSites. You may also remove the entire <Directory "/Users/saruman/Sites"> directive from the main configuration file and maintain the version in the file saruman.conf, but be warned that this represents a more advanced configuration task that may cause you problems.

Test the New Configuration

First, because we changed the configuration file, we must restart Apache by typing

# apachectl restart

Reload the main Web site from the URL http://computer-name.local/. Click the browser's reload button to ensure that it does not display a cached page. If everything has worked correctly, you'll see a new main Web site that sports the same look as the personal Web site. That wasn't our intention; we'd now replace the placeholder Web site with a real Web site. Our intention was to be able to populate the directory ~/Sites instead of /Library/Webserver/Documents.

Personal Web Sharing Document Roots

The document root for personal Web sites (those with URLs in the form http://computer-name.local/~username/) is controlled by the UserDir directive, not by the DocumentRoot directive.

If the changes have not worked, check Apache's log files, as described in the next section.

Tip

Sometimes, a browser's caching habits obscure configuration changes made to Apache. If you make a configuration change that appears to have no effect, click the reload button.

Check Apache's Log Files

Apache writes information to two log files, often used to monitor hits on your site or debug configuration changes. You'll find Apache's log entries in the two files

/var/log/httpd/access_log /var/log/httpd/error_log

View them with the tail command by typing

$ tail -f /var/log/httpd/access_log

Learn More

Project 21 explores the tail command.

Tip

Read the Apache manual at the URL http://localhost/manual/. Don't leave out the trailing forward slash when entering the URL.