HTML Version of the book

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 as 50 times faster, and you can ...

Part 1: mod_perl Administration

Book by Parts. Part 1: mod_perl Administration

Part 2: mod_perl Performance

Book by Parts. Part 2: mod_perl Performance

Part 3: Databases and mod_perl

Book by Parts. Part 3: Databases and mod_perl

Part 4: Debugging and Troubleshooting

Book by Parts. Part 4: Debugging and Troubleshooting

Part 5: mod_perl 2.0

Book by Parts. Part 5: mod_perl 2.0

Part 6: Appendixes

Book by Parts. Part 6: Appendixes

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 ...

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 think these two topics are ...

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 ...

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 URLs or book references. Unfortunately,...

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 same ...

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 later versions of mod_perl and Apache....

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 ...

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. In this book we will use ...

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 Perl Archive Network (CPAN) at ...

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 ...

9.2. Prerequisites Needed to Install Perl Modules on Windows

While Unix operating systems include standard utilities such as tar, gzip, ...

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 ...

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 ...

9.5. Using the Perl Package Manager

If you are using ActivePerl on Windows, or the Perl/Apache/mod_perl binary distribution discussed in ...

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 ...

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, creator of mod_perl. Doug's ...

Chapter 1. Introducing CGI and mod_perl

Contents: A Brief History of CGI The Apache 1.3 ...

1.1. A Brief History of CGI

When the World Wide Web was born, there was only one web server and one web ...

1.1.1. The HTTP Protocol

Interaction between the browser and the server is governed by the ...

1.1.2. The Common Gateway Interface Specification

If you are new to the CGI world, there's no need to worrybasic CGI programming is very easy. Ninety percent of CGI-specific code is concerned with ...

1.1.3. Apache CGI Handling with mod_cgi

The Apache server processes CGI scripts ...

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 mod_cgi and why mod_perl is such a big ...

1.2.1. Forking

1.2.2. CGI Scripts Under the Forking Model

One of the benefits of this model is ...

1.2.3. Performance Drawbacks of Forking

There are several drawbacks to mod_cgi that triggered the development of ...

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 ...

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 ...

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,...

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 ...

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. ...

1.5. References

The CGI specification: http://hoohoo.ncsa.uiuc.edu/cgi/ ...

Chapter 2. Getting Started Fast

Contents: Installing mod_perl 1.0 in Three ...

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 ...

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 a hurry to boot your new ...

2.2.1. Obtaining and Unpacking the Source Code

The

2.2.2. Building mod_perl

Move into the /home/stas/src/mod_perl-1.xx/ source distribution ...

2.2.3. Installing mod_perl

Running make install completes the installation process by installing all the Perl files required for ...

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 ...

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 ...

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 ...

2.5. Preparing the Scripts Directory

Now you have to select a directory where all the mod_perl scripts and modules will ...

2.6. A Sample Apache::Registry Script

One of mod_perl's benefits is that it can run existing CGI scripts written in Perl ...

2.6.1. Porting Existing CGI Scripts to mod_perl

Now it's time to move any existing CGI scripts from the /somewhere/cgi-...

2.7. A Simple mod_perl Content Handler

As we mentioned in the beginning of this chapter, mod_perl lets you run both ...

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 knowledge. With the basic ...

2.9. References

The Apache home page: http://www.apache.org/. The ...

Chapter 3. Installing mod_perl

