IN THIS CHAPTER
“While I'm still confused and uncertain, it's on a much higher plane, d'you see, and at least I know I'm bewildered about the really fundamental and important facts of the universe.” Treatle nodded. “I hadn't looked at it like that,” he said, “But you're absolutely right. He's really pushed back the boundaries of ignorance.” | ||
| --Discworld scientists at work—Terry Pratchett, Equal Rites | ||
As you have already seen throughout this book, most of the interesting functionality in Apache is implemented in modules rather than in the Apache core.
Apache, like many large software projects, operates on a modular model, where a very minimal set of crucial features are put into a core, or kernel, and everything else is implemented as a module, or plug-in, to that core. In this way, you can build Apache to have the smallest possible feature set, and, therefore, reduce the total size.
The Apache core implements an API (Application Programmer Interface), which modules can make calls into to access the basic functions the core provides, such as outputting HTTP headers, writing to the log files, and sending content to the client.
An Apache module extends the functionality of Apache and provides either directives or handlers (or filters in 2.0), which give the Web server administrator a way to affect the behavior of Apache in some way.
When a module is loaded it registers a list of the configuration directives and handlers that it provides with the core. When parsing the server configuration file at server startup, the value of each directive will be passed to the particular module that is responsible for it.
For example, mod_speling provides the CheckSpelling directive, which is used to set whether the spelling correction behavior is desired or not. When Apache encounters this directive while parsing the configuration file, it looks up who provides the directive and upon finding that mod_speling does, informs mod_speling of the setting.
You can see what modules you have installed, and the directives they provide, in one of two ways.
If you have mod_info installed and configured, you can view its output to get this information. (See Chapter 14, “Handlers and Filters,” for details about configuring mod_info.)
Or, from the command line you can run the httpd binary, providing it with the -l flag to see what modules have been built into Apache, or with the -L flag to see what configuration variables are made available by these modules.
The -l flag provides a simple listing of modules. Here is an example output from this command.
rbowen@rhiannon:~% /usr/local/apache/bin/httpd -l Compiled-in modules: http_core.c mod_env.c mod_log_config.c mod_mime.c mod_negotiation.c mod_status.c mod_info.c mod_include.c mod_autoindex.c mod_dir.c mod_cgi.c mod_asis.c mod_imap.c mod_actions.c mod_speling.c mod_userdir.c mod_alias.c mod_rewrite.c mod_access.c mod_auth.c mod_setenvif.c mod_perl.c
The -L flag returns much more detailed information, listing every available directive, what module provides it, and a one-to-three-line description of what the directive is for. For example, one directive might look like the following:
CheckSpelling (mod_speling.c)
whether or not to fix miscapitalized/misspelled requests
Allowed in *.conf anywhere and in .htaccess
when AllowOverride includes Options
A section like this appears for every directive defined by every module you have installed. For modules that you have installed as DSOs (dynamic shared objects), you will get this information only for modules that you have loaded under your current configuration.
In Chapter 2, “Acquiring and Installing Your Apache Server,” there is more discussion of shared objects and installing modules as shared objects.
First of all, this is not a book about writing Apache modules. For that, you should read Writing Apache Modules with Perl and C, from O'Reilly and Associates (http://www.oreilly.com/catalog/wrapmod/), which is an excellent reference to writing Apache modules.
The Apache Web site contains a complete listing of the Apache API, which is located at http://dev.apache.org/apidoc/. It provides each of the functions, a description of what it does, and an example of how to use it.
The Apache documentation also contains a short tutorial on using the Apache API. The tutorial has examples from real modules and it shows how to interact with the Apache API. It can be found at http://httpd.apache.org/docs/misc/API.html. Part of the Apache distribution is a module, called mod_example, which provides an example of how to write an Apache module and shows you how to go about accessing the Apache API. You should read that before you attempt to write your first Apache module.
As you saw in Chapter 2, there are two ways to install modules. When you build Apache you can either specify what modules you want installed, or you can build it as a shared object and decide in your configuration file whether or not to load that module. Each method has its advantages and disadvantages, but one method is not clearly better than the other for all Apache installations.
The first of the two methods of installing modules is building them into the httpd binary. This is frequently called “statically linked” because the various parts are compiled together into one final binary file, and it is not possible to dynamically swap out various components.
There are a number of things that you should know about installing a module this way, but whether each is an advantage or disadvantage really depends on your perspective and interpretation.
Building your modules into httpd requires that you know at compile time what modules you are going to need. The list of modules is passed to the configure script, and these modules are then compiled into the binary for the Apache daemon. You are not able to go back and change your mind on what modules you want, except by rebuilding the server.
httpd itself will be much larger, with all the modules built into it, than if you use mod_so to load them at the time your server starts.
Apache will start up slightly faster because it will not have to locate and load the various module files.
To add a particular module to Apache at compile time, you need to only add an argument to the list that is passed to the configure script.
For example, if you want to add mod_auth_db to your build of Apache, which is not compiled in by default, you would use a configure command line similar to the following:
./configure —prefix=/usr/local/apache —enable-module=auth_db
This will work for any module that is included with the Apache distribution.
This command should be run in the directory where you have unpacked your Apache source code, and should be followed by the commands make and make install to complete the installation.
See the next chapter for a listing of all the modules that come with Apache, and whether or not they are compiled in by default.
To build in a module that was not distributed with Apache—a third-party module—you will need to follow the instructions that came with that module. However, the general procedure in such a case is as follows:[1]
./configure —prefix=/usr/local/apache
—add-module=/path/to/mod_thirdparty.c
In the previous example, mod_thirdparty.c is the C language source code file for the module that you are including.
Some modules, such as mod_perl or mod_ssl, have very specific installation instructions that you need to follow, so always read the documentation for the third-party module before trying the previous technique.
The second way to install a module is as a DSO, or Dynamic Shared Object. This involves building Apache and its modules separately, and then loading the ones you want when you start the Apache server.
As with statically linking the modules, whether you consider a particular thing an advantage or a disadvantage, with respect to DSOs, is purely your opinion.
Building modules as shared objects allows you to decide to change what modules you have loaded on a moment's notice, just by changing the configuration file. If you want to add a new module, you only have to build that module, rather than rebuilding Apache. You then add a LoadModule directive to your main server configuration file, and restart the server.
Apache will start up slightly slower on restart, because it has to locate and load each of the .so files. However, this is seldom actually a noticeable slowdown, and does not translate into any slower performance after the startup is completed.
The main httpd binary will be substantially smaller than it would be if all the modules were built into it. But the combined size of the httpd binary and the various .so files will be roughly the same as the httpd binary with all the same modules built in.
To install a module as a shared object, rather than statically linked, you need merely to add the -enable-shared argument when you run configure.
For example, to install mod_rewrite as a DSO, you would use the following command:
./configure —prefix=/usr/local/apache
—enable-module=rewrite
—enable-shared=rewrite
You are not required to choose one method or the other—that is, you can install some modules statically, and other dynamically.
As before, the previous command needs to be followed by the commands make and make install to complete the process.
If you want to build all the modules that came with Apache as shared objects use the following convenience syntax:
./configure —prefix=/usr/local/apache
—enable-module=most
—enable-shared=max
This will build most, but not all, of the modules that are distributed with Apache. The ones left out are those considered experimental, and those, such as mod_auth_db, which require external libraries that might not be present.
The -enable-shared=max syntax can be used without the other parts of this command, if you want to ensure that all modules are installed as DSOs.
./configure —prefix=/usr/local/apache —enable-shared=max
This will build Apache with the standard list of enabled modules, and build them all as DSOs. Again, see the next chapter for a full list of the modules distributed with Apache, and the ones compiled by default.
The DSO functionality is implemented by mod_so, which must be built in to load the other modules. You can't build mod_so as a DSO.
Modules implement all the interesting functionality in Apache, with the core doing as little as possible. In Apache 2.0, the core does even less than it does in 1.3, with more of the functionality being pulled out into modules.
Modules can be installed statically or dynamically, as shared objects, if your operating system supports that functionality.
[1] The backslash character at the end of the line is a continuation character, telling the shell that the command continues on the next line. Most shells understand this notation. You can also just type the entire command on one line. It is broken into shorter lines to make its format fit the book.