Practical mod_perl | by Stas Bekman and Eric Cholet

Written for Perl web developers and web administrators, Practical mod_perl is an extensive guide to the nuts and bolts of the powerful and popular combination of Apache and mod_perl. From writing and debugging scripts to keeping your server running without failures, the techniques in this book will help you squeeze every ounce of power out of your server. True to its title, this is the practical guide to mod_perl.

Title	Practical mod_perl
Author	Stas Bekman and Eric Cholet
Publisher	O'Reilly and Associates
Year	2003
Copyright	Creative Commons Attribution Share-Alike License
Amazon	Practical mod_perl

Preface: mod_perl is an Apache module that builds the power of the Perl programming language directly into the Apache web server. With mod_perl, CGI scripts run as much ...

Part 1: mod_perl Administration: Part I. mod_perl Administration The first part of this book is about mod_perl administration. Here you'll find everything you need to do to get mod_perl ...

Part 2: mod_perl Performance: Part II. mod_perl Performance This section explains the details of tuning mod_perl and the scripts running under it, so you can squeeze every ounce of power ...

Part 3: Databases and mod_perl: Part III. Databases and mod_perl Databases are used to store and retrieve data, and are commonly used with mod_perl applications. In this section, we present ...

Part 4: Debugging and Troubleshooting: Part IV. Debugging and Troubleshooting If the rest of this book is about how to use mod_perl properly, this section is about what to do when things go wrong.

Part 5: mod_perl 2.0: Part V. mod_perl 2.0 The majority of this book covers mod_perl 1.x, which was the stable version of mod_perl at the time of this writing. However, the exciting ...

Part 6: Appendixes: Part VI. Appendixes This book has six appendixes: Appendix A is a mini-cookbook for mod_perl. Look here before reinventing the wheel; it's possible that ...

0.1. What You Need to Know: To use this book effectively, you need to be familiar with the day-to-day details of running a web server, and you need to know the Perl programming language.

0.2. Who This Book Is For: This book is not solely about mod_perl web development. It covers two main topics: server administration and programming under mod_perl. At first, you might ...

0.3. How This Book Is Organized: This book has four parts: Part I: mod_perl Administration Part I of this book focuses on the administration of mod_perl: getting it installed, configuring ...

0.4. Reference Sections: At the end of almost every chapter in this book, we include lists of resources that give further detail on relevant topics. The references are usually either ...

0.5. Filesystem Conventions: Throughout the book, unless mentioned otherwise, we assume that all the sources are downloaded and built in the directory /home/stas/src/. If you follow the ...

0.6. Apache and Perl Versions: We have used mod_perl 1.26 and Apache 1.3.24 in most of the examples in this book. You should be able to reproduce all the presented examples with these or ...

0.7. Typographic Conventions: The following typographic conventions are used in this book: Italic Used for filenames, command names, directory names, and Unix utilities. It is also used for ...

0.8. Command Interpreter Program (Shell) Conventions: When you type a command and press the Enter key to execute this command, it's usually interpreted by some kind of command interpreter program, known as a shell.

0.9. Installing Perl Modules: mod_perl and all the various Perl modules and helper utilities mentioned in this book are available via FTP and HTTP from any of the sites on the Comprehensive ...

9.1. Manual Installation: When you download a module manually, it's best to find the one closest to you. You can find a list of CPAN mirrors at http://mirror.cpan.org/. You can download ...

9.2. Prerequisites Needed to Install Perl Modules on Windows: While Unix operating systems include standard utilities such as tar, gzip, and make, Windows systems don't. For this reason, you will have to go through some ...

9.3. Building a Perl Module: Building a Perl module and installing it is simple and usually painless. Perl modules are distributed as gzipped tar archives. You can unpack them like this: ...

9.4. Using the CPAN Shell: A simpler way to do the same thing is to use Andreas Koenig's wonderful CPAN shell (recent Perl versions come bundled with this module). With it, you can ...

9.5. Using the Perl Package Manager: If you are using ActivePerl on Windows, or the Perl/Apache/mod_perl binary distribution discussed in Chapter 2, you will have access to a handy utility called ...

0.10. How to Contact Us: Please address comments and questions concerning this book to the publisher: O'Reilly Associates, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 (800) ...

0.11. Acknowledgments: Many people have contributed to this book over the long period while it was in the works. First things first. This book wouldn't exist without Doug MacEachern, ...

Chapter 1. Introducing CGI and mod_perl: Contents: A Brief History of CGI The Apache 1.3 Server Model The Development of mod_perl 1.0 Apache 1.3 Request Processing Phases ReferencesThis chapter ...

1.1. A Brief History of CGI: When the World Wide Web was born, there was only one web server and one web client. The httpd web server was developed by the Centre d'Etudes et de Recherche ...

1.1.1. The HTTP Protocol: Interaction between the browser and the server is governed by the HyperText Transfer Protocol (HTTP), now an official Internet standard maintained by the World ...

1.1.2. The Common Gateway Interface Specification: If you are new to the CGI world, there's no need to worry basic CGI programming is very easy. Ninety percent of CGI-specific code is concerned with reading ...

