Expanding Apache s Capabilities with Modules

Understanding Apache Administration

Apache is an extremely large piece of software that has hundreds of configuration options and possible setups. A number of books have been written about Apache. This section looks at the most common attributes that can be configured and how they affect your system. It is not meant to be a complete reference to Apache. Version 2.0 of Apache is available from http://www.apache.org, but it is not yet distributed with Tiger. The current shipping version, 1.3.33, is discussed here.

Controlling the Apache Process

You can start, stop, and restart Apache at any time using the /usr/sbin/apachectl utility. For example, to restart the server, type

 brezup:jray jray $ sudo /usr/sbin/apachectl restart 

TIP

The Start/Stop buttons and check box within the Sharing Preference panel can also be used to start and stop the Apache process.

Table 23.1 documents all the available apachectl options.

Table 23.1. The apachectl Administration Application Accepts These Commands

Options	Functions
start	Starts the Apache server.
stop	Stops the Apache server.
restart	Restarts Apache. This is equivalent to stopping and then starting the server. Current connections are closed.
fullstatus	Displays a full status of the server. This requires lynx to be installed.
status	Displays a summary of the server status. The lynx text browser is required.
graceful	Restarts the server gracefully. Current connections are not dropped.
configtest	Checks the configuration files for errors. Can be used regardless of the current server state.

An interface problem occurs with Apple's use of the Personal Web Sharing metaphor when it is applied to Apache. Each user has his own directory. When web sharing is turned on for one user, it is activated for everyone.

If the computer is a multiuser system and others have the administrative capability to control Apache, you cannot be certain whether web sharing is on or off. The only ways to guarantee that your files aren't being displayed on the Web is to manually disable viewing files using Apache configuration directives, remove the files from your ~/Sites directory, or set their permissions so that they are readable by the owner only.

Apache Configuration File Locations

Apple has done an excellent job of making the Apache web server configuration manageable for machines with large numbers of personal websites. Instead of a single monolithic configuration, like the standard Linux or Windows installation, the server can be configured on two different levels:

Systemwide configuration (path: /etc/httpd/httpd.conf) This is the master configuration file. It contains information about the system as a whole what directories are accessible, what plug-ins are in use, and so on. Changes to the web server as a whole are included here.

User-directory configuration (path: /etc/httpd/users/<username>.conf) When the Tiger Accounts System Preference panel creates a new account, it automatically adds a basic configuration file for that user within the /etc/httpd/users directory. This mini-configuration file determines the security for the web pages within a user's Sites folder.

By splitting up the configuration, the administrator can quickly adjust web permissions on a given account. To edit the user or system configuration, you must either log in (or su) as root or use sudo.

NOTE

Although the user configuration files are stored based on the user's name, they have no real connection to the actual user other than including the path to a personal Sites folder. These files can contain any Apache configuration option, including those that affect other users. The division by username is for ease of editing only.

Basic Apache Configuration Directives

Apache approaches configuration in a very object-oriented manner. The configuration files are XML-like, but not compliant, so don't attempt to edit them using the plist editor. Apache calls each configuration option a directive. The two types of configuration directives are

Global Global directives affect the entire server, everything from setting a name for the web server to loading and activating modules.

Container-based An Apache container is one of a number of objects that can hold web pages. For example, a directory is a container, a virtual host is a container, and an aliased location is also a container. If you don't know what these are, don't worry; we'll get there. For now, just realize that each container can be configured to limit who has access to what it contains, and what pages within it can do.

Global Options

The global options can fall anywhere within the server configuration file. If you're running a heavy-traffic website, you'll definitely want to change the defaults. By default, Apache starts only one server and keeps a maximum of five running at any given time. These numbers do not enable the server to quickly adapt to increased server load.

Table 23.2 documents the some of the most important configuration directives contained in the /etc/httpd/httpd.conf file. They are listed in the order in which you're likely to encounter them in the httpd.conf file.

Table 23.2. Global Apache Directives

