Show Contents Previous Page Next Page
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
Apache executable and the
apachectl control utility; the
configuration and log directories (
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
The default server root directory on Unix machines is
which we'll use throughout the book. However, in order to avoid typing
this long name, we suggest creating a pseudo-user named www
/usr/local/apache as its home directory.3
This allows you to refer to the server root quickly as
On Win32 systems, the default server root is
Group\Apache. However, many people change that to simply
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
~www/ htdocs in our examples (
on Win32 systems).
- Apache and mod_perl build directory
This is a directory where you can build Apache and
from their source distributions. There's no standard place for this. Different
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-
approach. All the core Apache directives are kept in
including virtual hosts and per-directory configuration sections. However,
we like to pull all the Apache Perl API directives into a separate file
perl.conf and then load it at server startup time with
the following set of directives:
The <IfModule> conditional directive allows us to use
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
httpd.conf and its sibling configuration files all live in
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."
This is the location of the server's executable CGI scripts, usually
~www/cgi-bin. We assume the default.
This is the location of Perl scripts running under
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
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
.so files under Unix,
files on Win32). The standard location for C API modules is
on Unix systems (
C:\Apache\libexec on Win32 systems).
There is no standard location for Perl API modules, so we recommend creating a directory
~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 (
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
.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:
Type of Module
Apache Perl module
- 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
2 The directory layout we describe here is the
default Apache layout. Other predefined layouts may be configured with the Apache
--with-layout= where can be
or another user-defined layout. Consult the Apache installation documention
for more details.
3 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 Show Contents Previous Page Next Page
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.
Copyright © 1999 by O'Reilly & Associates, Inc.