mod_perl Guide

Table of Contents:

• Introduction. Incentives. Credits.
• What is mod_perl
• What is covered in this document
• References and Acknowledgments
• Guide's Overview
• What's inside?
• Picking the Right Strategy
• Do it like me?!
• mod_perl Deploying Schemas Overview
• Stand alone mod_perl Enabled Apache Server
• One Plain 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
• squid server
• apache's mod_proxy
• Real World Scenarios of Implementing Various Strategies
• Before you dive into the gory details
• 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 (mod_perl):
  • Configuration of the servers
    • Basic httpd_docs Server's Configuration
    • Basic httpd_perl Server's Configuration
• Running 2 webservers and squid in httpd accelerator mode
• Running 1 webserver and squid in httpd accelerator mode
• Using mod_proxy
• mod_perl server as DSO
• Installation Notes
• Configuration and Installation
  • Perl
  • Apache
  • Mod_Perl
• How can I tell whether mod_perl is really installed
  • Testing by checking the error_log file
  • Testing by viewing /perl-status
  • Testing via telnet
  • Testing via a CGI script
  • Testing via lwp-request
• Is it possible to install and use apache/mod_perl without having a root access?
• Is it possible to determine which options were given to modperl's Makefile.PL
• Server Installation
  • make test fails
• Server Configuration
• mod_perl Specific Configuration
  • Alias Configurations
  • Location Configuration
  • PerlFreshRestart
  • /perl-status location
  • perl-startup file
    • Sample perl-startup file
    • What modules should you add to the startup file and why.
    • Is it possible to preopen a DB connection at the server startup?
• Perl behavior controls
• Tuning MinSpareServers MaxSpareServers StartServers MaxClients
• Publishing port numbers different from 80
• Perl Sections
• Configuring Apache + mod_perl with mod_macro
• General pitfalls
  • My cgi/perl code is being returned as a plain text instead of being executed by the webserver?
  • My script works under cgi-bin, but when called via mod_perl I see 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 basis.
  • Sometimes the script from one virtual host calls a script with
  • the server no longer retrieves the DirectoryIndex files for a directory
• Frequent mod_perl problems
• Coverage
• my() scoped variable in nested subroutines
• Segfaults caused by PerlFreshRestart
• CGI to mod_perl Porting. mod_perl Coding guidelines.
• Document Coverage
• Before you start to code
• Coding with mod_perl
  • What's different about modperl
    • Script's name space
    • Name collisions with Modules and libs
    • __END__ or __DATA__ tokens
    • Output from system calls
    • Using format()
    • Using exit()
    • Running from shell
    • I/O is different
    • HTTP + MIME Headers (PerlSendHeader)
    • NPH (Non Parsed Headers) scripts
    • BEGIN blocks
    • END blocks
    • Switches -w, -T
  • strict pragma
  • Turning warnings ON
  • diagnostics pragma
  • Global Variables
  • Code has been changed, but it seems the script is running the old code
  • Memory leakage
• Filehandlers and locks leakages
  • Sometimes it Works Sometimes Not (Very important!)
  • The Script is too dirty, It does the job and I can't afford rewriting it.
  • Apache::PerlRun - a closer look
• Redirecting Errors to Client instead of error_log
• Finding the line number the error/warning has been triggered at
• Forking subprocesses from mod_perl
• Performance. Benchmarks.
• Preload Perl modules at server startup
  • Preload Perl modules - Real Numbers
• Preopen DB connection at server startup
• Memory sharing
• Preload Registry Scripts
• Avoid Importing Functions
• Reducing the Memory Usage
• how can I find if my modperl scripts have memory leaks (and where)
• Limiting the size of the processes
• Limiting the resources used by httpd children
• Limiting the request rate speed (robots blocking)
• Benchmarks. Impressing your Boss and Colleagues.
  • Developers Talk
  • Benchmarking a Graphic hits counter with Persistent DB Connection
  • Benchmarking scripts with execution times below 1 second :)
  • PerlHandler's Benchmarking
• Tuning the Apache's configuration variables for the best performance
  • Tuning with ab - ApacheBench
  • Tuning with crashme script
  • Choosing MaxClients
  • Choosing MaxRequestsPerChild
  • Choosing MinSpareServers, MaxSpareServers and StartServers
  • Summary of Benchmarking to tune all 5 parameters
