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 2 - A First Module
Directory Layout Structure

We refer to a variety of special files and directories throughout this book. Although there is a standard Apache server layout, this standard has changed over time and many sites have extensively customized their layout. Furthermore, some operating systems which come with Apache preinstalled choose a nonstandard directory structure that is more consistent with the OS's way of doing things. To avoid potential confusion, we explain the directory structure we use in this book. If you are installing Apache and mod_perl for the first time, you might want to follow the suggestions given here for convenience.

Server root directory

This is the top of the Apache server tree. In a typical setup, this directory contains a bin directory for the httpd Apache executable and the apachectl control utility; the configuration and log directories (conf and logs); a directory for executable CGI scripts, cgi-bin; a directory for dynamically loaded modules, libexec; header files for building C-language modules, include; and the document root directory, htdocs.²

The default server root directory on Unix machines is /usr/local/apache, which we'll use throughout the book. However, in order to avoid typing this long name, we suggest creating a pseudo-user named www with /usr/local/apache as its home directory.³ This allows you to refer to the server root quickly as ~www.

On Win32 systems, the default server root is C:\Program Files\Apache Group\Apache. However, many people change that to simply C:\Apache, as we do here. Readers who use this platform should mentally substitute ~www with the path to their true server root.

Document root directory

This is the top of the web document tree, the default directory from which the server fetches documents when the remote user requests http://your.site/. We'll assume ~www/ htdocs in our examples (C:\Apache\htdocs on Win32 systems).

Apache and mod_perl build directory

This is a directory where you can build Apache and mod_perl from their source distributions. There's no standard place for this. Different people use /usr/src, /usr/build, /usr/ tmp, or their home directories. In order to keep the various packages in one place, we recommend ~www/build for this purpose.

httpd.conf, srm.conf, access.conf

These are the three important configuration files for the Apache server. There are three separate configuration files for historical reasons (to support backward compatibility with NCSA httpd). Any configuration directive can go into any of these files. Many sites have forcibly desegregated their directives and placed all their site's configuration directives into a single large httpd.conf file; in fact, this is the default as of Version 1.3.4 of Apache. Other sites use separate files for each virtual host and use the Include directive to load them all at configuration time.

We use a slightly modified version of the lump-everything-into-httpd.conf approach. All the core Apache directives are kept in httpd.conf, including virtual hosts and per-directory configuration sections. However, we like to pull all the Apache Perl API directives into a separate file named perl.conf and then load it at server startup time with the following set of directives:

<IfModule mod_perl.c>
 Include conf/perl.conf
</IfModule>

The <IfModule> conditional directive allows us to use the same httpd.conf file for servers that include the embedded Perl interpreter as well as those that do not. Notice that the argument to <IfModule> is the name of the module source code file, so you have to use mod_perl.c here, rather than mod_perl.

httpd.conf and its sibling configuration files all live in ~www/conf.

.htaccess

This is the file extension for the per-directory configuration files that can be located throughout the document tree. Although the name implies a role in access control, this is just another historical artifact. These files are more frequently used as a way to change per-directory configuration options without modifying the central configuration files. Some sites change the name of the .htaccess file to something more meaningful (or more obscure). We use the default name in our examples and, in fact, use the term ".htaccess file" somewhat generically rather than the longer, but more accurate, "per-directory access control and options file."

cgi-bin

This is the location of the server's executable CGI scripts, usually ~www/cgi-bin. We assume the default.

perl

This is the location of Perl scripts running under mod_perl's Apache::Registry module (which we talk more about later in this chapter). Perl source files located in this directory are executed as if they were CGI scripts but load and run much faster because they are interpreted directly by the server. We use ~www/perl in this book.

Module library tree

You need a convenient place to put any library files used by modules written under the Perl API and any dynamically loadable modules written with the C API (.o and .so files under Unix, .dll files on Win32). The standard location for C API modules is ~www/ libexec on Unix systems (C:\Apache\libexec on Win32 systems).

There is no standard location for Perl API modules, so we recommend creating a directory named ~www/lib/perl for this purpose.

"Perl module" and "Apache Perl module"

Speaking of which, there is a nasty potential ambiguity in the word "module" when referring to Apache modules written using the Perl API. Perl itself makes extensive use of loadable library modules (.pm files) that have nothing to do with running a web server. Making things even more confusing is the fact that the Apache modules written in Perl are usually .pm files themselves.

We try to minimize the ambiguity by referring to "Perl module" when we mean plain old Perl modules that are not involved in the web server and "Apache Perl module" when we mean Perl modules written to run under the Apache Perl API. In addition, all Apache Perl modules are named beginning with the word "Apache::". Here are some examples:

Perl library tree

This is the location of the Perl5 library tree, which was created when you (or someone else) installed Perl on your system. It contains Perl modules, Plain Old Documentation (POD) files, loadable library objects, and header files used for compiling new Perl modules. This directory can be located in a variety of amusing and surprising places, but on most systems it can be found in /usr/lib/perl5, /usr/local/lib/perl5, or C:\perl5 (Win32).

Footnotes

² The directory layout we describe here is the default Apache layout. Other predefined layouts may be configured with the Apache configuration option --with-layout= where can be GNU or another user-defined layout. Consult the Apache installation documention for more details.

³ If you do set up the www pseudo-user, be sure to forbid login for this user by locking the account password. You can make the httpd executable and its auxiliary files owned by this user if you wish, but the server should continue to run with the permissions of the "nobody" user as recommended by the default configuration. It's also sometimes handy to create a www group to which the webmaster and other users authorized to work in the server root belong.