Directive	Description
ServerType<standalone|inetd>	The Server type determines how Apache starts. Standalone servers are the default. inetd-based servers use the inetd process to activate a server only when it is accessed. This is inefficient and not recommended for all but the lowest-traffic systems.
ServerRoot <path>	The base path of the Apache binary files.
PidFile <path/filename>	The path (and filename) of the file that should store Apache's process ID.
Timeout <seconds>	The number of seconds that Apache will wait for a response from a remote client. When the time period has expired, the connection will be closed.
KeepAlive <On|Off>	Allows more than one request per connection. This is the default behavior of HTTP/1.1 browsers. Shutting this off might result in a higher server load and longer page load times for clients.
MaxKeepAliveRequests <#>	The maximum number of requests that can be made on a single connection.
KeepAliveTimeout	The number of seconds to wait between requests on a <seconds> single connection.
MinSpareServers <#>	Apache automatically regulates the number of running servers to keep up with incoming requests. This is the minimum number of servers kept running at any given time.
MaxSpareServers <#>	The maximum number of servers that will be kept running when there is no load. This is not a limit on the total number of server processes to start; it limits the number of unused processes that will be kept running to adapt to changes in load.
StartServers <#>	The number of servers to start when Apache is first launched.
MaxClients <#>	The MaxClients directive sets an upper limit on the number of servers that can be started at a given time. Keeping this number low can help prevent denial of service attacks from eating up all system resources. A heavy-volume server should rarely need more than 100.
MaxRequestsPerChild <#>	Some systems have memory leaks. A memory leak is a portion of the system software in which memory usage slowly grows in size. Apache recognizes that memory leaks might exist and automatically kills a server after it has processed a given number of requests, freeing up any memory it was using. The server process is then restarted, fresh and ready to go.
LoadModule <modulename><modulepath>	Loads an Apache module. Many modules will be installed automatically, so you rarely need to adjust anything.
AddModule <modulename.c>	Activates a loaded module.
Port <#>	The port number that the Apache server will use. The standard HTTP port is 80.
User <username>	The user ID under which Apache will run. Apache has the full access permissions of this user, so never, ever, EVER, set this to the root account. Tiger has the user www configured for the purpose of running Apache.
Group <groupname>	The group ID under which Apache will run. Like the User directive, this should never be set to a privileged value. If it is, any broken web applications could compromise your entire computer. You should use the www group for this purpose on Tiger.
ServerAdmin _<Email Address>	The email address of the web server operator.
ServerName <Server Name>	If your server has several different hostnames assigned, use the ServerName directive to set the one that will be returned to the client browser. This cannot be an arbitrary name; it must exist!
DocumentRoot <path to html files>	This defines the path to the main server HTML files. The Tiger default is /Library/WebServer/Documents.
UserDir <name of user's website directory>	The personal website directory within each user's home directory. As you already know, Mac OS X uses Sites; the default used in most Apache installs is public_html. Removing this directive will make individual users to unable to create websites.
DirectoryIndex <Default HTML file>	When a URL is specified by only a directory name, the web server attempts to display a default HTML file with this name.
AccessFileName <Access Filename>	The name of a file that, if encountered in a directory, will be read for additional configuration directives for that directory. Typically used to password-protect a directory. The default name is htaccess.
DefaultType	The default MIME type for outgoing documents. The text/html type should be used to serve HTML files.
HostnameLookups <On|Off>	If activated, Apache stores the full hostname of each computer accessing the server rather than its IP address. This is not recommended for servers with more than a trivial load. Hostname lookups can greatly slow down response time and overall server performance.
TypesConfig <mime-type configuration file>	The path to a file that contains a list of MIME types and file extensions that should be served with that MIME type. For example, the type text/html is applied to files with the .html extension. The default MIME types are located at /private/etc/httpd/mime.types.
LogLevel <level>	One of eight different error log levels: debug, info, notice, warn, error, crit, alert, or emerg.
LogFormat <Log Format><short name>	Defines a custom log format and assigns it to a name. This will be discussed shortly.
CustomLog <Logfilename><short name>	Sets a log filename and assigns it to one of the LogFormat types.
Alias <URL path><server pathname>	Creates a URL path that aliases to a different directory on the server.
ScriptAlias <URL path> <server pathname>	Creates a URL path that aliases to a directory containing CGI applications on the server.
Redirect <old URL> <new URL>	Redirects (transfers) a client from one URL to another. Can be used to transfer between URLs on the same server or to transfer a client accessing a local web page to a remote site.
AddType <MIME-type>_<extension(s)>	Adds a MIME-type without editing the mime.types file.
AddHandler server-parsed <file extension>	Activates server-side includes for files with the specified extension. The default SSI extension is .shtml.
AddHandler send-as-is <file extension>	When activated, files with the defined extension are sent directly to the remote client as is.
AddHandler imap-file<file extension>	Sets the extension for server-side imagemap features. All modern web browsers use client-side image maps, but if you need compatibility with Netscape 1.0 browsers, you need to use server-side maps.
ErrorHandler <error number> <Error Handler>	Sets an error handler from any one of the standard HTML error messages. This will be discussed in greater detail shortly.
Include <directory>	Reads multiple configuration files from a directory. This is set to /etc/httpd/users.

