Apache Cookbook | O'Reilly Media

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

For this cookbook to be useful, you need to install the Apache web server software. So what better way to start than with a set of recipes that deal with the installation?

There are many ways of installing this package; one of the features of open software like Apache is that anyone may make an installation kit. This allows vendors (such as Debian, FreeBSD, Red Hat, Mandrake, Hewlett-Packard, and so on) to customize the Apache file locations and default configuration settings so that these settings fit with the rest of their software. Unfortunately, one of the consequences of customization is that the various prepackaged installation kits are almost all different from one another.

In addition to installing it from a prepackaged kit, of which the variations are legion, there's always the option of building and installing it from the source yourself. This has both advantages and disadvantages; on the one hand you know exactly what you installed and where you put it, but on the other hand, it's likely that binary add-on packages will expect files to be in locations different than those you have chosen.

If setting up the web server is something you're going to do once and never again, using a packaged solution prepared by your system vendor is probably the way to go. However, if you anticipate applying source patches, adding or removing modules, or just fiddling with the server in general, building it yourself from the ground up is probably the preferred method. (The authors of this book, being confirmed bit-twiddlers, always build from source.)

This chapter covers some of the more common prepackaged installation varieties and also how to build them from the source yourself.

Throughout the chapter, we assume that you will be using dynamic shared objects (DSOs) rather than building modules statically into the server. The DSO approach is highly recommended; it not only makes it easy to update individual modules without having to rebuild the entire server, but it also makes adding or removing modules from the server's configuration a simple matter of editing the configuration file.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You have a Red Hat Linux server and want to install or upgrade the Apache web server on it using the packages that Red Hat prepares and maintains.

If you are a member of the Red Hat Network (RHN), Red Hat's subscription service, you can use Red Hat's up2date tool to maintain your Apache package:

# up2date -ui apache apache-devel apache-manual

If you're running a more recent version:

# up2date -ui httpd httpd-devel httpd-manual

