Table of Contents for

Apache Cookbook, 2nd Edition

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.

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 or later, 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.

The mod_dav source package 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>

Next, create a temporary directory for testing WebDAV functionality:

# cd /usr/local/apache
# mkdir htdocs/dav-test
# chgrp nobody htdocs/dav-test
#chmod g+w htdocs/dav-test

Add a stanza to your httpd.conf file that will enable this directory for WebDAV operations:

<Directory "/usr/local/apache/htdocs/dav-test">
    DAV On
</Directory>

Now restart your server. It should be ready to handle WebDAV operations directed to the /dav-test local URI. To test it with the cadaver tool, try the following commands; your output should look very similar to that shown:

% cd /tmp
% echo "Plain text" > dav-test.txt
% cadaver
dav:!> open http://localhost/dav-test
Looking up hostname... Connecting to server... connected.
dav:/dav-test/> put dav-test.txt
Uploading dav-test.txt to '/dav-test/dav-test.txt': (reconnecting...done)
Progress: [=  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==>] 100.0% of 11 
    bytes succeeded.
dav:/dav-test/> propset dav-test.txt MyProp 1023
Setting property on 'dav-test.txt': (reconnecting...done) succeeded.
dav:/dav-test/> propget dav-test.txt MyProp
Fetching properties for 'dav-test.txt':
Value of MyProp is: 1023
dav:/dav-test/> propdel dav-test.txt MyProp
Deleting property on 'dav-test.txt': succeeded.
dav:/dav-test/> close
Connection to 'localhost' closed.
dav:!> exit
%rm dav-test.txt

Properties are attributes of a WebDAV resource. Some are managed by the system, such as the resource’s size, but others can be arbitrary and added, changed, and removed by the user.

Once you have verified that mod_dav is working correctly, remove the htdocs/dav-test directory, and the corresponding <Directory> stanza in your httpd.conf file, and follow the guidelines in Recipe 6.18.

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 that 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 line 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.

The mod_dav Package 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 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:

C:\Apache-1.3>mkdir var

Now add the following lines to your httpd.conf file to enable WebDAV:

<IfModule mod_dav.c>
    DAVLockDB "C:/Apache-1.3/var/dav-lock"
</IfModule>

Create a temporary directory for testing mod_dav’s ability to function:

C:\Apache-1.3>mkdir htdocs\dav-test

Modify the <IfModule> container to enable WebDAV operations for this test directory:

<IfModule mod_dav.c>
    DAVLockDB "C:/Apache-1.3/var/dav-lock"
    <Directory "C:/Apache-1.3/htdocs/dav-test">
        DAV On
    </Directory>
</IfModule>

Now restart your server and try accessing the /dav-test location with a WebDAV client. If you’re using cadaver from another system, see Recipe 2.2 for detailed instructions. If you want to use Windows Explorer to test mod_dav, read the following section.

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

For Apache 1.3, download and unpack the mod_perl 1.0 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.

For Apache 2.0 and later, the process is similar. Download and unpack the mod_perl 2.0 source package, then use the following command:

% perl Makefile.PL MP_APXS=/usr/local/apach2/bin/apxs 

The mod_perl source package 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:

If your configuration is valid, the response should be a page containing simply the words, “Hello, world! Love, mod_perl.”

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-5.2.3
% ./configure \
>     --with-apxs2=/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>
    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. If you do, indicating a successful installation, remove the info.php file.

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

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.

The PHP module installation on Windows requires a lot of nitpicky manual steps. 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(); ?>

After restarting your server, try fetching the document info.php from it 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 the most basic installation. See the install.txt file in the PHP4 directory and the documentation on the Web site for more details.

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

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 SYSTEM tells the build to look for it, and you don’t have to find it yourself.

Unlike most other Apache modules, when adding mod_ssl you run the ./configure script that’s in mod_ssl’s directory, rather than the one in the Apache source directory; the module’s script makes changes to Apache’s and then invokes it directly.

This recipe is the bare basics; there are many optional components and features that mod_ssl allows you to specify at configuration time. For more information, consult the README and INSTALL files in the mod_ssl source directory, or the mod_ssl Web site at http://www.modssl.org.

You’re looking for Apache modules with a particular functionality, or by name, and you’ve heard about the Apache Module Registry.

Visit http://modules.apache.org and search for keywords related to the functionality you want, or portions of the module name.

The Apache modules registry is an unofficial site at which module authors can voluntarily register their work for easy location.

You want to install the mod_security module to take advantage of its simple and powerful filtering mechanisms.

The Makefile included with the mod_security package will do the building of the module and put it in the right place, but activating it in your server is your responsibility. Recent versions of the package include a set of core rules for handling things like blog spam and common attacks, and the rules are also available as a separate tarball, which may or may not be updated more frequently than the ones bundled with the software.

The current version of mod_security only supports version 2 of the Apache Web server. There is an older version that supports the 1.3 versions, but it is unlikely to be maintained for long.

You are trying to install a third-party module, but the Apache Web server refuses to recognize it.

Consult the sources for the module, or its documentation, or ask the author, in order to determine which version of Apache the package supports.

As significant changes are made to the Apache Web server, sometimes compatibility suffers as the API is changed. Although efforts are made to keep this sort of thing to a minimum, sometimes it is unavoidable.

To keep an incompatible module from being loaded and crashing the Web server when used, both modules and the server have a built-in “magic” number that is recorded when they’re built, and that relates to the version of the API. When the server tries to load a module DSO, it compares the module’s magic number with the server’s own, and if they aren’t compatible, the server refuses to load it.

The development team tries to keep the magic number compatibility within major version numbers, but not across them. That is, a module built for Apache 1.3 should work with almost any 1.3 version of the server built after the module was, but it definitely won’t work with a 2.0 server. Contrariwise, a 2.0 module won’t work with a 1.3 server under any circumstances.