mod_perl Guide

Table of Contents:

• Introduction. Incentives. Credits.
• What is mod_perl
  • mod_cgi
  • C API
  • Perl API
  • Apache::Registry
  • Apache::PerlRun
• What will you learn
• High-Profile Sites Running mod_perl
• References and Acknowledgments
• Guide's Overview
• What's inside?
• Perl Reference
• A Must Read!
• perldoc's Rarely Known But Very Useful Options
• Tracing Warnings Reports
• Variables Globally, Lexically Scoped And Fully Qualified
  • Additional reading references
• my() Scoped Variable in Nested Subroutines
  • The Poison
  • The Diagnosis
  • The Remedy
• When You Cannot Get Rid of The Inner Subroutine
  • Remedies for Inner Subroutines
• use(), require(), do(), %INC and @INC Explained
  • The @INC array
  • The %INC hash
  • Modules, Libraries and Files
  • require()
  • use()
  • do()
• Using Global Variables and Sharing Them Between Modules/Packages
  • Making Variables Global
  • Making Variables Global With strict Pragma On
  • Using Exporter.pm to Share Global Variables
  • Using the Perl Aliasing Feature to Share Global Variables
• The Scope of the Special Perl Variables
• Compiled Regular Expressions
• CGI to mod_perl Porting. mod_perl Coding guidelines.
• Document Coverage
• Before you start to code
• Exposing Apache::Registry secrets
  • The First Mystery
  • The Second Mystery
• Sometimes it Works, Sometimes it Doesn't
  • An Easy Break-in
  • Thinking mod_cgi
  • Regular Expression Memory
• Script's name space
• @INC and mod_perl
• Reloading Modules and Required Files
  • Restarting the server
  • Using Apache::StatINC for the Development Process
  • Configuration Files: Writing, Dynamically Updating and Reloading
    • Writing Configuration Files
    • Reloading Configuration Files
    • Dynamically updating configuration files
  • Reloading handlers
• Name collisions with Modules and libs
• More package name related issues
• __END__ and __DATA__ tokens
• Output from system calls
• Using format() and write()
• Terminating requests and processes, the exit() and child_terminate() functions
• die() and mod_perl
• Testing the Code from the Shell
• I/O is different
• STDIN, STDOUT and STDERR streams
• Global Variables Persistance
• Generating correct HTTP Headers
• NPH (Non Parsed Headers) scripts
• BEGIN blocks
• END blocks
• Command line Switches (-w, -T, etc)
  • Warnings
  • Taint Mode
  • Other switches
• The strict pragma
• Passing ENV variables to CGI
• -M and other time() file tests under mod_perl
• Apache and syslog
• Filehandlers and locks leakages
• Code has been changed, but it seems the script is running the old code
• The Script Is Too Dirty, But It Does The Job And I Cannot Afford To Rewrite It.
• Apache::PerlRun--a closer look
• Sharing variables between processes
• Performance. Benchmarks.
• Performance: The Big Picture
• Analysis of Software and Hardware Requirements
• Sharing Memory
• How Shared Is My Memory?
• Calculating Real Memory Usage
• Is my Code Shared?
• Preload Perl Modules at Server Startup
  • Preload Perl modules - Real Numbers
• Preload Registry Scripts
• Global vs Fully Qualified Variables
• Avoid Importing Functions
• PerlSetupEnv Off
• Proxying the mod_perl Server
• Caching Components with HTML::Mason
• KeepAlive
• Upload/Download of Big Files
• Forking and Executing Subprocesses from mod_perl
• Memory leakage
  • Reading In A Whole File
  • Copying Variables Between Functions
  • Work With Databases
• -DTWO_POT_OPTIMIZE and -DPACK_MALLOC Perl Options
• Checking script modification times
• Cached stat() calls
• Be carefull with symbolic links
• Limiting the Size of the Processes
• Limiting the Resources Used by httpd Children
• Limiting the Request Rate Speed (Robot Blocking)
• Benchmarks. Impressing Your Boss and Your Colleagues.
  • Developers Talk
  • Benchmarking a Graphic Hits Counter with Persistent DB Connections
  • Benchmarking Scripts with Execution Times Below 1 Second
  • Benchmarking PerlHandler
• Tuning Apache's Configuration Variables for the Best Performance
  • Tuning with ab - ApacheBench
  • Tuning with httperf
  • Tuning with the crashme Script
  • Choosing MaxClients
  • Choosing MaxRequestsPerChild
  • Choosing MinSpareServers, MaxSpareServers and StartServers
  • Summary of Benchmarking to tune all 5 parameters
