Configuring, Tuning and Debugging Apache

Until now, we have assumed our Apache installation is statically compiled, with all of the modules placed inside of Apache at compile time. This is the traditional way to compile Apache, and the default if you simply perform a “./configure”.

The problem with the above configuration is that it is relatively inflexible. What happens if you discover that you forgot to configure Apache to include a particular module? You will have to recompile the entire program, specifying which modules you do and don't want to include when running configure. This does not seem bad at first—after all, how often will you want to add a new module to the system?

However, the problem is deeper than that, in at least two ways. Why should Apache consume memory for modules that might not be used? In addition, why should I have to recompile Apache every time a new version of just one module is released?

In order to solve this problem, the Apache developers now support a system known as DSO, or “dynamic shared objects”. DSOs make it possible to compile Apache with only two statically linked modules, mod_core (which provides core functionality) and mod_so (which handles the loading of DSOs). All other modules can be built such that they are loaded only when necessary. Because modules are not an inherent part of Apache, they can also be upgraded without having to recompile the web server itself. As we will see below, this functionality can come in handy if you need to upgrade or debug an already-running and configured Apache server.

To compile Apache with DSOs, you will need to decide which modules you wish to compile statically, and which you will compile as DSOs. My preference is to make everything a DSO, but to compile only the modules that Apache installs by default. We can do this by changing our invocation of “configure”:

 ./configure --enable-shared=max

This will automatically enable mod_so, and will compile Apache with all of the default modules. After compiling Apache with make and installing it with make install, Apache will continue to work as before. The only difference is that it can now load modules dynamically, adding new modules to the already-compiled HTTP server as they are needed.

The default httpd.conf created by an Apache server compiled with --enable-shared looks slightly different from that created for a statically compiled Apache server. For one, most of the directives are hidden inside <IfModule> sections, making it possible for Apache to load even if some of its modules have not been loaded yet. In addition, each module must first be loaded with the LoadModule directive, and then enabled with the AddModule directive. For example:

LoadModule perl_module libexec/libperl.so
AddModule mod_perl.c

LoadModule takes two arguments, the name of the module and the file in which the .so file sits. The name must match the name with which the DSO module was compiled, while the file name should point to a directory relative to /usr/local/apache. In the above example, and by default, DSO modules are placed in /usr/local/apache/libexec.

In contrast with most of the other directives in httpd.conf, LoadModule and AddModule are sensitive to the order in which they are placed. LoadModule must come before AddModule, and each module must be loaded and added before its directives will work. In addition, some modules must be loaded before others, and will not work otherwise. If it is possible to let an automatic configuration tool take care of the insertion of LoadModule and AddModule, let it do so. This may save your web server from hard-to-track-down configuration problems.

Once Apache is compiled with DSO support, new modules can be added at any time. However, these modules must be compiled with the same configuration information that was present when the Apache server itself was compiled. This is handled automatically by apxs, the “Apache Extension” program, written by Ralf S. Engelschall. apxs makes it possible to compile an Apache module into a DSO (.so file), and then to install it into the appropriate Apache configuration. Unfortunately, there seems to be little or no documentation for apxs, meaning that it can be difficult to understand exactly what this program does or how it works.

For example, let us assume we have already compiled and installed Apache with DSO support. Several weeks later, we notice that many of the hits on our site are resulting in “file not found” errors, because users cannot spell the odd names we have used in our URLs. One solution is obviously to revamp the site such that users will be able to spell things more easily. But an easier solution is to install mod_speling, so capitalization and spelling are largely ignored.

To compile mod_speling as a DSO, type:

/usr/local/apache/bin/apxs -c mod_speling.oc

apxs will invoke gcc, compiling mod_speling. The result will not be directly executable, but rather a library that can be invoked by Apache. If the compilation was successful, then we can install mod_speling with the following command:

/usr/local/apache/bin/apxs -i -n -a mod_speling.so