If you aren't a member of RHN, you can still download the packages from one of Red Hat's servers (either ftp://ftp.redhat.com/ or ftp://updates.redhat.com/), and install it with the following command:

# rpm -Uvh apache

The -Uvh option to the rpm command tells it to:

Upgrade any existing version of the package already on the system or install it for the first time if it isn't.
Explain the process, so you can receive positive feedback that the installation is proceeding smoothly.
Display a pretty line of octothorpes (#) across the screen, marking the progress of the installation.

If you use the packages Red Hat maintains for its own platform, you will benefit from a simple and relatively standard installation. However, you can only update versions that Red Hat has put together an RPM package for, which typically means that you may be lagging weeks to months behind the latest stable version.

There is also the issue of platform compatibility; for instance, at some point the version of Apache provided for Red Hat Linux changed from 1.3 to 2.0, and newer versions of the operating system will probably only have the 2.0 packages available. Similarly, if you run an older version of Red Hat Linux, the newer packages will probably not install properly on your system.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to install the Apache web server software on a Windows platform.

If you already have Apache installed on your Windows system, remove it before installing a new version. Failure to do this results in unpredictable behavior. See Recipe 1.7.

Primarily, Windows is a graphically oriented environment, so the Apache install for Windows is correspondingly graphical in nature.

The simplest way to install Apache is to download and execute the Microsoft Software Installer (MSI) package from the Apache web site at http://httpd.apache.org/download. The following screenshots come from an actual installation made using this method.

Each step of the installation process is distinct in the process and you can revise earlier decisions, until the files are installed. The first screen (Figure 1-1) simply confirms what you're about to do and the version of the package you're installing.

Figure 1-1: First screen of Apache MSI install

The second screen (Figure 1-2) presents the Apache license. Its basic tenets boil down to the following: do what you want with the software, don't use the Apache marks (trademarks like the feather or the name Apache) without permission, and provide proper attribution for anything you build based on Apache software. (This only applies if you plan to distribute your package; if you use it strictly on an internal network, this isn't required.) You can't proceed past this screen until you agree to the license terms.

Figure 1-2: License agreement

Figure 1-3 shows the recommended reading for all new users of the Apache software. This describes special actions you should take, such as making configuration changes to close security exposures, so read it closely.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to build the Apache web server yourself from the sources directly (see Recipe 1.4), but don't know how to obtain them.

There are a number of ways to obtain the sources. You can access the latest version in close to real-time by using CVS, the tool used by the Apache developers for source control, you can download a release tarball, or you can install a source package prepared by a distributor, among others.

From a prepackaged tarball, download the tarball from http://httpd.apache.org/dist/, and then:

% tar xzvf 
               apache_1.3.27.tar.gz

If your version of tar doesn't support the z option for processing zipped archives, use this command instead:

% gunzip -c < 
               apache_1.3.27.tar.gz | tar xvf -

From the very latest up-to-the-minute Apache 1.3 source repository (not guaranteed to be completely functional), use:

% cvs -d :pserver:anoncvs@CVS.Apache.Org:/home/cvspublic login
     Password: anoncvs
% cvs -d :pserver:anoncvs@CVS.Apache.Org:/home/cvspublic checkout apache-1.3

You can fetch a particular release version instead of the bleeding edge code if you know the name the developers gave it. For example, this will pull the sources of the 1.3.27 release, which is expected to be stable, unlike the up-to-the-minute version:

% cvs -d :pserver:anoncvs@CVS.Apache.Org:/home/cvspublic checkout -r APACHE_1_3_27
     apache-1.3

From the very latest up-to-the-minute Apache 2.0 source repository (not guaranteed to be completely functional), use:

% cvs -d :pserver:anoncvs@CVS.Apache.Org:/home/cvspublic login
     Password: anoncvs
% cvs -d :pserver:anoncvs@CVS.Apache.Org:/home/cvspublic checkout -r 
     APACHE_2_0_BRANCH httpd-2.0
% cd httpd-2.0/srclib
% cvs checkout apr apr-util

As with the method for the 1.3 version of the server, you can fetch a particular release of the 2.0 code if you know the name assigned to it in CVS.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to build your Apache web server from the sources directly rather than installing it from a prepackaged kit.

Assuming that you already have the Apache source tree, whether you installed it from a tarball, CVS, or some distribution package, the following commands, executed in the top directory of the tree, builds the server package with most of the standard modules as DSOs:

Apache 1.3:

% ./configure --prefix=
               /usr/local/apache --with-layout=Apache 
     --enable-shared=max--enable-module=most
% make
# make install

For Apache 2.0:

% ./buildconf
% ./configure --prefix=
               /usr/local/apache --with-layout=Apache --enable-
     modules=most --enable-mods-shared=all
% make
# make install

If you want more detailed information about the various options and their meanings, you can use the following command:

% ./configure --help

Building the server from the sources can be complex and time-consuming, but it's required if you intend to make any changes to the source code. It gives you much more control over things, such as the use of shareable object libraries and the database routines available to modules. Building from source is also de rigeur if you're developing your own Apache modules.

The options to the configure script are many and varied; if you haven't used it before to build Apache, locate some online tutorials (such as those at http://Apache-Server.Com/tutorials/ or http://httpd.apache.org/docs-2.0/install.html) when you want to change the defaults. The default options generally produce a working server, although the filesystem locations and module choices may not be what you'd like; they may include modules you don't want or omit some you do. (See Chapter 2 for some examples.)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You have a complicated collection of modules you want to install correctly.

Download ApacheToolbox from http://www.apachetoolbox.com/. (Note that the version numbers will probably be different than these, which were the latest available when this section was written.) Unpack the file:

% bunzip2 
               Apachetoolbox-1.5.65.tar.bz2
% tar xvf 
               Apachetoolbox-1.5.65.tar

(Depending on your version of tar, you may be able to combine these operations into a single tar xjvf command.)

Then run the installation script:

# cd 
               Apachetoolbox-1.5.65
# ./install.sh

ApacheToolbox is developed and maintained by Bryan Andrews. It is a shell script that assists in the configuration and installation of Apache. It includes support for over 100 commonly used or standard modules.

When you run the script, you select modules from lists appearing on various screens. Once you have decided on your list of modules, ApacheToolbox downloads the third-party modules you have selected and the tools that you don't have installed, and then runs the Apache configure script with any arguments needed to create the combination you have requested.

The main screen (see Figure 1-11) lists the most popular third-party modules that ApacheToolbox can install. Select or deselect a particular module by typing the number next to that module's name.

Figure 1-11: Main screen of ApacheToolbox install

Typing apache moves you to the second screen (see Figure 1-12), which lists the standard Apache modules. Add or remove individual modules by typing the number next to their module names.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to be able to start and stop the server at need, using the appropriate tools.

On Unixish systems, use the apachectl script; on Windows, use the options in the Apache folder of the Start menu.

The basic Apache package includes tools to make it easy to control the server. For Unixish systems, this is usually a script called apachectl , but prepackaged distributions may replace or rename it. It can only perform one action at a time, and the action is specified by the argument on the command line. The options of interest are:

apachectl start: This will start the server if it isn't already running. If it is running, this option has no effect and may produce a warning message.
apachectl graceful: This option causes the server to reload its configuration files and gracefully restart its operation. Any current connections in progress are allowed to complete. The server will be started if it isn't running.
apachectl restart: Like the graceful option, this one makes the server reload its configuration files. However, existing connections are terminated immediately. If the server isn't running, this command will try to start it.
apachectl stop: This shuts the server down immediately. Any existing connections are terminated at once.

For Windows, the MSI installation of Apache includes menu items for controlling the server, as shown in Figure 1-13.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You have the Apache software installed on your system, and you want to remove it.

On Red Hat Linux, to remove an Apache version installed with the RPM tool, use:

# rpm -ev apache

Other packaging systems may provide some similar mechanism.

On Windows, Apache can be typically removed like any other MSI-installed software (see Figure 1-14).

Figure 1-14: Uninstalling the Apache software

Unfortunately, there is no generic works-for-all removal method for Apache installations on Unixish systems. Some packages, such as Red Hat's RPM, do remember what they installed so they can remove all the pieces, as shown in the solution. However, if the software was installed by building from the sources (see Recipe 1.4), the burden of knowing where files were put rests with the person who did the build and install. The same applies if the software was installed from source on a Windows system; it's only the MSI or InstallShield packages that make the appropriate connections to allow the use of the Add/Remove Software control panel.

Recipe 1.4

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There are a number of extremely popular modules for the Apache web server that are not included in the basic distribution. Most of these are separate because of licensing or support reasons; some are not distributed by the Apache Software Foundation because of a decision by the Apache developers; and some are integral parts of other projects. For instance, mod_ssl for Apache 1.3 is developed and maintained separately not only because of the U.S. export control laws (which were more restrictive when the package was originally developed), but because it requires changes to the core software that the Apache developers chose not to integrate.

This chapter provides recipes for installing some of the most popular of these third-party modules; when available, there are separate recipes for installation on Unixish systems and on Windows.

The most comprehensive list of third-party modules can be found in the Apache Module Registry at http://modules.apache.org/. Some modules are so popular—or complex—that they have entire sites devoted to them, as do the ones listed in this chapter.

Although hundreds of third-party modules are available, many module developers are only concerned with their single module. This means that there are potentially as many different sets of installation instructions as there are modules. The first recipe in this chapter describes an installation process that should work with many Apache 1.3 modules, but you should check with the individual packages' instructions to see if they have a different or more detailed process.

Many of the modules are available from organizations that prepackage or distribute Apache software, such as in the form of an RPM from Mandrake or Red Hat, but such prebuilt module packages include the assumptions of the packager. In other words, if you build the server from source and use custom locations for the files, don't be surprised if the installation of a packaged module fails.

All of the modules described in this chapter are supported with Apache 1.3 on Unixish systems. Status of support with Apache 2.0 on Windows is shown in Table 2-1.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You have downloaded a third-party module that isn't listed in this chapter, and you want to install it.

Move to the directory where the module's source file was unpacked, and then:

% /path/to/apache/
               bin/apxs -cia 
               module.c

In the case of a third-party module that consists of a single .c file, there is a good chance that it can be built and installed using the Solution. Modules that involve multiple source files should provide their own installation instructions.

The -cia options mean to compile, install, and activate. The first is pretty straightforward; install means put the .so file in the place Apache expects to find it, and activate means to add the module to the httpd.conf file.

The apxs manpage, typically ServerRoot/man/man8/apxs.8

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to add or enable WebDAV capabilities to your server. WebDAV permits specific documents to be reliably and securely manipulated by remote users without the need for FTP, to perform such tasks as adding, deleting, or updating files.

If you're using Apache 2.0, mod_dav is automatically available, although you may need to enable it at compile time with —enable-dav.

If you are using Apache 1.3, download and unpack the mod_dav source package from http://webdav.org/mod_dav/, and then:

% cd 
               mod_dav-1.0.3-1.3.6
% ./configure --with-
               apxs=/usr/local/
               apache/bin/apxs
% make
# make install

Restart the server, and be sure to read Recipe 6.18.

mod_dav is an encapsulated and well-behaved module that is easily built and added to an existing server. To test that it has been properly installed, you need to enable some location on the server for WebDAV management and verify access to that location with some WebDAV-capable tool. We recommend cadaver , which is an open source command-line WebDAV tool. (The URL for the cadaver tool is found at the end of this recipe.)

To enable your server for WebDAV operations, you need to add at least two directives to your httpd.conf file. The first identifies the location of the locking database used by mod_dav to keep WebDAV operations from interfering with each other; it needs to be in a directory that is writable by the server. For example:

# cd /usr/local/apache
# mkdir var
# chgrp nobody var
# chmod g+w var

Now add the following line to your httpd.conf file, outside any containers:

<IfModule mod_dav.c>
    DAVLockDB var/DAVlock
</IfModule>

The DAVLockDB location must not be on an NFS-mounted filesystem, because NFS doesn't support the sort of locking

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to enable WebDAV capabilities on your existing Apache 1.3 server with mod_dav.

Apache 2.0 includes mod_dav as a standard module, so you do not need to download and build it.

Download and unpack the mod_dav Windows package from http://webdav.org/mod_dav/win32/. Verify that your Apache installation already has the xmlparse.dll and xmltok.dll files in the ServerRoot directory; if they aren't there, check through the Apache directories to locate and copy them to the ServerRoot. mod_dav requires the Expat package, which is included with versions of the Apache web server after 1.3.9; these files hook into Expat, which mod_dav will use.

Put the mod_dav DLL file into the directory where Apache keeps its modules:

C:\>cd mod_dav-1.0.3-dev
C:\mod_dav-1.0.3-dev>copy mod_dav.dll C:\Apache\modules
C:\mod_dav-1.0.3-dev>cd \Apache

Add the following lines to your httpd.conf file:

LoadModule dav_module modules/mod_dav.dll

You may also need to add an AddModule line if your httpd.conf file includes a ClearModuleList directive and re-adds the other modules. Alternatively, you can insert the LoadModule for mod_dav after the ClearModuleList directive.

mod_dav is an encapsulated and well-behaved module that is easily built and added to an existing server. To test that it has been properly installed, you need to enable some location on the server for WebDAV management and verify access to that location with some WebDAV-capable tool, or browse to it in Windows Explorer, which knows how to access WebDAV locations (as of Windows 2000), or access it from a different system where cadaver or another WebDAV tool is available.

To enable your server for WebDAV operations, you need to add at least two directives to your ServerRoot/conf/httpd.conf file. The first identifies the location of the locking database used by

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to install the mod_perl scripting module to allow better Perl script performance and easy integration with the web server.

Download and unpack the mod_perl source package from http://perl.apache.org/. Then use the following command:

% perl Makefile.PL \
>     USE_APXS=1 \
>     WITH_APXS=
               /usr/local/apache/bin/apxs \
>     EVERYTHING=1 \
>     PERL_USELARGEFILES=0
% make
% make install

Restart your server.

mod_perl is quite a complex module, and there are several different ways to add it to your server. This recipe is the fastest and lowest-impact one; if it doesn't suit your needs, check the various README.* files in the package directory after unpacking. Because its primary language is Perl rather than C, the installation instructions are significantly different from those for most other modules.

Once you have restarted your server successfully, mod_perl should be available and configured as part of it. You can test it by making some changes to the httpd.conf file, adding a few scripts, and seeing whether the server processes them correctly. Here is a sample set of steps to test mod_perl's operation.

Create a directory where your mod_perl scripts can live:

# cd 
                     ServerRoot
# mkdir lib lib/perl lib/perl/Apache

Create a file named startup.pl in your server's conf/ directory that will give mod_perl some startup instructions:

#! /usr/bin/perl
BEGIN {
    use Apache (  );
    use lib Apache->server_root_relative('lib/perl');
}
use Apache::Registry (  );
use Apache::Constants (  );
use CGI qw(-compile :all);
use CGI::Carp (  );
1;

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to add the mod_php scripting module to your existing Apache web server.

Download the mod_php package source from the web site at http://php.net/ (follow the links for downloading) and unpack it. Then:

% cd php-4.3.2
% ./configure \
>     --with-apxs=
               /usr/local/apache/bin/
               apxs
% make
# make install

Restart the server.

To test that your installation was successful, create a file named info.php in your server's DocumentRoot; the file should contain the single line:

<?php phpinfo(  ); ?>

Add the following lines to your server's httpd.conf file:

<IfModule mod_php4.c>
    AddType application/x-httpd-php .php
    AddHandler application/x-httpd-php .php
</IfModule>

After restarting your server, try fetching the document info.php using a browser. You should see a detailed description of the PHP options that are active.

There are numerous additional options and extensions available for PHP; the recipe given here is only for the most basic installation.

Recipe 8.15
Recipe 8.16
http://php.net/

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to add the mod_php scripting module to your existing Apache server on Windows.

This recipe needs to be described largely in terms of actions rather than explicit commands to be issued.

Download the PHP Windows binary .zip file with API extensions (not the .exe file) from http://php.net/.
Unpack the .zip file into a directory where you can keep its contents indefinitely (such as C:\PHP4). If you use WinZip, be sure to select the Use folder names checkbox to preserve the directory structure inside the .zip file.
Copy the PHP4\SAPI\php4apache.dll to the \modules\ directory under your Apache installation's ServerRoot.
In a command-prompt window, change to the PHP4 directory where you unpacked the .zip file, and type:
```
...\PHP4>copy php.ini-dist %SYSTEMROOT%\php.ini
...\PHP4>copy php4ts.dll %SYSTEMROOT%
                  
```
(If installing on Windows 95 or Windows 98, use %WINDOWS% instead of %SYSTEMROOT%.)
Edit the %SYSTEMROOT%\php.ini file, locate the line that starts with extensions_dir, and change the value to point to the PHP4\extensions directory. For instance, if you unpacked the .zip file into C:\PHP4, this line should look like:
```
extensions_dir = C:\PHP4\extensions
```
Edit the conf\httpd.conf file under the Apache ServerRoot and add the following lines near the other LoadModule lines:
```
LoadModule php4_module modules/php4apache.dll
```
Add the following lines in some scope where they will apply to your .php files:
```
<IfModule mod_php4.c>
    AddType application/x-httpd-php .php
</IfModule>
```

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to add the mod_snake Python scripting module to your existing Apache server.

To install mod_snake on a Unixish system, download the source from the http://sourceforge.net/projects/modsnake/ web site (follow the link for downloading), unpack it, and then:

% cd 
               mod_snake-0.5.0
% ./configure --with-apxs=
               /usr/local/apache/bin/apxs
% make
# make install

Restart the server.

At the time of this writing, mod_snake cannot be installed on Windows.

mod_snake is a fairly standard Apache module; it can be added to an existing Apache installation without any source-level changes. It requires that you have Python installed, and that the apxs script has been properly configured and installed as part of the web server package.

See the README and INSTALL files in the unpacked package directory, and the HTML documentation in the examples/tut/ directory, for additional information, examples, and ways to test that your installation was successful.

Recipe 2.1
http://modsnake.sourceforge.net/

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to add SSL support to your Apache server with the mod_ssl secure HTTP module.

Windows

At the time of this writing, there is no supported means of installing mod_ssl on Windows.

Apache 2.0

mod_ssl is included with 2.0, although it is not automatically compiled nor installed when you build from source. You need to include the —enable-ssl option on your ./configure line, and enable it with LoadModule and AddModule directives.

Apache 1.3

To install mod_ssl on a Unixish system, download the tarball package from the http://www.modssl.org/ web site and unpack it. Then:

% cd 
                        mod_ssl-2.8.14-1.3.27
% ./configure \
>    --with-apache=..
                        /apache_1.3.27 \
>    --with-ssl=SYSTEM \
>    --prefix=
                        /usr/local/apache
% cd ../apache_1.3.27
% make
% make certificate

The mod_ssl package requires source-level changes to the base Apache code, and so the version of the mod_ssl package you install must match the version of the Apache distribution you have. If your Apache installation doesn't include the source (such as if you installed a binary-only RPM or other vendor distribution), you won't be able to add mod_ssl to it.

In addition to the Apache source, mod_ssl requires that you have Perl and the OpenSSL libraries installed. The —with-ssl option on the build configuration statement indicates where this is located; if it is in a vendor distributed directory, the special keyword

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Apache can, and usually does, record information about every request it processes. Controlling how this is done and extracting useful information out of these logs after the fact is at least as important as gathering the information in the first place.

The logfiles may record two types of data: information about the request itself, and possibly one or more messages about abnormal conditions encountered during processing (such as file permissions). You, as the webmaster, have a limited amount of control over the logging of error conditions, but a great deal of control over the format and amount of information logged about request processing (activity logging ). The server may log activity information about a request in multiple formats in mulitple log files, but it will only record a single copy of an error message.

One aspect of activity logging you should be aware of is that the log entry is formatted and written after the request has been completely processed. This means that the interval between the time a request begins and when it finishes may be long enough to make a difference.

For example, if your logfiles are rotated while a particularly large file is being downloaded, the log entry for the request will appear in the new logfile when the request completes, rather than in the old logfile when the request was started. In contrast, an error message is written to the error log as soon as it is encountered.

The web server will continue to record information in its logfiles as long as it's running. This can result in extremely large logfiles for a busy site and uncomfortably large ones even for a modest site. To keep the file sizes from growing ever larger, most sites rotate or roll over their logfiles on a semi-regular basis. Rolling over a logfile simply means persuading the server to stop writing to the current file and start recording to a new one. Due to Apache's determination to see that no records are lost, cajoling it to do this according to a specific timetable may require a bit of effort; some of the recipes in this chapter cover how to accomplish the task successfully and reliably (see Recipe 3.8 and Recipe 3.9).

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to add a little more detail to your access log entries.

Use the combined log format, rather than the common log format:

CustomLog logs/access_log combined

The default Apache logfile enables logging with the common log format, but it also provides the combined log format as a predefined LogFormat directive.

The combined log format offers two additional pieces of information not included in the common log format: the Referer (where the client linked from) and the User-agent (what browser they are using).

Every major logfile parsing software package is able to handle the combined format as well as the common format, and many of them give additional statistics based on these added fields. So you lose nothing by using this format and potentially gain some additional information.

http://httpd.apache.org/docs/mod/mod_log_config.html
http://httpd.apache.org/docs-2.0/mod/mod_log_config.html

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want more information in the error log in order to debug a problem.

Change (or add) the LogLevel line in your httpd.conf file. There are several possible arguments, which are enumerated below:

For example:

LogLevel Debug

There are several hierarchical levels of error logging available, each identified by its own keyword. The default value of LogLevel is warn. Listed in descending order of importance, the possible values are:

emerg: Emergencies; web server is unusable
alert: Action must be taken immediately
crit: Critical conditions
error: Error conditions
warn: Warning conditions
notice: Normal but significant condition
info: Informational

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to record data submitted with the POST method, such as from a web form.

Generally not possible in Apache 1.3 unless the POST-handling module explicitly records the data; possible in Apache 2.0 via input filter functionality, but no such filters are available at the time of this writing.

In Version 1.3 of Apache, only one module receives the chance to process the message body of a request, which contains the POST variable settings, and it's up to this module to record them. The request information is read from the network exactly once by the module chosen by the server to handle the response, and therefore, the information isn't available to the logging phase, which follows the content handling phase.

For example, if you're using mod_perl, you may be able to record the information if the content handler that delivers the response is a Perl script being handled by mod_perl.

Watch this book's web site for updates about the availability of an input filter to do this:

http://Apache-Cookbook.Com/
See various articles on the Web about Apache 2.0 filters, such as:

http://OnLAMP.Com/apache/
http://ApacheToday.Com/

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to log the IP address of the actual client requesting your pages, even if they're being requested through a proxy.

None.

Unfortunately, the HTTP protocol itself prevents this from being possible. From the client side, proxies are intended to be completely transparent; from the side of the origin server, where the content actually resides, they are meant to be almost utterly opaque, concealing the identity of a request.

Your best option is to log the IP address from which the request came. If it came directly from a browser, it will be the client's address; if it came through one or more proxy servers, it will be the address of the one that actually contacts your server.

Both the combined and common log formats include the %h format effector, which represents the (remote) client's identity. However, this may be a hostname rather than an address, depending on the setting of your HostNameLookups directive, among other things. If you always want the client's IP address to be included in your logfile, use the %a effector instead.

The HTTP protocol specification at ftp://ftp.isi.edu/in-notes/rfc2616.txt

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to record the MAC (hardware) address of clients that access your server.

This cannot be logged reliably in most network situations and not by Apache at all.

The MAC address is not meaningful except on local area networks (LANs) and is not available in wide-area network transactions. When a network packet goes through a router, such as when leaving a LAN, the router will typically rewrite the MAC address field with the router's hardware address.

The TCP/IP protocol specifications (see http://www.rfc-editor.org/cgi-bin/rfcsearch.pl and search for "TCP" in the title field)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to record all the cookies sent to your server by clients and all the cookies your server asks clients to set in their databases; this can be useful when debugging web applications that use cookies.

To log cookies received from the client:

CustomLog logs/cookies_in.log "%{UNIQUE_ID}e %{Cookie}i"
CustomLog logs/cookies2_in.log "%{UNIQUE_ID}e %{Cookie2}i"

To log cookie values set and sent by the server to the client:

CustomLog logs/cookies_out.log "%{UNIQUE_ID}e %{Set-Cookie}o"
CustomLog logs/cookies2_out.log "%{UNIQUE_ID}e %{Set-Cookie2}o"

Using the %{Set-Cookie}o format effector for debugging is not recommended if multiple cookies are (or may be) involved. Only the first one will be recorded in the logfile. See the Discussion text for an example.

At the time of this writing, the Apache package includes no way to record all cookie values, but one of the authors of this book is working on one. When it's available, it should be mentioned on this book's web site, http://Apache-Cookbook.Com/.

Cookie fields tend to be very long and complex, so the previous statements will create separate files for logging them. The cookie log entries can be correlated against the client request access log using the server-set UNIQUE_ID environment variable (assuming that mod_unique_id is active in the server and that the activity log format includes the environment variable with a %{UNIQUE_ID}e format effector).

At the time of this writing, the Cookie and Set-Cookie header fields are most commonly used. The Cookie2 and corresponding Set-Cookie2 fields are newer and have been designed to correct some of the shortcomings in the original specifications, but they haven't yet achieved much penetration.

Because of the manner in which the syntax of the cookie header fields has changed over time, these logging instructions may or may not capture the complete details of the cookies.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·

Table of Contents