• Persistent DB Connections
  • Preopening Connections at the Child Process' Fork Time
  • Caching prepare() Statements
  • Handling Timeouts
• Jeff's guide to mod_perl database performance
  • Analysis of the Problem
  • Optimizing Database Connections
  • Utilizing the Database Server's Cache
  • Eliminating SQL Statement Parsing
  • Conclusion
• Using $|=1 Under mod_perl and Better print() Techniques.
• More Reducing Memory Usage Tips
• Measuring the Subroutines Memory Usage
• Memory Swapping is Considered Bad
• Code Profiling
• Reducing the Number of stat() Calls
• Object Methods Calls Versus Function Calls
  • The Overhead with Light Subroutines
  • The Overhead with Heavy Subroutines
  • Are All Methods Slower than Functions?
• Imported Symbols and Memory Usage
• Sending Plain HTML as Compressed Output
• Increasing Shared Memory With mergemem
• mod_perl Installation
• Installing mod_perl in 10 Minutes and 10 Command Lines
• The Gory Details
  • Sources Configuration (perl Makefile.PL ...)
    • Configuration parameters
      • APACHE_SRC
      • DO_HTTPD, NO_HTTPD, PREP_HTTPD
      • Callback Hooks
      • EVERYTHING
      • PERL_TRACE
      • APACHE_HEADER_INSTALL
      • PERL_STATIC_EXTS
      • PERL_MARK_WHERE
      • APACI_ARGS
      • APACHE_PREFIX
    • Reusing Configuration Parameters
    • Discovering whether some option was configured
    • Using an Alternative Configuration File
    • perl Makefile.PL Troubleshooting
      • "A test compilation with your Makefile configuration failed..."
      • Missing or Misconfigured libgdbm.so
      • Undefined reference to `PL_perl_destruct_level'
  • mod_perl Building (make)
    • make Troubleshooting
      • Undefined reference to 'Perl_newAV'
      • Unrecognized format specifier for...
  • Built Server Testing (make test)
    • Manual Testing
    • make test Troubleshooting
      • make test fails
      • mod_perl.c is incompatible with this version of Apache
      • make test......skipping test on this platform
      • make test Fails Due to Misconfigured localhost Entry
  • Installation (make install)
  • Building Apache and mod_perl by Hand
• Installation Scenarios for Standalone mod_perl
  • The All-In-One Way
  • The Flexible Way
  • Build mod_perl as a DSO inside the Apache Source Tree via APACI
    • libperl.so and libperl.a
  • Build mod_perl as a DSO outside the Apache Source Tree via APXS
• Installation Scenarios for mod_perl and Other Components
  • mod_perl and mod_ssl (+openssl)
  • mod_perl and mod_ssl Rolled from RPMs
  • mod_perl and apache-ssl (+openssl)
  • mod_perl and Stronghold
    • Note For Solaris 2.5 users
• mod_perl Installation with the CPAN.pm Interactive Shell
• Installing on multiple machines
• using RPM, DEB and other packages to install mod_perl
  • Static debian package
  • A word on mod_perl RPM packages
  • Getting Started
  • Compiling RPM source files
  • Mix and Match RPM and source
  • Installing a single apache+mod_perl RPM
  • Compiling libapreq (Apache::Request) with the RH 6.0 mod_perl RPM
  • Installing separate Apache and mod_perl RPMs
  • Testing the mod_perl API
• Installation Without Superuser Privileges
  • Installing Perl Modules into a Directory of Choice
  • Making Your Scripts Find the Locally Installed Modules
  • The CPAN.pm Shell and Locally Installed Modules
  • Making a Local Apache Installation
  • Local mod_perl Enabled Apache Installation
    • Resource Usage
  • Local mod_perl Enabled Apache Installation with CPAN.pm
• Automating installation
• How can I tell whether mod_perl is running?
  • Checking the error_log
  • Testing by viewing /perl-status
  • Testing via telnet
  • Testing via a CGI script
  • Testing via lwp-request
• General Notes
  • Should I Rebuild mod_perl if I have Upgraded Perl?
  • Perl installation requirements
  • mod_auth_dbm nuances
  • Stripping Apache to make it almost a Perl-server
  • Saving the config.status Files with mod_perl, php, ssl and Other Components
  • What Compiler Should Be Used to Build mod_perl?
• OS Related Notes
• mod_perl Configuration
• Server Configuration
• Apache Configuration
  • Configuration Directives
  • <Directory>, <Location> and <Files>
  • How Directory, Location and Files Sections are Merged
  • Sub-Grouping of <Location>, <Directory> and <Files> Sections
  • Options Values Merging
• mod_perl Configuration
  • Alias Configurations
  • <Location> Configuration
  • PerlModule and PerlRequire Directives
  • Perl*Handlers
  • Stacked Handlers
  • Perl Method Handlers
  • PerlFreshRestart
  • PerlSetVar, PerlSetEnv and PerlPassEnv
  • PerlSetupEnv
  • PerlWarn and PerlTaintCheck
  • MinSpareServers MaxSpareServers StartServers MaxClients MaxRequestsPerChild
• Start-up File
  • The Sample Start-up File
  • What Modules Should You Add to the Start-up File and Why
  • The Confusion with use() at the Server Start-up File
  • The Confusion with Global Variables in Start-up File
• <Perl>...</Perl> Sections
  • Usage
  • Enabling
  • Verifying
  • Debugging
• Validating the Configuration Syntax
• Enabling Remote Server Configuration Reports
• Publishing Port Numbers Different from 80
• Configuring Apache + mod_perl with mod_macro
• General Pitfalls
  • My CGI/Perl Code Gets Returned as a Plain Text Instead of Being Executed by the Webserver
  • My Script Works under mod_cgi, but when Called via mod_perl I Get a 'Save-As' Prompt
  • Is There a Way to Provide a Different startup.pl File for Each Individual Virtual Host
  • Is There a Way to Modify @INC on a Per-Virtual-Host or Per-Location Basis.
  • A Script From One Virtual Host Calls a Script with the Same Path From the Other Virtual Host
  • the Server no Longer Retrieves the DirectoryIndex Files for a Directory
• Configuration Security Concerns
• Apache Restarts Twice On Start
• Knowing the proxy_pass'ed Connection Type
• Choosing the Right Strategy
• Do it like I do it!?
• mod_perl Deployment Overview
• Alternative architectures for running one and two servers
  • Standalone mod_perl Enabled Apache Server
  • One Plain Apache and One mod_perl-enabled Apache Servers
  • One light non-Apache and One mod_perl enabled Apache Servers
• Adding a Proxy Server in http Accelerator Mode
• Implementations of Proxy Servers
  • The Squid Server
  • Apache's mod_proxy
• When One Machine is not Enough for SQL DB and mod_perl
  • Servers' Requirements
  • The Problem
  • The Solution
    • Pros
    • Cons
  • Three Machines Model
• Real World Scenarios
• Standalone mod_perl Enabled Apache Server
  • Installation in 10 lines
  • Installation in 10 paragraphs
  • Configuration
• One Plain and One mod_perl enabled Apache Servers
  • Configuration and Compilation of the Sources.
    • Building the httpd_docs Server
    • Building the httpd_perl Server
  • Configuration of the servers
    • Basic httpd_docs Server Configuration
    • Basic httpd_perl Server Configuration
• Running Two webservers and Squid in httpd Accelerator Mode
• Running One Webserver and Squid in httpd Accelerator Mode
• One Light and One Heavy Server where All HTML is Perl-generated
  • Installation and Configuration
  • Tricks, Traps and Gotchas
• mod_proxy
  • Concepts and Configuration Directives
    • ProxyPass
    • ProxyPassReverse
  • Buffering Feature
    • Setting the Buffering Limits on Various OSes
      • IOBUFSIZE Source Code Definition
      • ProxyReceiveBufferSize Configuration Directive
      • Hacking the Code
  • Caching
  • Building process
• mod_proxy_add_forward and X-Forwarded-For header
• HTTP Authentication With Two Servers Plus a Proxy
• mod_rewrite Examples
• Frequent mod_perl problems
• Coverage
• my() scoped variable in nested subroutines
• Segfaults caused by PerlFreshRestart
• Problems with DSO
• Controlling and Monitoring the Server
• Restarting techniques
• Implications of sending TERM, HUP, and USR1 to the server
• Using apachectl to control the server
• Safe Code Updates on a Live Production Server
• An Intentional Disabling of Live Scripts
• SUID Start-up Scripts
• Preparing for Machine Reboot
• Monitoring the Server. A watchdog.
• Running a Server in Single Process Mode
• Starting a Personal Server for Each Developer
• Wrapper to Emulate the Server Environment
• Log Rotation
• Preventing mod_perl Processes From Going Wild
• Things obvious to others, but not to you
• Coverage
• Where do the warnings/errors go?
• Setting environment variables for scripts called from CGI.
• Warnings and Errors Troubleshooting Index
• General Advice
• Building and Installation
• Configuration and Startup
  • libexec/libperl.so: open failed: No such file or directory
  • Invalid command 'PerlHandler'...
  • RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl
  • "Apache.pm failed to load!"
• Code Parsing and Compilation
  • Value of $x will not stay shared at - line 5
  • Value of $x may be unavailable at - line 5.
  • Can't locate loadable object for module XXX
  • Can't locate object method "get_handlers"...
  • Missing right bracket at line ...
  • Can't load '.../auto/DBI/DBI.so' for module DBI
• Runtime
  • Incorrect line number reporting in error/warn log messages
  • rwrite returned -1
  • caught SIGPIPE in process
  • Client hit STOP or Netscape bit it!
  • Global symbol "$foo" requires explicit package name
  • Use of uninitialized value at (eval 80) line 12.
  • Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at
  • Callback called exit
  • Out of memory!
  • server reached MaxClients setting, consider raising the MaxClients setting
  • syntax error at /dev/null line 1, near "line arguments:"
  • Can't call method "register_cleanup" (CGI.pm)
• Shutdown and Restart
  • Evil things might happen when using PerlFreshRestart
  • Constant subroutine XXX redefined
  • Can't undef active subroutine
  • [warn] child process 30388 did not exit, sending another SIGHUP
• Windows OS specific notes
  • Apache::DBI
• Correct Headers - A quick guide for mod_perl users
• SYNOPSIS
• The origin of this chapter
• DESCRIPTION
• 1) Why headers
• 2) Which Headers
  • 2.1) Date related headers
  • 2.1.1) Date
  • 2.1.2) Last-Modified
  • 2.1.3) Expires and Cache-Control
  • 2.2) Content related headers
  • 2.2.1) Content-Type
  • 2.2.2) Content-Length
  • 2.2.3) Entity Tags
  • 2.3) Content Negotiation
  • 2.3.1) Vary
• 3) Requests
  • 3.1) HEAD
  • 3.2) POST
  • 3.3) GET
  • 3.4) Conditional GET
  • 3.) Avoiding to deal with them
• References and other literature
  • [1]
  • [2]
  • [3]
  • [4]
  • [5]
• VERSION
• AUTHOR
• Protecting Your Site
• The Importance of Your site's Security
• Illustrated Security Scenarios
  • Non authenticated access for internal IPs, Authenticated for external IPs
• Authentication code snippets
  • Forcing re-authentication
  • OK, AUTH_REQUIRED and FORBIDDEN in Authentication handlers
• mod_perl and Relational Databases
• Why Relational (SQL) Databases
• Apache::DBI - Initiate a persistent database connection
  • Introduction
  • Configuration
  • Preopening DBI connections
  • Debugging Apache::DBI
  • Troubleshooting
    • The Morning Bug
    • Opening connections with different parameters
    • Cannot find the DBI handler
    • Apache:DBI does not work
    • Skipping connection cache during server startup
    • Debugging code which deploys DBI
• mysql_use_result vs. mysql_store_result.
• Optimize: Run Two SQL Engine Servers
• Some useful code snippets to be used with relational Databases
  • Turning SQL query writing into a short and simple task
  • The My::DB module
  • My::DB Module's Usage Examples
• mod_perl and dbm files
• Where and Why to use dbm files
• mod_perl and dbm
• Locking dbm handlers
• Flawed Locking Methods Which Must Not Be Used
• Lock Wrappers Overview
• Tie::DB_Lock
• DB_File::Lock2
• mod_perl for ISPs. mod_perl and Virtual Hosts.
• ISPs providing mod_perl services - a fantasy or reality.
• Virtual Hosts in the guide
• Debugging mod_perl
• Curing The "Internal Server Error"
• Helping error_log to Help Us
• The Importance of Warnings
  • diagnostics pragma
• Monitoring the error_log file
• Hanging processes: Detection and Diagnostics
  • An Example of the Code that Might Hang the Process
  • Detecting hanging processes
  • Determination of the reason
• Handling the 'User pressed Stop button' case
  • Detecting Aborted Connections
  • The Importance of Cleanup Code
    • Critical Section
    • Safe Resource Locking
    • Cleanup Code
• Handling the server timeout cases and working with $SIG{ALRM}
• Looking inside the server
  • Apache::Status -- Embedded interpreter status information
    • Minimal Configuration
    • Extended Configuration
    • Usage
    • Compiled Registry Scripts section seems to be empty.
  • mod_status
  • Apache::VMonitor -- Visual System and Apache Server Monitor
    • Configuration
• Sometimes script works, sometimes does not
• Code Debug
  • Locating and correcting Syntax Errors
  • Using Apache::FakeRequest to Debug Apache Perl Modules
  • Finding the Line Number the Error/Warning has been Triggered at
  • Using print() Function for Debugging
  • Using print() and Data::Dumper for Debugging
  • The Importance of Good Coding Style and Conciseness
  • Introduction into Perl Debugger
  • Interactive Perl Debugging under mod_cgi
  • Non-Interactive Perl Debugging under mod_perl
  • Interactive mod_perl Debugging
  • ptkdb and Interactive mod_perl Debugging
  • Debugging when Server Crashes on Startup before Writing to Log File.
• Debugging Hanging processes (continued)
  • Debugging core Dumping Code
• PERL_DESTRUCT_LEVEL Environment Variable
• PERL_DEBUG=1 Build Option
• Apache::Debug
• Debug Tracing
• gdb says there are no debugging symbols
• Debugging Signal Handlers ($SIG{FOO})
• Code Profiling
• Devel::Peek
• How can I find if my mod_perl scripts have memory leaks
• Debugging your code in Single Server Mode
• Workarounds for some known bugs in browsers.
• Preventing QUERY_STRING from getting corrupted because of &entity key names.
• IE 4.x does not re-post data to a non-port-80 URL
• Apache::* modules
• Apache::Session - Maintain session state across HTTP requests
• Apache::DBI - Initiate a persistent database connection
• Apache::Watchdog::RunAway - Hanging Processes Monitor and Terminator
• Apache::VMonitor - Visual System and Apache Server Monitor
• Apache::GTopLimit - Limit Apache httpd processes
• Apache::Request (libapreq) - Generic Apache Request Library
• Apache::PerlRun - Run unaltered CGI scripts under mod_perl
• Apache::RegistryNG -- Apache::Registry New Generation
• Apache::RegistryBB -- Apache::Registry Bare Bones
• Apache::GzipChain - compress HTML (or anything) in the OutputChain
• Apache::PerlVINC - set a different @INC perl-location
• Apache::LogSTDERR
• Apache::RedirectLogFix
• Apache::SubProcess
• Code Snippets
• Redirecting Errors to the Client Instead of error_log
• Emulating the Authentication Mechanism
• Caching the POSTed Data
• Cache Control for Regular and Error Modes
• Redirect a POST Request, Forwarding the Content
• Reading POST Data, then Redirecting or Doing Something Else
• Redirecting While Maintaining Environment Variables
• Terminating a Child Process on Request Completion
• More on Relative Paths
• Watching the error_log File Without Telneting to the Server
• Accessing Variables from the Caller's Package
• Handling Cookies
• Sending Multiple Cookies with Perl API
• Passing and Preserving Custom Data Structures Between Handlers
• Passing Notes Between mod_perl and other (non-perl) Apache Modules
• Passing Environment Variables Between Handlers
• CGI::params in the mod_perl-ish Way
• Subclassing Apache::Request Example
• Sending Email from mod_perl
• Code Unloading
• A Simple Handler To Print The Environment Variables
• mod_rewrite Based On Query String and URI Implemented in Perl
• Setting PerlHandler Based on MIME Type
• Using DESTROY to Finalize Output
• Mysql Backup and Restore Scripts
• Choosing an Operating System and Hardware
• Is it important?
• Choosing an Operating System
  • Stability and Robustness
  • Memory Management
  • Memory Leakages
  • Sharing Memory
  • Cost and Support
  • Discontinued products
  • OS Releases
• Choosing Hardware
  • Expected site traffic
  • Cash
  • Internet Connection
  • I/O performance
  • Memory
  • Bottlenecks
  • Conclusion
• mod_perl Advocacy
• Thoughts about scalability and flexibility
• The boss, the developer and advocacy
• A summary of perl/cgi discussion at slashdot.org
• Getting Help and Further Learning
• READ ME FIRST
• Contacting me
• Get help with mod_perl
• Get help with Perl
• Get help with Perl/CGI
• Get help with Apache
• Get help with DBI
• Get help with Squid - Internet Object Cache
• Appendix A: Downloading software and documentation
• Coverage
• Perl
• Apache
• mod_perl
• Squid - Internet Object Cache
• thttpd - tiny/turbo/throttling HTTP server
• mod_proxy_add_forward
• httperf - webserver Benchmarking tool
• ab - ApacheBench
• High-Availability Linux Project
• Apache::Request
• DataBases

• CHANGES
• Download
  • All the HTML files, POD sources and build scripts are available from my directory at CPAN or its mirrors.

The Writing Apache Modules with Perl and C book can be purchased online from O'Reilly and Amazon.com.

Master Copy URL: http://perl.apache.org/guide Copyright © 1998-2000 Stas Bekman. All rights reserved.
Written by Stas Bekman. Last Modified at 04/09/2000		Use of the Camel for Perl is a trademark of O'Reilly & Associates, and is used by permission.