NOTE

Several of the Apache directives refer to the number of server processes that should be started. These processes are subprocesses of the parent Apache process. When you use apachectl to control the server, you are controlling all the Apache processes.

This is only a partial list of commonly used global directives for a complete list, visit Apache's website.

Container Options

The second type of Apache directives are container based. These directives control how Apache serves a certain group of files. Files are chosen based on pattern, location (URL), or directory and are denoted by a start and end tag in the Apache configuration file. For example, the /etc/httpd/users/ configuration files define a container consisting of each user's Sites directory. This is the configuration file created for my jray user account (in my case, that file would be /etc/httpd/users/jray.conf):

 <Directory "/Users/jray/Sites/">   Options Indexes MultiViews   AllowOverride None   Order allow,deny   Allow from all </Directory> 

In this example, the directory /Users/jray/Sites is the container. Web pages within this container can use the Indexes and Multiviews options. The AllowOverride, Order, and Allow directives control who has access to the files within this container. This will be explained in more detail in the "Using Password Protection Features" section later.

Besides a directory container, there are other constructs that can also be added to the configuration file(s):

• Directory Creates a directory-based container. All files within the named directory are part of the container.

• DirectoryMatch Like Directory, but uses a regular expression to match directory names. Check out Chapter 18, "Using Scripting Languages," for an introduction to regular expressions.

• Files Groups files based on their names. All files matching the specified name are included in the container. The filename should be given exactly, or you should use the ? and * wildcards to match a single unknown character or any number of unknown characters.

• FilesMatch Similar to Files, but matches filenames based on a regular expression rather than an exact name.

• Location The Location container is similar to Directory, but matches web content based on a URL, rather than a full-server directory.

• LocationMatch If you've been following along, you'll probably guess correctly that LocationMatch is the same as Location, but matches the URL based on a regular expression.

• VirtualHost The VirtualHost container defines a virtual server within the main server. For external clients, the virtual host appears identical to any other web server. To you, the system administrator, it is a directory on your server that gets its very own domain name. You'll see how this can be set up shortly.

Within the container objects, the administrator can add a number of directives to control access to the contents or what special features are available in that location. Table 23.3 includes the container directives you'll encounter most often. We're going to explicitly set up password protection and virtual hosting shortly because this can be a bit tricky just going on the directive definitions alone.

Table 23.3. Apache Container Directives

