Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 8 - Customizing the Apache Configuration Process

In this section...

Introduction Simple Configuration with the PerlSetVar Directive The Apache Configuration Directive API Configuring Apache with Perl Documenting Configuration Files

Introduction

In this Chapter

• Simple Configuration with the PerlSetVar Directive
• The Apache Configuration Directive API
• Configuring Apache with Perl
• Documenting Configuration Files

This chapter covers an important but complex aspect of the Apache Perl API--the process of controlling and customizing the Apache configuration process itself. Using the techniques shown in this chapter, you will be able to define new configuration file directives that provide runtime configuration information to your modules. You will also be able to take over all or part of the Apache configuration process and write Perl code to dynamically configure the server at startup time.

Simple Configuration with the PerlSetVar Directive

The Apache Perl API provides a simple mechanism for passing information from configuration files to Perl modules using the PerlSetVar directive. As we've seen, the directive takes two arguments, the name of a variable and its value:

PerlSetVar FoodForThought apples

Because Perl is such a whiz at parsing text, it's trivial to pass an array or even a hash in this way. For example, here's one way (out of a great many) to pass an array:

# in configuration file
PerlSetVar FoodForThought apples:oranges:kiwis:mangos

# in Perl module
@foodForThought = split ":", $r->dir_config('FoodForThought');

And here's a way to pass a hash:

# in configuration file
PerlSetVar FoodForThought apples=>23,kiwis=>12
# in Perl module
%foodForThought = split /\s*(?:=>|,)\s*/, $r->dir_config('FoodForThought);

Notice that the pattern match allows whitespace to come before or after the comma or arrow operators, just as Perl does.

By modifying the pattern match appropriately, you can pass more complex configuration information. The only trick is to remember to put double quotes around the configuration value if it contains whitespace and not to allow your text editor to wrap it to another line. You can use backslash as a continuation character if you find long lines a pain to read:

PerlSetVar FoodForThought "apples    => 23,\
                          kiwis     => 12,\
                          rutabagas => 0"

If you have a really complex configuration, then you are probably better off using a separate configuration file and pointing to it using a single PerlSetVar directive. The server_root_relative() method is useful for specifying configuration files that are relative to the server root:

# in server configuration file
PerlSetVar  FoodConfig conf/food.conf

# in Perl module
$conf_file = $r->server_root_relative($r->dir_config('FoodConfig'));

Despite the simplicity of this approach, there are times when you may prefer to create your own "first-class" configuration directives. This becomes particularly desirable when you have many different directives, when the exact syntax of the directives is important and you want Apache to check the syntax at startup time, or when you are planning to distribute your module and want it to appear polished. There is also a performance penalty associated with parsing PerlSetVar configuration at request time, which you avoid using first-class configuration directives because they are parsed once at server startup time.