Module Basics

I'll have to admit up front that this section is already well covered in the Apache documentation. But rather than telling you to go read the manual, I'll try to provide a smooth introduction with no more information than is necessary to start building modules. If you want to find out more than I've laid out, I encourage you to consult the authoritative source. A URL is provided in the References at the end of this chapter.

Apache can be configured (and on Linux systems, it often is) to provide nearly all of its functionality through modules, which are really just shared libraries. The libraries, or .so files, are usually stored in a single resource directory. On my Debian system, the path is /usr/lib/apache/1.3. The base distribution contains a number of standard modules to do URI mapping, access control, script invocation, logging, and so on. When Apache needs to use some part of a module's functionality, it dynamically loads it into memory and resolves the symbols that it needs. Linux has very good support for dynamic loading that is sometimes lacking on other operating systems, and Apache was built to take advantage of these advanced features, if they're present.

It's important to note that these modules are different from the kernel modules that are also available under Linux, and they provide extensions to the functionality of the kernel. Apache modules have an .so extension and run in nonprivileged user space. Kernel modules have an .o extension and run in kernel space with direct access to physical memory, input/output (I/O) ports, and hardware. However, the mechanism by which they are loaded is quite similar.

All the modules visible to Apache are listed in the configuration file httpd.conf. Modules that are not necessary for a given installation can be commented out, to reduce the memory footprint of the server and speed it up. Here is a sample of the configuration file for my server:

 # LoadModule vhost_alias_module /usr/lib/apache/1.3/mod_vhost_alias.so

 # LoadModule env_module /usr/lib/apache/1.3/mod_env.so

 LoadModule config_log_module /usr/lib/apache/1.3/mod_log_config.so

 # LoadModule mime_magic_module /usr/lib/apache/1.3/mod_mime_magic.so

 LoadModule mime_module /usr/lib/apache/1.3/mod_mime.so

 LoadModule negotiation_module /usr/lib/apache/1.3/mod_negotiation.so

  LoadModule status_module /usr/lib/apache/1.3/mod_status.so

  # LoadModule info_module /usr/lib/apache/1.3/mod_info.so

  # LoadModule includes_module /usr/lib/apache/1.3/mod_include.so

  LoadModule autoindex_module /usr/lib/apache/1.3/mod_autoindex.so

There are about 30 modules total, and many of them are commented out. When you create your own modules, you'll have to provide a LoadModule directive for it.

So What Do Modules Do?

When a client requests a file, the Apache server breaks down the request into several steps:

· URI mapping

· Authentication

· Authorization

· MIME-type mapping

· Replying to the client

· Logging

Actually, there are a couple of more steps, but they're not often used. Then for each step of the request, Apache walks through the list of currently loaded modules and asks each one if it would like to affect the outcome of that step. A module can indicate interest, defer to the next module, or raise a server error of some sort . If a module expresses interest, then the server will call a handler function within that module, passing it information about the request.

In the replying-to-client step, a module can actually have multiple named handlers. These names are used in the Apache configuration file when the module is being set up to handle all requests to a certain subdirectory or all requests for a particular file type. When Apache gets to the point where it needs to provide the headers and body of the HTTP response, it will call the appropriate handler function instead of using the default behavior of sending the contents of a file. By using this mechanism, a module can send dynamically generated data that does not exist on the file system. For example, the mod_dir module uses a named handler to display an HTML-formatted directory listing, and the mod_cgi module uses a named handler to invoke an external script and send the output to the client.

Most modules will never indicate interest in more than one or two steps. For example, the mod_log_config module has only a handler for the logging step. The mod_mime module, on the other hand, has only a handler for the MIME-type mapping step.

As with all rules, there are some exceptions, and you can find more detailed information in the Apache documentation. This brief introduction should describe enough about the inner workings of Apache to get started building your own simple modules.