1.1.3. Apache CGI Handling with mod_cgi: The Apache server processes CGI scripts via an Apache module called mod_cgi. (See later in this chapter for more information on request-processing phases and ...

1.2. The Apache 1.3 Server Model: Now that you know how CGI works, let's talk about how Apache implements mod_cgi. This is important because it will help you understand the limitations of ...

1.2.1. Forking: Apache 1.3 on all Unix flavors uses the forking model.[8] When you start the server, a single process, called the parent process, is started. Its main ...

1.2.2. CGI Scripts Under the Forking Model: One of the benefits of this model is that if something causes the child process to die (e.g., a badly written CGI script), it won't cause the whole service to ...

1.2.3. Performance Drawbacks of Forking: There are several drawbacks to mod_cgi that triggered the development of improved web technologies. The first problem lies in the fact that a new process is ...

1.3. The Development of mod_perl 1.0: Of the various attempts to improve on mod_cgi's shortcomings, mod_perl has proven to be one of the better solutions and has been widely adopted by CGI ...

1.3.1. Running CGI Scripts with mod_perl: Since many web application developers are interested in the content delivery phase and come from a CGI background, mod_perl includes packages designed to make ...

1.4. Apache 1.3 Request Processing Phases: To understand mod_perl, you should understand how request processing works within Apache. When Apache receives a request, it processes it in 11 phases. For ...

1.4.1. Apache 1.3 Modules and the mod_perl 1.0 API: The advantage of breaking up the request process into phases is that Apache gives a programmer the opportunity to hook into the process at any of those phases.

1.4.2. mod_perl 1.0 and the mod_perl API: Like other Apache modules, mod_perl is written in C, registers handlers for request phases, and uses the Apache API. However, mod_perl doesn't directly process ...

1.5. References: The CGI specification: http://hoohoo.ncsa.uiuc.edu/cgi/ The HTTP/1.1 standard: http://www.w3.org/Protocols/rfc2616/rfc2616.html Various information about CGI ...

Chapter 2. Getting Started Fast: Contents: Installing mod_perl 1.0 in Three Steps Installing mod_perl on Unix Platforms Configuring and Starting the mod_perl Server Installing mod_perl for ...

2.1. Installing mod_perl 1.0 in Three Steps: You can install mod_perl in three easy steps: obtain the source files required to build mod_perl, build mod_perl, and install it. Building mod_perl from source ...

2.2. Installing mod_perl on Unix Platforms: Now let's go over the installation again, this time with each step explained in detail and with some troubleshooting advice. If the build worked and you are in ...

2.2.1. Obtaining and Unpacking the Source Code: The first step is to obtain the source code distributions of Apache and mod_perl. These distributions can be retrieved from http://www.apache.org/dist/httpd/ ...

2.2.2. Building mod_perl: Move into the /home/stas/src/mod_perl-1.xx/ source distribution directory: panic% cd mod_perl-1.xx The next step is to create the Makefile. This is no ...

2.2.3. Installing mod_perl: Running make install completes the installation process by installing all the Perl files required for mod_perl to run. It also installs the mod_perl ...

2.3. Configuring and Starting the mod_perl Server: Once you have mod_perl installed, you need to configure the server and test it. The first thing to do is ensure that Apache was built correctly and that it can ...

2.4. Installing mod_perl for Windows: Apache runs on many flavors of Unix and Unix-like operating systems. Version 1.3 introduced a port to the Windows family of operating systems, often named ...

2.4.1. Installing mod_perl with the Perl Package Manager: If you are already a Perl developer on Windows, it is likely that you have ActivePerl (see http://www.activestate.com/) installed. In that case, you can get a ...

2.5. Preparing the Scripts Directory: Now you have to select a directory where all the mod_perl scripts and modules will be placed. We usually create a directory called modperl under our home ...

2.6. A Sample Apache::Registry Script: One of mod_perl's benefits is that it can run existing CGI scripts written in Perl that were previously used under mod_cgi (the standard Apache CGI handler).

2.6.1. Porting Existing CGI Scripts to mod_perl: Now it's time to move any existing CGI scripts from the /somewhere/cgi-bin directory to /home/stas/modperl. Once moved, they should run much faster when ...

2.7. A Simple mod_perl Content Handler: As we mentioned in the beginning of this chapter, mod_perl lets you run both scripts and handlers. The previous example showed a script, which is probably the ...

2.8. Is This All We Need to Know About mod_perl?: So do you need to know more about mod_perl? The answer is, Yes and no. Just as with Perl, effective scripts can be written even with very little mod_perl ...

2.9. References: The Apache home page: http://www.apache.org/. The mod_perl home page: http://perl.apache.org/. The CPAN home page: http://cpan.org/ CPAN is the Comprehensive ...

Chapter 3. Installing mod_perl: Contents: Configuring the Source Building mod_perl (make) Testing the Server (make test) Installation (make install) Installation Scenarios for Standalone ...

3.1. Configuring the Source: Before building and installing mod_perl you will have to configure it, as you would configure any other Perl module: panic% perl Makefile.PL [parameters]. Perl ...

3.1.1. Controlling the Build Process: The configuration stage of the build is performed by the command perl Makefile.PL, which accepts various parameters. This section covers all of the ...

3.1.2. Activating Callback Hooks: A callback hook (also known simply as a callback) is a reference to a subroutine. In Perl, we create subroutine references with the following syntax: $callback ...

3.1.3. Activating Standard API Features: The following options enable various standard features of the mod_perl API. While not absolutely needed, they're very handy and there's little penalty in ...

3.1.4. Enabling Extra Features: mod_perl comes with a number of other features. Most of them are disabled by default. This is the list of features and options to enable them: Perl sections ...

3.1.5. Reusing Configuration Parameters: When you have to upgrade the server, it's sometimes hard to remember what parameters you used in the previous mod_perl build. So it's a good idea to save them ...

3.1.6. Discovering Whether a Feature Was Enabled: mod_perl Version 1.25 introduced Apache::MyConfig, which provides access to the various hooks and features set when mod_perl was built. This circumvents the ...

3.1.7. Using an Alternative Configuration File: By default, mod_perl provides its own copy of the Configuration file to Apache's configure utility. If you want to pass it your own version, do this: panic% ...

3.1.8. perl Makefile.PL Troubleshooting: During the configuration (perl Makefile.PL) stage, you may encounter some of these problems. To help you avoid them, let's study them, find out why they ...

3.1.8.1. A test compilation with your Makefile configuration failed...: When you see the following error during the perl Makefile.PL stage: ** A test compilation with your Makefile configuration ** failed. This is most likely ...

3.1.8.2. Missing or misconfigured libgdbm.so: On some Red Hat Linux systems, you might encounter a problem during the perl Makefile.PL stage, when Perl was installed from an rpm package built with the gdbm ...

3.1.8.3. Undefined reference to `PL_perl_destruct_level': When manually building mod_perl using the shared library: panic% cd mod_perl-1.xx panic% perl Makefile.PL PREP_HTTPD=1 panic% make make test panic# make ...

3.2. Building mod_perl (make): After completing the configuration, it's time to build the server by simply calling: panic% make The make program first compiles the source files and creates a ...

3.2.1. What Compiler Should Be Used to Build mod_perl?: All Perl modules that use C extensions must be compiled using the compiler with which your copy of Perl was built. When you run perl Makefile.PL, a Makefile is ...

3.2.2. make Troubleshooting: The following errors are the ones that frequently occur during the make process when building mod_perl. Continue to: prev: 3.2.1. What Compiler Should Be ...

3.2.2.1. Undefined reference to `Perl_newAV': This and similar error messages may show up during the make process. Generally it happens when you have a broken Perl installation. If it's installed from a ...

3.2.2.2. Unrecognized format specifier for...: This error is usually reported due to the problems with some versions of the SFIO library. Try to use the latest version to get around this problem or, if you ...

3.3. Testing the Server (make test): After building the server, it's a good idea to test it throughly by calling: panic% make test Fortunately, mod_perl comes with a big collection of tests, which ...

3.3.1. Manual Testing: Tests are invoked by running the ./TEST script located in the ./t directory. Use the -v option for verbose tests. You might run an individual test like this: ...

3.3.2. make test Troubleshooting: The following sections cover problems that you may encounter during the testing stage. Continue to: prev: 3.3.1. Manual Testing Table of Contents next: 3.

3.3.2.1. make test fails: make test requires Apache to be running already, so if you specified NO_HTTPD=1 during the perl Makefile.PL stage, you'll have to build httpd independently ...

3.3.2.2. mod_perl.c is incompatible with this version of Apache: If you had a stale Apache header layout in one of the include paths during the build process, you will see the message mod_perl.c is incompatible with this ...

3.3.2.3. make test......skipping test on this platform: make test may report some tests as skipped. They are skipped because you are missing the modules that are needed for these tests to pass. You might want to ...

3.3.2.4. make test fails due to misconfigured localhost entry: The make test suite uses localhost to run the tests that require a network. Make sure you have this entry in /etc/hosts: 127.0.0.1 localhost.localdomain ...

3.4. Installation (make install): After testing the server, the last step is to install it. First install all the Perl files (usually as root): panic# make install Then go to the Apache source ...

3.4.1. Manually Building a mod_perl-Enabled Apache: If you want to build httpd separately from mod_perl, you should use the NO_HTTPD=1 option during the perl Makefile.PL (mod_perl build) stage. Then you will ...

3.5. Installation Scenarios for Standalone mod_perl: When building mod_perl, the mod_perl C source files that have to be compiled into the httpd executable usually are copied to the subdirectory src/modules/perl/ ...

3.5.1. The All-in-One Way: If your goal is just to build and install Apache with mod_perl out of their source trees, and you have no interest in further adjusting or enhancing Apache, ...

3.5.2. Building mod_perl and Apache Separately: However, sometimes you might need more flexibility while building mod_perl. If you build mod_perl into the Apache binary (httpd) in separate steps, you'll also ...

3.5.3. When DSOs Can Be Used: If you want to build mod_perl as a DSO, you must make sure that Perl was built with the system's native malloc( ). If Perl was built with its own malloc( ) and ...

3.5.4. Building mod_perl as a DSO via APACI: We have already mentioned that the new mod_perl build environment (with USE_APACI) is a hybrid. What does that mean? It means, for instance, that you can use ...

3.5.5. Building mod_perl as a DSO via APXS: We've seen how to build mod_perl as a DSO inside the Apache source tree, but there is a nifty alternative: building mod_perl as a DSO outside the Apache source ...

3.6. Building mod_perl with Other Components: mod_perl is often used with other components that plug into Apache, such as PHP and SSL. In this section, we'll show you a build combining mod_perl with PHP.

3.6.1. Installing mod_perl with PHP: The following is a simple installation scenario of a combination mod_perl and PHP build for the Apache server. We aren't going to use a custom installation ...

3.6.2. Installing mod_perl with mod_ssl (+openssl): mod_ssl provides strong cryptography for the Apache 1.3 web server via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols.

3.6.3. Installing mod_perl with Apache-SSL (+openssl): Apache-SSL is a secure web server based on Apache and SSLeay/OpenSSL. It is licensed under a BSD-style license, which means that you are free to use it for ...

3.6.4. Installing mod_perl with Stronghold: Stronghold is a secure SSL web server for Unix that allows you to give your web site full-strength, 128-bit encryption. It's a commercial product provided by ...

3.7. Installing mod_perl with the CPAN.pm Interactive Shell: Installation of mod_perl and all the required packages is much easier with the help of the CPAN.pm module, which provides, among other features, a shell ...

3.8. Installing mod_perl on Multiple Machines: You may want to build httpd once and then copy it to other machines. But the Perl side of mod_perl needs the Apache header files to compile. To avoid dragging ...

3.9. Installation into a Nonstandard Directory: There are situations when you need to install mod_perl-enabled Apache and other components (such as Perl libraries) into nonstandard locations. For example, ...

3.9.1. Installing Perl Modules into a Nonstandard Directory: Before we proceed, let's look at how to install any Perl module into a nonstandard directory. For an example, let's use the package that includes CGI.pm and a ...

3.9.2. Finding Modules Installed in Nonstandard Directories: Installing Perl modules into nonstandard directories is only half the battle. We also have to let Perl know what these directories are. Perl modules are ...

3.9.2.1. Modifying @INC: Modifying @INC is quite easy. The best approach is to use the lib module (pragma) by adding the following snippet at the top of any of your scripts that ...

3.9.2.2. Using the PERL5LIB environment variable: Now, let's assume the following scenario. We have installed the LWP package in our local repository. Now we want to install another module (e.g., mod_perl), ...

3.9.3. Using the CPAN.pm Shell with Nonstandard Installation Directories: As we saw previously in this chapter, using the CPAN.pmshell to install mod_perl saves a great deal of time. It does the job for us, even detecting the missing ...

3.9.4. Making a Local Apache Installation: Just as with Perl modules, if you don't have the permissions required to install Apache into the system area, you have to install them locally under your home ...

3.9.5. Nonstandard mod_perl-Enabled Apache Installation: Now that we know how to install local Apache and Perl modules separately, let's see how to install mod_perl-enabled Apache in our home directory. It's almost ...

3.9.6. Nonstandard mod_perl-Enabled Apache Installation with CPAN.pm: Again, CPAN makes installation and upgrades simpler. You have seen how to install a mod_perl-enabled server using CPAN.pm's interactive shell. You have seen ...

3.10. How Can I Tell if mod_perl Is Running?: There are several ways to find out if mod_perl is enabled in your version of Apache. In older versions of Apache (versions earlier than 1.3.6), you could check ...

3.10.1. Checking the error_log File: One way to check for mod_perl is to check the error_log file for the following message at server startup: [Sat May 18 18:08:01 2002] [notice] Apache/1.3.24 ( ...

3.10.2. Testing by Viewing /perl-status: Assuming that you have configured the Location /perl-status section in the server configuration file as explained in Chapter 9, fetch http://www.example.com/ ...

3.10.3. Testing via Telnet: Knowing the port you have configured Apache to listen on, you can use Telnet to talk directly to it. Assuming that your mod_perl-enabled server listens to port ...

3.10.4. Testing via a CGI Script: Another method to test for mod_perl is to invoke a CGI script that dumps the server's environment. We assume that you have configured the server so that ...

3.10.5. Testing via lwp-request: Assuming you have the libwww-perl (LWP) package installed, you can run the following tests. (Most likely you do have it installed, since you need it to pass ...

3.11. General Notes: This section looks at some other installation issues you may encounter. Continue to: prev: 3.10.5. Testing via lwp-request Table of Contents next: 3.11.1.

3.11.1. How Do I Make the Installation More Secure?: Unix systems usually provide chroot or jail mechanisms, which allow you to run subsystems isolated from the main system. So if a subsystem gets compromised, ...

3.11.2. Can I Run mod_perl-Enabled Apache as suExec?: The answer is definitively no. You can't suid a part of a process. mod_perl lives inside the Apache process, so its UID and GID are the same as those of the ...

3.11.3. Should I Rebuild mod_perl if I Have Upgraded Perl?: Yes, you should. You have to rebuild the mod_perl-enabled server, because it has a hardcoded @INC variable. This points to the old Perl and is probably linked ...

3.11.4. mod_auth_dbm Nuances: If you are a mod_auth_dbm or mod_auth_db user, you may need to edit Perl's Config module. When Perl is configured, it attempts to find libraries for ndbm, gdbm, ...

3.12. References: Apache Toolbox (http://apachetoolbox.com/) provides a means to easily compile Apache with about 60 different Apache modules. It is fully customizable and menu- ...

Chapter 4. mod_perl Configuration: Contents: Apache Configuration mod_perl Configuration The Startup File Apache Configuration in Perl Validating the Configuration Syntax The Scope of mod_perl ...

4.1. Apache Configuration: Apache configuration can be confusing. To minimize the number of things that can go wrong, it's a good idea to first configure Apache itself without mod_perl.

4.1.1. Configuration Files: Prior to Version 1.3.4, the default Apache installation used three configuration files: httpd.conf, srm.conf, and access.conf. Although there were historical ...

4.1.2. Configuration Directives: A basic setup requires little configuration. If you moved any directories after Apache was installed, they should be updated in httpd.conf. Here are just a ...

4.1.3. <Directory>, <Location>, and <Files> Sections: Let's discuss the basics of the Directory , Location , and Files sections. Remember that there is more to know about them than what we list here, and the rest ...

4.1.3.1. <Directory directoryPath> ... </Directory>: Scope: Can appear in server and virtual host configurations. Directory and /Directory are used to enclose a group of directives that will apply to only the ...

4.1.3.2. <Files filename > ... </Files>: Scope: Can appear in server and virtual host configurations, as well as in .htaccess files. The Files directive provides access control by filename and is ...

4.1.3.3. <Location URI> ... </Location>: Scope: Can appear in server and virtual host configurations. The Location directive provides for directive scope limitation by URI. It is similar to the ...

4.1.4. Merging <Directory>, <Location>, and <Files> Sections: When configuring the server, it's important to understand the order in which the rules of each section are applied to requests. The order of merging is: ...

4.1.5. Subgrouping of <Directory>, <Location>, and <Files> Sections: Let's say that you want all files to be handled the same way, except for a few of the files in a specific directory and its subdirectories. For example, say ...

4.1.6. Options Directive Merging: Normally, if multiple Options directives apply to a directory, the most specific one is taken completely; the options are not merged. However, if all the ...

4.1.7. MinSpareServers, MaxSpareServers, StartServers, MaxClients, and MaxRequestsPerChild: MinSpareServers, MaxSpareServers, StartServers, and MaxClients are standard Apache configuration directives that control the number of servers being launched ...

4.2. mod_perl Configuration: When you have tested that the Apache server works on your machine, it's time to configure the mod_perl part. Although some of the configuration directives are ...

4.2.1. Alias Configurations: For many reasons, a server can never allow access to its entire directory hierarchy. Although there is really no indication of this given to the web browser, ...

4.2.1.1. Running scripts located in the same directory under different handlers: Sometimes you will want to map the same directory to a few different locations and execute each file according to the way it was requested. For example, in the ...

4.2.2. <Location /perl> Sections: The Location section assigns a number of rules that the server follows when the request's URI matches the location. Just as it is a widely accepted convention ...

4.2.3. PerlModule and PerlRequire: As we saw earlier, a module should be loaded before its handler can be used. PerlModule and PerlRequire are the two mod_perl directives that are used to load ...

4.2.4. PerlHandlers: As mentioned in Chapter 1, Apache specifies 11 phases of the request loop. In order of processing, they are: Post-read-request, URI translation, header parsing, ...

4.2.5. The handler( ) Subroutine: By default, the mod_perl API expects a subroutine named handler( ) to handle the request in the registered Perl*Handler module. Thus, if your module implements ...

4.2.6. Investigating the Request Phases: Imagine a complex server setup in which many different Perl and non-Perl handlers participate in the request processing, and one or more of these handlers ...

4.2.7. Stacked Handlers: With the mod_perl stacked handlers mechanism, it is possible for more than one Perl*Handler to be defined and executed during any stage of a request. Perl* ...

4.2.8. Perl Method Handlers: If mod_perl was built with: panic% perl Makefile.PL PERL_METHOD_HANDLERS=1 [ ... ] or: panic% perl Makefile.PL EVERYTHING=1 [ ... ] it's possible to write ...

4.2.9. PerlFreshRestart: To reload PerlRequire, PerlModule, and other use( ) d modules, and to flush the Apache::Registry cache on server restart, add this directive to httpd.conf: ...

4.2.10. PerlSetEnv and PerlPassEnv: In addition to Apache's SetEnv and PassEnv directives, respectively setting and passing shell environment variables, mod_perl provides its own directives: ...

4.2.11. PerlSetVar and PerlAddVar: PerlSetVar is another directive introduced by mod_perl. It is very similar to PerlSetEnv, but the key/value pairs are stored in an Apache::Table object and ...

4.2.12. PerlSetupEnv: Certain Perl modules used in CGI code (such as CGI.pm) rely on a number of environment variables that are normally set by mod_cgi. For example, many modules ...

4.2.13. PerlWarn and PerlTaintCheck: PerlWarn and PerlTaintCheck have two possible values, On and Off. PerlWarn turns warnings on and off globally to the whole server, and PerlTaintCheck controls ...

4.3. The Startup File: At server startup, before child processes are spawned, you can do much more than just preload modules. You might want to register code that will initialize a ...

4.3.1. A Sample Startup File: Let's look at a real-world startup file. The elements of the file are shown here, followed by their descriptions. use strict; This pragma is worth using in ...

4.3.2. Syntax Validation: If the startup file doesn't include any modules that require the mod_perl runtime environment during their loading, you can validate its syntax with: panic% ...

4.3.3. What Modules Should Be Added to the Startup File: Every module loaded at server startup will be shared among the server children, saving a lot of RAM on your machine. Usually, we put most of the code we ...

4.3.4. The Confusion with use( ) in the Server Startup File: Some people wonder why they need to duplicate use Modulename in the startup file and in the script itself. The confusion arises due to misunderstanding use( ).

4.4. Apache Configuration in Perl: With Perl ... /Perl sections, you can configure your server entirely in Perl. It's probably not worth it if you have simple configuration files, but if you run ...

4.4.1. Constructing <Perl> Sections: Perl sections can contain any and as much Perl code as you wish. Perl sections are compiled into a special package called Apache::ReadConfig. mod_perl looks ...

4.4.2. Breaking Out of <Perl> Sections: Behind the scenes, mod_perl defines a package called Apache::ReadConfig in which it keeps all the variables that you define inside the Perl sections. So Perl ...

4.4.3. Cheating with Apache->httpd_conf: In fact, you can create a complete configuration file in Perl. For example, instead of putting the following lines in httpd.conf: NameVirtualHost 10.0.0.10 ...

4.4.4. Declaring Package Names in Perl Sections: Be careful when you declare package names inside Perl sections. For example, this code has a problem: Perl package Book::Trans; use Apache::Constants qw(: ...

4.4.5. Verifying <Perl> Sections: How do we know whether the configuration made inside Perl sections was correct? First we need to check the validity of the Perl syntax. To do that, we should ...

4.4.6. Saving the Perl Configuration: Instead of dumping the generated Perl configuration, you may decide to store it in a file. For example, if you want to store it in httpd_config.pl, you can do ...

4.4.7. Debugging: If your configuration doesn't seem to do what it's supposed to do, you should debug it. First, build mod_perl with: panic% perl Makefile.PL PERL_TRACE=1 [...] ...

4.5. Validating the Configuration Syntax: Before you restart a server on a live production machine after the configuration has been changed, it's essential to validate that the configuration file is ...

4.6. The Scope of mod_perl Configuration Directives: Table 4-1 depicts where the various mod_perl configuration directives can be used. Table 4-1. The Scope of mod_perl configuration directives Directive Global ...

4.7. Apache Restarts Twice: When the server is restarted, the configuration and module initialization phases are called twice before the children are forked. The second restart is done to ...

4.8. Enabling Remote Server Configuration Reports: The nifty mod_info Apache module displays the complete server configuration in your browser. In order to use it, you have to compile it in or, if the server ...

4.9. Tips and Tricks: The following are miscellaneous tips and tricks that might save you lots of time when configuring mod_perl and Apache. Continue to: prev: 4.8. Enabling ...

4.9.1. Publishing Port Numbers Other Than 80: If you are using a dual-server setup, with a mod_perl server listening on a high port (e.g., 8080), don't publish the high port number in URLs. Rather, use a ...

4.9.2. Running the Same Script from Different Virtual Hosts: When running under a virtual host, Apache::Registry and other registry family handlers will compile each script into a separate package. The package name ...

4.10. Configuration Security Concerns: Any service open to the Internet at large must take security into account. Large, complex software tends to expose subtle vulnerabilities that attackers can ...

4.10.1. Using Only Absolutely Necessary Components: The more modules you have enabled in your web server, the more complex the code and interaction between these modules will be. The more complex the code in ...

4.10.2. Taint Checking: Make sure to run the server with the following setting in the httpd.conf file: PerlTaintCheck On As discussed in Chapter 6, taint checking doesn't ensure that ...

4.10.3. Hiding Server Information: We aren't completely sure why the default value of the ServerTokens directive in Apache is Full rather than Minimal. It seems like Full is really useful only ...

4.10.4. Making the mod_perl Server Inaccessible from the Outside: It is best not to expose mod_perl to the outside world, as it creates a potential security risk by revealing which modules you use and which operating system ...

4.10.5. Protecting Private Status Locations: It's a good idea to protect your various monitors, such as /perl-status, by password. The less information you provide for intruders, the harder it will be for ...

4.11. General Pitfalls: The following are some of the mostly frequently asked questions related to mod_perl configuration issues (and the answers, of course). My CGI/Perl code is ...

4.12. References: To learn regular expressions for use in DirectoryMatch or equivalent sections, the book Mastering Regular Expressions, by Jeffrey E. F. Friedl (O'Reilly), may ...

Chapter 5. Web Server Control, Monitoring, Upgrade, and Maintenance: Contents: Starting the Server in Multi-Process Mode Starting the Server in Single-Process Mode Using kill to Control Processes Using apachectl to Control the ...

5.1. Starting the Server in Multi-Process Mode: To start Apache manually, just run its executable. For example, on our machine, a mod_perl-enabled Apache executable is located at /home/httpd/httpd_perl/ ...

5.2. Starting the Server in Single-Process Mode: When developing new code, it is often helpful to run the server in single-process mode. This is most often used to find bugs in code that seems to work fine ...

5.3. Using kill to Control Processes: Linux and other Unix-like operating systems support a form of interprocess communication called signals. The kill command is used to send a signal to a running ...

5.3.1. kill Signals for Stopping and Restarting Apache: Apache performs certain actions in response to the KILL, TERM, HUP, and USR1 signals (as arguments to kill). All Apache system administrators should be ...

5.3.2. Speeding Up Apache's Termination and Restart: Restart or termination of a mod_perl server may sometimes take quite a long time, perhaps even tens of seconds. The reason for this is a call to the ...

5.3.3. Finding the Right Apache PID: In order to send a signal to a process, its PID must be known. But in the case of Apache, there are many httpd processes running. Which one should be used? The ...

5.4. Using apachectl to Control the Server: The Apache distribution comes with a script to control the server called apachectl, installed into the same location as the httpd executable. For the sake of ...

5.5. Validating Server Configuration: If the configuration file has syntax errors, attempting to restart the server will fail and the server will die. However, if a graceful restart is attempted ...

5.6. Setuid root Startup Scripts: If a group of developers need to be able to start and stop the server, there may be a temptation to give them the root password, which is probably not a wise ...

5.6.1. Introduction to setuid Executables: A setuid executable has the setuid permissions bit set, with the following command: panic% chmod u+s filename This sets the process's effective user ID to that ...

5.6.2. Apache Startup Script's setuid Security: In the situation where several developers need to be able to start and stop an Apache server that is run by the root account, setuid access must be available ...

5.6.3. Sample setuid Apache Startup Script: Example 5-1 shows a sample setuid Apache startup script. Note the line marked WORKAROUND, which fixes an obscure error when starting a mod_perl-enabled Apache, ...

5.7. Preparing for Machine Reboot: When using a non-production development box, it is OK to start and stop the web server by hand when necessary. On a production system, however, it is possible ...

5.8. Upgrading a Live Server: When you're developing code on a development server, anything goes: modifying the configuration, adding or upgrading Perl modules without checking that they ...

5.8.1. Upgrading Intranet Servers: An Intranet server generally serves the company's internal staff by allowing them to share and distribute internal information, read internal email, and ...

5.8.2. Upgrading 24 × 7 Internet Servers: Internet servers are normally expected to be available 24 hours a day, 7 days a week. E-commerce sites, global B2B (business-to-business) sites, and any other ...

5.8.2.1. The server cluster: When a service is very popular, a single machine probably will not be able to keep up with the number of requests the service has to handle. In this situation, ...

5.8.2.2. The single server: It's not uncommon for a popular web site to run on a single machine. It's also common for a web site to run on multiple machines, with one machine dedicated to ...

5.8.2.2.1. Upgrading live server components by swapping machines: There are many things that you might need to update on a server, ranging from a major upgrade of the operating system to just an update of a single piece of ...

5.8.2.2.2. Upgrading a live server with port forwarding: Using more than one machine to perform an update may not be convenient, or even possible. An alternative solution is to use the port-forwarding capabilities of ...

5.8.2.2.3. Upgrading a live server with prepackaged components: Assuming that the testbed machine and the live server have an identical software installation, consider preparing an upgrade package with the components that ...

5.8.2.2.4. Upgrading a live server using symbolic links: Yet another alternative is to use symbolic links for upgrades. This concept is quite simple: install a package into some directory and symlink to it. So, if ...

5.8.2.2.5. Upgrading Perl code: Although new versions of mod_perl and Apache may not be released for months at a time and the need to upgrade them may not be pressing, the handlers and ...

5.8.2.2.6. Moving files and restarting the server: Now let's discuss the techniques used to upgrade live server scripts and handlers. The most common scenario is a live running service that needs to be upgraded ...

5.8.2.2.7. Using CVS for code upgrades: The Concurrent Versions System (CVS) is an open source version-control system that allows multiple developers to work on code or configuration in a central ...

5.8.3. Disabling Scripts and Handlers on a Live Server: Perl programs running on the mod_perl server may be dependent on resources that can become temporarily unavailable when they are being upgraded or maintained.

5.8.3.1. Disabling code running under Apache::Registry: If just a few scripts need to be disabled temporarily, and if they are running under the Apache::Registry handler, a maintenance message can be displayed ...

5.8.3.2. Disabling code running under other handlers: Under non-Apache::Registry handlers, you need to modify the configuration. You must either point all requests to a new location or replace the handler with one ...

5.8.3.3. Disabling services with help from the frontend server: Many sites use a more complicated setup in which a light Apache frontend server serves static content but proxies all requests for dynamic content to the heavy ...

5.8.4. Scheduled Routine Maintenance: If maintenance tasks can be scheduled when no one is using the server, you can write a simple PerlAccessHandler that will automatically disable the server and ...

5.9. Three-Tier Server Scheme: Development, Staging, and Production: To facilitate transfer from the development server to the production server, the code should be free of any server-dependent variables. This will ensure that ...

5.9.1. Starting a Personal Server for Each Developer: When just one developer is working on a specific server, there are fewer problems, because she can have complete control over the server. However, often a ...

5.10. Web Server Monitoring: Once the production system is working, you may think that the job is done and the developers can switch to a new project. Unfortunately, in most cases the ...

5.10.1. Interactive Monitoring: When you're getting started, it usually helps to monitor the server interactively. Many different tools are available to do this. We will discuss a few of them ...

5.10.2. Apache::VMonitor—The Visual System and Apache Server Monitor: The Apache::VMonitor module provides even better monitoring functionality than top. It supplies all the relevant information that top does, plus all the Apache- ...

5.10.2.1. Prerequisites and configuration: To run Apache::VMonitor, you need to have Apache::Scoreboard installed and configured in httpd.conf. Apache::Scoreboard, in turn, requires mod_status to be ...

5.10.2.2. Multi-processes and system overall status reporting mode: The first mode is the one that's used most often, since it allows you to monitor almost all important system resources from one location. For your convenience, ...

5.10.2.3. Single-process extensive reporting system: If you need to get in-depth information about a single process, just click on its PID. If the chosen process is a mod_perl process, the following information ...

5.10.3. Automated Monitoring: As we mentioned earlier, the more things are automated, the more stable the server will be. In general, there are three things that we want to ensure: Apache ...

5.10.3.1. mod_perl server watchdogs: One simple watchdog solution is to use a slightly modified apachectlscript, which we have called apache.watchdog. Call it from cron every 30 minutes or even ...

5.11. Server Maintenance Chores: It is not enough to have your server and service up and running. The server must be maintained and monitored even when everything seems to be fine. This ...

5.11.1. Handling Log Files: Apache generally logs all the web server access events in the access_log file, whereas errors and warnings go into the error_log file. The access_log file can ...

5.11.1.1. Scheduled log file rotation: The first issue is solved by having a process that rotates the logs run by cron at certain times (usually off-peak hours, if this term is still valid in the 24- ...

5.11.1.2. Non-scheduled emergency log rotation: As we mentioned earlier, there are times when the web server goes wild and starts to rapidly log lots of messages to the error_log file. If no one monitors ...

5.11.1.3. Centralized logging: If you are running more than one server on the same machine, Apache offers the choice of either having a separate set of log files for each server, or using a ...

5.11.2. Swapping Prevention: Before we delve into swapping process details, let's look briefly at memory components and memory management. Computer memory is called RAM (Random Access ...

5.11.3. Limiting Resources Used by Apache Child Processes: There are times when we need to prevent processes from excessive consumption of system resources. This includes limiting CPU or memory usage, the number of ...

5.11.3.1. OS-specific notes: Under certain Linux setups, malloc( ) uses mmap( ) instead of brk( ). This is done to conserve virtual memory that is, when a program malloc( )s a large block ...

5.11.4. Tracking and Terminating Hanging Processes: Generally, limits should be imposed on mod_perl processes to prevent mayhem if something goes wrong. There is no need to limit processes if the code does not ...

5.11.5. Limiting the Number of Processes Serving the Same Resource: To limit the number of Apache children that can simultaneously serve a specific resource, take a look at the Apache mod_throttle_access module. Throttling ...

5.11.6. Limiting the Request-Rate Speed (Robot Blocking): Web services generally welcome search engine robots, also called spiders. Search engine robots are programs that query the site and index its documents for a ...

5.12. References: Stopping and Restarting Apache, from the Apache documentation: http://httpd.apache.org/docs/stopping.html. RPM resources: The Red Hat Package Manager web site: ...

Chapter 6. Coding with mod_perl in Mind: Contents: Before You Start to Code Exposing Apache::Registry Secrets Namespace Issues Perl Specifics in the mod_perl Environment CHECK and INIT Blocks Apache:: ...

6.1. Before You Start to Code: There are three important things you need to know before you start your journey in a mod_perl world: how to access mod_perl and related documentation, and how ...

6.1.1. Accessing Documentation: mod_perl doesn't tolerate sloppy programming. Although we're confident that you're a talented, meticulously careful programmer whose programs run perfectly ...

6.1.2. The strict Pragma: We're sure you already do this, but it's absolutely essential to start all your scripts and modules with: use strict; It's especially important to have the ...

6.1.3. Enabling Warnings: It's also important to develop your code with Perl reporting every possible relevant warning. Under mod_perl, you can turn this mode on globally, just like you ...

6.2. Exposing Apache::Registry Secrets: Let's start with some simple code and see what can go wrong with it. This simple CGI script initializes a variable $counter to 0 and prints its value to the ...

6.2.1. The First Mystery: Why Does the Script Go Beyond 5?: If we look at the error_log file (we did enable warnings), we'll see something like this: Variable $counter will not stay shared at /home/httpd/perl/counter.pl ...

6.2.2. The Second Mystery—Inconsistent Growth over Reloads: Let's return to our original example and proceed with the second mystery we noticed. Why have we seen inconsistent results over numerous reloads? What happens ...

6.3. Namespace Issues: If your service consists of a single script, you will probably have no namespace problems. But web services usually are built from many scripts and handlers.

6.3.1. The @INC Array: Perl's @INC array is like the PATH environment variable for the shell program. Whereas PATH contains a list of directories to search for executable programs, @ ...

6.3.2. The %INC Hash: Perl's %INC hash is used to cache the names of the files and modules that were loaded and compiled by use( ), require( ), or do( )statements. Every time a file ...

6.3.3. Name Collisions with Modules and Libraries: In this section, we'll look at two scenarios with failures related to namespaces. For the following discussion, we will always look at a single child process. & ...

6.3.3.1. A first faulty scenario: It is impossible to use two modules with identical names on the same server. Only the first one found in a use( ) or a require( )statement will be loaded and ...

6.3.3.2. A second faulty scenario: Now consider the following scenario: project/MyConfig.pm project/runA.pl project/runB.pl Now there is a single project with two scripts, runA.pl and runB.pl, ...

6.3.3.3. A quick but ineffective hackish solution: The following solution should be used only as a short term bandage. You can force reloading of the modules either by fiddling with %INC or by replacing use( ) ...

6.3.3.4. A first solution: The first faulty scenario can be solved by placing library modules in a subdirectory structure so that they have different path prefixes. The new filesystem ...

6.3.3.5. A second solution: Another approach is to use a full path to the script, so the latter will be used as a key in %INC: require /home/httpd/perl/project/MyConfig.pm ; With this ...

6.3.3.6. A third solution: This solution makes use of package-name declaration in the require( ) d modules. For example: package ProjectA::Config; Similarly, for ProjectB, the package ...

6.4. Perl Specifics in the mod_perl Environment: In the following sections, we discuss the specifics of Perl's behavior under mod_perl. Continue to: prev: 6.3.3.6. A third solution Table of Contents ...

6.4.1. exit( ): Perl's core exit( ) function shouldn't be used in mod_perl code. Calling it causes the mod_perl process to exit, which defeats the purpose of using mod_perl.

6.4.2. die( ): die( ) is usually used to abort the flow of the program if something goes wrong. For example, this common idiom is used when opening files: open FILE, foo or ...

6.4.3. Global Variable Persistence: Under mod_perl a child process doesn't exit after serving a single request. Thus, global variables persist inside the same process from request to request.

6.4.4. STDIN, STDOUT, and STDERR Streams: Under mod_perl, both STDIN and STDOUT are tied to the socket from which the request originated. If, for example, you use a third-party module that prints some ...

6.4.5. Redirecting STDOUT into a Scalar Variable: Sometimes you encounter a black-box function that prints its output to the default file handle (usually STDOUT) when you would rather put the output into a ...

6.4.6. print( ): Under mod_perl, CORE::print( ) (using either STDOUT as a filehandle argument or no filehandle at all) will redirect output to Apache::print( ), since the ...

6.4.7. Formats: The interface to file handles that are linked to variables with Perl's tie( ) function is not yet complete. The format( ) and write( ) functions are missing.

6.4.8. Output from System Calls: The output of system( ), exec( ), and open(PIPE, |program ) calls will not be sent to the browser unless Perl was configured with sfio. To learn if your ...

6.4.9. BEGIN blocks: Perl executes BEGIN blocks as soon as possible, when it's compiling the code. The same is true under mod_perl. However, since mod_perl normally compiles ...

6.4.10. END Blocks: As the perlmod manpage explains, an ENDsubroutine is executed when the Perl interpreter exits. In the mod_perl environment, the Perl interpreter exits only ...

6.5. CHECK and INIT Blocks: The CHECK and INIT blocks run when compilation is complete, but before the program starts. CHECK can mean checkpoint, double-check, or even just stop. INIT ...

6.5.1. $^T and time( ): Under mod_perl, processes don't quit after serving a single request. Thus, $^T gets initialized to the server startup time and retains this value throughout ...

6.5.2. Command-Line Switches: When a Perl script is run from the command line, the shell invokes the Perl interpreter via the #!/bin/perl directive, which is the first line of the script ( ...

6.5.2.1. Warnings: There are three ways to enable warnings: Globally to all processes In httpd.conf, set: PerlWarn On You can then fine-tune your code, turning warnings off and ...

6.5.2.2. Taint mode: Perl's -T switch enables taint mode. In taint mode, Perl performs some checks on how your program is using the data passed to it. For example, taint checks ...

6.5.3. Compiled Regular Expressions: When using a regular expression containing an interpolated Perl variable that you are confident will not change during the execution of the program, a standard ...

6.5.3.1. Matching patterns repeatedly: Another technique may also be used, depending on the complexity of the regex to which it is applied. One common situation in which a compiled regex is usually ...

6.6. Apache::Registry Specifics: The following coding issues are relevant only for scripts running under the Apache::Registry content handler and similar handlers, such as Apache::PerlRun. Of ...

6.6.1. __END__ and __DATA__ Tokens: An Apache::Registry script cannot contain __END__ or _ _DATA_ _ tokens, because Apache::Registry wraps the original script's code into a subroutine called ...

6.6.2. Symbolic Links: Apache::Registry caches the script in the package whose name is constructed from the URI from which the script is accessed. If the same script can be reached ...

6.6.3. Return Codes: Apache::Registry normally assumes a return code of OK (200) and sends it for you. If a different return code needs to be sent, $r- status( ) can be used. For ...

6.7. Transition from mod_cgi Scripts to Apache Handlers: If you don't need to preserve backward compatibility with mod_cgi, you can port mod_cgi scripts to use mod_perl-specific APIs. This allows you to benefit from ...

6.7.1. Starting with a mod_cgi-Compatible Script: Example 6-18 shows the original script's code. Example 6-18. cookie_script.pl use strict; use CGI; use CGI::Cookie; use vars qw($q $switch $status $sessionID); ...

6.7.2. Converting into a Perl Content Handler: Let's now convert this script into a content handler. There are two parts to this task: first configure Apache to run the new code as a Perl handler, then ...

6.7.3. Converting to use the mod_perl API and mod_perl-Specific Modules: Now that we have a complete PerlHandler, let's convert it to use the mod_perl API and mod_perl-specific modules. First, this may give us better performance ...

6.8. Loading and Reloading Modules: You often need to reload modules in development and production environments. mod_perl tries hard to avoid unnecessary module reloading, but sometimes ( ...

6.8.1. The @INC Array Under mod_perl: Under mod_perl, @INC can be modified only during server startup. After each request, mod_perl resets @INC's value to the one it had before the request. If ...

6.8.2. Reloading Modules and Required Files: When working with mod_cgi, you can change the code and rerun the CGI script from your browser to see the changes. Since the script isn't cached in memory, the ...

6.8.2.1. Restarting the server: The simplest approach is to restart the server each time you apply some change to your code. Restarting techniques are covered in Chapter 5. After restarting ...

6.8.2.2. Using Apache::StatINC: Help comes from the Apache::StatINC module. When Perl pulls in a file with require( ), it stores the full pathname as a value in the global hash %INC with the ...

6.8.2.3. Using Apache::Reload: Apache::Reload is a newer module that comes as a drop-in replacement for Apache::StatINC. It provides extra functionality and is more flexible. To make Apache:: ...

6.8.2.4. Using dynamic configuration files: Sometimes you may want an application to monitor its own configuration file and reload it when it is altered. But you don't want to restart the server for ...

6.8.2.4.1. Writing configuration files: We'll start by describing various approaches to writing configuration files, and their strengths and weaknesses. If your configuration file contains only a few ...

6.8.2.4.2. Reloading configuration files: First, lets look at a simple case, in which we just have to look after a simple configuration file like the one below. Imagine a script that tells you who is ...

6.8.2.4.3. Dynamically updating configuration files: The CGI script below allows a system administrator to dynamically update a configuration file through a web interface. This script, combined with the code we ...

6.9. Handling the "User Pressed Stop Button" Case: When a user presses the Stop or Reload button, the current socket connection is broken (aborted). It would be nice if Apache could always immediately detect ...

6.9.1. Detecting Aborted Connections: Now let's use the knowledge we have acquired to trace the execution of the code and watch all the events as they happen. Let's take a simple Apache:: ...

6.9.2. The Importance of Cleanup Code: Cleanup code is a critical issue with aborted scripts. For example, what happens to locked resources, if there are any? Will they be freed or not? If not, ...

6.9.2.1. Critical section: First, we want to take a little detour to discuss the critical section issue. Let's start with a resource-locking scheme. A schematic representation of a ...

6.9.2.2. Safe resource locking and cleanup code: Now let's get back to this section's main issue, safe resource locking. If you don't make a habit of closing all files that you open, you may encounter many ...

6.10. Handling Server Timeout Cases and Working with $SIG{ALRM}: Similar to the case where a user aborts the script execution by pressing the Stop button, the browser itself might abort the script if it hasn't returned any ...

6.11. Generating Correct HTTP Headers: An HTTP response header consists of at least two fields: HTTP response and MIME-type header Content-Type: HTTP/1.0 200 OK Content-Type: text/plain After adding ...

6.12. Method Handlers: The Browse and See, Browse and View Example: Let's look at an example of the method-handler concepts presented in Chapter 4. Suppose you need to implement a handler that allows browsing the files in the ...

6.13. References: Just the FAQs: Coping with Scoping, an article by Mark-Jason Dominus about how Perl handles variables and namespaces, and the difference between use vars( ) ...

Chapter 7. Identifying Your Performance Problems: Contents: Looking at the Big Picture Asking the Right Questions ReferencesYou have been assigned to improve the performance of your company's web service. The ...

7.1. Looking at the Big Picture: To make the user's web-browsing experience as painless as possible, every effort must be made to wring the last drop of performance from the server. Many ...

7.2. Asking the Right Questions: There is much more to the web service than writing the code, and firing the server to crunch this code. But before you specify a set of questions that will ...

7.3. References: http://slashdot.org/ is a site for geeks with news interesting to geeks. It has become very popular and gathers large crowds of people who read the posted ...

Chapter 8. Choosing a Platform for the Best Performance: Contents: Choosing the Right Operating System Choosing the Right Hardware ReferencesBefore you start to optimize your code and server configuration, you need ...

8.1. Choosing the Right Operating System: This section discusses the characteristics and features you should be looking for to support a mod_perl-enabled Apache server. When you know what you want from ...

8.1.1. mod_perl Support for the Operating System: Clearly, before choosing an OS, you will want to make sure that mod_perl even runs on it! As you will have noticed throughout this book, mod_perl 1.x is ...

8.1.2. Stability and Robustness: Probably the most important features in an OS are stability and robustness. You are in an Internet business. You do not keep normal 9 A.M. to 5 P.M. working ...

8.1.3. Good Memory Management: You want an OS with a good memory-management implementation. Some OSes are well known as memory hogs. The same code can use twice as much memory on one OS ...

8.1.4. Avoiding Memory Leaks: Some OSes and/or their libraries (e.g., C runtime libraries) suffer from memory leaks. A leak is when some process requests a chunk of memory for temporary ...

8.1.5. Memory-Sharing Capabilities: You want an OS with good memory-sharing capabilities. If you preload the Perl modules and scripts at server startup, they are shared between the spawned ...

8.1.6. The Real Cost of Support: If you are in a big business, you probably do not mind paying another $1,000 for some fancy OS with bundled support. But if your resources are low, you will ...

8.1.7. Discontinued Products: You might find yourself in a position where you have invested a lot of time and money into developing some proprietary software that is bundled with the OS you ...

8.1.8. Keeping Up with OS Releases: Actively developed OSes generally try to keep pace with the latest technology developments and continually optimize the kernel and other parts of the OS to ...

8.2. Choosing the Right Hardware: Sometimes the most expensive machine is not the one that provides the best performance. Your demands on the platform hardware are based on many aspects and ...

8.2.1. Machine Strength Demands According to Expected Site Traffic: If you are building a fan site and you want to amaze your friends with a mod_perl guestbook, any old 486 machine could do it. But if you are in a serious ...

8.2.2. A Single Strong Machine Versus Many Weaker Machines: Let's start with a claim that a four-year-old processor is still very powerful and can be put to good use. Now let's say that for a given amount of money you ...

8.2.3. Getting a Fast Internet Connection: You have the best hardware you can get, but the service is still crawling. What's wrong? Make sure you have a fast Internet connection not necessarily as fast ...

8.2.4. Tuning I/O Performance: If your service is I/O-bound (i.e., does a lot of read/write operations to disk) you need a very fast disk, especially when using a relational database. Don't ...

8.2.5. How Much Memory Is Enough?: How much RAM do you need? Nowadays, chances are that you will hear: Memory is cheap, the more you buy the better. But how much is enough? The answer is pretty ...

8.2.6. Getting a Fault-Tolerant CPU: Make sure that the CPU is operating within its specifications. Many boxes are shipped with incorrect settings for CPU clock speed, power supply voltage, etc.

8.2.7. Detecting and Avoiding Bottlenecks: You might use the most expensive components but still get bad performance. Why? Let me introduce an annoying word: bottleneck. A machine is an aggregate of ...

8.2.8. Solving Hardware Requirement Conflicts: It may happen that the combination of software components you find yourself using gives rise to conflicting requirements for the optimization of tuning ...

8.3. References: For more information about RAID, see the Disk-HOWTO, Module-HOWTO, and Parallel-Processing-HOWTO, available from the Linux Documentation Project and its ...

Chapter 9. Essential Tools for Performance Tuning: Contents: Server Benchmarking Perl Code Benchmarking Process Memory Measurements Apache::Status and Measuring Code Memory Usage Code Profiling Techniques ...

9.1. Server Benchmarking: As web service developers, the most important thing we should strive for is to offer the user a fast, trouble-free browsing experience. Measuring the response ...

9.1.1. ApacheBench: ApacheBench (ab) is a tool for benchmarking your Apache HTTP server. It is designed to give you an idea of the performance that your current Apache ...

9.1.2. httperf: httperf is another tool for measuring web server performance. Its input and reports are different from the ones we saw while using ApacheBench. This tool's ...

9.1.3. http_load: http_load is yet another utility that does web server load testing. It can simulate a 33.6 Kbps modem connection (-throttle) and allows you to provide a file ...

9.1.4. Other Web Server Benchmark Utilities: The following are also interesting benchmarking applications implemented in Perl: HTTP::WebTest The HTTP::WebTest module (available from CPAN) runs tests on ...

9.2. Perl Code Benchmarking: If you want to benchmark your Perl code, you can use the Benchmark module. For example, let's say that our code generates many long strings and finally prints ...

9.3. Process Memory Measurements: A very important aspect of performance tuning is to make sure that your applications don't use too much memory. If they do, you cannot run many servers, and ...

9.4. Apache::Status and Measuring Code Memory Usage: The Apache::Status module allows you to peek inside the Perl interpreter in the Apache web server. You can watch the status of the Perl interpreter: what ...

9.5. Code Profiling Techniques: The profiling process helps you to determine which subroutines (or just snippets of code) take longest to execute and which subroutines are called most often.

9.5.1. Profiling with Devel::DProf: Devel::DProf collects information on the execution time of a Perl script and of the subroutines in that script. Let's take for example the diagnostics pragma ...

9.5.2. Profiling with Devel::SmallProf: The Devel::SmallProf profiler is focused on the time taken for a program run on a line-by-line basis. It is called small because it's supposed to impose very ...

9.6. References: The diagnostics pragma is a part of the Perl distribution. See perldoc diagnostics for more information about the program, and perldoc perldiag for Perl ...

Chapter 10. Improving Performance with Shared Memory and Proper Forking: Contents: Sharing Memory Forking and Executing Subprocessesfrom mod_perl ReferencesIn this chapter we will talk about two issues that play an important role in ...

10.1. Sharing Memory: The sharing of memory is a very important factor. If your OS supports it (and most sane systems do), a lot of memory can be saved by sharing it between child ...

10.1.1. Calculating Real Memory Usage: We have shown how to measure the size of the process's shared memory, but we still want to know what the real memory usage is. Obviously this cannot be ...

10.1.2. Memory-Sharing Validation: How do you find out if the code you write is shared between processes or not? The code should remain shared, except when it is on a memory page used by ...

10.1.2.1. Variable unsharing caused by regular expressions: Let's write a module called Book::MyShared, shown in Example 10-1, which we will preload at server startup so that all the variables of this module are ...

10.1.2.2. Numerical versus string access to variables: Data can get unshared on read as well for example, when a numerical variable is accessed as a string. Example 10-7 shows some code that proves this. Example 10- ...

10.1.3. Preloading Perl Modules at Server Startup: As we just explained, to get the code-sharing effect, you should preload the code before the child processes get spawned. The right place to preload modules is ...

10.1.4. Preloading Registry Scripts at Server Startup: Suppose you find yourself stuck with self-contained Perl CGI scripts (i.e., all the code placed in the CGI script itself). You would like to preload modules to ...

10.1.5. Module Initialization at Server Startup: It's important to preload modules and scripts at server startup. But for some modules this isn't enough, and you have to prerun their initialization code to ...

10.1.5.1. Initializing DBI.pm: The first example is the DBI module. DBI works with many database drivers from the DBD:: category (e.g., DBD::mysql). If you want to minimize memory use after ...

10.1.5.2. Initializing CGI.pm: CGI.pm is a big module that by default postpones the compilation of its methods until they are actually needed, thus making it possible to use it under a slow ...

10.1.6. Memory Preallocation: Perl reuses allocated memory whenever possible. With Devel::Peek we can actually see this happening by peeking at the variable data structure. Consider the ...

10.2. Forking and Executing Subprocessesfrom mod_perl: When you fork Apache, you are forking the entire Apache server, lock, stock and barrel. Not only are you duplicating your Perl code and the Perl interpreter, ...

10.2.1. Forking a New Process: The typical way to call fork( ) under mod_perl is illustrated in Example 10-13. Example 10-13. fork1.pl defined (my $kid = fork) or die Cannot fork: $!\n ; if ( ...

10.2.2. Freeing the Parent Process: In the child code, you must also close all the pipes to the connection socket that were opened by the parent process (i.e., STDIN and STDOUT) and inherited by ...

10.2.3. Detaching the Forked Process: Now what happens if the forked process is running and we decide that we need to restart the web server? This forked process will be aborted, because when the ...

10.2.4. Avoiding Zombie Processes: Normally, every process has a parent. Many processes are children of the init process, whose PID is 1. When you fork a process, you must wait( ) or waitpid( ) ...

10.2.5. A Complete Fork Example: Now let's put all the bits of code together and show a well-written example that solves all the problems discussed so far. We will use an Apache:: ...

10.2.6. Starting a Long-Running External Program: What happens if we cannot just run Perl code from the spawned process? We may have a compiled utility, such as a program written in C, or a Perl program that ...

10.2.7. Starting a Short-Running External Program: Sometimes you need to call an external program and you cannot continue before this program completes its run (e.g., if you need it to return some result). In ...

10.2.8. Executing system( ) or exec( ) in the Right Way: The Perl exec( ) and system( ) functions behave identically in the way they spawn a program. Let's use system( ) as an example. Consider the following code: ...

10.3. References: Mastering Regular Expressions, by Jeffrey E. F. Friedl (O'Reilly). Chapters 2 and 4 in Operating Systems: Design And Implementation, by Andrew S. Tanenbaum and ...

Chapter 11. Tuning Performance by Tweaking Apache's Configuration: Contents: Setting the MaxClients Directive Setting the MaxRequestsPerChild Directive Setting MinSpareServers, MaxSpareServers, and StartServers KeepAlive ...

11.1. Setting the MaxClients Directive: It's important to specify MaxClients on the basis of the resources your machine has. The MaxClients directive sets the limit on the number of simultaneous ...

11.2. Setting the MaxRequestsPerChild Directive: The MaxRequestsPerChild directive sets the limit on the number of requests that an individual child process can handle during its lifetime. After ...

11.3. Setting MinSpareServers, MaxSpareServers, and StartServers: With mod_perl enabled, it might take as much as 20 seconds from the time you start the server until it is ready to serve incoming requests. This delay depends ...

11.4. KeepAlive: If your mod_perl server's httpd.conf file includes the following directives: KeepAlive On MaxKeepAliveRequests 100 KeepAliveTimeout 15 you have a real ...

11.5. PerlSetupEnv: By default, PerlSetupEnv is On, but PerlSetupEnv Off is another optimization you should consider. mod_perl modifies the environment to make it appear as if the ...

11.6. Reducing the Number of stat( ) Calls Made by Apache: If (using truss, strace, or another tool available for your OS) you watch the system calls that your mod_perl server makes while processing a request, you will ...

11.7. Symbolic Links Lookup: The two options FollowSymLinks and SymLinksIfOwnerMatch are designed for the user's security. Unless FollowSymLinks is enabled, symbolic links will not be ...

11.8. Disabling DNS Resolution: You should make sure that your httpd.conf file has this setting: HostnameLookups Off This is the default. If this directive is set to On (or even worse, Double) ...

11.9. Response Compressing: Have you ever served a huge HTML file (e.g., a file bloated with JavaScript code) and wondered how you could send it compressed, thus dramatically cutting down ...

11.10. References: Apache Performance Notes: http://httpd.apache.org/docs/misc/perf-tuning.html. OS-specific hints on running a high-performance web server: http://httpd.apache.

Chapter 12. Server Setup Strategies: Contents: mod_perl Deployment Overview Standalone mod_perl-Enabled Apache Server One Plain and One mod_perl-Enabled Apache Server One Light Non-Apache and One ...

12.1. mod_perl Deployment Overview: There are several different ways to build, configure, and deploy your mod_perl-enabled server. Some of them are: One big binary (for mod_perl) and one ...

12.2. Standalone mod_perl-Enabled Apache Server: The first and simplest scenario uses a straightforward, standalone, mod_perl-enabled Apache server, as shown in Figure 12-1. Just take your plain Apache server ...

12.3. One Plain and One mod_perl-Enabled Apache Server: As mentioned earlier, when running scripts under mod_perl you will notice that the httpd processes consume a huge amount of virtual memory from 5 MB-15 MB, and ...

12.3.1. Choosing the Target Installation Directories Layout: If you're going to run two Apache servers, you'll need two complete (and different) sets of configuration, log, and other files. In this scenario we'll use a ...

12.3.2. Configuration and Compilation of the Sources: Now we proceed to configure and compile the sources using the directory layout we have just described. Continue to: prev: 12.3.1. Choosing the Target ...

12.3.2.1. Building the httpd_docs server: The first step is to configure the source: panic% cd /home/stas/src/httpd_docs/apache_1.3.x panic% ./configure --prefix=/home/httpd/httpd_docs \ --enable- ...

12.3.2.2. Building the httpd_perl server: Now we proceed with the source configuration and installation of the httpd_perl server. panic% cd /home/stas/src/httpd_perl/mod_perl-1.xx panic% perl Makefile.

12.3.3. Configuration of the Servers: When we have completed the build process, the last stage before running the servers is to configure them. Continue to: prev: 12.3.2.2. Building the ...

12.3.3.1. Basic httpd_docs server configuration: Configuring the httpd_docs server is a very easy task. Open /home/httpd/httpd_docs/conf/httpd.conf in your favorite text editor and configure it as you usually ...

12.3.3.2. Basic httpd_perl server configuration: Now we edit the /home/httpd/httpd_perl/conf/httpd.conf file. The first thing to do is to set a Port directive it should be different from that used by the ...

12.4. One Light Non-Apache and One mod_perl-Enabled Apache Server: If the only requirement from the light server is for it to serve static objects, you can get away with non-Apache servers, which have an even smaller memory ...

12.5. Adding a Proxy Server in httpd Accelerator Mode: We have already presented a solution with two servers: one plain Apache server, which is very light and configured to serve static objects, and the other with ...

12.6. The Squid Server and mod_perl: To give you an idea of what Squid is, we will reproduce the following bullets from Squid's home page (http://www.squid-cache.org/): Squid is... A full-featured ...

12.6.1. Pros and Cons: The advantages of using Squid are: Caching of static objects. These are served much faster, assuming that your cache size is big enough to keep the most ...

12.6.2. Light Apache, mod_perl, and Squid Setup Implementation Details: You will find the installation details for the Squid server on the Squid web site (http://www.squid-cache.org/). In our case it was preinstalled with Mandrake ...

12.6.3. mod_perl and Squid Setup Implementation Details: When one of the authors was first told about Squid, he thought: Hey, now I can drop the httpd_docs server and have just Squid and the httpd_perl servers. Since ...

12.7. Apache's mod_proxy Module: Apache's mod_proxy module implements a proxy and cache for Apache. It implements proxying capabilities for the following protocols: FTP, CONNECT (for SSL), ...

12.7.1. Concepts and Configuration Directives: In the following explanation, we will use www.example.com as the main server users access when they want to get some kind of service and backend.example.com as ...

12.7.1.1. ProxyPass: You can use the ProxyPass configuration directive to map remote hosts into the URL space of the local server; the local server does not act as a proxy in the ...

12.7.1.2. ProxyPassReverse: This directive lets Apache adjust the URL in the Location header on HTTP redirect responses. This is essential when Apache is used as a reverse proxy to avoid ...

12.7.1.3. Security issues: Whenever you use mod_proxy you need to make sure that your server will not become a proxy for freeriders. Allowing clients to issue proxy requests is ...

12.7.2. Knowing the Proxypassed Connection Type: Let's say that you have a frontend server running mod_ssl, mod_rewrite, and mod_proxy. You want to make sure that your user is using a secure connection for ...

12.7.3. Buffering Feature: In addition to correcting the URI on its way back from the backend server, mod_proxy, like Squid, also provides buffering services that benefit mod_perl and ...

12.7.4. Closing Lingering Connections with lingerd: Because of some technical complications in TCP/IP, at the end of each client connection, it is not enough for Apache to close the socket and forget about it; ...

12.7.5. Caching Feature: Apache does caching as well. It's relevant to mod_perl only if you produce proper headers, so your scripts' output can be cached. See the Apache documentation ...

12.7.6. Build Process: To build mod_proxy into Apache, just add enable-module=proxy during the Apache ./configurestage. Since you will probably need mod_rewrite's capability as well, ...

12.8. mod_rewrite Examples: In the mod_proxy and mod_perl servers scenario, ProxyPass was used to redirect all requests to the mod_perl server by matching the beginning of the relative ...

12.9. Getting the Remote Server IP in the Backend Server in the Proxy Setup: When using the proxy setup to boost performance, you might face the problem that the remote IP always seems to be 127.0.0.1, which is your proxy's IP. To solve ...

12.10. Frontend/Backend Proxying with Virtual Hosts: This section explains a configuration setup for proxying your backend mod_perl servers when you need to use virtual hosts. Continue to: prev: 12.9.

12.10.1. Virtual Host Flavors: Apache supports three flavors of virtual hosts: IP-based virtual hosts In this form, each virtual host uses its own IP address. Under Unix, multiple IP ...

12.10.2. Dual-Server Virtual Host Configuration: In the dual-server setup, which virtual host flavor is used on the frontend (reverse proxy) server is irrelevant. When running a large number of virtual hosts, ...

12.10.3. Virtual Hosts and Main Server Interaction: When using virtual hosts, any configuration directive outside of a VirtualHost container is applied to a virtual host called the main server, which plays a ...

12.10.4. Frontend Server Configuration: The following example illustrates the use of name-based virtual hosts. We define two virtual hosts, www.example.com and www.example.org, which will reverse- ...

12.10.5. Backend Server Configuration: This section describes the configuration of the backend server. The backend server listens on the loopback (localhost) interface: BindAddress 127.0.0.1 In this ...

12.11. HTTP Authentication with Two Servers and a Proxy: In a setup with one frontend server that proxies to a backend mod_perl server, authentication should be performed entirely on one of the servers: don't mix and ...

12.12. When One Machine Is Not Enough for Your RDBMS DataBase and mod_perl: Imagine a scenario where you start your business as a small service providing a web site. After a while your business becomes very popular, and at some point ...

12.12.1. Server Requirements: Let's first look at what kind of software the web and database servers are, what they need to run fast, and what implications they have on the rest of the ...

12.12.2. The Problem: With the database and the web server on the same machine, you have conflicting interests. During peak loads, Apache will spawn more processes and use RAM that ...

12.12.3. The Solution: The solution is to add another machine, which allows a setup where both the database and the web server run on their own dedicated machines. This solution has ...

12.12.4. Three Machine Model: Since we are talking about using a dedicated machine for each server, you might consider adding a third machine to do the proxy work; this will make your setup ...

12.13. Running More than One mod_perl Server on the Same Machine: Let's assume that you have two different sets of code that have little or nothing in common different Perl modules, no code sharing. Typical numbers can be 4 ...

12.14. SSL Functionality and a mod_perl Server: If you need SSL functionality, you can get it by adding the mod_ssl or equivalent Apache-SSL to the light frontend server (httpd_docs) or the heavy backend ...

12.15. Uploading and Downloading Big Files: You don't want to tie up your precious mod_perl backend server children doing something as long and simple as transferring a file, especially a big one. The ...

12.16. References: Chapter 9 ( Tuning Apache and mod_perl ) in mod_perl Developer's Cookbook, by Geoffrey Young, Paul Lindner, and Randy Kobes (Sams Publishing). mod_backhand, ...

Chapter 13. TMTOWTDI: Convenience and Habit Versus Performance: Contents: Apache::Registry PerlHandler Versus Custom PerlHandler Apache::args Versus Apache::Request::param Versus CGI::param Buffered Printing and Better ...

13.1. Apache::Registry PerlHandler Versus Custom PerlHandler: At some point you have to decide whether to use Apache::Registry or similar handlers and stick to writing scripts only for content generation, or to write pure ...

13.2. Apache::args Versus Apache::Request::param Versus CGI::param: Apache::args, Apache::Request::param, and CGI::param are the three most common ways to process input arguments in mod_perl handlers and scripts. Let's write ...

13.3. Buffered Printing and Better print( ) Techniques: As you probably know, this statement: local $|=1; disables buffering of the currently select( )ed file handle (the default is STDOUT). Under mod_perl, the ...

13.4. Interpolation, Concatenation, or List: Let's revisit the various approaches of munging with strings, and compare the speed of using lists of strings versus interpolation. We will add a string ...

13.5. Keeping a Small Memory Footprint: Since mod_perl processes tend to consume a lot of memory as the number of loaded modules and scripts grows during the child's lifetime, it's important to know ...

13.5.1. "Bloatware" Modules: Perl IO:: modules are very convenient, but let's see what it costs to use them. The following command (Perl 5.6.1 on Linux) reveals that when we use IO we also ...

13.5.2. Importing Symbols: Imported symbols act just like global variables; they can add up memory quickly. In addition to polluting the namespace, a process grows by the size of the ...

13.6. Object Methods Calls Versus Function Calls: Which form of subroutine call is more efficient: object methods or function calls? Let's look at the overhead. Continue to: prev: 13.5.2. Importing ...

13.6.1. The Overhead with Light Subroutines: Let's do some benchmarking. We will start by using empty methods, which will allow us to measure the real difference in the overhead each kind of call ...

13.6.2. The Overhead with Heavy Subroutines: The above results don't mean that you shouldn't use methods. Generally your functions do something, and the more they do the less significant the overhead of ...

13.6.3. Are All Methods Slower Than Functions?: Some modules' APIs are misleading for example, CGI.pm allows you to execute its subroutines as functions or as methods. As you will see in a moment, its ...

13.7. Using the Perl stat( ) Call's Cached Results: When you call stat( ) (or its variants -M, -e, etc.), the returned information is cached internally. If you need to make an additional check on the same file, ...

13.8. time( ) System Call Versus $r->request_time: If you need to know the time at which the request started, you can either install PerlPostReadRequestHandler, which adjusts the special Perl variable $^T to ...

13.9. Printing Unmodified Files: To send a complete file from disk, without applying any modifications first, instead of: my $filename = /tmp/foo ; my $fh = Apache::gensym( ); # generate a new ...

13.10. Caching and Pre-Caching: In some situations, you may have data that is expensive to generate but must be created on the fly. If the data can be reused, it may be more efficient to ...

13.11. Caching with Memoize: If you have a subroutine with simpler logic, where a returned value is solely a function of an input, you can use the Memoize module, which does the caching ...

13.12. Comparing Runtime Performance of Perl and C: Perl is commonly used for web scripting because it is quick and easy to write, and very easy to change. Compiled languages usually take a lot more time and ...

13.12.1. Building Perl Extensions with XS and h2xs: Perl comes with a nifty utility called h2xs that builds a skeleton for a new module. It's useful whether you are going to write a module with extensions in C/C+ ...

13.12.2. The Benchmark: We are now ready to write the benchmark code. Take a look at Example 13-27. Example 13-27. factorial_benchmark.pl use strict; use Benchmark; use Book:: ...

13.12.3. Inline.pm: Using XS and SWIG may seem like a lot of time and work, especially for something as simple as our factorial benchmark. Fortunately, there is a new module ...

13.12.4. Perl Extensions Conclusion: We have presented two techniques to extend your Perl code with the power of other languages (the C language in particular, but Inline.pm lets you embed other ...

13.13. References: XS macro language resources: perlguts, perlxs, and perlxstut manpages Dean Roehrich's XS CookBookA and CookBookB: http://search.cpan.org/search?dist=CookBookA ...

Chapter 14. Defensive Measures for Performance Enhancement: Contents: Controlling Your Memory Usage Coding for a Smaller Memory Footprint Conclusion ReferencesIf you have already worked with mod_perl, you have probably ...

14.1. Controlling Your Memory Usage: When you need to control the size of your httpd processes, use one of the two modules, Apache::GTopLimit and Apache::SizeLimit, which kill Apache httpd ...

14.1.1. Defining the Minimum Shared Memory Size Threshold: As we have already discussed, when it is first created, an Apache child process usually has a large fraction of its memory shared with its parent. During the ...

14.1.1.1. Potential drawbacks of memory-sharing restrictions: In Chapter 11 we devised a formula to calculate the optimum value for the MaxClients directive when sharing is taking place. In the same section, we warned ...

14.1.2. Defining the Maximum Memory Size Threshold: No less important than maximizing shared memory is restricting the absolute size of the processes. If the processes grow after each request, and if nothing ...

14.1.3. Defining the Maximum Unshared Memory Size Threshold: Instead of setting the shared and total memory usage thresholds, you can set a single threshold that measures the amount of unshared memory by subtracting the ...

14.2. Coding for a Smaller Memory Footprint: The following sections present proactive techniques that prevent processes from growing large in the first place. Continue to: prev: 14.1.3. Defining the ...

14.2.1. Memory Reuse: Consider the code in Example 14-1. Example 14-1. memory_hog.pl use GTop ( ); my $gtop = GTop- new; my $proc = $gtop- proc_mem($$); print size before: , $gtop- ...

14.2.2. Big Input, Big Damage: This section demonstrates how a malicious user can bring the service down or cause problems by submitting unexpectedly big data. Imagine that you have a ...

14.2.3. Small Input, Big Damage: This section demonstrates how a small input submitted by a malicious user may hog the whole server. Imagine an online service that allows users to create a ...

14.2.4. Think Production, Not Development: Developers often use sample inputs for testing their new code. But sometimes they forget that the real inputs can be much bigger than those they used in ...

14.2.5. Passing Variables: Let's talk about passing variables to a subroutine. There are two ways to do this: you can pass a copy of the variable to the subroutine (this is called ...

14.2.6. Memory Leakage: It's normal for a process to grow when it processes its first few requests. They may be different requests, or the same requests processing different data. You ...

14.3. Conclusion: The impacts of coding style, efficiency, differences in data, potential abuse by users, and a host of other factors combine to make each web service unique.

14.4. References: The mod_limitipconn.c and Apache::LimitIPConn Apache modules: http://dominia.org/djao/limitipconn.html These modules allow web server administrators to limit ...

Chapter 15. Improving Performance Through Build Options: Contents: Server Size as a Function of Compiled-in Features mod_status and ExtendedStatus On DYNAMIC_MODULE_LIMIT Apache Build Option Perl Build Options ...

15.1. Server Size as a Function of Compiled-in Features: You might wonder if it's better to compile in only the required modules and mod_perl hooks, or if it doesn't really matter. To answer this question, let's ...

15.2. mod_status and ExtendedStatus On: If you build in mod_status and you also set: ExtendedStatus On in httpd.conf, on every request Apache will perform two calls to gettimeofday(2) (or times(2), ...

15.3. DYNAMIC_MODULE_LIMIT Apache Build Option: If you have no intention of using dynamically loaded modules (you probably don't if you're tuning your server for every last ounce of performance), you should ...

15.4. Perl Build Options: The Perl interpreter is the brain of the mod_perl server. If you can optimize Perl into doing things faster under mod_perl, you'll make the whole server faster.

15.5. Architecture-Specific Compile Options: When you build Apache and Perl, you can optimize the compiled applications to take advantage of the benefits of your machine's architecture. Everything depends ...

15.6. References: The GCC manual: http://gcc.gnu.org/onlinedocs/ Code Optimization Using the GNU C Compiler, by Rahul U Joshi: http://www.linuxgazette.com/issue71/joshi.html ...

Chapter 16. HTTP Headers for Optimal Performance: Contents: Date-Related Headers Content Headers Content Negotiation HTTP Requests Avoiding Dealing with Headers ReferencesHeader composition is often neglected ...

16.1. Date-Related Headers: The various headers related to when a document was created, when it was last modified, and when it should be considered stale are discussed in the following ...

16.1.1. Date Header: Section 14.18 of the HTTP standard deals with the circumstances under which we must or must not send a Date header. For almost everything a normal mod_perl ...

16.1.2. Last-Modified Header: Section 14.29 of the HTTP standard covers the Last-Modified header, which is mostly used as a weak validator. Here is an excerpt from the HTTP specification: A ...

16.1.3. Expires and Cache-Control Headers: Section 14.21 of the HTTP standard deals with the Expires header. The purpose of the Expires header is to determine a point in time after which the document ...

16.2. Content Headers: The following sections describe the HTTP headers that specify the type and length of the content, and the version of the content being sent. Note that in this ...

16.2.1. Content-Type Header: Most CGI programmers are familiar with Content-Type. Sections 3.7, 7.2.1, and 14.17 of the HTTP specification cover the details. mod_perl has a content_type( ) ...

16.2.2. Content-Length Header: According to section 14.13 of the HTTP specification, the Content-Length header is the number of octets (8-bit bytes) in the body of a message. If the length ...

16.2.3. Entity Tags: An entity tag (ETag) is a validator that can be used instead of, or in addition to, the Last-Modified header; it is a quoted string that can be used to ...

16.3. Content Negotiation: Content negotiation is a wonderful feature that was introduced with HTTP/1.1. Unfortunately it is not yet widely supported. Probably the most popular usage ...

16.3.1. The Vary Header: To signal to the recipient that content negotiation has been used to determine the best available representation for a given request, the server must include a ...

16.4. HTTP Requests: Section 13.11 of the specification states that the only two cacheable methods are GET and HEAD. Responses to POST requests are not cacheable, as you'll see in ...

16.4.1. GET Requests: Most mod_perl programs are written to service GET requests. The server passes the request to the mod_perl code, which composes and sends back the headers and ...

16.4.2. Conditional GET Requests: A rather challenging request that may be received is the conditional GET, which typically means a request with an If-Modified-Since header. The HTTP ...

16.4.3. HEAD Requests: Among the headers described thus far, the date-related ones (Date, Last-Modified, and Expires/Cache-Control) are usually easy to produce and thus should be ...

16.4.4. POST Requests: The response to a POST request is not cacheable, due to an underspecification in the HTTP standards. Section 13.4 does not forbid caching of responses to POST ...

16.5. Avoiding Dealing with Headers: There is another approach to dynamic content that is possible with mod_perl. This approach is appropriate if the content changes relatively infrequently, if we ...

16.6. References: Hypertext Transfer Protocol HTTP/1.0, RFC 1945T, by T. Berners-Lee, et al.: http://www.w3.org/Protocols/rfc1945/rfc1945.txt Hypertext Transfer Protocol HTTP/1.

Chapter 17. Databases Overview: Contents: Volatile Databases Non-Volatile Databases ReferencesWhat's a database? We can use pretty much anything as a database, as long as it allows us to ...

17.1. Volatile Databases: We use volatile databases all the time, even if we don't think about them as real databases. These databases are usually just part of the programs we run. & ...

17.1.1. In-Memory Databases in a Single Process: If, for example, we want to store the number of Perl objects that exist in our program's data, we can use a variable as a volatile database: package Book:: ...

17.1.2. In-Memory Databases Across Multiple Processes: Sharing results is more efficient than having each child potentially waste a lot of time generating redundant data. On the other hand, the information may not ...

17.2. Non-Volatile Databases: Some information is so important that you cannot afford to lose it. Consider the name and password for authenticating users. If a person registers at a site ...

17.2.1. Flat-File Databases: If we have a small amount of data, sometimes the easiest technique is to just write this data in a text file. For example, if we have a few records with a ...

17.2.2. Filesystem Databases: Many people don't realize that in some cases, the filesystem can serve perfectly well as a database. In fact, you are probably using this kind of database ...

17.2.3. DBM Databases: DBM databases are very similar to flat-file databases, but if all you need is to store the key/value pairs, they will do it much faster. Their use is much ...

17.2.4. Relational Databases: Of course, the most advanced solution is a relational database. But even though it provides the best solution in many cases, it's not always the one you should ...

17.3. References: Chapters 2 and 3 of the book Programming the Perl DBI, by Alligator Descartes and Tim Bunce (O'Reilly), provide a good overview of relational and nonrelational ...

Chapter 18. mod_perl Data-Sharing Techniques: Contents: Sharing the Read-Only Data in and Between Processes Sharing Data Between Various Handlers ReferencesIn this chapter, we discuss the ways mod_perl ...

18.1. Sharing the Read-Only Data in and Between Processes: If you need to access some data in your code that's static and will not be modified, you can save time and resources by processing the data once and caching it ...

18.2. Sharing Data Between Various Handlers: Sometimes you want to set some data in one of the early handler phases and make it available in the latter handlers. For example, say you set some data in a ...

18.3. References: mod_include, an Apache module that provides Server-Side Includes (SSI): http://httpd.apache.org/docs/mod/mod_include.html Continue to: prev: 18.2.

Chapter 19. DBM and mod_perl: Contents: mod_perl and DBM Resource Locking Flawed Locking Methods Locking Wrappers Overview Tie::DB_Lock Examples ReferencesSome of the earliest databases ...

19.1. mod_perl and DBM: Where does mod_perl fit into the picture? If you need read-only access to a DBM file in your mod_perl code, the operation is much faster if you keep the DBM ...

19.2. Resource Locking: Database locking is required if more than one process will try to modify the data. In an environment in which there are both reading and writing processes, the ...

19.2.1. Deadlocks: First let's make sure that you know how processes work with the CPU. Each process gets a tiny CPU time slice before another process takes over. Usually ...

19.2.2. Exclusive Locking Starvation: If a shared lock request is issued, it is granted immediately if the file is not locked or has another shared lock on it. If the file has an exclusive lock on ...

19.3. Flawed Locking Methods: The suggested locking methods in the first and second editions of the book Programming Perl (O'Reilly) and the DB_File manpage (before Version 1.72, fixed in 1.

19.4. Locking Wrappers Overview: Here are the pros and cons of the DBM file-locking wrappers available from CPAN: Tie::DB_Lock A DB_File wrapper that creates copies of the DBM file for read ...

19.5. Tie::DB_Lock: Tie::DB_Lock ties hashes to databases using shared and exclusive locks. This module, written by Ken Williams, solves the problems discussed earlier. The main ...

19.6. Examples: Let's look at a few examples that will demonstrate the theory presented at the beginning of the chapter. Continue to: prev: 19.5. Tie::DB_Lock Table of ...

19.6.1. tie( )-ing Once and Forever: If you know that your code accesses the DBM file in read-only mode and you want to gain the maximum data-retrieval speed, you should tie the DBM file during ...

19.6.2. Read/Write Access: This simple example will show you how to use the DBM file when you want to be able to safely modify it in addition to just reading from it. As mentioned ...

19.6.3. Storing Complex Data Structures: As mentioned earlier, you can use the MLDBM module to store complex data structures in the DBM file (which apparently accepts only a scalar as a single value).

19.7. References: Chapter 14 in Perl Cookbook, by Tom Christiansen and Nathan Torkington (O'Reilly) Chapter 17 in Learning Perl, Second Edition, by Randal L. Schwartz and Tom ...

Chapter 20. Relational Databases and mod_perl: Contents: Persistent Database Connections with Apache::DBI Improving Performance DBI Debug Techniques ReferencesNowadays, millions of people surf the Internet.

20.1. Persistent Database Connections with Apache::DBI: When people first started to use the Web, they found that they needed to write web interfaces to their databases, or add databases to drive their web ...

20.1.1. Apache::DBI Connections: The DBI module can make use of the Apache::DBI module. When the DBI module loads, it tests whether the environment variable $ENV{MOD_PERL} is set and whether ...

20.1.2. When to Use Apache::DBI (and When Not to Use It): You will want to use the Apache::DBI module only if you are opening just a few database connections per process. If there are ten child processes and each ...

20.1.3. Configuring Apache::DBI: Apache::DBI will not work unless mod_perl was built with: PERL_CHILD_INIT=1 PERL_STACKED_HANDLERS=1 or: EVERYTHING=1 during the perl Makefile.PL ... stage.

20.1.4. Debugging Apache::DBI: If you are not sure whether this module is working as advertised and that your connections are actually persistent, you should enable debug mode in the startup.

20.1.5. Caveats and Troubleshooting: This section covers some of the risks and things to keep in mind when using Apache::DBI. Continue to: prev: 20.1.4. Debugging Apache::DBI Table of ...

20.1.5.1. Database locking risks: When you use Apache::DBI or similar persistent connections, be very careful about locking the database (LOCK TABLE ...) or single rows. MySQL threads keep ...

20.1.5.2. Transactions: A standard Perl script using DBI will automatically perform a rollback whenever the script exits. In the case of persistent database connections, the database ...

20.1.5.3. Opening connections with different parameters: When Apache::DBI receives a connection request, before it decides to use an existing cached connection it insists that the new connection be opened in exactly ...

20.1.5.4. Cannot find the DBI handler: You must use DBI- connect( ) as in normal DBI usage to get your $dbh database handle. Using Apache::DBI does not eliminate the need to write proper DBI code.

20.1.5.5. The morning bug: The SQL server keeps a connection to the client open for a limited period of time. In the early days of Apache::DBI, everyone was bitten by the so-called ...

20.1.5.6. Apache:DBI does not work: If Apache::DBI doesn't work, first make sure that you have it installed. Then make sure that you configured mod_perl with either: PERL_CHILD_INIT=1 ...

20.1.5.7. Skipping connection cache during server startup: Does your error_log look like this? 10169 Apache::DBI PerlChildInitHandler 10169 Apache::DBI skipping connection cache during server startup Database handle ...

20.2. Improving Performance: Let's now talk about various techniques that allow you to boost the speed of applications that work with relational databases. A whole book could be devoted to ...

20.2.1. Preopening DBI Connections: If you are using Apache::DBI and you want to make sure that a database connection will already be open when your code is first executed within each child ...

20.2.2. Improving Speed by Skipping ping( ): If you use Apache::DBI and want to save a little bit of time, you can change how often the ping( ) method is called. The following setting in a startup file: ...

20.2.3. Efficient Record-Retrieval Techniques: When working with a relational database, you'll often encounter the need to read the retrieved set of records into your program, then format and print them to ...

20.2.4. mysql_use_result Versus mysql_store_result Attributes: Many mod_perl developers use MySQL as their preferred relational database server because of its speed. Depending on the situation, it may be possible to change ...

20.2.5. Running Two or More Relational Databases: Sometimes you end up running many databases on the same machine. These might have very different needs. For example, one may handle user sessions (updated ...

20.2.6. Caching prepare( ) Statements: You can also benefit from persistent connections by replacing prepare( ) with prepare_cached( ). That way you will always be sure that you have a good ...

20.3. DBI Debug Techniques: Sometimes the code that talks to the database server doesn't seem to work. It's important to know how to debug this code at the DBI level. Here is how this ...

20.4. References: Introduction to Structured Query Language : http://web.archive.org/web/20011116021648/w3.one.net/~jhoffman/sqltut.htm (http://web.archive.org/web/ ...

Chapter 21. Error Handling and Debugging: Contents: Warnings and Errors Explained Debugging Code in Single-Server Mode Tracing System Calls Tracing mod_perl-Specific Perl Calls Debugging Perl Code ...

21.1. Warnings and Errors Explained: The Perl interpreter distinguishes between warnings and errors. Warnings are messages that the Perl interpreter prints to STDERR (or to Apache's error log ...

21.1.1. The Importance of Warnings: Just like errors, Perl's optional warnings, if they are enabled, go to the error_log file. You have enabled them in your development server, haven't you? We ...

21.1.1.1. The diagnostics pragma: This pragma extends the terse diagnostics normally emitted during the compilation and runtime phases and augments them with the more verbose and endearing ...

21.1.2. Curing "Internal Server Error" Problems: Say you've just installed a new script, and when you try it out you see the grey screen of death saying Internal Server Error (Figure 21-1). Or even worse, you' ...

21.1.3. Making Use of the error_log: It's a good idea to keep the error_log open all the time in a dedicated terminal using tail -f: panic% tail -f /home/httpd/httpd_perl/logs/error_log or less -S: ...

21.1.4. Displaying Errors to Users: If you spend a lot of time browsing the Internet, you will see many error messages, ranging from generic but useless messages like An error has happened to the ...

21.2. Debugging Code in Single-Server Mode: Normally, Apache runs one parent process and several children. The parent starts new child processes as required, logs errors, kills off child processes that ...

21.3. Tracing System Calls: Most Unix-style operating systems offer a tracing utility that intercepts and records the system calls that are called by a process and the signals that are ...

21.4. Tracing mod_perl-Specific Perl Calls: When we are interested in mod_perl-level events, it's quite hard to use system-level tracing, both because of the system trace's verbosity and because it's ...

21.5. Debugging Perl Code: It's a known fact that programmers spend a lot of time debugging their code. Sometimes we spend more time debugging code than writing it. The lion's share of ...

21.5.1. Locating and Correcting Syntax Errors: While developing code, we sometimes make syntax errors, such as forgetting to put a comma in a list or a semicolon at the end of a statement. Don't Skimp on ...

21.5.2. Using Apache::FakeRequest to Debug Apache Perl Modules: Apache::FakeRequest is used to set up an empty Apache request object that can be used for debugging. The Apache::FakeRequest methods just set internal ...

21.5.3. Using print( ) for Debugging: The universal debugging tool across nearly all platforms and programming languages is printf( ) (or equivalent output functions). This function can send data ...

21.5.4. Using print( ) and Data::Dumper for Debugging: Sometimes we need to peek into complex data structures, and trying to print them out can be tricky. That's where Data::Dumper comes to the rescue. For example, ...

21.5.5. The Importance of a Good, Concise Coding Style: Don't strive for elegant, clever code. Try to develop a good coding style by writing code that is concise, yet easy to understand. It's much easier to find ...

21.5.6. Introduction to the Perl Debugger: As we saw earlier, it's almost always possible to debug code with the help of print( ). However, it is impossible to anticipate all the possible paths of ...

21.5.7. Interactive Perl Debugging Under mod_cgi: Devel::ptkdb is a visual Perl debugger that uses Perl/Tk for the user interface and requires a windows system like X Windows or Windows to run. To debug a ...

21.5.8. Noninteractive Perl Debugging Under mod_perl: To debug scripts running under mod_perl noninteractively (i.e., to print the Perl execution trace), simply set the usual environment variables that control ...

21.5.9. Interactive mod_perl Debugging: Now we'll look at how the interactive debugger is used in a mod_perl environment. The Apache::DB module available from CPAN provides a wrapper around perldb ...

21.5.9.1. ptkdb and interactive mod_perl debugging: As we saw earlier, we can use the ptkdb visual debugger to debug CGI scripts running under mod_cgi. At the time of writing it works partially under mod_perl as ...

21.6. Analyzing Dumped core Files: When your application dies with the Segmentation fault error (generated by the default SIGSEGVsignal handler) and generates a core file, you can analyze the ...

21.6.1. Getting Ready to Debug: To debug the core file, you may need to recompile Perl and mod_perl so that their executables contain debugging symbols. Usually you have to recompile only ...

21.6.2. Creating a Faulty Package: The next stage is to create a package that aborts abnormally with a segfault, so you will be able to reproduce the problem and exercise the debugging technique ...

21.6.3. Dumping the core File: Now let's dump the core file from within the mod_perl server. Sometimes the program aborts abnormally via the SIGSEGVsignal (a segfault), but no core file is ...

21.6.4. Analyzing the core File: First we start gdb, with the location of the mod_perl executable and the core file as the arguments: panic% gdb /home/httpd/httpd_perl/bin/httpd_perl /home/ ...

21.6.5. Extracting the Backtrace Automatically: With the help of Debug::FaultAutoBT, you can try to get the backtrace extracted automatically, without any need for the core file. As of this writing this CPAN ...

21.7. Hanging Processes: Detection and Diagnostics: Sometimes an httpd process might hang in the middle of processing a request. This may happen because of a bug in the code, such as being stuck in a while loop.

21.7.1. Hanging Because of an Operating System Problem: Sometimes you can find a process hanging because of some kind of system problem. For example, if the processes was doing some disk I/O operation, it might get ...

21.7.2. When a Process Might Hang: In Chapter 19, we discussed the concept of deadlock. This can happen when two processes are each trying to acquire locks on the resources held by the other.

21.7.3. Detecting Hanging Processes: It's not so easy to detect hanging processes. There is no way you can tell how long the request is taking to process by using plain system utilities such as ps ...

21.7.4. Determination of the Reason: Given the PID, there are three ways to find out where the server is hanging: Deploy the Perl calls-tracing mechanism. This will allow you to spot the location ...

21.7.4.1. Using the Perl trace: To see where an httpd process is spinning, the first step is to add the following to your startup file: package Book::StartUp; use Carp ( ); $SIG{'USR2'} = sub ...

21.7.4.2. Using the system calls trace: Let's write another similar mod_perl script that hangs, and deploy strace to find the point at which it hangs (see Example 21-11). Example 21-11. hangme.pl ...

21.7.4.3. Using the interactive debugger: Another way to see a trace of the running code is to use a debugger such as gdb (the GNU debugger). It's supposed to work on any platform that supports the GNU ...

21.7.5. mod_perl gdb Debug Macros: So far we have seen only the use of the curinfo gdb macro. Let's explore a few more gdb macros that come with the mod_perl source and might be handy during a ...

21.8. Useful Debug Modules: You may find the modules discussed in this section very useful while debugging your code. They will allow you to learn a lot about Perl internals. ...

21.8.1. B::Deparse: Perl optimizes many things away at compile time, which explains why Perl is so fast under mod_perl. If you want to see what code is actually executed at ...

21.8.2. -D Runtime Option: You can watch your code as it's being compiled and executed by Perl via the -D runtime option. Perl will generate different output according to the extra ...

21.8.3. Devel::Peek and Apache::Peek: Devel::Peek is a very useful module for looking at the Perl internals. It's especially useful for debugging XS code. With Devel::Peek we can look at Perl ...

21.8.4. Devel::Symdump and Apache::Symdump: Devel::Symdump allows us to access Perl's symbol table. This package is object oriented. To instantiate an object, you should provide the name of the package ...

21.8.5. Apache::Debug: This module sends what may be helpful debugging information to the client, rather than to the error_log file. This module specifies only the dump( ) method: ...

21.8.6. Other Debug Modules: The following are a few other modules that you may find of use, but in this book we won't delve deeply into their details: Apache::DumpHeaders is used to watch ...

21.9. Looking Inside the Server: There are a number of tools that allow you look at the server internals at runtime, through a convenient web interface. Continue to: prev: 21.8.6. Other ...

21.9.1. Apache::Status—Embedded Interpreter Status Information: This is a very useful module. It lets you watch what happens to the Perl part of the mod_perl server. You can watch the size of all subroutines and variables, ...

21.9.1.1. Minimal configuration: This configuration enables the Apache::Status module with its minimum feature set. Add this to httpd.conf: Location /perl-status SetHandler perl-script ...

21.9.1.2. Extended configuration: There are several variables you can use to modify the behavior of Apache::Status: PerlSetVar StatusOptionsAll On This single directive will enable all of the ...

21.9.1.3. Usage: Assuming that your mod_perl server is listening on port 81, fetch http://www.example.com:81/perl-status: Embedded Perl version v5.6.1 for Apache/1.3.17 (Unix) ...

21.9.2. mod_status: The mod_status module allows a server administrator to find out how well the server is performing. An HTML page is presented that gives the current server ...

21.10. References: Perl Debugged, by Peter Scott and Ed Wright (Addison Wesley). A good book on how to debug Perl code and how to code in Perl so you won't need to debug.

Chapter 22. Troubleshooting mod_perl: Contents: Configuration and Startup Code Parsing and Compilation Runtime Shutdown and RestartWhen something goes wrong, we expect the software to report the ...

22.1. Configuration and Startup: This section covers errors you might encounter when you start the server. Continue to: prev: Chapter 22. Troubleshooting mod_perl Table of Contents next: ...

22.1.1. libexec/libperl.so: open failed: No such file or directory: If you get this error when you start the server, it probably means that your version of Perl was itself compiled with a shared library called libperl.so.

22.1.2. install_driver(Oracle) failed: Can't load `.../DBD/Oracle/Oracle.so' for module DBD::Oracle: Here's an example of the full error report that you might see: install_driver(Oracle) failed: Can't load '/usr/lib/perl5/site_perl/5.6.1/i386-linux/auto/DBD/ ...

22.1.3. Invalid command `PerlHandler'...: Here's an example of the full error report that you might see: Syntax error on line 393 of /home/httpd/httpd_perl/conf/httpd.conf: Invalid command 'PerlHandler' ...

22.1.4. RegistryLoader: Translation of uri [...] to filename failed: Here's an example of the full error report that you might see: RegistryLoader: Translation of uri [/home/httpd/perl/test.pl] to filename failed [tried: /home/ ...

22.2. Code Parsing and Compilation: The following warnings and errors might be reported when the Perl code is compiled. This may be during the server startup phase or, if the code hasn't yet been ...

22.2.1. Value of $x will not stay shared at - line 5: This warning usually happens when scripts are run under Apache::Registry and similar handlers, and some function uses a lexically scoped variable that is ...

22.2.2. Value of $x may be unavailable at - line 5: Similar to the previous section, the warning may happen under Apache::Registry and similar handlers, and should be considered an error. The cause is discussed ...

22.2.3. Can't locate loadable object for module ...: Here's an example of the full error report that you might see: Can't locate loadable object for module Apache::Util in @INC... In this particular example, it ...

22.2.4. Can't locate object method "get_handlers" ...: If you see this error: Can't locate object method get_handlers via package Apache you need to rebuild your mod_perl with stacked handlers; that is, with ...

22.2.5. Missing right bracket at line ...: This error usually means you really do have a syntax error. However, you might also see it because a script running under Apache::Registry is using either the ...

22.2.6. Can't load `.../auto/DBI/DBI.so' for module DBI: If you have the DBI module installed, this error is usually caused by binary incompatibilities. Check that all your modules were compiled with the same Perl ...

22.3. Runtime: Once you have your server up and running and most of the code working correctly, you may still encounter errors generated by your code at runtime. Some ...

22.3.1. foo ... at /dev/null line 0: Under mod_perl, you may receive a warning or an error in the error_log file that specifies /dev/null as the source file and line 0 as the line number where the ...

22.3.2. Segfaults When Using XML::Parser: If some processes have segmentation faults when using XML::Parser, you should use the following flags during Apache configuration: --disable-rule=EXPAT This ...

22.3.3. exit signal Segmentation fault (11): If you build mod_perl and mod_php in the same binary, you might get a segmentation fault followed by this error: exit signal Segmentation fault (11) The ...

22.3.4. CGI Code Is Returned as Plain Text Instead of Being Executed: If the CGI program is not actually executed but is just returned as plain text, it means the server doesn't recognize it as a CGI script. Check your ...

22.3.5. rwrite returned -1: This error message is returned when the client breaks the connection while your script is trying to write to the client. With Apache 1.3.x, you should see the ...

22.3.6. Global symbol "$foo" requires explicit package name: This error message is printed when a nondeclared variable is used in the code running under the strict pragma. For example, consider the short script below, ...

22.3.7. Use of uninitialized value at (eval 80) line 12: If you see this message, your code includes an undefined variable that you have used as if it was already defined and initialized. For example: my $param = $q- ...

22.3.8. Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at: This error usually happens when two scripts or handlers (Apache::Registry in this case) call a function defined in a library without a package definition, or ...

22.3.9. Callback called exit: Callback called exit is just a generic message when Perl encounters an unrecoverable error during perl_call_sv( ). mod_perl uses perl_call_sv( ) to invoke all ...

22.3.10. Out of memory!: If something goes really wrong with your code, Perl may die with an Out of memory! and/or Callback called exit message. Common causes of this are infinite ...

22.3.11. syntax error at /dev/null line 1, near "line arguments:": If you see an error of this kind: syntax error at /dev/null line 1, near line arguments: Execution of /dev/null aborted due to compilation errors. parse: ...

22.4. Shutdown and Restart: When you shut down or restart the server, you may encounter the problems presented in the following sections. Continue to: prev: 22.3.11. syntax error at ...

22.4.1. Evil Things Might Happen When Using PerlFreshRestart: Unfortunately, not all Perl modules are robust enough to survive reload. For them this is an unusual situation. PerlFreshRestart does not much more than: while ...

22.4.2. [warn] child process 30388 did not exit, sending another SIGHUP: With Apache Version 1.3.0 and higher, mod_perl will call the perl_destruct( ) Perl API function during the child exit phase. This will cause proper execution ...

22.4.3. Processes Get Stuck on Graceful Restart: If after doing a graceful restart (e.g, by sending kill -USR1) you see via mod_status or Apache::VMonitor that a process is stuck in state G (Gracefully ...

Chapter 23. Getting Help and Online Resources: Contents: How to Report Problems Mailing List Etiquette ResourcesIn this chapter, we propose a way to solve your mod_perl-related problems and provide starting ...

23.1. How to Report Problems: When reporting a problem to the mod_perl mailing list, always send these details: Anything in the error_log file that looks suspicious and possibly related to ...

23.1.1. Getting the Backtrace from Core Dumps: If you get a core dump (segmentation fault), send a backtrace if possible. Before you try to produce it, rebuild mod_perl with: panic% perl Makefile.PL ...

23.1.2. Spinning Processes: The gdb attaching to the live process approach is helpful when debugging a spinning process. You can also get a Perl stack trace of a spinning process by ...

23.2. Mailing List Etiquette: Like any community, the mod_perl mailing list has its own rules of etiquette that you would be wise to avoid violating: Never contact people in person to ask a ...

23.3. Resources: This section includes centralized resources that you should find useful when you work with mod_perl and related technologies, such as Apache, Perl, CGI, CVS, ...

23.3.1. mod_perl: mod_perl home page: http://perl.apache.org/ mod_perl documentation: http://perl.apache.org/docs/ mod_perl books Writing Apache Modules with Perl and C, by ...

23.3.2. mod_perl Mailing Lists: The mod_perl mailing list The Apache/Perl mailing list is available for mod_perl users and developers to share ideas, solve problems, and discuss things ...

23.3.3. Perl: The following resources are available for Perl: Books: Programming Perl, Third Edition, by Larry Wall, Tom Christiansen, and Jon Orwant (O'Reilly) The Perl ...

23.3.4. Perl/CGI: The following resources are valuable for learning more about writing CGI scripts with Perl: The Official Guide to CGI.pm, by Lincoln Stein (John Wiley Sons) ...

23.3.5. Apache: The following resources are useful for learning more about Apache: Apache Software Foundation home: http://www.apache.org/ Apache httpd server: http://httpd.

23.3.6. DBI and SQL: The following resources are useful for questions on DBI and SQL: Introduction to Structured Query Language: http://www.dbbm.fiocruz.br/class/Lecture/d17/sql/ ...

23.3.7. Squid: Home page: http://www.squid-cache.org/ FAQ: http://www.squid-cache.org/Doc/FAQ/FAQ.html Users guide: http://www.squid-cache.org/Doc/Users-Guide/ Mailing lists: ...

23.3.8. CVS: CVS instructions for access to the mod_perl repository: http://perl.apache.org/contribute/cvs_howto.html Open source development with CVS: http://cvsbook.red- ...

23.3.9. Performance and Scalability: Techniques and Technologies for Scaling Internet Services mailing list: scalable@arctic.org. Subscribe by sending a message to scalable-subscribe@arctic.org.

23.3.10. Web Security: Web Security: A Step-by-Step Reference Guide, by Lincoln Stein (Addison Wesley) Web Security and Electronic Commerce, by Simpson Garfinkle with Gene Spafford ( ...

Chapter 24. mod_perl 2.0: Installation and Configuration: Contents: What's New in Apache 2.0 What's New in Perl 5.6.0-5.8.0 What's New in mod_perl 2.0 Installing mod_perl 2.0 Configuring mod_perl 2.0 ResourcesSince ...

24.1. What's New in Apache 2.0: Whereas Apache 1.2 and 1.3 were based on the NCSA httpd code base, Apache 2.0 rewrote big chunks of the 1.3 code base, mainly to support numerous new features ...

24.2. What's New in Perl 5.6.0-5.8.0: As mentioned earlier, Perl 5.6.0 is the minimum requirement for mod_perl 2.0. However, certain new features work only with Perl 5.8.0 and higher. The following ...

24.3. What's New in mod_perl 2.0: The new features introduced by Apache 2.0 and the Perl 5.6 and 5.8 generations provide the base of the new mod_perl 2.0 features. In addition, mod_perl 2.0 ...

24.3.1. Thread Support: In order to adapt to the Apache 2.0 threads architecture (for threaded MPMs), mod_perl 2.0 needs to use thread-safe Perl interpreters, also known as ithreads ( ...

24.3.2. Perl Interface to the APR and Apache APIs: As we mentioned earlier, Apache 2.0 uses two APIs: The Apache Portable Runtime (APR) API, which implements a portable and efficient API to generically work ...

24.3.3. Other New Features: In addition to the already mentioned new features in mod_perl 2.0, the following are of major importance: Apache 2.0 protocol modules are supported. Later we ...

24.3.4. Improved and More Flexible Configuration: mod_perl 2.0 provides new configuration directives for the newly added features and improves upon existing ones. For example, the PerlOptions directive ...

24.3.5. Optimizations: The rewrite of mod_perl gives us a chance to build a smarter, stronger, and faster implementation based on lessons learned over the years since mod_perl was ...

24.4. Installing mod_perl 2.0: Since as of this writing mod_perl 2.0 hasn't yet been released, the installation instructions may change a bit, but the basics should be the same. Always refer ...

24.4.1. Installing from Source: First download the latest stable sources of Apache 2.0, mod_perl 2.0, and Perl 5.8.0.[59] Remember that mod_perl 1.0 works only with Apache 1.3, and mod_perl 2.

24.4.2. Installing Binaries: Apache 2.0 binaries can be obtained from http://httpd.apache.org/dist/binaries/. Perl 5.6.1 or 5.8.0 binaries can be obtained from http://cpan.org/ports/index.

24.5. Configuring mod_perl 2.0: Similar to mod_perl 1.0, in order to use mod_perl 2.0 a few configuration settings should be added to httpd.conf. They are quite similar to the 1.0 settings, ...

24.5.1. Enabling mod_perl: To enable mod_perl as a DSO, add this to httpd.conf: LoadModule perl_module modules/mod_perl.so This setting specifies the location of the mod_perl module ...

24.5.2. Accessing the mod_perl 2.0 Modules: To prevent you from inadvertently loading mod_perl 1.0 modules, mod_perl 2.0 Perl modules are installed into dedicated directories under Apache2/. The Apache2 ...

24.5.3. Startup File: Next, a startup file with Perl code usually is loaded: PerlRequire /home/httpd/httpd-2.0/perl/startup.pl It's used to adjust Perl module search paths in @INC, ...

24.5.4. Perl's Command-Line Switches: Now you can pass Perl's command-line switches in httpd.conf by using the PerlSwitches directive, instead of using complicated workarounds. For example, to ...

24.5.5. mod_perl 2.0 Core Handlers: mod_perl 2.0 provides two types of core handlers: modperl and perl-script. Continue to: prev: 24.5.4. Perl's Command-Line Switches Table of Contents next: ...

24.5.5.1. modperl: modperl is configured as: SetHandler modperl This is the bare mod_perl handler type, which just calls the Perl*Handler's callback function. If you don't need ...

24.5.5.2. perl-script: perl-script is configured as: SetHandler perl-script Most mod_perl handlers use the perl-script handler. Here are a few things to note: PerlOptions + ...

24.5.5.3. A simple response handler example: Let's demonstrate the differences between the modperl and perl-script core handlers. Example 24-2 represents a simple mod_perl response handler that prints out ...

24.5.6. PerlOptions Directive: The PerlOptions directive provides fine-grained configuration for what were compile-time-only options in the first mod_perl generation. It also provides ...

24.5.6.1. Enable: On by default; can be used to disable mod_perl for a given VirtualHost . For example: VirtualHost ... PerlOptions -Enable /VirtualHost Continue to: prev: ...

24.5.6.2. Clone: Share the parent Perl interpreter, but give the VirtualHost its own interpreter pool. For example, should you wish to fine-tune interpreter pools for a given ...

24.5.6.3. Parent: Create a new parent Perl interpreter for the given VirtualHost and give it its own interpreter pool (implies the Clone option). A common problem with mod_perl ...

24.5.6.4. PerlHandler: Disable specific Perl*Handlers (all compiled-in handlers are enabled by default). The option name is derived from the Perl*Handler name, by stripping the Perl ...

24.5.6.5. AutoLoad: Resolve Perl*Handlers at startup time; loads the modules from disk if they're not already loaded. In mod_perl 1.0, configured Perl*Handlers that are not fully ...

24.5.6.6. GlobalRequest: Set up the global Apache::RequestRec object for use with Apache- request. This setting is needed, for example, if you use CGI.pm to process the incoming ...

24.5.6.7. ParseHeaders: Scan output for HTTP headers. This option provides the same functionality as mod_perl 1.0's PerlSendHeaders option, but it's more robust. It usually must be ...

24.5.6.8. MergeHandlers: Turn on merging of Perl*Handler arrays. For example, with this setting: PerlFixupHandler Apache::FixupA Location /inside PerlFixupHandler Apache::FixupB / ...

24.5.6.9. SetupEnv: Set up environment variables for each request, la mod_cgi. When this option is enabled, mod_perl fiddles with the environment to make it appear as if the code ...

24.5.7. Thread-Mode-Specific Directives: The following directives are enabled only in a threaded MPM mod_perl: Continue to: prev: 24.5.6.9. SetupEnv Table of Contents next: 24.5.7.1.

24.5.7.1. PerlInterpStart: The number of interpreters to clone at startup time. Continue to: prev: 24.5.7. Thread-Mode-Specific Directives Table of Contents next: 24.5.7.2.

24.5.7.2. PerlInterpMax: If all running interpreters are in use, mod_perl will clone new interpreters to handle the request, up until this number of interpreters is reached. When ...

24.5.7.3. PerlInterpMinSpare: The minimum number of available interpreters this parameter will clone before a request comes in. Continue to: prev: 24.5.7.2. PerlInterpMax Table of ...

24.5.7.4. PerlInterpMaxSpare: mod_perl will throttle down the number of interpreters to this number as those in use become available. Continue to: prev: 24.5.7.3. PerlInterpMinSpare ...

24.5.7.5. PerlInterpMaxRequests: The maximum number of requests an interpreter should serve. The interpreter is destroyed and replaced with a fresh clone when this number is reached. ...

24.5.7.6. PerlInterpScope: As mentioned, when a request in a threaded MPM is handled by mod_perl, an interpreter must be pulled from the interpreter pool. The interpreter is then ...

24.5.8. Retrieving Server Startup Options: The httpd server startup options can be retrieved using Apache::exists_config_define( ). For example, to check if the server was started in single-process mode: ...

24.6. Resources: For up-to-date documentation on mod_perl 2.0, see: http://perl.apache.org/docs/2.0/ Continue to: prev: 24.5.8. Retrieving Server Startup Options Table of ...

Chapter 25. Programming for mod_perl 2.0: Contents: Migrating to and Programming with mod_perl 2.0 New Apache Phases and Corresponding Perl*Handlers I/O FilteringIn this chapter, we discuss how to ...

25.1. Migrating to and Programming with mod_perl 2.0: In mod_perl 2.0, several configuration directives were renamed or removed. Several APIs also were changed, renamed, removed, or moved to new packages. Certain ...

25.1.1. The Shortest Migration Path: mod_perl 2.0 provides two backward-compatibility layers: one for the configuration files and the other for the code. If you are concerned about preserving ...

25.1.2. Migrating Configuration Files: To migrate the configuration files to mod_perl 2.0 syntax, you may need to make certain adjustments. Several configuration directives are deprecated in 2.0 but ...

25.1.2.1. PerlHandler: PerlHandler has been replaced with PerlResponseHandler. Continue to: prev: 25.1.2. Migrating Configuration Files Table of Contents next: 25.1.2.2.

25.1.2.2. PerlSendHeader: PerlSendHeader has been replaced with the PerlOptions +/-ParseHeaders directive: PerlSendHeader On = PerlOptions +ParseHeaders PerlSendHeader Off = PerlOptions ...

25.1.2.3. PerlSetupEnv: PerlSetupEnv has been replaced with the PerlOptions +/-SetupEnv directive: PerlSetupEnv On = PerlOptions +SetupEnv PerlSetupEnv Off = PerlOptions -SetupEnv & ...

25.1.2.4. PerlTaintCheck: Taint mode can now be turned on with: PerlSwitches -T As with standard Perl, taint mode is disabled by default. Once enabled, taint mode cannot be turned off. & ...

25.1.2.5. PerlWarn: Warnings now can be enabled globally with: PerlSwitches -w Continue to: prev: 25.1.2.4. PerlTaintCheck Table of Contents next: 25.1.2.6. PerlFreshRestart ...

25.1.2.6. PerlFreshRestart: PerlFreshRestart is a mod_perl 1.0 legacy option and doesn't exist in mod_perl 2.0. A full tear-down and startup of interpreters is done on restart. If you ...

25.1.3. Code Porting: mod_perl 2.0 is trying hard to be backward compatible with mod_perl 1.0. However, some things (mostly APIs) have changed. To gain complete compatibility with 1.

25.1.4. ModPerl::Registry Family: In mod_perl 2.0, Apache::Registry and friends (Apache::PerlRun, Apache::RegistryNG, etc.) have migrated into the ModPerl:: namespace. The new family is based ...

25.1.5. Method Handlers: In mod_perl 1.0, method handlers had to be specified by using the ($$) prototype: package Eagle; @ISA = qw(Bird); sub handler ($$) { my($class, $r) = @_; ...; } ...

25.1.6. Apache::StatINC Replacement: Apache::StatINC has been replaced by Apache::Reload, which works for both mod_perl generations. To migrate to Apache::Reload, simply replace: PerlInitHandler ...

25.2. New Apache Phases and Corresponding PerlHandlers: Because the majority of the Apache phases supported by mod_perl haven't changed since mod_perl 1.0, in this chapter we will discuss only those phases and ...

25.2.1. Server Configuration and Startup Phases: open_logs, configured with PerlOpenLogsHandler, and post_config, configured with PerlPostConfigHandler, are the two new phases available during server startup.

25.2.1.1. PerlOpenLogsHandler: The open_logs phase happens just before the post_config phase. Handlers registered by PerlOpenLogsHandler are usually used for opening module-specific log ...

25.2.1.2. PerlPostConfigHandler: The post_config phase happens right after Apache has processed the configuration files, before any child processes are spawned (which happens at the child_init ...

25.2.1.3. PerlChildInitHandler: The child_init phase happens immediately after a child process is spawned. Each child process (not a thread!) will run the hooks of this phase only once in its ...

25.2.1.4. PerlChildExitHandler: The child_exit phase is executed before the child process exits. Notice that it happens only when the process exits, not when the thread exits (assuming that ...

25.2.2. Connection Phases: Since Apache 2.0 makes it possible to implement protocols other than HTTP, the connection phases pre_connection, configured with PerlPreConnectionHandler, and ...

25.2.2.1. PerlPreConnectionHandler: The pre_connection phase happens just after the server accepts the connection, but before it is handed off to a protocol module to be served. It gives modules ...

25.2.2.2. PerlProcessConnectionHandler: The process_connection phase is used to process incoming connections. Only protocol modules should assign handlers for this phase, as it gives them an ...

25.2.2.2.1. Socket-based protocol module: To demonstrate the workings of a protocol module, we'll take a look at the Book::Eliza module, which sends the data read from the client as input to Chatbot:: ...

25.2.2.2.2. Bucket brigade-based protocol module: Now let's look at the same module, but this time implemented by manipulating bucket brigades. It runs its output through a connection output filter that turns ...

25.2.3. HTTP Request Phases: The HTTP request phases themselves have not changed from mod_perl 1.0, except the PerlHandler directive has been renamed PerlResponseHandler to better match ...

25.3. I/O Filtering: Now let's talk about a totally new feature of mod_perl 2.0: input/output filtering. As of this writing the mod_perl filtering API hasn't been finalized, and it' ...

25.3.1. I/O Filtering Concepts: Before introducing the mod_perl filtering API, there are several important concepts to understand. Continue to: prev: 25.3. I/O Filtering Table of ...

25.3.1.1. Two methods for manipulating data: As discussed in the last chapter, Apache 2.0 considers all incoming and outgoing data as chunks of information, disregarding their kind and source or storage ...

25.3.1.2. HTTP request versus connection filters: HTTP request filters are applied when Apache serves an HTTP request. HTTP request input filters get invoked on the body of the HTTP request only if the body is ...

25.3.1.3. Multiple invocations of filter handlers: Unlike other Apache handlers, filter handlers may get invoked more than once during the same request. Filters get invoked as many times as the number of bucket ...

25.3.1.4. Blocking calls: All filters (excluding the core filter that reads from the network and the core filter that writes to it) block at least once when invoked. Depending on ...

25.3.2. Filter Configuration: HTTP request filter handlers are declared using the FilterRequestHandler attribute. Consider the following request input and output filter skeletons: package ...

25.3.3. Input Filters: We looked at how input filters call each other in Figure 25-5. Now let's look at some examples of input filters. Continue to: prev: 25.3.2. Filter ...

25.3.3.1. Bucket brigade-based connection input filter: Let's say that we want to test how our handlers behave when they are requested as HEAD requests rather than GET requests. We can alter the request headers at ...

25.3.3.2. Bucket brigade-based HTTP request input filter: Let's look at the request input filter that lowers the case of the text in the request's body, Book::InputRequestFilterLC (shown in Example 25-7). Example 25-7.

25.3.3.3. Stream-based HTTP request input filter: Let's now look at the same filter implemented using the stream-based filtering API (see Example 25-8). Example 25-8. Book/InputRequestFilterLC2.pm package Book: ...

25.3.4. Output Filters: Earlier, in Figure 25-6, we saw how output filters call each other. Now let's look at some examples of output filters. Continue to: prev: 25.3.3.3.

25.3.4.1. Stream-based HTTP request output filter: The PerlOutputFilterHandler handler registers and configures output filters. The example of a stream-based output filter that we are going to present is ...

25.3.4.2. Another stream-based HTTP request output filter: Let's look at another example of an HTTP request output filter but first, let's develop a response handler that sends two lines of output: the numerals ...

25.3.4.3. Bucket brigade-based HTTP request output filter: The filter implementation in Example 25-12 uses the bucket brigades API to accomplish exactly the same task as the filter in Example 25-11. Example 25-12. Book/ ...

Appendix A. mod_perl Recipes: Contents: Emulating the Authentication Mechanism Reusing Data from POST Requests Redirecting POST Requests Redirecting While Maintaining Environment Variables ...

A.1. Emulating the Authentication Mechanism: You can authenticate users with your own mechanism (instead of the standard one) but still make Apache think that the user was authenticated by the standard ...

A.2. Reusing Data from POST Requests: What happens if you need to access the POST ed data more than once. For example, suppose you need to reuse it in subsequent handlers of the same request? POST ...

A.3. Redirecting POST Requests: Under mod_cgi, it's not easy to redirect POST requests to another location. With mod_perl, however, you can easily redirect POST requests. All you have to do ...

A.4. Redirecting While Maintaining Environment Variables: Let's say you have a module that sets some environment variables. Redirecting most likely tells the web browser to fetch the new page. This makes it a totally ...

A.5. Handling Cookies: Unless you use a module such as CGI::Cookie or Apache::Cookie, you need to handle cookies yourself. Cookies are accessed via the $ENV{HTTP_COOKIE} environment ...

A.6. Sending Multiple Cookies with the mod_perl API: Given that you have prepared your cookies in @cookies, the following code will submit all the cookies: for (@cookies) { $r- headers_out- add('Set-Cookie' = $_); ...

A.7. Sending Cookies in REDIRECT Responses: You should use err_headers_out( ), not headers_out( ), when you want to send cookies in a REDIRECT response or in any other non-2XX response. The difference ...

A.8. CGI::params in the mod_perlish Way: Assuming that all your variables are single key-value pairs, you can retrieve request parameters in a way similar to using CGI::params with this technique: my $ ...

A.9. Sending Email from mod_perl: There is nothing special about sending email from mod_perl, it's just that we do it a lot. There are a few important issues. The most widely used approach is ...

A.10. mod_rewrite in Perl: mod_rewrite provides virtually any functionality you can think of for manipulating URLs. Because of its highly generalized nature and use of complex regular ...

A.11. Setting PerlHandler Based on MIME Type: It's very easy to implement a dispatching module based on the MIME type of the request that is, for different content handlers to be called for different MIME ...

A.12. Singleton Database Handles: Let's say we have an object we want to be able to access anywhere in the code, without making it a global variable or passing it as an argument to functions.

A.13. Terminating a Child Process on Request Completion: If you want to terminate the child process upon completion of processing the current request, use the child_terminate( ) method anywhere in the code: $r- ...

A.14. References: mod_perl Developer's Cookbook, by Geoffrey Young, Paul Lindner, and Randy Kobes (Sams Publishing). Selected chapters and code examples available online from ...

Appendix B. Apache Perl Modules: Contents: Development-Stage Modules Modules to Aid Debugging Control and Monitoring Modules Server Configuration Modules Authentication-Phase Modules ...

B.1. Development-Stage Modules: The following modules are mainly useful during the code-development cycle. Some of them can also be useful in the production environment. Continue to: ...

B.1.1. Apache::Reload—Automatically Reload Changed Modules: Apache::Reload is used to make specific modules reload themselves when they have changed. It's also very useful for mod_perl module development. Covered in ...

B.1.2. Apache::PerlVINC—Allow Module Versioning in <Location> and <VirtualHost> blocks: This module makes it possible to have different @INC values for different VirtualHost s, Location s, and equivalent configuration blocks. Suppose two versions ...

B.1.3. Apache::DProf—Hook Devel::DProf into mod_perl: Covered in Chapter 9. Available from CPAN. See the module manpage for more information. Continue to: prev: B.1.2. Apache::PerlVINC Allow Module ...

B.1.4. Apache::SmallProf—Hook Devel::SmallProf into mod_perl: Covered in Chapter 9. Available from CPAN. See the module manpage for more information. Continue to: prev: B.1.3. Apache::DProf Hook Devel::DProf into ...

B.1.5. Apache::FakeRequest—Fake Request Object for Debugging: Covered in Chapter 21. Available from CPAN. See the module manpage for more information. Continue to: prev: B.1.4. Apache::SmallProf Hook Devel:: ...

B.1.6. Apache::test—Facilitate Testing of Apache:: Modules: This module helps authors of Apache::* modules write test suites that can query a running Apache server with mod_perl and their modules loaded into it. Its ...

B.2. Modules to Aid Debugging: The following modules are used mainly when something is not working properly and needs to be debugged. Unless your bug is very hard to reproduce and the ...

B.2.1. Apache::DB—Hooks for the Interactive Perl Debugger: Allows developers to interactively debug mod_perl. Covered in Chapter 9. Available from CPAN. See the module manpage for more information. Continue to: ...

B.2.2. Apache::Debug—Utilities for Debugging Embedded Perl Code: Covered in Chapter 21. Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.2.1. Apache::DB Hooks ...

B.2.3. Apache::DebugInfo—Send Debug Information to Client: Available from CPAN. See the module manpage for more information. Continue to: prev: B.2.2. Apache::Debug Utilities for Debugging Embedded Perl Code ...

B.2.4. Apache::Leak—Module for Tracking Memory Leaks in mod_perl Code: Covered in Chapter 14. Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.2.3. Apache::DebugInfo ...

B.2.5. Apache::Peek—A Data Debugging Tool for the XS Programmer: Covered in Chapter 10. Available from CPAN. See the module manpage for more information. Continue to: prev: B.2.4. Apache::Leak Module for Tracking ...

B.2.6. Apache::Symbol—Avoid the Mandatory `Subroutine Redefined' Warning: Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.2.5. Apache::Peek A Data Debugging Tool for ...

B.2.7. Apache::Symdump—Symbol Table Snapshots: Covered in Chapter 21. Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.2.6. Apache::Symbol ...

B.3.1. Apache::Watchdog::RunAway—Hanging Processes Monitor and Terminator: Covered in Chapter 5. Available from CPAN. See the module manpage for more information. Continue to: prev: B.2.7. Apache::Symdump Symbol Table Snapshots ...

B.3.2. Apache::VMonitor—Visual System and Apache Server Monitor: Covered in Chapter 5. Available from CPAN. See the module manpage for more information. Continue to: prev: B.3.1. Apache::Watchdog::RunAway Hanging ...

B.3.3. Apache::SizeLimit—Limit Apache httpd Processes: This module allows you to kill off Apache processes if they grow too large or if they share too little of their memory. It's similar to Apache::GTopLimit.

B.3.4. Apache::GTopLimit—Limit Apache httpd Processes: This module allows you to kill off Apache processes if they grow too large or if they share too little of their memory. It's similar to Apache::SizeLimit.

B.3.5. Apache::TimedRedirect—Redirect URLs for a Given Time Period: Apache::TimedRedirect is a mod_perl TransHandler module that allows the configuration of a timed redirect. In other words, if a user enters a web site and the ...

B.3.6. Apache::Resource—Limit Resources Used by httpd Children: Apache::Resource uses the BSD::Resource module, which uses the C function setrlimit( ) to set limits on system resources such as memory and CPU usage. Covered ...

B.3.7. Apache::Status—Embedded Interpreter Status Information: The Apache::Status module provides various information about the status of the Perl interpreter embedded in the server. Covered in Chapter 21. Available from ...

B.4.1. Apache::ModuleConfig—Interface to Configuration API: Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.3.7. Apache::Status Embedded Interpreter ...

B.4.2. Apache::PerlSections—Utilities for Working with <Perl> Sections: Apache::PerlSections configures Apache entirely in Perl. Covered in Chapter 4. Supplied with the mod_perl distribution. See the module manpage for more ...

B.4.3. Apache::httpd_conf—Generate an httpd.conf File: The Apache::httpd_conf module will generate a tiny httpd.conf file, which pulls itself back in via a Perl section. Any additional arguments passed to the write( ...

B.4.4. Apache::src—Methods for Locating and Parsing Bits of Apache Source Code: This module provides methods for locating and parsing bits of Apache source code. For example: my $src = Apache::src- new; my $v = $src- httpd_version; returns ...

B.4.5. Apache::ConfigFile—Parse an Apache-Style httpd.conf Configuration File: This module parses httpd.conf, or any compatible configuration file, and provides methods for accessing the values from the parsed file. Available from CPAN.

B.5. Authentication-Phase Modules: The following modules make it easier to handle the authentication phase: AuthenCache Cache authentication credentials AuthCookie Authentication and ...

B.6. Authorization-Phase Modules: The following modules make it easier to handle the authorization phase: AuthCookie Authentication and authorization via cookies AuthzDBI Group authorization ...

B.7. Access-Phase Modules: The following modules are used during the access request phase: AccessLimitNum Limit user access by the number of requests RobotLimit Limit the access of ...

B.7.1. Stonehenge::Throttle—Limit Bandwith Consumption by IP Address: http://www.stonehenge.com/merlyn/LinuxMag/col17.html The source code to Stonehenge::Throttle is available from http://www.stonehenge.com/merlyn/LinuxMag/col17.

B.8.1. Apache::MimeXML—mod_perl Mime Encoding Sniffer for XML Files: This module is an XML content-type sniffer. It reads the encoding attribute in the XML declaration and returns an appropriate content-type heading. If no ...

B.8.2. Apache::MIMEMapper—Associates File Extensions with PerlHandlers: Apache::MIMEMapper extends the core AddHandler directive to allow you to dispatch different PerlHandlers based on the file extension of the requested resource.

B.9.1. Apache::AddHostPath—Adds Some or All of the Hostname and Port to the URI: This module transforms the requested URI based on the hostname and port number from the HTTP request header. It allows you to manage an arbitrary number of ...

B.9.2. Apache::ProxyPass—implement ProxyPass in Perl: This module implements the Apache mod_proxy module in Perl. Based on Apache::ProxyPassThru. Available from CPAN. See the module manpage for more information. & ...

B.9.3. Apache::ProxyPassThru—Skeleton for Vanilla Proxy: This module uses libwww-perl as its web client, feeding the response back into the Apache API request_recstructure. PerlHandler will be invoked only if the ...

B.9.4. Apache::Throttle—Speed-Based Content Negotiation: Apache::Throttle is a package designed to allow Apache web servers to negotiate content based on the speed of the connection. Its primary purpose is to ...

B.9.5. Apache::TransLDAP—Trans Handler Example: This module is an example of how you can create a trans handler. This particular example translates from a user's virtual directory on the server to the ...

B.10.1. Apache::RefererBlock—Block Request Based Upon "Referer" Header: Apache::RefererBlock will examine each request. If the MIME type of the requested file is one of those listed in RefBlockMimeTypes, it will check the request's ...

B.10.2. Apache::Usertrack—Emulate the mod_usertrack Apache Module: As of this writing no documentation is available. Available from CPAN. Continue to: prev: B.10.1. Apache::RefererBlock Block Request Based Upon Referer ...

B.11. Generic Content-Generation Modules: These modules extend mod_perl functionality during the content-generation phase. Some of them can also be used during earlier phases. Continue to: prev: ...

B.11.1. Apache::Registry and Apache::PerlRun: These two modules allow mod_cgi Perl scripts to run unaltered under mod_perl. They are covered throughout the book, mainly in Chapter 6 and Chapter 13. See ...

B.11.2. Apache::RegistryNG—Apache::Registry New Generation: Apache::RegistryNG is almost the same as Apache::Registry, except that it uses filenames instead of URIs for namespaces. It also uses an object-oriented ...

B.11.3. Apache::RegistryBB—Apache::Registry Bare Bones: This works just like Apache::Registry, but it does not test the x bit (-x file test for executable mode), compiles the file only once (no stat( ) call is made ...

B.11.4. Apache::Request (libapreq)—Generic Apache Request Library: This package contains modules for manipulating client request data via the Apache API with Perl and C. Functionality includes: Parsing application/x-www-form- ...

B.11.5. Apache::Dispatch—Call PerlHandlers with the Ease of Registry Scripts: Apache::Dispatch translates $r- uri into a class and method and runs it as a PerlHandler. Basically, this allows you to call PerlHandlers as you would Registry ...

B.12.1. Apache::AutoIndex—Perl Replacement for the mod_autoindex and mod_dir Apache Modules: This module can completely replace the mod_dir and mod_autoindex standard directory-handling modules shipped with Apache. Available from CPAN. See the module ...

B.12.2. Apache::WAP::AutoIndex—WAP Demonstration Module: This is a simple module to demonstrate the use of CGI::WML to create a WML (wireless) file browser using mod_perl. It was written to accompany an article in ...

B.12.3. Apache::WAP::MailPeek—Demonstrate Use of WML Delivery: This is a simple module to demonstrate the use of delivery of WML with mod_perl. It was written to accompany an article in the Perl Journal (Issue number 20).

B.12.4. Apache::Archive—Expose Archive Files Through the Apache Web Server: Apache::Archive is a mod_perl extension that allows the Apache HTTP server to expose .tar and .tar.gz archives on the fly. When a client requests such an ...

B.12.5. Apache::Gateway—Implement a Gateway: The Apache::Gateway module implements a gateway using LWP with assorted optional features. From the HTTP/1.1 draft, a gateway is: [a] server which acts as an ...

B.12.6. Apache::NNTPGateway—NNTP Interface for a mod_perl-Enabled Apache Web Server.: Available from CPAN. See the module manpage for more information. Continue to: prev: B.12.5. Apache::Gateway Implement a Gateway Table of Contents next: ...

B.12.7. Apache::PrettyPerl—Syntax Highlighting for Perl Files: An Apache mod_perl PerlHandler that outputs color syntax-highlighted Perl files in the client's browser. Available from CPAN. See the module manpage for more ...

B.12.8. Apache::PrettyText—Reformat .txt Files for Client Display: Dynamically formats .txt files so they look nicer in the client's browser. Available from CPAN. See the module manpage for more information. Continue to: ...

B.12.9. Apache::RandomLocation—Random File Display: Given a list of locations in ConfigFile, this module will instruct the browser to redirect to one of them. The locations in ConfigFile are listed one per line, ...

B.12.10. Apache::Stage—Manage a Staging Directory: A staging directory is a place where the author of an HTML document checks the look and feel of the document before it's uploaded to the final location. A ...

B.12.11. Apache::Roaming—A mod_perl Handler for Roaming Profiles: With Apache::Roaming you can use your Apache web server as a Netscape Roaming Access server. This allows users to store Netscape Communicator 4.5+ preferences, ...

B.12.12. Apache::Backhand—Write mod_backhand Functions in Perl: Apache::Backhand ties mod_perl together with mod_backhand, in two major ways. First, the Apache::Backhand module itself provides access to the global and ...

B.13.1. Apache::DBI—Initiate a Persistent Database Connection: Covered in Chapter 20. Available from CPAN. See the module manpage for more information. Continue to: prev: B.12.12. Apache::Backhand Write mod_backhand ...

B.13.2. Apache::OWA—Oracle's PL/SQL Web Toolkit for Apache: This module makes it possible to run scripts written using Oracle's PL/SQL Web Toolkit under Apache. Available from CPAN. See the module manpage for more ...

B.13.3. Apache::Sybase::CTlib—Persistent CTlib Connection Management for Apache: Available from CPAN. See the module manpage for more information. Continue to: prev: B.13.2. Apache::OWA Oracle's PL/SQL Web Toolkit for Apache Table of ...

B.14.1. Apache::ASP—Active Server Pages for Apache with mod_perl: Apache::ASP provides an Active Server Pages port to the Apache web server with Perl scripting only and enables developing of dynamic web applications with ...

B.14.2. Apache::AxKit—XML Toolkit for mod_perl: AxKit is a suite of tools for the Apache httpd server running mod_perl. It provides developers with extremely flexible options for delivering XML to all kinds ...

B.14.3. HTML::Embperl—Embed Perl into HTML: Embperl gives you the power to embed Perl code in your HTML documents and the ability to build your web site out of small, reusable objects in an object- ...

B.14.4. Apache::EmbperlChain—Process Embedded Perl in HTML in the OutputChain: Uses Apache::OutputChain to filter the output of content generators through Apache::Embperl. Available from CPAN. See the module manpage for more information. & ...

B.14.5. Apache::ePerl—Embedded Perl 5 Language: ePerl interprets an ASCII file that contains Perl program statements by replacing any Perl code it finds with the result of evaluating that code (which may be ...

B.14.6. Apache::iNcom—E-Commerce Framework: Apache::iNcom is an e-commerce framework. It is not a ready-to-run merchant system. It integrates the different components needed for e-commerce into a ...

B.14.7. Apache::Mason—Perl-Based Web Site Development and Delivery System: Apache::Mason allows web pages and sites to be constructed from shared, reusable building blocks called components. Components contain a mixture of Perl and ...

B.14.8. Apache::PageKit—Web Applications Framework: Apache::PageKit is a web applications framework that is based on mod_perl. This framework is distinguished from others (such as Embperl and Mason) by providing ...

B.14.9. Template Toolkit—Template Processing System: The Template Toolkit is a collection of modules that implements a fast, flexible, powerful, and extensible template processing system. It was originally ...

B.15.1. Apache::OutputChain—Chain Stacked Perl Handlers: Apache::OutputChain was written to explore the possibilities of stacked handlers in mod_perl. It ties STDOUT to an object that catches the output and makes it ...

B.15.2. Apache::Clean—mod_perl Interface Into HTML::Clean: Apache::Clean uses HTML::Clean to tidy up large, messy HTML, saving bandwidth. It is particularly useful with Apache::Compress for maximum size reduction.

B.15.3. Apache::Filter—Alter the Output of Previous Handlers: In the following configuration: Files ~ *\.fltr SetHandler perl-script PerlSetVar Filter On PerlHandler Filter1 Filter2 Filter3 /Files each of the handlers ...

B.15.4. Apache::GzipChain—Compress HTML (or Anything) in the OutputChain: Covered in Chapter 13. Available from CPAN. See the module manpage for more information. Continue to: prev: B.15.3. Apache::Filter Alter the Output of ...

B.15.5. Apache::PassFile—Send File via OutputChain: See Apache::GzipChain. It's a part of the same package as Apache::GzipChain. Continue to: prev: B.15.4. Apache::GzipChain Compress HTML (or Anything) in ...

B.15.6. Apache::Gzip—Auto-Compress Web Files with gzip: Similar to Apache::GzipChain but works with Apache::Filter. This configuration: PerlModule Apache::Filter Files ~ *\.html SetHandler perl-script PerlSetVar ...

B.15.7. Apache::Compress—Auto-Compress Web Files with gzip: This module lets you send the content of an HTTP response as gzip-compressed data. Certain browsers (e.g., Netscape and IE) can request content compression via ...

B.15.8. Apache::Layer—Layer Content Tree Over One or More Others: This module is designed to allow multiple content trees to be layered on top of each other within the Apache server. Available from CPAN. See the module ...

B.15.9. Apache::Sandwich—Layered Document (Sandwich) Maker: The Apache::Sandwich module allows you to add per-directory custom header and footer content to a given URI. Works only with GET requests. Output of combined ...

B.15.10. Apache::SimpleReplace—Simple Template Framework: Apache::SimpleReplace provides a simple way to insert content within an established template for uniform content delivery. While the end result is similar to ...

B.15.11. Apache::SSI—Implement Server-Side Includes in Perl: Apache::SSI implements the functionality of mod_include for handling server-parsed HTML documents. It runs under Apache's mod_perl. There are two main reasons ...

B.16.1. Apache::RedirectLogFix—Correct Status While Logging: Because of the way mod_perl handles redirects, the status code is not properly logged. The Apache::RedirectLogFix module works around this bug until mod_perl ...

B.16.2. Apache::DBILogConfig—Logs Access Information in a DBI Database: This module replicates the functionality of the standard Apache module mod_log_config but logs information in a DBI-compatible database instead of a file.

B.16.3. Apache::DBILogger—Tracks What's Being Transferred in a DBI Database: This module tracks what's being transferred by the Apache web server in SQL database (everything with a DBI/DBD driver). This allows you to get statistics (of ...

B.16.4. Apache::DumpHeaders—Watch HTTP Transaction via Headers: This module is used to watch an HTTP transaction, looking at the client and server headers. With Apache::ProxyPassThru configured, you can watch your browser ...

B.16.5. Apache::Traffic—Track Hits and Bytes Transferred on a Per-User Basis: This module tracks the total number of hits and bytes transferred per day by the Apache web server, on a per-user basis. This allows for real-time statistics ...

B.17.1. Apache::Module—Interface to Apache C Module Structures: This module provides an interface to the list of Apache modules configured with your httpd server and their module *structures. Available from CPAN. See the ...

B.17.2. Apache::ShowRequest—Show Phases and Module Participation: Part of the Apache::Module package. This module allows you to see the all phases of the request and what modules are participating in each of the phases.

B.17.3. Apache::SubProcess—Interface to Apache Subprocess API: The output of system( ), exec( ), and open(PIPE, |program ) calls will not be sent to the browser unless your Perl interpreter was configured with sfio. One ...

B.17.4. Apache::Connection—Interface to the Apache conn_rec Data Structure: This module provides the Perl interface to the conn_rec data structure, which includes various records unique to each connection, such as the state of a ...

B.17.5. Apache::Constants—Constants Defined in httpd.h: Server constants (OK, DENIED, NOT_FOUND, etc.) used by Apache modules are defined in httpd.h and other header files. This module gives Perl access to those ...

B.17.6. Apache::ExtUtils—Utilities for Apache C/Perl Glue: Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.17.5. Apache::Constants Constants Defined in ...

B.17.7. Apache::File—Advanced Functions for Manipulating Files on the Server Side: Apache::File does two things. First, it provides an object-oriented interface to file handles, similar to Perl's standard IO::File class. While the Apache:: ...

B.17.8. Apache::Log—Interface to Apache Logging: The Apache::Log module provides an interface to Apache's ap_log_error( ) and ap_log_rerror( ) routines. Supplied with the mod_perl distribution. See the module ...

B.17.9. Apache::LogFile—Interface to Apache's Logging Routines: The PerlLogFile directive from this package can be used to hook a Perl file handle to a piped logger or to a file open for appending. If the first character of ...

B.17.10. Apache::Scoreboard—Perl Interface to Apache's scoreboard.h: Apache keeps track of server activity in a structure known as the scoreboard. There is a slot in the scoreboard for each child server, containing information ...

B.17.11. Apache::Server—Perl Interface to the Apache server_rec Struct: The Apache::Server class contains information about the server's configuration. Using this class it's possible to retrieve any data set in httpd.conf and Perl ...

B.17.12. Apache::Table—Perl Interface to the Apache Table Struct: This module provides tied interfaces to Apache data structures. By using it you can add, merge, and clear entries in headers_in, headers_out, err_headers_out, ...

B.17.13. Apache::URI—URI Component Parsing and Unparsing: This module provides an interface to the Apache util_uri module and the uri_componentsstructure. The available methods are: parsed_uri( ), parse( ), unparse( ), ...

B.17.14. Apache::Util—Perl Interface to Apache C Utility Functions: This module provides a Perl interface to some of the C utility functions available in Apache. The same functionality is avaliable in libwww-perl, but the C ...

B.18.1. Apache::Session—Maintain Session State Across HTTP Requests: This module provides mod_perl with a mechanism for storing persistent user data in a global hash, which is independent of the underlying storage mechanism.

B.18.2. Apache::RequestNotes—Easy, Consistent Access to Cookie and Form Data Across Each Request Phase: Apache::RequestNotes provides a simple interface allowing all phases of the request cycle access to cookie or form input parameters in a consistent manner.

B.18.3. Apache::Cookie—HTTP Cookies Class: The Apache::Cookie module is a Perl interface to the cookie routines in libapreq. The interface is based on the CGI::Cookie module. Available from CPAN. See ...

B.18.4. Apache::Icon—Look Up Icon Images: This module rips out the icon guts of mod_autoindex and provides a Perl interface for looking up icon images. The motivation is to piggy-back the existing ...

B.18.5. Apache::Include—Utilities for mod_perl/mod_include Integration: The Apache::Include module provides a handler, making it simple to include Apache::Registryscripts with the mod_include Perl directive. Apache::Registryscripts ...

B.18.6. Apache::Language—Perl Transparent Language Support for Apache Modules and mod_perl Scripts: The goal of this module is to provide a simple way for mod_perl module writers to include support for multiple language requests. An Apache::Language object ...

B.18.7. Apache::Mmap—Perl Interface to the mmap(2) System Call: The Apache::Mmap module lets you use mmap to map in a file as a Perl variable rather than reading the file into dynamically allocated memory. It works only if ...

B.18.8. Apache::GD::Graph—Generate Graphs in an Apache Handler: The primary purpose of this module is to provide a very easy-to-use, lightweight, and fast charting capability for static pages, dynamic pages, and CGI scripts, ...

B.18.9. Apache::Motd—Provide motd (Message of the Day) Functionality to a Web Server: This module provides an alternative and more efficient method of notifying your web users of potential downtime or problems affecting your web server and web ...

B.18.10. Apache::ParseLog—Object-Oriented Perl Extension for Parsing Apache Log Files: Apache::ParseLog provides an easy way to parse the Apache log files, using object-oriented constructs. The module is flexible, and the data it generates can be ...

B.18.11. Apache::RegistryLoader—Compile Apache::Registry Scripts at Server Startup: Covered in Chapter 13. Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.18.10. Apache::ParseLog ...

B.18.12. Apache::SIG—Override Apache Signal Handlers with Perl's Signal Handlers: Covered in Chapter 6. Supplied with the mod_perl distribution. See the module manpage for more information. Continue to: prev: B.18.11. Apache:: ...

B.18.13. Apache::TempFile—Allocate Temporary Filenames for the Duration of a Request: This module provides unique paths for temporary files and ensures that they are removed when the current request is completed. Available from CPAN. See the ...

B.18.14. Xmms—Perl Interface to the xmms Media Player: A collection of Perl interfaces for the xmms media player. Includes a module that allows you to control xmms from the browser. mod_perl generates a page with ...

B.18.15. Module::Use—Log and Load Used Perl Modules: Module::Use records the modules used over the course of the Perl interpreter's lifetime. If the logging module is able, the old logs are read and frequently ...

Appendix C. ISPs Providing mod_perl Services: Contents: Users Sharing a Single Web Server Users Sharing a Single Machine Giving Each User a Separate Machine (Colocation) Giving Each User a Virtual ...

C.1. Users Sharing a Single Web Server: An ISP cannot let users run their code under mod_perl on the main server. There are many reasons for this. Here are just a few to consider: Memory usage One ...

C.2. Users Sharing a Single Machine: A better approach is to give each user a dedicated web server, still running on the same machine. Now each server can run under its owners' permissions, thus ...

C.3. Giving Each User a Separate Machine (Colocation): A much better and simpler (but costly) solution is colocation. Let the users hook their (or your) standalone machines into your network, and forget about the ...

C.4. Giving Each User a Virtual Machine: If users cannot afford dedicated machines, it's possible to provide each user with a virtual machine, assuming that you have a very powerful server that can ...

Appendix D. The Template Toolkit: Contents: Fetching and Installing the Template Toolkit Overview Typical Uses Template Toolkit Language Processing Templates Apache/mod_perl Handler Apache:: ...

D.1. Fetching and Installing the Template Toolkit: You can fetch the Template Toolkit from any CPAN site. It can be found at the following URL: http://www.cpan.org/modules/by-module/Template/. Once you've ...

D.2. Overview: The Template Toolkit is a collection of Perl modules, scripts, and other useful bits and pieces that collectively implement a powerful template processing ...

D.3. Typical Uses: A typical use of the Template Toolkit is as an offline tool for generating static web pages from source templates. This alone can be invaluable as a way of ...

D.4. Template Toolkit Language: The Template Toolkit implements a general-purpose presentation language rather than a general-purpose programming language. What that means is that for general ...

D.4.1. Simple Template Example: So without further ado, let's see what a typical template looks like: p Here are some interesting links: ul li a href= /a /li /ul /p The first thing to note is ...

D.5. Processing Templates: In addition to the ttree script mentioned earlier, tpage is distributed with the Template Toolkit for no-frills simple template processing. You might use it ...

D.6. Apache/mod_perl Handler: There isn't much to change between the implementation of a Perl CGI script such as the example above and the equivalent Apache/mod_perl handler. The great ...

D.7. Apache::Template Module: If you're not looking to do anything too adventurous in terms of application processing in your handler, the Apache::Template module might be all you need to ...

D.8. Hangman Application: In this section we're going to develop a web application based on the classic hangman example from the O'Reilly book Writing Apache Modules with Perl and C.

D.8.1. Hangman CGI Script: The first implementation shows a simple all-in-one CGI script that gets the job done quickly and easily. Following that, we'll look at how it can be adapted ...

D.8.2. Hangman with Modular Templates: Perhaps the biggest limitation of the previous example is that the presentation template isn't at all modular. In this example, we're going to split the one ...

D.8.3. Hangman Plug-in: To take our example a stage further, we're going to convert this simple application into a Template Toolkit plug-in module. A plug-in is just like any other ...

D.8.4. Self-Contained Hangman Template: One of the benefits of writing the hangman application as a plug-in is that you no longer need to write a CGI script at all. You can load and use the plug-in ...

D.9. References: This chapter deals with a lot of code, some of which was included in listings and some of which was not because it was too long. You can get all the code and ...

Appendix E. The AxKit XML Application Server: Contents: Installing and Configuring AxKit Your First AxKit Page Dynamic Content More XPathScript Details XSLT Putting Everything Together More Reasons to Use ...

E.1. Installing and Configuring AxKit: There are many configuration options that allow you to customize your AxKit installation, but in this section we aim to get you started as quickly and simply ...

E.2. Your First AxKit Page: Now we're going to see how AxKit works, by transforming an XML file containing data about Camelids (note the dubious Perl reference) into HTML. First you will ...

E.2.1. If Something Goes Wrong: If you don't see HTML in your browser but instead get the source XML, you will need to check your error log. (In Internet Explorer you will see a tree-based ...

E.2.2. How it Works?: The stylesheet above specifies how the various tags work. The ASP % % syntax delimits Perl code from HTML. You can execute any code within the stylesheet. In ...

E.2.3. XPath: One of the key specifications being used in XML technologies is XPath. This is a little language used within other languages for selecting nodes within an XML ...

E.3. Dynamic Content: AxKit has a flexible tool called eXtensible Server Pages (XSP) for creating XML from various data sources such as relational databases, cookies, and form ...

E.3.1. Handling Form Parameters: The AxKit::XSP::Param taglib allows you to easily read form and query string parameters within an XSP page. The following example shows how a page can submit ...

E.3.2. Handling Cookies: AxKit::XSP::Cookie is a taglib interface to Apache::Cookie (part of the libapreq package). The following example demonstrates both retrieving and setting a ...

E.3.3. Sending Email: With the AxKit::XSP::Sendmail taglib, it is very simple to send email from an XSP page. This taglib combines email-address verification, using the Email::Valid ...

E.3.4. Handling Exceptions: The exception taglib, AxKit::XSP::Exception, is used to catch exceptions. The syntax is very simple: rather than allowing different types of exceptions, it is ...

E.3.5. Utilities Taglib: The AxKit::XSP::Util taglib includes some utility methods for including XML from the filesystem, from a URI, or as the return value from an expression. ( ...

E.3.6. Executing SQL: Perhaps the most interesting taglib of all is the ESQL taglib, which allows you to execute SQL queries against a DBI-compatible database and provides access to ...

E.4. More XPathScript Details: XPathScript aims to provide the power and flexibility of XSLT as an XML transformation language, without the restriction of XSLT's XML-based syntax. Unlike ...

E.4.1. The XPathScript API: Along with the code delimiters, XPathScript provides stylesheet developers with a full API for accessing and transforming the source XML file. This API can be ...

E.4.1.1. Extracting values: A simple example to get us started is to use the API to bring in the title from a DocBook article. A DocBook article title looks like this: article artheader ...

E.4.1.2. Declarative templates: We saw declarative templates earlier in this appendix, in Section E.2. The $t hash is the key to declarative templates. The apply_templates( ) function ...

E.5. XSLT: One of the most important technologies to come out of the W3C is eXtensible Stylesheet Language Transformations (XSLT). XSLT provides a way to transform one ...

E.5.1. Anatomy of an XSLT Stylesheet: All XSLT stylesheets contain the following: An XML declaration (optional) An xsl:stylesheet element as the document's root element Zero or more template rules ...

E.5.2. Template Rules and Recursion: Let's take our basic stylesheet and extend it to allow us to transform the DocBook XML document presented in Example E-8 into HTML. Example E-8. camelhistory.

E.5.3. Learning More: We have only scratched the surface of how XSLT can be used to transform XML documents. For more information, see the following resources: The XSLT ...

E.6. Putting Everything Together: The last key piece to AxKit is how everything is tied together. We have a clean separation of logic, presentation, and content, but we've only briefly ...

E.7. More Reasons to Use AxKit: Hopefully this will have whetted your appetite to play with AxKit. If you still need convincing, here are some extra things AxKit can do: AxKit can work with ...

Appendix F. HTTP Status Codes: Contents: HTTP/1.0 Status Codes HTTP/1.1 Status Codes ReferencesThe HyperText Transfer Protocol (HTTP) is an application-level protocol for distributed, ...

F.1. HTTP/1.0 Status Codes: Successful 2xx: 200 HTTP_OK 201 HTTP_CREATED 202 HTTP_ACCEPTED 204 HTTP_NO_CONTENT Redirection 3xx: 300 HTTP_MOVED_PERMANENTLY 301 HTTP_MOVED_TEMPORARILY 302 ...

F.2. HTTP/1.1 Status Codes: Informational 1xx: 100 HTTP_CONTINUE 101 HTTP_SWITCHING_PROTOCOLS Successful 2xx: 200 HTTP_OK 201 HTTP_CREATED 202 HTTP_ACCEPTED 203 HTTP_NON_AUTHORITATIVE 204 ...

F.3. References: All the information related to web protocols can be found at the World Wide Web Consortium's site, http://www.w3.org/Protocols/. There are many mirrors of the ...

Colophon: Our look is the result of reader comments, our own experimentation, and feedback from distribution channels. Distinctive covers complement our distinctive ...

Index: Symbols & Numbers: Practical mod_perl Book Index: 0

Index: A: Practical mod_perl Book Index: A

Index: B: Practical mod_perl Book Index: B

Index: C: Practical mod_perl Book Index: C

Index: D: Practical mod_perl Book Index: D

Index: E: Practical mod_perl Book Index: E

Index: F: Practical mod_perl Book Index: F

Index: G: Practical mod_perl Book Index: G

Index: H: Practical mod_perl Book Index: H

Index: I: Practical mod_perl Book Index: I

Index: J: Practical mod_perl Book Index: J

Index: K: Practical mod_perl Book Index: K

Index: L: Practical mod_perl Book Index: L

Index: M: Practical mod_perl Book Index: M

Index: N: Practical mod_perl Book Index: N

Index: O: Practical mod_perl Book Index: O

Index: P: Practical mod_perl Book Index: P

Index: Q: Practical mod_perl Book Index: Q

Index: R: Practical mod_perl Book Index: R

Index: S: Practical mod_perl Book Index: S

Index: T: Practical mod_perl Book Index: T

Index: U: Practical mod_perl Book Index: U

Index: V: Practical mod_perl Book Index: V

Index: W: Practical mod_perl Book Index: W

Index: X: Practical mod_perl Book Index: X

Index: Y: Practical mod_perl Book Index: Y

Index: Z: Practical mod_perl Book Index: Z

Headaches Begone! A Systemic Approach To Healing Your Headaches

Don't Let Your Bike Seat Ruin Your Sex Life Book

Practical mod_perl | by Stas Bekman and Eric Cholet

Search

My Books

Discover