Writing Apache Modules with Perl and C

8.2. The Apache Configuration Directive API

Apache provides an API for defining configuration directives. You provide the directive's name, syntax, and a string briefly summarizing the directive's intended usage. You may also limit the applicability of the directive to certain parts of the configuration files. Apache parses the directive and passes the parsed structure to your module for processing. Your module will then use this information to set up global variables or initialize whatever it needs.

The process of defining new configuration directives is not as simple as other parts of the Perl API. This is because configuration directives are defined in a compiled C structure that cannot be built dynamically at runtime. In order to work with this restriction, mod_perl requires you to take the following roundabout route:

1. Create an empty module directory with h2xs.

2. Modify the newly created Makefile.PL file to declare an array containing the definitions for the new configuration directives and to invoke the command_table() function from a helper module named Apache::ExtUtils.

3. Write a .pm file containing Perl handlers for each of the configuration directives you define.

4. Run perl Makefile.PL to autogenerate a .xs file.

5. Run make and make install to create the loadable module and move it into place.

6. Add a PerlModule directive to the server configuration file to load the module at server startup time.

We'll take you through a short example first to show you the whole process and then get ...