• Persistent DB Connections
• Using $|=1 under mod_perl and better print() techniques.
• Profiling
• CGI.pm's object methods calls vs. function calls
• Things obvious to others, but not to you
• Coverage
• my() scoped variable in nested subroutines
  • The poison
  • The diagnosis
  • The remedy
• Reloading Modules and Required Files
  • Restarting the server
  • Using Apache::StatINC
  • Reloading only specific files
• Compiled Regular Expressions
• Debugging your code in Single Server Mode
• -M and other time() file tests under mod_perl
• Handling the 'User pressed Stop button' case
• Handling the server timeout cases
• Where do the warnings/errors go?
• Setting environment variables for scripts called from CGI.
• Warnings and Errors: Where and Why.
• General Advice
• Incorrect line number reporting in error/warn log messages
• Value of $x will not stay shared at - line 5
• Value of $x may be unavailable at - line 5.
• mod_perl: rwrite returned -1
• caught SIGPIPE in process
• Client hit STOP or Netscape bit it!
• Constant subroutine ... redefined
• Global symbol "$foo" requires explicit package name
• Can't undef active subroutine
• Use of uninitialized value at (eval 80) line 12.
• Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at
• Can't load '.../auto/DBI/DBI.so' for module DBI
• Callback called exit
• Out of memory!
• [warn] child process 30388 did not exit, sending another SIGHUP
• RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl
• Evil things might happen when using PerlFreshRestart
• server reached MaxClients setting, consider raising the MaxClients setting
• mod_perl and Relational Databases
• Why Relational (SQL) Databases
• Apache::DBI - Initiate a persistent database connection
  • Introduction
  • Configuration
  • Preopening DBI connections
  • Debugging Apache::DBI
  • Problems and solutions
    • The morning bug
    • Cannot find the DBI handler
    • Apache:DBI does not work
  • Some useful code snippets to be used with relational Databases
    • Turning the SQL queries writing into an short and simple task
    • 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
• Tie::DB_Lock
• Code snippets
• mod_perl for ISPs. mod_perl and Virtual Hosts.
• ISPs providing mod_perl services - a fantasy or reality.
• Virtual Hosts in the guide
• Controlling and Monitoring the Server
• Restarting techniques
• Implications of sending TERM, HUP, and USR1 to the server
• Using apachectl to control the server
• SUID start-up scripts
• Monitoring the Server. A watchdog.
• Running server in a single mode
• Starting a personal server for each developer
• Wrapper to emulate the server environment
• Log Rotation
• Preventing from modperl process to eat up all the disk's space, when it goes wild.
• mod_perl Status. Peeking into the Server's Perl Innards
• Watching the server
  • Configuration
  • Usage
  • Compiled Registry Scripts section seems to be empty.
• Debugging mod_perl
• Sometimes script works, Sometimes Not
• Apache::DB - Run the interactive Perl debugger under mod_perl
• Debug Tracing
• Getting some decent debug info when running under mod_perl
• gdb says there are no debugging symbols
• Workarounds for some known bugs in browsers.
• Preventing QUERY_STRING to get corrupted with &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::Request (libapreq) - Generic Apache Request Library
• Apache::PerlRun - Run unaltered CGI scripts under mod_perl
• Perl Reference
• Coverage
• Using global variables and sharing them between modules/packages
  • Making the variables global
  • Making the variables global with strict pragma On
  • Using Exporter.pm to share global variables
  • Using aliasing perl feature to share global variables
• Code Snippets
• Sending MIME headers
• How to avoid printing the header more than once.
• More on relative paths
• Watching the error_log file without telneting to the server.
• Accessing variables from the caller's package
• Handling cookies
• Getting Helped and Further Learning
• READ ME FIRST
• This document's Author
• Get helped with mod_perl
• Get helped with Perl
• Get helped with Perl/CGI
• Get helped with Apache
• Get helped with DBI
• Appendix A: Downloading software and documentation
• Coverage
• perl
• apache
• mod_perl
• Squid
• thttpd
• mod_proxy_add_forward

• Guide All in One. Ready for Printing
• CHANGES
• Search perl.apache.org along with this guide
• Download all files guide.tar.gz or sources and build scripts guide-src.tar.gz

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

Written by Stas Bekman. Last Modified at 05/08/1999		Use of the Camel for Perl is a trademark of O'Reilly & Associates, and is used by permission.