books

previous page: Version Control with Subversion | by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato
  
page up: Computer Books
  
next page: 55 Ways to Have Fun With Google | by Philipp Lenssen

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.

TitlePractical mod_perl
AuthorStas Bekman and Eric Cholet
PublisherO'Reilly and Associates
Year2003
CopyrightCreative Commons Attribution Share-Alike License
AmazonPractical 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







TOP
previous page: Version Control with Subversion | by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato
  
page up: Computer Books
  
next page: 55 Ways to Have Fun With Google | by Philipp Lenssen