HTML Version of the book
The full book in HTML
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 ...
10.2.3. Detaching the Forked Process
- Now what happens if the forked ...
10.2.4. Avoiding Zombie Processes
- Normally, every process has a parent....
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 ...
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 ...
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.,...
10.2.8. Executing system( ) or exec( ) in the Right Way
- The Perl exec( ) and system( ) functions behave ...
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 ...
Chapter 11. Tuning Performance by Tweaking Apache's Configuration
- Contents: Setting the MaxClients ...
11.1. Setting the MaxClients Directive
- It's important to ...
11.2. Setting the MaxRequestsPerChild Directive
- The MaxRequestsPerChild directive sets the limit on ...
11.3. Setting MinSpareServers, MaxSpareServers, and StartServers
- With mod_perl enabled, it might take as ...
11.4. KeepAlive
- If your mod_perl server's httpd.conf file includes the following directives: ...
11.5. PerlSetupEnv
- By default, PerlSetupEnv is On, but PerlSetupEnv ...
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 ...
11.7. Symbolic Links Lookup
- The two options FollowSymLinks ...
11.8. Disabling DNS Resolution
- You should make sure that your httpd.conf file has this setting: HostnameLookups Off This is ...
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 ...
11.10. References
- Apache Performance Notes: http://httpd.apache....
Chapter 12. Server Setup Strategies
- Contents: mod_perl Deployment ...
12.1. mod_perl Deployment Overview
- There are several different ways to build, configure, and deploy your ...
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 ...
12.3. One Plain and One mod_perl-Enabled Apache Server
- As mentioned earlier, when running ...
12.3.1. Choosing the Target Installation Directories Layout
- If you're going to run two Apache ...
12.3.2. Configuration and Compilation of the Sources
- Now we proceed to configure and ...
12.3.2.1. Building the httpd_docs server
- The first step is to configure the source: ...
12.3.2.2. Building the httpd_perl server
- Now we proceed with the source configuration and installation of the ...
12.3.3. Configuration of the Servers
- When we have completed the build process, the last stage before running ...
12.3.3.1. Basic httpd_docs server configuration
- Configuring the httpd_docs server is a very easy task. Open /...
12.3.3.2. Basic httpd_perl server configuration
- Now we edit the /home/httpd/httpd_perl/conf/httpd.conf file. 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,...
12.5. Adding a Proxy Server in httpd Accelerator Mode
- We have already presented a solution with two servers: one plain Apache server, ...
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 ...
12.6.1. Pros and Cons
- The advantages of using Squid are: Caching of static ...
12.6.2. Light Apache, mod_perl, and Squid Setup Implementation Details
- You will find the installation ...
12.6.3. mod_perl and Squid Setup Implementation Details
- When one of the authors was first ...
12.7. Apache's mod_proxy Module
- Apache's mod_proxy module implements a proxy and cache for Apache. It ...
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 ...
12.7.1.1. ProxyPass
- You
12.7.1.2. ProxyPassReverse
-
12.7.1.3. Security issues
- Whenever
12.7.2. Knowing the Proxypassed Connection Type
- Let's say that you have a frontend server running mod_ssl, mod_rewrite, and ...
12.7.3. Buffering Feature
- In addition to correcting the URI on ...
12.7.4. Closing Lingering Connections with lingerd
- Because of some technical ...
12.7.5. Caching Feature
- Apache does caching as well. It's relevant to mod_perl only if you produce ...
12.7.6. Build Process
- To build mod_proxy into Apache, just add enable-module=...
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 ...
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....
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. ...
12.10.1. Virtual Host Flavors
- Apache supports three flavors of ...
12.10.2. Dual-Server Virtual Host Configuration
- In the dual-server setup, which ...
12.10.3. Virtual Hosts and Main Server Interaction
- When using virtual hosts, any configuration directive outside of a VirtualHost ...
12.10.4. Frontend Server Configuration
- The following example illustrates ...
12.10.5. Backend Server Configuration
- This section describes the ...
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, ...
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 ...
12.12.1. Server Requirements
- Let's first look at what kind of ...
12.12.2. The Problem
- With the database and the web ...
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. ...
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 ...
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 commondifferent Perl modules, no code sharing. Typical numbers ...
12.14. SSL Functionality and a mod_perl Server
- If you need SSL functionality, you can get it by adding the mod_ssl or ...
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 ...
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). ...
Chapter 13. TMTOWTDI: Convenience and Habit Versus Performance
- Contents: Apache::Registry PerlHandler Versus Custom ...
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 ...
13.2. Apache::args Versus Apache::Request::param Versus CGI::param
- Apache::args, Apache::Request::...
13.3. Buffered Printing and Better print( ) Techniques
- As you probably know, this statement:...
13.4. Interpolation, Concatenation, or List
- Let's revisit the various approaches of munging with strings, and compare the ...
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 how to keep memory usage down. Let's ...
13.5.1. "Bloatware" Modules
- Perl IO:: ...
13.5.2. Importing Symbols
- Imported symbols act just like ...
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. ...
13.6.1. The Overhead with Light Subroutines
- Let's do some benchmarking. We will ...
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 ...
13.6.3. Are All Methods Slower Than Functions?
- Some modules' APIs are misleading...
13.7. Using the Perl stat( ) Call's Cached Results
- When you call stat( ) (or its variants -M, -e, etc.), the returned information is ...
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 ...
13.9. Printing Unmodified Files
- To send a complete file from disk, without applying any modifications first, instead of: ...
13.10. Caching and Pre-Caching
- In some situations, you may have data that is expensive to generate but must be ...
13.11. Caching with Memoize
- If you have a subroutine with simpler logic, where a returned value is solely a ...
13.12. Comparing Runtime Performance of Perl and C
- Perl is commonly used for web scripting because it is quick and easy to write, ...
13.12.1. Building Perl Extensions with XS and h2xs
- Perl comes ...
13.12.2. The Benchmark
- We are now ready to write the benchmark code. Take a look at ...
13.12.3. Inline.pm
- Using XS and SWIG may seem like a ...
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 ...
13.13. References
- XS macro language resources: perlguts, perlxs, and perlxstut manpages ...
Chapter 14. Defensive Measures for Performance Enhancement
- Contents: Controlling Your Memory ...
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 ...
14.1.1. Defining the Minimum Shared Memory Size Threshold
- As we have already discussed, when it is first created, an Apache child ...
14.1.1.1. Potential drawbacks of memory-sharing restrictions
- In Chapter 11 we devised a formula to calculate the optimum value for the ...
14.1.2. Defining the Maximum Memory Size Threshold
- No less important than maximizing shared memory is restricting the ...
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 ...
14.2. Coding for a Smaller Memory Footprint
- The following sections present proactive techniques that prevent processes from growing large in the first place. ...
14.2.1. Memory Reuse
- Consider the code in Example 14-1. ...
14.2.2. Big Input, Big Damage
- This section demonstrates how a malicious user ...
14.2.3. Small Input, Big Damage
- This section demonstrates how a small input submitted by a malicious user ...
14.2.4. Think Production, Not Development
- Developers often use sample inputs ...
14.2.5. Passing Variables
- Let's talk about passing variables ...
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 ...
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. You will therefore need to consider ...
14.4. References
- The mod_limitipconn.c and Apache::LimitIPConn Apache modules: http://dominia.org/djao/...
Chapter 15. Improving Performance Through Build Options
- Contents: Server Size as a Function of Compiled-in ...
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 ...
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 add -DDYNAMIC_MODULE_LIMIT=0 ...
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. Generally, optimizing the Perl ...
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 on the kind of compiler that ...
15.6. References
- The GCC manual: http://gcc.gnu.org/onlinedocs/ Code Optimization Using the GNU C Compiler, by Rahul U Joshi: ...
Chapter 16. HTTP Headers for Optimal Performance
- Contents: Date-Related Headers Content ...
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 ...
16.1.1. Date Header
- Section 14.18 of the HTTP standard ...
16.1.2. Last-Modified Header
- Section 14.29 of the HTTP standard ...
16.1.3. Expires and Cache-Control Headers
- Section 14.21 of the HTTP standard ...
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 section we often use the term ...
16.2.1. Content-Type Header
- Most CGI programmers are familiar ...
16.2.2. Content-Length Header
- According to section 14.13 of the ...
16.2.3. Entity Tags
- An entity tag (ETag) is a ...
16.3. Content Negotiation
- Content negotiation is a wonderful feature that was introduced with HTTP/1.1. Unfortunately it is not yet widely ...
16.3.1. The Vary Header
- To signal to the recipient that content ...
16.4. HTTP Requests
- Section 13.11 of the specification states that the only two cacheable methods are GET and HEAD. Responses to POST ...
16.4.1. GET Requests
- Most mod_perl programs are written to service GET ...
16.4.2. Conditional GET Requests
- A rather challenging request that may be ...
16.4.3. HEAD Requests
- Among the headers described thus far, the date-related ones (...
16.4.4. POST Requests
- The response to a POST request ...
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 ...
16.6. References
- Hypertext Transfer ProtocolHTTP/1.0, RFC 1945T, by T. Berners-Lee, et al.: http://www.w3.org/Protocols/rfc1945/...
Chapter 17. Databases Overview
- Contents: Volatile Databases Non-Volatile ...
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: ...
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 ...
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 that charges a subscription fee, it ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 TransHandler ...
18.3. References
- mod_include, an Apache module that provides Server-Side Includes (SSI): http://httpd.apache.org/docs/mod/mod_include....
Chapter 19. DBM and mod_perl
- Contents: mod_perl and DBM Resource ...
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 ...
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 ...
19.2.1. Deadlocks
- First let's make sure that you know how processes work with the CPU. Each ...
19.2.2. Exclusive Locking Starvation
- If a shared lock request is issued, it is granted immediately if the file ...
19.3. Flawed Locking Methods
- The suggested locking methods in the first and second editions of the book Programming Perl (O'Reilly) and the <...
19.4. Locking Wrappers Overview
- Here are the pros and cons of the DBM file-locking wrappers available from CPAN:...
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 ...
19.6. Examples
- Let's look at a few examples that will demonstrate the theory presented at the beginning of the chapter. ...
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 ...
19.6.2. Read/Write Access
- This simple example will show you how to use the DBM file when you want to ...
19.6.3. Storing Complex Data Structures
- As mentioned earlier, you can use ...
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:: ...
20.1. Persistent Database Connections with Apache::DBI
- When people first started to use the ...
20.1.1. Apache::DBI Connections
- The DBI module ...
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 ...
20.1.3. Configuring Apache::DBI
- Apache::DBI will not ...
20.1.4. Debugging Apache::DBI
- If you are not sure whether this module is working as advertised and that ...
20.1.5. Caveats and Troubleshooting
- This section covers some of the risks and things to keep in mind when using Apache::DBI. ...
20.1.5.1. Database locking risks
- When you use Apache:: ...
20.1.5.2. Transactions
- A standard Perl script ...
20.1.5.3. Opening connections with different parameters
- When Apache::DBI receives a connection request, ...
20.1.5.4. Cannot find the DBI handler
- You must use DBI-connect( ) as in ...
20.1.5.5. The morning bug
- The SQL server keeps a connection to the client open for a limited period ...
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 ...
20.1.5.7. Skipping connection cache during server startup
- Does your error_log look like this? 10169 Apache::DBI PerlChildInitHandler ...
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 this topic, so here we will ...
20.2.1. Preopening DBI Connections
- If you are using Apache::DBI and ...
20.2.2. Improving Speed by Skipping ping( )
- If you use Apache::DBI and want ...
20.2.3. Efficient Record-Retrieval Techniques
- When working with a relational database, you'll often encounter the need to ...
20.2.4. mysql_use_result Versus mysql_store_result Attributes
- Many mod_perl ...
20.2.5. Running Two or More Relational Databases
- Sometimes you end up running many ...
20.2.6. Caching prepare( ) Statements
- You can also benefit from persistent connections by replacing ...
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 ...
20.4. References
- Introduction to Structured Query Language: http://web.archive.org/web/20011116021648/w3.one.net/~...
Chapter 21. Error Handling and Debugging
- Contents: Warnings and Errors ...
21.1. Warnings and Errors Explained
- The Perl
21.1.1. The Importance of Warnings
- Just like errors, Perl's optional warnings, if they are enabled, go to the <...
21.1.1.1. The diagnostics pragma
- This pragma extends the terse ...
21.1.2. Curing "Internal Server Error" Problems
- Say you've just installed a new ...
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 ...
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 ...
21.2. Debugging Code in Single-Server Mode
- Normally, Apache runs one parent process and several children. The parent ...
21.3. Tracing System Calls
- Most Unix-style operating systems offer a tracing utility that intercepts and records the system calls 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-...
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 ...
21.5.1. Locating and Correcting Syntax Errors
- While
21.5.2. Using Apache::FakeRequest to Debug Apache Perl Modules
- Apache::FakeRequest is used to set up an empty ...
21.5.3. Using print( ) for Debugging
- The universal debugging tool across nearly all platforms and programming ...
21.5.4. Using print( ) and Data::Dumper for Debugging
- Sometimes we need to peek into ...
21.5.5. The Importance of a Good, Concise Coding Style
- Don't strive for elegant, ...
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 ...
21.5.7. Interactive Perl Debugging Under mod_cgi
- Devel::ptkdb is a visual Perl debugger that uses ...
21.5.8. Noninteractive Perl Debugging Under mod_perl
- To debug scripts running under mod_perl noninteractively (i.e., to print ...
21.5.9. Interactive mod_perl Debugging
- Now we'
21.5.9.1. ptkdb and interactive mod_perl debugging
- As we saw earlier, we can use the <...
21.6. Analyzing Dumped core Files
- When your application dies with the Segmentation fault error (generated by ...
21.6.1. Getting Ready to Debug
- To debug the core file, you may need to recompile Perl and mod_perl ...
21.6.2. Creating a Faulty Package
- The next stage is to create a ...
21.6.3. Dumping the core File
- Now let's dump the core file ...
21.6.4. Analyzing the core File
- First we start gdb, with the location of the ...
21.6.5. Extracting the Backtrace Automatically
- With the help of Debug::...
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. Or ...
21.7.1. Hanging Because of an Operating System Problem
- Sometimes ...
21.7.2. When a Process Might Hang
- In Chapter 19, we discussed the ...
21.7.3. Detecting Hanging Processes
- It's not so easy to detect hanging processes. There is no way you can tell ...
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 ...
21.7.4.1. Using the Perl trace
- To see where an httpd ...
21.7.4.2. Using the system calls trace
- Let's write another similar ...
21.7.4.3. Using the interactive debugger
- Another
21.7.5. mod_perl gdb Debug Macros
- So far we have seen only the use of the curinfo ...
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 ...
21.8.2. -D Runtime Option
- You can
21.8.3. Devel::Peek and Apache::Peek
- Devel::Peek ...
21.8.4. Devel::Symdump and Apache::Symdump
- Devel::Symdump ...
21.8.5. Apache::Debug
- This module sends what may be helpful debugging information to the client, ...
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: ...
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. ...
21.9.1. Apache::Status—Embedded Interpreter Status Information
- This is a very useful module. It ...
21.9.1.1. Minimal configuration
- This configuration enables the Apache::Status ...
21.9.1.2. Extended configuration
- There are several variables you can use to modify the behavior of ...
21.9.1.3. Usage
- Assuming that your mod_perl server is listening on port 81, fetch http://www.example.com:81/perl-status:...
21.9.2. mod_status
- The mod_status module allows a ...
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 ...
22.1. Configuration and Startup
- This section covers errors you might encounter when you start the server. ...
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 ...
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(...
22.1.3. Invalid command `PerlHandler'...
- Here's an example of the full error report that you might see: Syntax error on ...
22.1.4. RegistryLoader: Translation of uri [...] to filename failed
- Here's an example of the full error report that you might see: RegistryLoader: ...
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 ...
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 ...
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 ...
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 ...
22.2.4. Can't locate object method "get_handlers" ...
- If you see this error: Can't locate object method get_handlers via package ...
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 ...
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 ...
22.3. Runtime
- Once you have your server up and running and most of the code working correctly, you may still encounter errors ...
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 ...
22.3.2. Segfaults When Using XML::Parser
- If some processes have segmentation faults when using XML::Parser, you should use the ...
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:...
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 ...
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 ...
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 ...
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 ...
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) ...
22.3.9. Callback called exit
- Callback called exit is just a generic message when Perl encounters an unrecoverable error during ...
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 ...
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 ...
22.4. Shutdown and Restart
- When you shut down or restart the server,...
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. ...
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 ...
22.4.3. Processes Get Stuck on Graceful Restart
- If after doing a graceful restart (e.g, by sending kill -USR1) you ...
Chapter 23. Getting Help and Online Resources
- Contents: How to Report Problems Mailing List ...
23.1. How to Report Problems
- When reporting a problem to the mod_perl mailing list, always send these ...
23.1.1. Getting the Backtrace from Core Dumps
- If you get a core dump (segmentation fault), send a backtrace if ...
23.1.2. Spinning Processes
- The gdb attaching to the live process ...
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 ...
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, Squid, DBI, SQL, Security, etc. ...
23.3.1. mod_perl
- mod_perl home ...
23.3.2. mod_perl Mailing Lists
- The mod_perl mailing list The Apache/Perl mailing list is available for mod_perl users and ...
23.3.3. Perl
- The following resources are available for Perl: Books: ...
23.3.4. Perl/CGI
- The following resources are valuable for learning more about writing CGI ...
23.3.5. Apache
- The following resources are useful for learning more about Apache: ...
23.3.6. DBI and SQL
- The following resources ...
23.3.7. Squid
- Home page: http://www.squid-...
23.3.8. CVS
- CVS instructions for access to the mod_perl repository: ...
23.3.9. Performance and Scalability
- Techniques and ...
23.3.10. Web Security
- Web Security: A Step-by-Step Reference Guide, by Lincoln ...
Chapter 24. mod_perl 2.0: Installation and Configuration
- Contents: What's New in Apache 2.0 What's ...
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 ...
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 ...
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 reimplements itself from scratch, ...
24.3.1. Thread Support
- In order to adapt to the Apache 2.0 threads architecture (for threaded MPMs)...
24.3.2. Perl Interface to the APR and Apache APIs
- As we mentioned earlier, ...
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 ...
24.3.4. Improved and More Flexible Configuration
- mod_perl 2.0 provides new configuration directives for the newly added ...
24.3.5. Optimizations
- The rewrite of mod_perl gives us a chance to build a smarter, stronger, and ...
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 to the mod_perl documentation for ...
24.4.1. Installing from Source
- First download the latest stable ...
24.4.2. Installing Binaries
- Apache 2.0 binaries can be obtained ...
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, but some directives were ...
24.5.1. Enabling mod_perl
- To enable mod_perl as a DSO, add this to httpd.conf: ...
24.5.2. Accessing the mod_perl 2.0 Modules
- To prevent you from inadvertently loading mod_perl 1.0 modules, mod_perl 2....
24.5.3. Startup File
- Next, a startup file with Perl code ...
24.5.4. Perl's Command-Line Switches
- Now you can pass Perl' ...
24.5.5. mod_perl 2.0 Core Handlers
- mod_perl 2.0 provides two types of core handlers: modperl and perl-script. ...
24.5.5.1. modperl
- modperl is configured as: SetHandler modperl This is the bare ...
24.5.5.2. perl-script
- perl-script ...
24.5.5.3. A simple response handler example
- Let's demonstrate the differences between the modperl<...
24.5.6. PerlOptions Directive
- The PerlOptions directive ...
24.5.6.1. Enable
- On by default; can be used to disable mod_perl for a given VirtualHost. For ...
24.5.6.2. Clone
- Share the parent Perl interpreter, but give the VirtualHost its own interpreter ...
24.5.6.3. Parent
- Create a new parent Perl interpreter for the given VirtualHost and give it its ...
24.5.6.4. PerlHandler
- Disable specific Perl*Handlers (all compiled-in handlers are enabled by default). The ...
24.5.6.5. AutoLoad
- Resolve Perl*Handlers at startup time; loads the modules from disk if they're not ...
24.5.6.6. GlobalRequest
- Set up the global Apache::RequestRec object for use with Apache-...
24.5.6.7. ParseHeaders
- Scan output for HTTP headers. This option provides the same functionality as mod_perl 1.0's ...
24.5.6.8. MergeHandlers
- Turn on merging of Perl*Handler arrays. For example, with this setting: ...
24.5.6.9. SetupEnv
- Set up environment variables for each request, la mod_cgi. When this option is enabled, mod_perl ...
24.5.7. Thread-Mode-Specific Directives
- The following directives are enabled only in a threaded MPM mod_perl: ...
24.5.7.1. PerlInterpStart
- The number of interpreters to clone at startup time. ...
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. ...
24.5.7.3. PerlInterpMinSpare
- The minimum number of available interpreters this parameter will clone before a request comes in. ...
24.5.7.4. PerlInterpMaxSpare
- mod_perl will throttle down the number of interpreters to this number as those in use become available. ...
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 ...
24.6. Resources
- For up-to-date documentation on mod_perl 2.0, see: http://perl.apache.org/docs/2.0/ ...
Chapter 25. Programming for mod_perl 2.0
- Contents: Migrating to and Programming with mod_perl 2. ...
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, ...
25.1.1. The Shortest Migration Path
- mod_perl 2.0 provides two backward-compatibility layers: one for the ...
25.1.2. Migrating Configuration Files
- To migrate the configuration files to mod_perl 2.0 syntax, you may need to ...
25.1.2.1. PerlHandler
- PerlHandler has been replaced with ...
25.1.2.2. PerlSendHeader
- PerlSendHeader has been replaced with the PerlOptions +/-...
25.1.2.3. PerlSetupEnv
- PerlSetupEnv has been replaced with the PerlOptions +/-...
25.1.2.4. PerlTaintCheck
- Taint mode can now be turned on with: PerlSwitches -T ...
25.1.2.5. PerlWarn
- Warnings now can be enabled globally with: PerlSwitches - ...
25.1.2.6. PerlFreshRestart
- PerlFreshRestart is a mod_perl 1.0 legacy ...
25.1.3. Code Porting
- mod_perl 2.0 is trying hard to be backward compatible with mod_perl 1.0. ...
25.1.4. ModPerl::Registry Family
- In mod_perl 2.0, Apache::Registry and friends (Apache::PerlRun, <...
25.1.5. Method Handlers
- In mod_perl 1.0, method handlers had to be specified by using ...
25.1.6. Apache::StatINC Replacement
- Apache::StatINC has been replaced by Apache::Reload, which works ...
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 ...
25.2.1. Server Configuration and Startup Phases
- open_logs, configured with PerlOpenLogsHandler, and post_config, configured with ...
25.2.1.1. PerlOpenLogsHandler
- The open_logs phase happens just before the post_config phase. Handlers registered ...
25.2.1.2. PerlPostConfigHandler
- The post_config phase happens right after Apache has processed the configuration files, before any child ...
25.2.1.3. PerlChildInitHandler
- The child_init phase happens immediately after a child process is spawned. Each child process (not a ...
25.2.1.4. PerlChildExitHandler
- The child_exit phase is executed before the child process exits. Notice that it happens only when the ...
25.2.2. Connection Phases
- Since Apache 2.0 makes it possible to implement protocols other than HTTP, the connection phases pre_connection<...
25.2.2.1. PerlPreConnectionHandler
- The pre_connection phase happens just after the server accepts the connection, but before it is handed ...
25.2.2.2. PerlProcessConnectionHandler
- The process_connection phase is used to process incoming connections. Only protocol modules should assign ...
25.2.2.2.1. Socket-based protocol module
- To demonstrate the workings of a protocol module, we'll take a look at ...
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 ...
25.2.3. HTTP Request Phases
- The HTTP request phases themselves have not changed from mod_perl 1.0, except the ...
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's possible that it will ...
25.3.1. I/O Filtering Concepts
- Before introducing the mod_perl filtering API, there are several important concepts to understand. ...
25.3.1.1. Two methods for manipulating data
- As discussed in the last chapter, Apache 2.0 considers all incoming and ...
25.3.1.2. HTTP request versus connection filters
- HTTP request filters are applied when Apache serves an HTTP request. ...
25.3.1.3. Multiple invocations of filter handlers
- Unlike other Apache handlers, filter handlers may get invoked more than ...
25.3.1.4. Blocking calls
- All filters (excluding the core filter that reads from the network and ...
25.3.2. Filter Configuration
- HTTP request filter handlers are declared using the ...
25.3.3. Input Filters
- We looked at how input filters call each other in Figure 25-5. Now let's look at some ...
25.3.3.1. Bucket brigade-based connection input filter
- Let's say that we want to test how ...
25.3.3.2. Bucket brigade-based HTTP request input filter
- Let's look at the request input ...
25.3.3.3. Stream-based HTTP request input filter
- Let's now look at the same filter ...
25.3.4. Output Filters
- Earlier, in Figure 25-6, we saw how output filters call each other. Now let's look at ...
25.3.4.1. Stream-based HTTP request output filter
- The PerlOutputFilterHandler handler registers ...
25.3.4.2. Another stream-based HTTP request output filter
- Let's look at another example of an HTTP request output filterbut first, let's develop a response handler that sends two lines of output: the ...
25.3.4.3. Bucket brigade-based HTTP request output filter
- The filter implementation in ...
Appendix A. mod_perl Recipes
- Contents: Emulating the Authentication ...
A.1. Emulating the Authentication Mechanism
- You can authenticate users with your own ...
A.2. Reusing Data from POST Requests
- What happens if you need to access the ...
A.3. Redirecting POST Requests
- Under mod_cgi, it's not easy to redirect POST requests to ...
A.4. Redirecting While Maintaining Environment Variables
- Let's say you have a module that sets some ...
A.5. Handling Cookies
- Unless you use a module such as CGI::Cookie or Apache::Cookie, you ...
A.6. Sending Multiple Cookies with the mod_perl API
- Given that you have prepared your cookies in @cookies, ...
A.7. Sending Cookies in REDIRECT Responses
- You should use err_headers_out( ), ...
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 ...
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 ...
A.10. mod_rewrite in Perl
- mod_rewrite provides virtually any functionality you can think of for manipulating ...
A.11. Setting PerlHandler Based on MIME Type
- It's very easy to implement a dispatching module based on the MIME type of the ...
A.12. Singleton Database Handles
- Let's say we have an object we want to be ...
A.13. Terminating a Child Process on Request Completion
- If you want to terminate the child process upon completion of processing the ...
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 ...
B.1. Development-Stage Modules
- The following modules are mainly useful during the code-development cycle. Some ...
B.1.1. Apache::Reload—Automatically Reload Changed Modules
- Apache::Reload is used to make specific modules ...
B.1.2. Apache::PerlVINC—Allow Module Versioning in <Location> and <VirtualHost> blocks
- This module makes it possible ...
B.1.3. Apache::DProf—Hook Devel::DProf into mod_perl
- Covered in Chapter 9. Available from CPAN. See the ...
B.1.4. Apache::SmallProf—Hook Devel::SmallProf into mod_perl
- Covered in Chapter 9. Available from CPAN. See the ...
B.1.5. Apache::FakeRequest—Fake Request Object for Debugging
- Covered in Chapter 21. Available from CPAN. See the ...
B.1.6. Apache::test—Facilitate Testing of Apache:: Modules
- This module helps authors of Apache::* modules write ...
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 ...
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. ...
B.2.2. Apache::Debug—Utilities for Debugging Embedded Perl Code
- Covered in Chapter 21. Supplied with the mod_perl distribution. ...
B.2.3. Apache::DebugInfo—Send Debug Information to Client
- Available from CPAN. See the module manpage for more information. ...
B.2.4. Apache::Leak—Module for Tracking Memory Leaks in mod_perl Code
- Covered in Chapter 14. Supplied with the mod_perl distribution. ...
B.2.5. Apache::Peek—A Data Debugging Tool for the XS Programmer
- Covered in Chapter 10. Available from CPAN. See the module manpage ...
B.2.6. Apache::Symbol—Avoid the Mandatory `Subroutine Redefined' Warning
- Supplied with the mod_perl distribution. See the module manpage for more ...
B.2.7. Apache::Symdump—Symbol Table Snapshots
- Covered in Chapter 21. Supplied with the mod_perl distribution. See the ...
B.3.1. Apache::Watchdog::RunAway—Hanging Processes Monitor and Terminator
- Covered in Chapter 5. Available from CPAN. See ...
B.3.2. Apache::VMonitor—Visual System and Apache Server Monitor
- Covered in Chapter 5. Available from CPAN. See the ...
B.3.3. Apache::SizeLimit—Limit Apache httpd Processes
- This module allows you to kill off ...
B.3.4. Apache::GTopLimit—Limit Apache httpd Processes
- This module allows you to kill off Apache processes if they grow too large or ...
B.3.5. Apache::TimedRedirect—Redirect URLs for a Given Time Period
- Apache::TimedRedirect is a mod_perl ...
B.3.6. Apache::Resource—Limit Resources Used by httpd Children
- Apache::Resource uses the BSD::Resource module, ...
B.3.7. Apache::Status—Embedded Interpreter Status Information
- The Apache::Status module provides various ...
B.4.1. Apache::ModuleConfig—Interface to Configuration API
- Supplied with the mod_perl distribution. See ...
B.4.2. Apache::PerlSections—Utilities for Working with <Perl> Sections
- Apache::PerlSections configures Apache entirely in ...
B.4.3. Apache::httpd_conf—Generate an httpd.conf File
- The Apache::httpd_conf module will generate a ...
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 ...
B.4.5. Apache::ConfigFile—Parse an Apache-Style httpd.conf Configuration File
- This module parses httpd.conf, or any compatible configuration file, ...
B.5. Authentication-Phase Modules
- The following modules make it easier to handle the authentication phase: AuthenCache ...
B.6. Authorization-Phase Modules
- The following modules make it easier to handle the authorization phase: AuthCookie ...
B.7. Access-Phase Modules
- The following modules are used during the access request phase: AccessLimitNum Limit ...
B.7.1. Stonehenge::Throttle—Limit Bandwith Consumption by IP Address
- http://www.stonehenge.com/merlyn/LinuxMag/col17.html The source code to ...
B.8.1. Apache::MimeXML—mod_perl Mime Encoding Sniffer for XML Files
- This module is an XML content-type sniffer. ...
B.8.2. Apache::MIMEMapper—Associates File Extensions with PerlHandlers
- Apache::MIMEMapper extends the core ...
B.9.1. Apache::AddHostPath—Adds Some or All of the Hostname and Port to the URI
- This module transforms the ...
B.9.2. Apache::ProxyPass—implement ProxyPass in Perl
- This module implements the Apache mod_proxy module in Perl. Based ...
B.9.3. Apache::ProxyPassThru—Skeleton for Vanilla Proxy
- This module uses libwww-perl as its web client, feeding the response ...
B.9.4. Apache::Throttle—Speed-Based Content Negotiation
- Apache::Throttle is a package designed to allow ...
B.9.5. Apache::TransLDAP—Trans Handler Example
- This module is an example of how you can create a trans handler. This ...
B.10.1. Apache::RefererBlock—Block Request Based Upon "Referer" Header
- Apache::RefererBlock will examine ...
B.10.2. Apache::Usertrack—Emulate the mod_usertrack Apache Module
- As of this writing no documentation is available. Available from CPAN....
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 ...
B.11.1. Apache::Registry and Apache::PerlRun
- These two modules allow mod_cgi ...
B.11.2. Apache::RegistryNG—Apache::Registry New Generation
- Apache::RegistryNG is almost the same as ...
B.11.3. Apache::RegistryBB—Apache::Registry Bare Bones
- This works just like Apache::Registry, but it does ...
B.11.4. Apache::Request (libapreq)—Generic Apache Request Library
- This package contains modules for manipulating client request data via the ...
B.11.5. Apache::Dispatch—Call PerlHandlers with the Ease of Registry Scripts
- Apache::Dispatch translates $r-uri ...
B.12.1. Apache::AutoIndex—Perl Replacement for the mod_autoindex and mod_dir Apache Modules
- This module can completely replace the <...
B.12.2. Apache::WAP::AutoIndex—WAP Demonstration Module
- This is a simple module to demonstrate the use of CGI::...
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 ...
B.12.4. Apache::Archive—Expose Archive Files Through the Apache Web Server
- Apache::Archive is a mod_perl extension that allows ...
B.12.5. Apache::Gateway—Implement a Gateway
- The Apache::Gateway module implements a gateway ...
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. ...
B.12.7. Apache::PrettyPerl—Syntax Highlighting for Perl Files
- An Apache mod_perl PerlHandler that outputs color ...
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 ...
B.12.9. Apache::RandomLocation—Random File Display
- Given a list of locations in ConfigFile, this module ...
B.12.10. Apache::Stage—Manage a Staging Directory
- A staging directory is a place where the author of an HTML document checks ...
B.12.11. Apache::Roaming—A mod_perl Handler for Roaming Profiles
- With Apache::Roaming you can use your Apache web ...
B.12.12. Apache::Backhand—Write mod_backhand Functions in Perl
- Apache::Backhand ties mod_perl together with ...
B.13.1. Apache::DBI—Initiate a Persistent Database Connection
- Covered in Chapter 20. Available from CPAN. See the ...
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 ...
B.13.3. Apache::Sybase::CTlib—Persistent CTlib Connection Management for Apache
- Available from CPAN. See the module manpage for more information. ...
B.14.1. Apache::ASP—Active Server Pages for Apache with mod_perl
- Apache::ASP provides an Active Server ...
B.14.2. Apache::AxKit—XML Toolkit for mod_perl
- AxKit is a suite of tools for the Apache httpd server running mod_perl....
B.14.3. HTML::Embperl—Embed Perl into HTML
- Embperl gives you the power to embed Perl code in ...
B.14.4. Apache::EmbperlChain—Process Embedded Perl in HTML in the OutputChain
- Uses Apache::OutputChain to filter the output of ...
B.14.5. Apache::ePerl—Embedded Perl 5 Language
- ePerl interprets an ASCII file that contains Perl ...
B.14.6. Apache::iNcom—E-Commerce Framework
- Apache::iNcom is an e-commerce framework. It is not ...
B.14.7. Apache::Mason—Perl-Based Web Site Development and Delivery System
- Apache::Mason allows web pages and sites to be ...
B.14.8. Apache::PageKit—Web Applications Framework
- Apache::PageKit is a web applications framework that ...
B.14.9. Template Toolkit—Template Processing System
- The Template Toolkit is a collection of modules that implements a fast, ...
B.15.1. Apache::OutputChain—Chain Stacked Perl Handlers
- Apache::OutputChain was written ...
B.15.2. Apache::Clean—mod_perl Interface Into HTML::Clean
- Apache::Clean uses HTML::Clean to tidy ...
B.15.3. Apache::Filter—Alter the Output of Previous Handlers
- In the following configuration: Files ~ *\.fltr SetHandler perl-script PerlSetVar Filter On ...
B.15.4. Apache::GzipChain—Compress HTML (or Anything) in the OutputChain
- Covered in Chapter 13. Available from CPAN. See the module manpage <...
B.15.5. Apache::PassFile—Send File via OutputChain
- See Apache::GzipChain. It's a part of the same ...
B.15.6. Apache::Gzip—Auto-Compress Web Files with gzip
- Similar to Apache::GzipChain but works with ...
B.15.7. Apache::Compress—Auto-Compress Web Files with gzip
- This module lets you send the content of an HTTP response as gzip-...
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 ...
B.15.9. Apache::Sandwich—Layered Document (Sandwich) Maker
- The Apache::Sandwich module allows you to add per-...
B.15.10. Apache::SimpleReplace—Simple Template Framework
- Apache::SimpleReplace provides a simple way to ...
B.15.11. Apache::SSI—Implement Server-Side Includes in Perl
- Apache::SSI implements the functionality of ...
B.16.1. Apache::RedirectLogFix—Correct Status While Logging
- Because of the way mod_perl handles redirects, ...
B.16.2. Apache::DBILogConfig—Logs Access Information in a DBI Database
- This module replicates the functionality of the standard Apache module ...
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 ...
B.16.4. Apache::DumpHeaders—Watch HTTP Transaction via Headers
- This module is used to watch an HTTP transaction, looking at the client and ...
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 ...
B.17.1. Apache::Module—Interface to Apache C Module Structures
- This module provides an ...
B.17.2. Apache::ShowRequest—Show Phases and Module Participation
- Part of the Apache::Module package. This module ...
B.17.3. Apache::SubProcess—Interface to Apache Subprocess API
- The output of system( ), exec( ), and open(PIPE,|program) calls will not be ...
B.17.4. Apache::Connection—Interface to the Apache conn_rec Data Structure
- This module provides the Perl interface to the ...
B.17.5. Apache::Constants—Constants Defined in httpd.h
- Server constants (OK, DENIED, NOT_FOUND, etc.) ...
B.17.6. Apache::ExtUtils—Utilities for Apache C/Perl Glue
- Supplied with the mod_perl distribution. See the module manpage for more ...
B.17.7. Apache::File—Advanced Functions for Manipulating Files on the Server Side
- Apache::File does two things. First, it provides an ...
B.17.8. Apache::Log—Interface to Apache Logging
- The Apache::Log module provides an interface to ...
B.17.9. Apache::LogFile—Interface to Apache's Logging Routines
- The PerlLogFile directive from this package can be ...
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....
B.17.11. Apache::Server—Perl Interface to the Apache server_rec Struct
- The Apache::Server class contains information about ...
B.17.12. Apache::Table—Perl Interface to the Apache Table Struct
- This module provides tied interfaces to Apache data structures. By using it ...
B.17.13. Apache::URI—URI Component Parsing and Unparsing
- This module provides an interface to the Apache util_uri<...
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 ...
B.18.1. Apache::Session—Maintain Session State Across HTTP Requests
- This module provides mod_perl with a ...
B.18.2. Apache::RequestNotes—Easy, Consistent Access to Cookie and Form Data Across Each Request Phase
- Apache::RequestNotes provides a simple interface ...
B.18.3. Apache::Cookie—HTTP Cookies Class
- The Apache::Cookie module is a Perl interface to the ...
B.18.4. Apache::Icon—Look Up Icon Images
- This module rips out the icon guts of mod_autoindex and provides a Perl ...
B.18.5. Apache::Include—Utilities for mod_perl/mod_include Integration
- The Apache::Include module provides a handler, ...
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 ...
B.18.7. Apache::Mmap—Perl Interface to the mmap(2) System Call
- The Apache::Mmap module lets you use ...
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, ...
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 ...
B.18.10. Apache::ParseLog—Object-Oriented Perl Extension for Parsing Apache Log Files
- Apache::ParseLog provides an easy way to parse the ...
B.18.11. Apache::RegistryLoader—Compile Apache::Registry Scripts at Server Startup
- Covered in Chapter 13. Supplied with the ...
B.18.12. Apache::SIG—Override Apache Signal Handlers with Perl's Signal Handlers
- Covered in Chapter 6. Supplied with the ...
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 ...
B.18.14. Xmms—Perl Interface to the xmms Media Player
- A collection of Perl interfaces for the xmms media player. Includes a ...
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. ...
Appendix C. ISPs Providing mod_perl Services
- Contents: Users Sharing a Single Web ...
C.1. Users Sharing a Single Web Server
- An ISP cannot let users run their code under mod_perl on the main server. There ...
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' ...
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 ...
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 ...
Appendix D. The Template Toolkit
- Contents: Fetching and Installing the Template ...
D.1. Fetching and Installing the Template Toolkit
- You can fetch the Template Toolkit ...
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 ...
D.4.1. Simple Template Example
- So without further ado, let's see what a typical template looks like:
D.5. Processing Templates
- In addition to the ttree script mentioned earlier, tpage is ...
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 ...
D.7. Apache::Template Module
- If you're not looking to do anything too ...
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 ...
D.8.1. Hangman CGI Script
- The first implementation shows a simple all-in-one CGI script that gets the ...
D.8.2. Hangman with Modular Templates
- Perhaps the biggest limitation of the previous example is that the ...
D.8.3. Hangman Plug-in
- To take our example a stage further, we'...
D.8.4. Self-Contained Hangman Template
- One of the benefits of writing the hangman application as a plug-in is that ...
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 configuration files from ...
Appendix E. The AxKit XML Application Server
- Contents: Installing and Configuring AxKit ...
E.1. Installing and Configuring AxKit
- There are many configuration ...
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 ...
E.2.1. If Something Goes Wrong
- If you don't see HTML in your browser but instead get the source XML, you will ...
E.2.2. How it Works?
- The stylesheet above specifies how the various tags work. The ASP ...
E.2.3. XPath
- One of the key specifications being used in XML technologies is XPath. This is ...
E.3. Dynamic Content
- AxKit has a flexible tool called eXtensible Server Pages (XSP) for creating ...
E.3.1. Handling Form Parameters
- The AxKit::XSP::Param taglib allows ...
E.3.2. Handling Cookies
- AxKit::XSP::Cookie is a ...
E.3.3. Sending Email
- With the AxKit::XSP::Sendmail taglib, it is very ...
E.3.4. Handling Exceptions
- The exception taglib, AxKit::XSP::Exception, ...
E.3.5. Utilities Taglib
- The AxKit::XSP::Util taglib ...
E.3.6. Executing SQL
- Perhaps the most interesting taglib of ...
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 XSLT, which has special modes for ...
E.4.1. The XPathScript API
- Along with the code delimiters, XPathScript provides stylesheet developers with a full API for accessing and ...
E.4.1.1. Extracting values
- A simple example to get us started is to use the API to bring in the title ...
E.4.1.2. Declarative templates
- We saw declarative templates earlier in ...
E.5. XSLT
- One of the most important technologies to come out of the W3C is eXtensible Stylesheet Language Transformations (XSLT). ...
E.5.1. Anatomy of an XSLT Stylesheet
- All XSLT stylesheets contain the ...
E.5.2. Template Rules and Recursion
- Let's take our basic stylesheet and ...
E.5.3. Learning More
- We have only scratched the surface of how XSLT can be used ...
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 introduced using processing instructions for ...
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: ...
Appendix F. HTTP Status Codes
- Contents: HTTP/1.0 Status Codes HTTP/1.1 Status Codes<...
F.1. HTTP/1.0 Status Codes
- Successful 2xx: 200 HTTP_OK 201 HTTP_CREATED 202 HTTP_ACCEPTED 204 ...
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 ...
Colophon
- Our look is the result of reader
comments, our own experimentation, and feedback from distribution
channels. Distinctive covers complement our distinctive approach
to technical topics, breathing personality and life into
potentially dry subjects...
Index: Symbols & Numbers
- Book Index: 0
Index: A
- Book Index: A
Index: B
- Book Index: B
Index: C
- Book Index: C
Index: D
- Book Index: D
Index: E
- Book Index: E
Index: F
- Book Index: F
Index: G
- Book Index: G
Index: H
- Book Index: H
Index: I
- Book Index: I
Index: J
- Book Index: J
Index: K
- Book Index: K
Index: L
- Book Index: L
Index: M
- Book Index: M
Index: N
- Book Index: N
Index: O
- Book Index: O
Index: P
- Book Index: P
Index: Q
- Book Index: Q
Index: R
- Book Index: R
Index: S
- Book Index: S
Index: T
- Book Index: T
Index: U
- Book Index: U
Index: V
- Book Index: V
Index: W
- Book Index: W
Index: X
- Book Index: X
Index: Y
- Book Index: Y
Index: Z
- Book Index: Z
HTML version tarball: practical-mod_perl-html.tar.gz.