Options <Option List>	Sets the special capabilities of the server container. There are eight possible options; each can be preceded by an optional + or to add or remove it.
AllowOverride <All>|<None>| <Directive Type>	Chooses the server-defined directives that a local .htaccess file can override. The .htaccess file is used to apply directives outside of the main Apache server configuration and can be edited by any user with access to the directory. For that reason, it is important to allow only trusted users to override options. None disables all overrides; All allows all server directives to be overridden or specifies a combination of AuthConfig, FileInfo, Indexes, Limit, or Options to allow these directive types to be overridden.
Order <Deny|Allow>, <Deny|Allow> |mutual-failure	Controls the order in which security controls are evaluated whether or not the list of allowed hosts (Allow) or denied hosts (Deny) is checked first.
Allow from <allowed networks|all>	A list of IP addresses, networks and subnets, or domain names that can be allowed access to the resource.
Deny from <allowed networks|all>	A list of IP addresses, networks and subnets, or domain names that should be denied access to the resource.
AuthType <Basic|Digest>	Attaches HTTP authorization password protection to a directory.
AuthName <text string>	Identifies the password-protected resource to the end user.
AuthUserFile _<userfile path>	Sets a path to the userfile being used for basic authentication.
AuthDigestFile <digest userfile path>	Sets a path to the MD5 Digest password file used with Digest authentication.
AuthGroupFile <groupfile path>	Sets the path to a file containing group definitions for use with authentication.
Require user|group|valid-user <user/group list>	Allows only listed users, groups, or any valid user to access a directory. The users and groups are not Tiger users unless you're using mod_auth_apple, which will be discussed shortly. They are created with the htpasswd command.
ErrorDocument <ErrorID><Document `Path>	Used to substitute a custom-error page in place of the default Apache pages. Use the standard HTTPD error codes (such as 404) and a path to the HTML page to display when the error occurs within the given resource.
ServerAdmin	The email address of the administrator of a virtual host.
DocumentRoot	The root-level directory for a virtual host.
ServerName	The fully qualified domain name for a virtual host, such as www.poisontooth.com.

Common Apache Configuration Modifications

To get a handle on configuration, let's take a look at a few different directives in use. Remember that, because of their global nature, global directives can be used anywhere within the /etc/httpd/httpd.conf configuration file, whereas container-based directives must be used within a container as described earlier.

Creating URL Aliases (Global)

As you build a complex web server, you'll probably want to spread files out and organize them using different directories. This can lead to extremely long URLs, such as/mydocuments/work/project1/summary/data/. This URL is a bit bulky to be considered convenient if it were commonly accessed or publicly advertised.

Thankfully, you can shorten long URLs by creating an alias. Aliases work in a manner similar to the Tiger Finder aliases. A short name is given that, when accessed, will automatically retrieve files from another location. To alias the long data URL to something shorter, such as /data/, you would use the following command:

 Alias /data/ /mydocuments/work/project1/summary/data 

Aliases can be used to access files anywhere on the server, not just within the server document root. Obviously, the files in the alias directory need to be readable by the Apache process owner.

Redirecting from One URL to Another (Global)

Websites change. URLs change. For established websites, changing the location of a single page can be a nightmare for users bookmarks break and advertised URLs fail. Although this might seem trivial to experienced web surfers, some users might not be persistent enough to figure out where the page has gone.

Many websites put a redirection page up in place of the missing page. This type of redirection relies on a browser tag to take the user to another URL after a set timeout period. This is effective for most modern browsers, but it takes several seconds between loading the original page and the redirection. In addition, a page needs to be created for each location that might be accessed by the client. This could be hundreds of pages!

A simpler, faster, neater way is to use the Redirect directive. Redirect forces the client browser to transfer to a different URL before the original page even opens. Entire URL structures can be redirected using a single command. The destination URL can even be on a remote server!

For example, if you've decided to move all the files under a URL called /ourcatalog/toys to a new server with the URL www.mynewstoreonline.com/toys, you could use

 RedirectPermanent /ourcatalog/toys http://www.mynewstoreonline.com/toys 

If a user attempted to access the URL /ourcatalog/toys/cooltoy1.html, he would immediately be transferred to http://www.mynewstoreonline.com/toys/cooltoy1.html.

Using redirects is more reliable and transparent for the end user. Avoid using HTML-based redirects, and rely on the Apache RedirectPermanent directive to hide changes in the structure of your website.

Increasing and Customizing Logging Capability (Global)

Apache on Tiger stores its log files in the directory /var/log/httpd. By default, there are two logs: access_log and error_log.

The access_log file contains a record of what remote computers have accessed Apache, what they asked for, and when they did it. For example:

 140.254.85.2 - - [02/September/2003:16:49:47 -0400] "GET /extimage/images/           26_thumb.jpg HTTP/1.1" 200 27012 140.254.85.2 - - [02/September/2003:16:49:47 -0400] "GET /extimage/images/           27_thumb.jpg HTTP/1.1" 200 35793 140.254.85.2 - - [02/September/2003:16:49:47 -0400] "GET /extimage/images/           28_thumb.jpg HTTP/1.1" 200 26141 140.254.85.2 - - [02/September/2003:16:49:47 -0400] "GET /extimage/images/           30_thumb.jpg HTTP/1.1" 200 29316 140.254.85.2 - - [02/September/2003:16:49:47 -0400] "GET /extimage/images/           29_thumb.jpg HTTP/1.1" 200 33626 

This log excerpt shows five requests for .jpg images from the Apache server. Five fields are stored with each log entry:

• Remote Client The machine accessing the Apache web server. In these examples, that client is 140.254.85.2.

• Date and Time A time and date stamp for when the request was made. These five requests were made on September 2, 2003, at 4:49 p.m.

• Request String The actual request that the remote machine made. Most requests begin with GET and are followed by the resource to retrieve, and then the version of the HTTP protocol to retrieve it with. The five requests in the example are for files within the /extimage/images/ directory of the server's documents folder.

• Response Code Identifies how the remote server responded to the request. The code 200 shows that the request was successfully served. A 404, on the other hand, indicates that the request couldn't be satisfied because the resource wasn't found. The response codes for HTTP 1.1 are available from http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html.

• Response Size The number of bytes sent to the remote client to satisfy the request.

NOTE

There are actually seven fields in this log format. The second and third fields contain a - that indicates a value could not be determined. It is unlikely that you'll see values here.

This style of access log is known as the common log format. Log formats are completely customizable using the global LogFormat directive. The common format is defined as

 LogFormat "%h %l %u %t \"%r\" %>s %b" common 

Each of the %h elements denotes an element to be stored in the log file. The \" is an escaped quote, meaning that a quote will also be stored in that location. You can build a log format using the following:

%h Hostname of the requesting computer

%a IP address of the remote computer

%r Request string

%t Time of request

%T Amount of time taken to serve the request

%b Bytes sent

%U URL path requested

%P Process ID of the child that served the request

%>s The last status reported by the server.

%{Referer}i The referring URL (the URL that contained the link to current page)

%{User-Agent}i The string identifies the remote browser

TIP

This is only a partial listing. You can find a complete list of the Apache log elements at http://httpd.apache.org/docs/mod/mod_log_config.html#logformt.

You define a log format by using the LogFormat line, a string containing the format elements, and a name for the file. For example, to define a log called mylog that stores only the hostname of the remote client for each request, you would use

 LogFormat "%h" mylog 

Except for custom solutions, you'll be best served by one of Apache's default log formats. Although the common log is common, it probably isn't the best thing for doing extensive reporting. A better choice is Apache's combined log format. The combined log format includes referer and user-agent strings with each request. Most web analysis packages use the combined log style.

To activate a log format, use the CustomLog directive, followed by the pathname for the log and the log name. To activate the combined log format, uncomment the following line within the /etc/httpd/httpd.conf file:

 CustomLog "/private/var/log/httpd/access_log" combined 

Log files are an important part of any web server. They can provide important data on the popular pages of the server, errors that have occurred, and how much traffic your system is getting. We will look at an easy way to provide log analysis later in "Interpreting Web Server Log Files."

NOTE

The error_log is not shown here because it should contain only startup and shutdown messages. If a security violation or configuration error occurs, it is recorded to this file. In addition, programmers can find detailed information about program errors written to this location.

Using Password Protection Features

Password-protecting a directory is extremely simple. For example, suppose that a user wants to password-protect his entire public website for development purposes. The first step is to set up a username and password file that will contain the login information for those who are allowed to access the resource. This is accomplished using htpasswd. There are two steps to the process: First, create a new password file with a single user; second, add additional usernames/passwords to it.

To create a new file, use the syntax htpasswd -c <pathname> <initial username>. For example,

 brezup:jray jray $ htpasswd -c /Users/jray/webpasswords jray New password:  Re-type new password:  Adding password for user jray 

A new password file (/Users/jray/webpasswords) is created, and the initial user jray is added.

Subsequent users can be added by calling htpasswd -b <pathname><username> <password>:

 brezup:jray jray $ htpasswd -b /Users/jray/webpasswords testuser testpass Adding password for user testuser 

The password file now has two entries: the initial jray user, and testuser.

Next, create a directory container that encompasses the files that need to be protected. Because this example is protecting a personal website, the container already exists as a <username>.conf file in /etc/httpd/users:

 <Directory "/Users/jray/Sites/">   Options Indexes MultiViews ExecCGI   AllowOverride None   Order allow,deny   Allow from all </Directory> 

NOTE

This file from this example has been modified slightly since the initial Tiger installation. The options directive includes ExecCGI to enable CGI development to take place.

To this directory container, add AuthType, AuthName, AuthUserFile, and Require directives. You must be root or using sudo to edit the file:

 <Directory "/Users/jray/Sites/">   AuthType Basic   AuthName "John's Development Site"   AuthUserFile /Users/jray/webpasswords   Require valid-user   Options Indexes MultiViews ExecCGI   AllowOverride None   Order allow,deny   Allow from all </Directory> 

The AuthUserFile is set to the name of the password file created with htpasswd, whereas the Require valid-user directive allows any user in the password file to gain access to the protected resource. To activate the authentication, use sudo /usr/sbin/apachectl restart:

 brezup:jray jray $ sudo /usr/sbin/apachectl restart /usr/sbin/apachectl restart: httpd restarted 

Attempting to access the /Users/jray/Sites directory (~jray) now opens an HTTP authentication dialog, as seen in Figure 23.2.

Figure 23.2. The directory is now password-protected.

Authenticating Against User Accounts with mod_auth_apple

Using the basic Apache authentication is fine in many cases, but you might find yourself wanting to protect resources based on actual user accounts on your computer. Although it's simple enough to create a password file for each user, these passwords will not be updated as users update their Tiger passwords. The real solution is to provide an authentication mechanism by which resources could be protected by actual system accounts and system passwords. This is entirely possible courtesy of Apple's mod_auth_apple Apache module.

Included with Tiger Server by default, Tiger client users can download and install mod_auth_apple with very little trouble. There are two components to the install: First, a missing header file Security/checkpw.h must be copied from the Darwin CVS repository or mirror, and then the source code for mod_auth_apple can be downloaded and installed.

The header file can be downloaded directly from Apple at http://developer.apple.com/darwin/projects/darwin/darwinserver/, but you'll need to register before downloading. Alternatively, download the header from http://www.opendarwin.org/cgi-bin/cvsweb.cgi/src/Security/checkpw/. After downloading, make a new directory /usr/include/Security, and copy the header file to the new location:

 brezup:jray jray $ curl -O "http://www.opendarwin.org/cgi-bin/cvsweb.cgi/~checkout~/src /Security/ checkpw/checkpw.h" brezup:jray jray $ sudo mkdir /usr/include/Security brezup:jray jray $ sudo mv checkpw.h /usr/include/Security/ 

Next, download the latest mod_auth_apple package from http://developer.apple.com/darwin/projects/darwin/darwinserver/, unarchive it, and then enter the source distribution directory. (Note: To download mod_auth_apple, you will need to create an Apple ID if you don't already have one.)

 brezup:jray jray $ tar zxf mod_auth_apple-XS-10.3.tgz brezup:jray jray $ cd mod_auth_apple 

Be sure to check the Apple README file for installation instructions; they might change between versions. The instructions shown here are modified from Apple's directions so that the software configures automatically. Use make followed by sudo apxs -i -a mod_auth_apple.so to compile and install the module:

 brezup:jray mod_auth_apple $ make /usr/sbin/apxs -c -Wc,"-traditional-cpp -Wno-four-char-constants   -F/System/Library/PrivateFrameworks -DUSE_CHKUSRNAMPASSWD"   -Wl,"-bundle_loader /usr/sbin/httpd -framework Security"   -o mod_auth_apple.so mod_auth_apple.c gcc -DDARWIN -DUSE_HSREGEX -DUSE_EXPAT -I../lib/expat-lite   -g -Os -pipe -DHARD_SERVER_LIMIT=2048 -DEAPI -DSHARED_MODULE   -I/usr/include/httpd -traditional-cpp -Wno-four-char-constants   -F/System/Library/PrivateFrameworks -DUSE_CHKUSRNAMPASSWD -c mod_auth_apple.c ... brezup:jray mod_auth_apple $ sudo apxs -i -a mod_auth_apple.so [activating module 'apple_auth' in /private/etc/httpd/httpd.conf] cp mod_auth_apple.so /usr/libexec/httpd/mod_auth_apple.so chmod 755 /usr/libexec/httpd/mod_auth_apple.so cp /private/etc/httpd/httpd.conf /private/etc/httpd/httpd.conf.bak cp /private/etc/httpd/httpd.conf.new /private/etc/httpd/httpd.conf rm /private/etc/httpd/httpd.conf.new 

The mod_auth_apple module is now compiled and installed. Using it is identical to the examples we've already seen for Basic authentication, except no password file is needed. For example, to protect my Sites directory so that only my account (jray) can access it, I would use the following in my /etc/httpd/users/jray.conf file:

 <Directory "/Users/jray/Sites/">   AuthType Basic   AuthName "John's Development Site"   Require user jray   Options Indexes MultiViews ExecCGI   AllowOverride None   Order allow,deny   Allow from all </Directory> 

To verify against any account on the machine, replace Require user jray with Require valid-user. Alternatively, to validate against a group, Require group <groupname> could be employed.

CAUTION

The authentication methods shown here uses Basic authentication, which passes clear-text information (usernames/passwords) over the network. A more secure form, called Digest authentication, is also available, which encrypts passwords before sending them. In addition, Apple offers a digest form of its authentication module that you can use to gain a bit of security. (See http://httpd.apache.org/docs/howto/auth.html#digest for more information on Digest authentication.)

Unfortunately, Digest authentication should not be considered truly secure because the encrypted password itself is sent as plaintext and could simply be provided to the remote server to authenticate. To truly be secure, you'll need SSL support, which is covered in the Mac OS X Tiger Unleashed supplement Enabling Apache SSL Support, downloadable at http://www.macosxunleashed.com/downloads/apachessl.pdf.

Restricting Access by Network

To create more stringent control over the users who can access a given resource, use Allow and Deny to set up networks that should or shouldn't have access to portions of your website. This is extremely useful for setting up intranet sites that should only be accessible by a given subnet. For example, assume that you want to restrict access to a resource from everyone except the subnet 192.168.0.x. The following rules define the access permissions:

 Allow from 192.168.0.0/255.255.255.0 Deny from all 

Because there isn't an ordering specified, what really happens with these rules is ambiguous. Is the connection allowed because of the allow statement? Or denied because all the connections are denied?

To solve the problem, insert the Order directive:

 Order Deny,Allow Allow from 192.168.0.0/255.255.255.0 Deny from all 

With this ordering, an incoming connection is first compared to the deny list. Because all access is denied by default, any address matches this rule. However, the Allow directive is used for the final evaluation of the connection and will allow any connection from the network 192.168.0.0 with the subnet 255.255.255.0.

Using different orderings and different Allow/Deny lists, you can lock down a website to only those people who should have access, or disable troublesome hosts that misuse the site.

TIP

As with any change to the Apache configuration file, you must use sudo /usr/sbin/apachectl to restart the server.

An alternative to restarting is to add an .htaccess file to the directory you want to protect. This file can contain any of the standard directory container directives and will be automatically read when Apache attempts to read any file from the directory.

Creating Virtual Hosts

A virtual host is a unique container object, in that it can define an entirely separate web space unrelated to the main Apache website or user sites. For example, the three domains poisontooth.com, vujevich.com, and shadesofinsanity.com are all being served from a single computer. To the end user, these appear to be different and unique hosts. To Apache, however, they're just different directories on the same hard drive.

There are two types of virtual hosts name-based and IP-based as described in the following list:

Name-based These hosts rely on the HTTP/1.1 protocol to work. A single IP address is used on the server, but there are multiple DNS name entries for that single address. When connecting to the server, the client browser sends a request for a web page, along with the name of the server it should come from. Apache uses that information to serve the correct page. This works for all but the oldest 2.0 revision browsers.

IP-based These hosts rely on Apache's capability to listen to multiple IP addresses simultaneously. Each domain name is assigned to a different IP address. Apache can differentiate between the different incoming addresses and serve the appropriate documents for each. This works on any browser, but is costly in terms of the IP addresses that it consumes.

To set up a virtual host, you must first have an IP address and a domain name assigned for the host. If you're using name-based hosts, you will have a single IP address but multiple hostnames. Your ISP or network administrator should be able to help set up this information.

TIP

Tiger users who are attempting to configure IP-based virtual hosts will need to assign multiple IPs to an interface by duplicating their existing network interfaces within the Network System Preference pane.

Alternatively, additional IPs can be added from the command line by using ifconfig <interface> alias <additional IP address> 255.255.255.255. For most single-network-card systems, the interface will be en0. AirPort cards are usually identified with en1. For example:

 sudo ifconfig en0 alias 192.168.0.200 255.255.255.255  

This adds the IP address 192.168.0.200 as an additional address to the Tiger system. Aliases added in this manner will have to be included in a startup file such as /etc/rc to activate at boot.

There are only two differences in the Apache configuration of name-based and IP-based virtual hosts. Name-based hosts must include the NameVirtualHost directive, whereas IP-based hosts will need to use Listen to inform Apache of all the available addresses.

Let's take a look at two different ways to configure the virtual hosts www.mycompany.com and www.yourcompany.com. First, we'll use named-based hosting.

Assume that both mycompany and yourcompany domain names point to the IP address 192.168.0.100. To configure name-based virtual hosts, you could add the following directives to the end of the /etc/httpd/httpd.conf file:

 NameVirtualHost 192.168.0.100 <VirtualHost 192.168.0.100>     ServerName www.mycompany.com     DocumentRoot /Users/jray/mycompany     ServerAdmin [e-mail] </VirtualHost> <VirtualHost 192.168.0.100>     ServerName www.yourcompany.com     DocumentRoot /Users/jray/yourcompany     ServerAdmin [e-mail] </VirtualHost> 

The NameVirtualHost sets up the IP address that Apache will expect multiple domain name requests to come in on. The two VirtualHost directives define the basic properties of the two sites: what their real domain names are, where the HTML documents are loaded, and the email address for the person who runs the site.

Creating this same setup using IP-based hosts doesn't require much additional effort. For this sample configuration, assume that www.mycompany.com has the address 192.168.0.100 and that www.yourcompany.com uses 192.168.0.101. The configuration becomes

 Listen 192.168.0.100 Listen 192.168.0.101 <VirtualHost 192.168.0.100>     ServerName www.mycompany.com     DocumentRoot /Users/jray/mycompany     ServerAdmin [e-mail] </VirtualHost> <VirtualHost 192.168.0.101>     ServerName www.yourcompany.com     DocumentRoot /Users/jray/yourcompany     ServerAdmin [e-mail] </VirtualHost> 

This time, the Listen directive is used to tell Apache to watch for incoming web connections on both of the available IP addresses. The VirtualHost containers remain the same, except they now use different IP addresses for the two different sites.

Virtual hosting provides an important capability to the web server. Although available with a GUI configuration tool in Tiger Server, the Apache distribution included in the standard version of Tiger is every bit as powerful. It just takes a bit of manual editing to get things done!