Contents: Configuring the Source Building mod_perl (...

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:...

3.1.1. Controlling the Build Process

The configuration stage of the build is ...

3.1.2. Activating Callback Hooks

A callback hook (also known simply as a callback) is a reference to a ...

3.1.3. Activating Standard API Features

The following options enable various standard features of the mod_perl API. ...

3.1.4. Enabling Extra Features

mod_perl comes with a number of other features. Most of them are disabled by ...

3.1.5. Reusing Configuration Parameters

When you have to upgrade the server, it'...

3.1.6. Discovering Whether a Feature Was Enabled

mod_perl Version 1.25 introduced Apache::MyConfig, ...

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. ...

3.1.8. perl Makefile.PL Troubleshooting

During the configuration (perl Makefile....

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 ...

3.1.8.2. Missing or misconfigured libgdbm.so

On some Red Hat Linux systems, you might encounter a problem during the ...

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....

3.2. Building mod_perl (make)

After completing the configuration, it's time to build the server by simply ...

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....

3.2.2. make Troubleshooting

The following errors are the ones that frequently occur during the make ...

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 ...

3.2.2.2. Unrecognized format specifier for...

This error is usually reported due to the problems with some versions of the SFIO library....

3.3. Testing the Server (make test)

After building the server, it's a good idea to test it throughly by calling: <...

3.3.1. Manual Testing

Tests

3.3.2. make test Troubleshooting

The following ...

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 ...

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 ...

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 ...

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 ...

3.4. Installation (make install)

After testing the server, the last step is to install it. First install all the ...

3.4.1. Manually Building a mod_perl-Enabled Apache

If you want to build httpd ...

3.5. Installation Scenarios for Standalone mod_perl

When building mod_perl, the mod_perl C source files that have to be compiled into ...

3.5.1. The All-in-One Way

If your goal is just to build and install Apache with mod_perl out of their ...

3.5.2. Building mod_perl and Apache Separately

However, sometimes you might need more ...

3.5.3. When DSOs Can Be Used

If you want to build mod_perl as a DSO, ...

3.5.4. Building mod_perl as a DSO via APACI

We have already mentioned that the new ...

3.5.5. Building mod_perl as a DSO via APXS

We've seen how to build mod_perl as a ...

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. We'll also show how to build a secure ...

3.6.1. Installing mod_perl with PHP

The following is a simple installation ...

3.6.2. Installing mod_perl with mod_ssl (+openssl)

mod_ssl provides strong cryptography for ...

3.6.3. Installing mod_perl with Apache-SSL (+openssl)

Apache-SSL is a secure web server based ...

3.6.4. Installing mod_perl with Stronghold

Stronghold is a ...

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 ...

3.8. Installing mod_perl on Multiple Machines

You may want to build httpd once and then copy it to other machines. But ...

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

3.9.2. Finding Modules Installed in Nonstandard Directories

Installing ...

3.9.2.1. Modifying @INC

3.9.2.2. Using the PERL5LIB environment variable

Now, let's ...

3.9.3. Using the CPAN.pm Shell with Nonstandard Installation Directories

As we saw previously in this chapter, ...

3.9.4. Making a Local Apache Installation

Just as with Perl modules, if you don't ...

3.9.5. Nonstandard mod_perl-Enabled Apache Installation

Now that we know how to install local Apache and Perl modules separately, let'...

3.9.6. Nonstandard mod_perl-Enabled Apache Installation with CPAN.pm

Again, CPAN makes installation and ...

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 (...

3.10.1. Checking the error_log File

One way to check for mod_perl is to ...

3.10.2. Testing by Viewing /perl-status

Assuming that you have configured ...

3.10.3. Testing via Telnet

Knowing the port you have configured ...

3.10.4. Testing via a CGI Script

Another

3.10.5. Testing via lwp-request

Assuming you have ...

3.11. General Notes

This section looks at some other installation issues you may encounter. ...

3.11.1. How Do I Make the Installation More Secure?

Unix systems usually provide chroot or jail ...

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. ...

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 @...

3.11.4. mod_auth_dbm Nuances

If you are a mod_auth_dbm or ...

3.12. References

Apache Toolbox (http://apachetoolbox.com/) provides a means to easily ...

Chapter 4. mod_perl Configuration

Contents: Apache Configuration mod_perl Configuration<...

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 ...

4.1.1. Configuration Files

Prior to Version 1.3.4, the default Apache installation used three ...

4.1.2. Configuration Directives

A basic setup requires little ...

4.1.3. <Directory>, <Location>, and <Files> Sections

Let's discuss the basics of the Directory, Location, and Files&...

4.1.3.1. <Directory directoryPath> ... </Directory>

Scope: Can appear in server and virtual host configurations. ...

4.1.3.2. <Files filename > ... </Files>

Scope: Can appear in server and virtual host configurations, as well as in .htaccess files. The ...

4.1.3.3. <Location URI> ... </Location>

Scope: Can appear in server and virtual host configurations. The ...

4.1.4. Merging <Directory>, <Location>, and <Files> Sections

When configuring the server, it's ...

4.1.5. Subgrouping of <Directory>, <Location>, and <Files> Sections

Let's say that you want all files to be ...

4.1.6. Options Directive Merging

Normally, if ...

4.1.7. MinSpareServers, MaxSpareServers, StartServers, MaxClients, and MaxRequestsPerChild

MinSpareServers, ...

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 ...

4.2.1. Alias Configurations

For many reasons, a server can never ...

4.2.1.1. Running scripts located in the same directory under different handlers

Sometimes you will want to map the ...

4.2.2. <Location /perl> Sections

The Location section assigns a number of ...

4.2.3. PerlModule and PerlRequire

As we saw earlier, a module should be loaded before its handler can be used. ...

4.2.4. PerlHandlers

As mentioned in Chapter 1, Apache specifies 11 phases ...

4.2.5. The handler( ) Subroutine

By default, the mod_perl API expects a subroutine named ...

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 ...

4.2.7. Stacked Handlers

With the mod_perl stacked ...

4.2.8. Perl Method Handlers

If mod_perl was built with: ...

4.2.9. PerlFreshRestart

To reload ...

4.2.10. PerlSetEnv and PerlPassEnv

In addition to Apache' ...

4.2.11. PerlSetVar and PerlAddVar

PerlSetVar is another directive introduced by mod_perl. It is very similar to ...

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 ...

4.2.13. PerlWarn and PerlTaintCheck

PerlWarn and PerlTaintCheck ...

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 ...

4.3.1. A Sample Startup File

Let's look at a real-world startup file. The elements of the file are shown ...

4.3.2. Syntax Validation

If the startup file doesn't include any ...

4.3.3. What Modules Should Be Added to the Startup File

Every

4.3.4. The Confusion with use( ) in the Server Startup File

Some

4.4. Apache Configuration in Perl

With Perl ... /Perlsections, you ...

4.4.1. Constructing <Perl> Sections

4.4.2. Breaking Out of <Perl> Sections

Behind the scenes, mod_perl defines a ...

4.4.3. Cheating with Apache->httpd_conf

In fact, you can create a complete configuration file in Perl. For example, ...

4.4.4. Declaring Package Names in Perl Sections

Be careful when you declare package names inside Perl sections. For example, this ...

4.4.5. Verifying <Perl> Sections

How do we know whether the configuration made inside Perlsections was correct? ...

4.4.6. Saving the Perl Configuration

Instead of dumping the generated Perl configuration, you may decide to store ...

4.4.7. Debugging

If your configuration doesn't seem to do what it's supposed to do, you should ...

4.5. Validating the Configuration Syntax

Before you restart a server on a live production machine after the configuration ...

4.6. The Scope of mod_perl Configuration Directives

Table 4-1 depicts where the ...

4.7. Apache Restarts Twice

When the server is restarted, the configuration and module initialization phases are called twice before the children ...

4.8. Enabling Remote Server Configuration Reports

The nifty mod_info Apache module displays the complete server configuration in ...

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. ...

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 ...

4.9.2. Running the Same Script from Different Virtual Hosts

When running under a virtual host, Apache::Registry ...

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 exploit to gain unauthorized access to ...

4.10.1. Using Only Absolutely Necessary Components

The more modules you have enabled in your web server, the more complex the ...

4.10.2. Taint Checking

Make sure to run the server with the following setting in the httpd....

4.10.3. Hiding Server Information

We aren't completely sure why the default value of the ...

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 ...

4.10.5. Protecting Private Status Locations

It's a good idea to protect your various monitors, such as /perl-...

4.11. General Pitfalls

The following are some of the mostly frequently asked questions related to mod_perl configuration issues (and the ...

4.12. References

To learn regular expressions for use in DirectoryMatch or equivalent sections, the book Mastering Regular ...

Chapter 5. Web Server Control, Monitoring, Upgrade, and Maintenance

Contents: Starting the Server in Multi-Process ...

5.1. Starting the Server in Multi-Process Mode

To start Apache manually, just run its ...

5.2. Starting the Server in Single-Process Mode

When developing new code, it is often helpful to run the server in single-process ...

5.3. Using kill to Control Processes

Linux and other Unix-like operating systems support a form of interprocess ...

5.3.1. kill Signals for Stopping and Restarting Apache

Apache

5.3.2. Speeding Up Apache's Termination and Restart

Restart or termination of a mod_perl server may sometimes take quite a long ...

5.3.3. Finding the Right Apache PID

In order to send a signal to a process, ...

5.4. Using apachectl to Control the Server

The Apache distribution comes with a script ...

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,...

5.6. Setuid root Startup Scripts

If a group of developers need to be able to ...

5.6.1. Introduction to setuid Executables

A setuid

5.6.2. Apache Startup Script's setuid Security

In the

5.6.3. Sample setuid Apache Startup Script

Example 5-1 shows a ...

5.7. Preparing for Machine Reboot

When using a non-production development box, it is OK to start and stop the web ...

5.8. Upgrading a Live Server

When you're developing code on a development server, anything goes: modifying the configuration, adding or upgrading ...

5.8.1. Upgrading Intranet Servers

An Intranet server generally serves the ...

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 ...

5.8.2.1. The server cluster

When a service is very popular, a ...

5.8.2.2. The single server

It's not uncommon for a popular web ...

5.8.2.2.1. Upgrading live server components by swapping machines

There are many things that you might ...

5.8.2.2.2. Upgrading a live server with port forwarding

Using

5.8.2.2.3. Upgrading a live server with prepackaged components

Assuming that the testbed machine ...

5.8.2.2.4. Upgrading a live server using symbolic links

Yet another alternative is to use ...

5.8.2.2.5. Upgrading Perl code

Although new versions of mod_perl ...

5.8.2.2.6. Moving files and restarting the server

5.8.2.2.7. Using CVS for code upgrades

The Concurrent Versions System (CVS) ...

5.8.3. Disabling Scripts and Handlers on a Live Server

Perl programs running on the mod_perl server may be dependent on resources ...

5.8.3.1. Disabling code running under Apache::Registry

If just a few scripts need to be ...

5.8.3.2. Disabling code running under other handlers

Under non-Apache::...

5.8.3.3. Disabling services with help from the frontend server

Many sites use a more complicated ...

5.8.4. Scheduled Routine Maintenance

If maintenance tasks can be scheduled ...

5.9. Three-Tier Server Scheme: Development, Staging, and Production

To facilitate transfer from the development server to the production server, the ...

5.9.1. Starting a Personal Server for Each Developer

When just one developer is working on a specific server, there are fewer ...

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 server will still need to be maintained ...

5.10.1. Interactive Monitoring

When you' ...

5.10.2. Apache::VMonitor—The Visual System and Apache Server Monitor

The Apache::VMonitor ...

5.10.2.1. Prerequisites and configuration

To run Apache::VMonitor, you need to have Apache::...

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 ...

5.10.2.3. Single-process extensive reporting system

If you need to get in-depth information about a single process, just click ...

5.10.3. Automated Monitoring

As we

5.10.3.1. mod_perl server watchdogs

One simple watchdog solution is to use a slightly modified apachectl<...

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 includes security auditing as well as ...

5.11.1. Handling Log Files

Apache

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 ...

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 ...

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 ...

5.11.2. Swapping Prevention

Before we delve into swapping process details, let's look briefly at memory components and memory management. ...

5.11.3. Limiting Resources Used by Apache Child Processes

There are times when we need to prevent ...

5.11.3.1. OS-specific notes

Under certain Linux setups, malloc( ) uses mmap( ) instead of brk( ). This ...

5.11.4. Tracking and Terminating Hanging Processes

Generally, limits ...

5.11.5. Limiting the Number of Processes Serving the Same Resource

To limit the number of Apache children that can simultaneously serve a ...

5.11.6. Limiting the Request-Rate Speed (Robot Blocking)

Web

5.12. References

Stopping and Restarting Apache, from the Apache documentation: http://httpd.apache.org/docs/...

Chapter 6. Coding with mod_perl in Mind

Contents: Before You Start to Code Exposing ...

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 ...

6.1.1. Accessing Documentation

mod_perl doesn't tolerate sloppy programming. Although we're confident that you're a talented, meticulously careful ...

6.1.2. The strict Pragma

We're sure ...

6.1.3. Enabling Warnings

It's also important to develop your code with Perl reporting every possible ...

6.2. Exposing Apache::Registry Secrets

Let's start with some simple code and see what can go wrong with it. This simple ...

6.2.1. The First Mystery: Why Does the Script Go Beyond 5?

If we

6.2.2. The Second Mystery—Inconsistent Growth over Reloads

Let's return to ...

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. In the following sections, we will ...

6.3.1. The @INC Array

Perl's @INC array is like the ...

6.3.2. The %INC Hash

Perl's %INC hash is used to cache the names of the ...

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 ...

6.3.3.1. A first faulty scenario

It is impossible to use two modules with identical names on the same server. ...

6.3.3.2. A second faulty scenario

Now consider the following scenario: ...

6.3.3.3. A quick but ineffective hackish solution

The following solution should be used only as a short term bandage. You can ...

6.3.3.4. A first solution

The first faulty scenario can be solved by placing library modules in a ...

6.3.3.5. A second solution

Another approach is to use a full path to the script, so the latter will be ...

6.3.3.6. A third solution

This solution makes use of package-name declaration in the ...

6.4. Perl Specifics in the mod_perl Environment

In the following sections, we discuss the specifics of Perl's behavior under mod_perl. ...

6.4.1. exit( )

Perl's core exit( )...

6.4.2. die( )

die( ) is ...

6.4.3. Global Variable Persistence

Under

6.4.4. STDIN, STDOUT, and STDERR Streams

Under mod_perl, ...

6.4.5. Redirecting STDOUT into a Scalar Variable

Sometimes ...

6.4.6. print( )

Under mod_perl, CORE::print( ) (using either ...

6.4.7. Formats

6.4.8. Output from System Calls

The

6.4.9. BEGIN blocks

Perl executes BEGIN blocks as soon as possible, when ...

6.4.10. END Blocks

As the perlmod manpage explains, an ...

6.5. CHECK and INIT Blocks

The CHECK and ...

6.5.1. $^T and time( )

Under mod_perl, processes don't quit after serving a single request. Thus, $^...

6.5.2. Command-Line Switches

When a Perl script is run from the command line, the shell invokes the Perl ...

6.5.2.1. Warnings

There are three ways to enable warnings: Globally to all ...

6.5.2.2. Taint mode

Perl's -T switch enables taint ...

6.5.3. Compiled Regular Expressions

6.5.3.1. Matching patterns repeatedly

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::...

6.6.1. __END__ and __DATA__ Tokens

An Apache:: ...

6.6.2. Symbolic Links

Apache::

6.6.3. Return Codes

Apache::

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 features not available under mod_cgi ...

6.7.1. Starting with a mod_cgi-Compatible Script

Example 6-18 shows the original script's code. ...

6.7.2. Converting into a Perl Content Handler

Let's now ...

6.7.3. Converting to use the mod_perl API and mod_perl-Specific Modules

Now that we have a ...

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 (especially during the development process) we ...

6.8.1. The @INC Array Under mod_perl

Under mod_perl, @INC can be modified only during ...

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, ...

6.8.2.1. Restarting the server

The simplest approach is to restart ...

6.8.2.2. Using Apache::StatINC

6.8.2.3. Using Apache::Reload

Apache::

6.8.2.4. Using dynamic configuration files

Sometimes you ...

6.8.2.4.1. Writing configuration files

We'll start by describing various approaches to writing configuration ...

6.8.2.4.2. Reloading configuration files

First, lets look at a simple case, in which we just have to look after a ...

6.8.2.4.3. Dynamically updating configuration files

The CGI script below allows a system administrator to dynamically update a ...

6.9. Handling the "User Pressed Stop Button" Case

When a user presses the Stop or Reload button, the current socket connection is ...

6.9.1. Detecting Aborted Connections

Now let's use the knowledge we have ...

6.9.2. The Importance of Cleanup Code

6.9.2.1. Critical section

First, we want to take a little detour to discuss the critical section ...

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 ...

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 ...

6.11. Generating Correct HTTP Headers

An HTTP response header consists of at least two fields: HTTP response and MIME-...

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 ...

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 ...

Chapter 7. Identifying Your Performance Problems

Contents: Looking at the Big Picture Asking 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 ...

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 ...

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 ...

Chapter 8. Choosing a Platform for the Best Performance

Contents: Choosing the Right Operating ...

8.1. Choosing the Right Operating System

This section discusses the characteristics and features you should be looking ...

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 ...

8.1.2. Stability and Robustness

Probably the most important features in an OS are stability and robustness. ...

8.1.3. Good Memory Management

You want an OS with a good memory-management implementation. Some OSes are ...

8.1.4. Avoiding Memory Leaks

Some OSes and/or their libraries (e.g., C runtime libraries) suffer from ...

8.1.5. Memory-Sharing Capabilities

You want an OS with good memory-sharing capabilities. If you preload the Perl ...

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. ...

8.1.7. Discontinued Products

You might find yourself in a position where you have invested a lot of time ...

8.1.8. Keeping Up with OS Releases

Actively developed OSes generally try to keep pace with the latest technology developments and continually optimize ...

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 ...

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 ...

8.2.3. Getting a Fast Internet Connection

You have the best hardware you can get, but the service is still crawling. ...

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 ...

8.2.5. How Much Memory Is Enough?

How much RAM do you need? Nowadays, chances are that you will hear: Memory is ...

8.2.6. Getting a Fault-Tolerant CPU

Make sure that the CPU is operating ...

8.2.7. Detecting and Avoiding Bottlenecks

You might use the most expensive ...

8.2.8. Solving Hardware Requirement Conflicts

It may happen that the combination of software components you find yourself ...

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 mirrors (...

Chapter 9. Essential Tools for Performance Tuning

Contents: Server Benchmarking Perl Code ...

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 ...

9.1.1. ApacheBench

ApacheBench (ab) is a tool ...

9.1.2. httperf

httperf is another tool for ...

9.1.3. http_load

http_load is yet another utility ...

9.1.4. Other Web Server Benchmark Utilities

The following are also interesting benchmarking applications implemented in Perl: HTTP::WebTest ...

9.2. Perl Code Benchmarking

If you want to benchmark your Perl code, you can use the ...

9.3. Process Memory Measurements

A very important aspect of performance tuning is to make sure that your ...

9.4. Apache::Status and Measuring Code Memory Usage

The Apache::Status ...

9.5. Code Profiling Techniques

The profiling process helps you to determine which subroutines (or just snippets ...

9.5.1. Profiling with Devel::DProf

Devel::DProf ...

9.5.2. Profiling with Devel::SmallProf

The Devel::SmallProf ...

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 ...

Chapter 10. Improving Performance with Shared Memory and Proper Forking

Contents: Sharing Memory Forking ...

10.1. Sharing Memory

The sharing of memory is a very important factor. If your OS supports it (and ...

10.1.1. Calculating Real Memory Usage

We have shown how to measure the ...

10.1.2. Memory-Sharing Validation

How do you find out if the code you write is shared between processes or ...

10.1.2.1. Variable unsharing caused by regular expressions

Let's write a module ...

10.1.2.2. Numerical versus string access to variables

Data can get unshared ...

10.1.3. Preloading Perl Modules at Server Startup

As we just explained, to get the ...

10.1.4. Preloading Registry Scripts at Server Startup

Suppose you find yourself stuck with ...

10.1.5. Module Initialization at Server Startup

It's important to preload modules ...

10.1.5.1. Initializing DBI.pm

The first example is the DBI module. ...

10.1.5.2. Initializing CGI.pm

CGI.pm is a big module that by default postpones ...

10.1.6. Memory Preallocation

Perl reuses allocated ...

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, but you are also duplicating all the ...

10.2.1. Forking a New Process

The typical way to call fork( ) under mod_perl is <...

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 ...