book

Practical mod_perl

by Stas Bekman, Eric Cholet

May 2003

Intermediate to advanced

924 pages

26h 21m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Practical mod_perl
Preface
What You Need to KnowWho This Book Is ForHow This Book Is OrganizedReference SectionsFilesystem ConventionsApache and Perl VersionsTypographic ConventionsCommand Interpreter Program (Shell) ConventionsInstalling Perl ModulesManual InstallationPrerequisites Needed to Install Perl Modules on WindowsBuilding a Perl ModuleUsing the CPAN ShellUsing the Perl Package ManagerHow to Contact UsAcknowledgments
I. mod_perl Administration
1. Introducing CGI and mod_perl
1.1. A Brief History of CGI1.1.1. The HTTP Protocol1.1.2. The Common Gateway Interface Specification1.1.3. Apache CGI Handling with mod_cgi1.2. The Apache 1.3 Server Model1.2.1. Forking1.2.2. CGI Scripts Under the Forking Model1.2.3. Performance Drawbacks of Forking1.3. The Development of mod_perl 1.01.3.1. Running CGI Scripts with mod_perl1.4. Apache 1.3 Request Processing Phases1.4.1. Apache 1.3 Modules and the mod_perl 1.0 API1.4.2. mod_perl 1.0 and the mod_perl API1.5. References
2. Getting Started Fast
2.1. Installing mod_perl 1.0 in Three Steps2.2. Installing mod_perl on Unix Platforms2.2.1. Obtaining and Unpacking the Source Code2.2.2. Building mod_perl2.2.3. Installing mod_perl2.3. Configuring and Starting the mod_perl Server2.4. Installing mod_perl for Windows2.4.1. Installing mod_perl with the Perl Package Manager2.5. Preparing the Scripts Directory2.6. A Sample Apache::Registry Script2.6.1. Porting Existing CGI Scripts to mod_perl2.7. A Simple mod_perl Content Handler2.8. Is This All We Need to Know About mod_perl?2.9. References
3. Installing mod_perl
3.1. Configuring the Source3.1.1. Controlling the Build Process3.1.2. Activating Callback Hooks3.1.3. Activating Standard API Features3.1.4. Enabling Extra Features3.1.5. Reusing Configuration Parameters3.1.6. Discovering Whether a Feature Was Enabled3.1.7. Using an Alternative Configuration File3.1.8. perl Makefile.PL Troubleshooting3.1.8.1. A test compilation with your Makefile configuration failed...3.1.8.2. Missing or misconfigured libgdbm.so3.1.8.3. Undefined reference to `PL_perl_destruct_level’3.2. Building mod_perl (make)3.2.1. What Compiler Should Be Used to Build mod_perl?3.2.2. make Troubleshooting3.2.2.1. Undefined reference to `Perl_newAV’3.2.2.2. Unrecognized format specifier for...3.3. Testing the Server (make test)3.3.1. Manual Testing3.3.2. make test Troubleshooting3.3.2.1. make test fails3.3.2.2. mod_perl.c is incompatible with this version of Apache3.3.2.3. make test......skipping test on this platform3.3.2.4. make test fails due to misconfigured localhost entry3.4. Installation (make install)3.4.1. Manually Building a mod_perl-Enabled Apache3.5. Installation Scenarios for Standalone mod_perl3.5.1. The All-in-One Way3.5.2. Building mod_perl and Apache Separately3.5.3. When DSOs Can Be Used3.5.4. Building mod_perl as a DSO via APACI3.5.5. Building mod_perl as a DSO via APXS3.6. Building mod_perl with Other Components3.6.1. Installing mod_perl with PHP3.6.2. Installing mod_perl with mod_ssl (+openssl)3.6.3. Installing mod_perl with Apache-SSL (+openssl)3.6.4. Installing mod_perl with Stronghold3.7. Installing mod_perl with the CPAN.pm Interactive Shell3.8. Installing mod_perl on Multiple Machines3.9. Installation into a Nonstandard Directory3.9.1. Installing Perl Modules into a Nonstandard Directory3.9.2. Finding Modules Installed in Nonstandard Directories3.9.2.1. Modifying @INC3.9.2.2. Using the PERL5LIB environment variable3.9.3. Using the CPAN.pm Shell with Nonstandard Installation Directories3.9.4. Making a Local Apache Installation3.9.5. Nonstandard mod_perl-Enabled Apache Installation3.9.6. Nonstandard mod_perl-Enabled Apache Installation with CPAN.pm3.10. How Can I Tell if mod_perl Is Running?3.10.1. Checking the error_log File3.10.2. Testing by Viewing /perl-status3.10.3. Testing via Telnet3.10.4. Testing via a CGI Script3.10.5. Testing via lwp-request3.11. General Notes3.11.1. How Do I Make the Installation More Secure?3.11.2. Can I Run mod_perl-Enabled Apache as suExec?3.11.3. Should I Rebuild mod_perl if I Have Upgraded Perl?3.11.4. mod_auth_dbm Nuances3.12. References
4. mod_perl Configuration
4.1. Apache Configuration4.1.1. Configuration Files4.1.2. Configuration Directives4.1.3. <Directory>, <Location>, and <Files> Sections4.1.3.1. <Directory directoryPath> ... </Directory>4.1.3.2. <Files filename > ... </Files>4.1.3.3. <Location URI> ... </Location>4.1.4. Merging <Directory>, <Location>, and <Files> Sections4.1.5. Subgrouping of <Directory>, <Location>, and <Files> Sections4.1.6. Options Directive Merging4.1.7. MinSpareServers, MaxSpareServers, StartServers, MaxClients, and MaxRequestsPerChild4.2. mod_perl Configuration4.2.1. Alias Configurations4.2.1.1. Running scripts located in the same directory under different handlers4.2.2. <Location /perl> Sections4.2.3. PerlModule and PerlRequire4.2.4. Perl*Handlers4.2.5. The handler( ) Subroutine4.2.6. Investigating the Request Phases4.2.7. Stacked Handlers4.2.8. Perl Method Handlers4.2.9. PerlFreshRestart4.2.10. PerlSetEnv and PerlPassEnv4.2.11. PerlSetVar and PerlAddVar4.2.12. PerlSetupEnv4.2.13. PerlWarn and PerlTaintCheck4.3. The Startup File4.3.1. A Sample Startup File4.3.2. Syntax Validation4.3.3. What Modules Should Be Added to the Startup File4.3.4. The Confusion with use( ) in the Server Startup File4.4. Apache Configuration in Perl4.4.1. Constructing <Perl> Sections4.4.2. Breaking Out of <Perl> Sections4.4.3. Cheating with Apache->httpd_conf4.4.4. Declaring Package Names in Perl Sections4.4.5. Verifying <Perl> Sections4.4.6. Saving the Perl Configuration4.4.7. Debugging4.5. Validating the Configuration Syntax4.6. The Scope of mod_perl Configuration Directives4.7. Apache Restarts Twice4.8. Enabling Remote Server Configuration Reports4.9. Tips and Tricks4.9.1. Publishing Port Numbers Other Than 804.9.2. Running the Same Script from Different Virtual Hosts4.10. Configuration Security Concerns4.10.1. Using Only Absolutely Necessary Components4.10.2. Taint Checking4.10.3. Hiding Server Information4.10.4. Making the mod_perl Server Inaccessible from the Outside4.10.5. Protecting Private Status Locations4.11. General Pitfalls4.12. References
5. Web Server Control, Monitoring, Upgrade, and Maintenance
5.1. Starting the Server in Multi-Process Mode5.2. Starting the Server in Single-Process Mode5.3. Using kill to Control Processes5.3.1. kill Signals for Stopping and Restarting Apache5.3.2. Speeding Up Apache’s Termination and Restart5.3.3. Finding the Right Apache PID5.4. Using apachectl to Control the Server5.5. Validating Server Configuration5.6. Setuid root Startup Scripts5.6.1. Introduction to setuid Executables5.6.2. Apache Startup Script’s setuid Security5.6.3. Sample setuid Apache Startup Script5.7. Preparing for Machine Reboot5.8. Upgrading a Live Server5.8.1. Upgrading Intranet Servers5.8.2. Upgrading 24 × 7 Internet Servers5.8.2.1. The server cluster5.8.2.2. The single server5.8.2.2.1. Upgrading live server components by swapping machines5.8.2.2.2. Upgrading a live server with port forwarding5.8.2.2.3. Upgrading a live server with prepackaged components5.8.2.2.4. Upgrading a live server using symbolic links5.8.2.2.5. Upgrading Perl code5.8.2.2.6. Moving files and restarting the server5.8.2.2.7. Using CVS for code upgrades5.8.3. Disabling Scripts and Handlers on a Live Server5.8.3.1. Disabling code running under Apache::Registry5.8.3.2. Disabling code running under other handlers5.8.3.3. Disabling services with help from the frontend server5.8.4. Scheduled Routine Maintenance5.9. Three-Tier Server Scheme: Development, Staging, and Production5.9.1. Starting a Personal Server for Each Developer5.10. Web Server Monitoring5.10.1. Interactive Monitoring5.10.2. Apache::VMonitor—The Visual System and Apache Server Monitor5.10.2.1. Prerequisites and configuration5.10.2.2. Multi-processes and system overall status reporting mode5.10.2.3. Single-process extensive reporting system5.10.3. Automated Monitoring5.10.3.1. mod_perl server watchdogs5.11. Server Maintenance Chores5.11.1. Handling Log Files5.11.1.1. Scheduled log file rotation5.11.1.2. Non-scheduled emergency log rotation5.11.1.3. Centralized logging5.11.2. Swapping Prevention5.11.3. Limiting Resources Used by Apache Child Processes5.11.3.1. OS-specific notes5.11.4. Tracking and Terminating Hanging Processes5.11.5. Limiting the Number of Processes Serving the Same Resource5.11.6. Limiting the Request-Rate Speed (Robot Blocking)5.12. References
6. Coding with mod_perl in Mind
6.1. Before You Start to Code6.1.1. Accessing Documentation6.1.2. The strict Pragma6.1.3. Enabling Warnings6.2. Exposing Apache::Registry Secrets6.2.1. The First Mystery: Why Does the Script Go Beyond 5?6.2.2. The Second Mystery—Inconsistent Growth over Reloads6.3. Namespace Issues6.3.1. The @INC Array6.3.2. The %INC Hash6.3.3. Name Collisions with Modules and Libraries6.3.3.1. A first faulty scenario6.3.3.2. A second faulty scenario6.3.3.3. A quick but ineffective hackish solution6.3.3.4. A first solution6.3.3.5. A second solution6.3.3.6. A third solution6.4. Perl Specifics in the mod_perl Environment6.4.1. exit( )6.4.2. die( )6.4.3. Global Variable Persistence6.4.4. STDIN, STDOUT, and STDERR Streams6.4.5. Redirecting STDOUT into a Scalar Variable6.4.6. print( )6.4.7. Formats6.4.8. Output from System Calls6.4.9. BEGIN blocks6.4.10. END Blocks6.5. CHECK and INIT Blocks6.5.1. $^T and time( )6.5.2. Command-Line Switches6.5.2.1. Warnings6.5.2.2. Taint mode6.5.3. Compiled Regular Expressions6.5.3.1. Matching patterns repeatedly6.6. Apache::Registry Specifics6.6.1. _ _END_ _ and _ _DATA_ _ Tokens6.6.2. Symbolic Links6.6.3. Return Codes6.7. Transition from mod_cgi Scripts to Apache Handlers6.7.1. Starting with a mod_cgi-Compatible Script6.7.2. Converting into a Perl Content Handler6.7.3. Converting to use the mod_perl API and mod_perl-Specific Modules6.8. Loading and Reloading Modules6.8.1. The @INC Array Under mod_perl6.8.2. Reloading Modules and Required Files6.8.2.1. Restarting the server6.8.2.2. Using Apache::StatINC6.8.2.3. Using Apache::Reload6.8.2.4. Using dynamic configuration files6.8.2.4.1. Writing configuration files6.8.2.4.2. Reloading configuration files6.8.2.4.3. Dynamically updating configuration files6.9. Handling the “User Pressed Stop Button” Case6.9.1. Detecting Aborted Connections6.9.2. The Importance of Cleanup Code6.9.2.1. Critical section6.9.2.2. Safe resource locking and cleanup code6.10. Handling Server Timeout Cases and Working with $SIG{ALRM}6.11. Generating Correct HTTP Headers6.12. Method Handlers: The Browse and See, Browse and View Example6.13. References
II. mod_perl Performance

7. Identifying Your Performance Problems
7.1. Looking at the Big Picture7.2. Asking the Right Questions7.3. References
8. Choosing a Platform for the Best Performance
8.1. Choosing the Right Operating System8.1.1. mod_perl Support for the Operating System8.1.2. Stability and Robustness8.1.3. Good Memory Management8.1.4. Avoiding Memory Leaks8.1.5. Memory-Sharing Capabilities8.1.6. The Real Cost of Support8.1.7. Discontinued Products8.1.8. Keeping Up with OS Releases8.2. Choosing the Right Hardware8.2.1. Machine Strength Demands According to Expected Site Traffic8.2.2. A Single Strong Machine Versus Many Weaker Machines8.2.3. Getting a Fast Internet Connection8.2.4. Tuning I/O Performance8.2.5. How Much Memory Is Enough?8.2.6. Getting a Fault-Tolerant CPU8.2.7. Detecting and Avoiding Bottlenecks8.2.8. Solving Hardware Requirement Conflicts8.3. References
9. Essential Tools for Performance Tuning
9.1. Server Benchmarking9.1.1. ApacheBench9.1.2. httperf9.1.3. http_load9.1.4. Other Web Server Benchmark Utilities9.2. Perl Code Benchmarking9.3. Process Memory Measurements9.4. Apache::Status and Measuring Code Memory Usage9.5. Code Profiling Techniques9.5.1. Profiling with Devel::DProf9.5.2. Profiling with Devel::SmallProf9.6. References
10. Improving Performance with Shared Memory and Proper Forking
10.1. Sharing Memory10.1.1. Calculating Real Memory Usage10.1.2. Memory-Sharing Validation10.1.2.1. Variable unsharing caused by regular expressions10.1.2.2. Numerical versus string access to variables10.1.3. Preloading Perl Modules at Server Startup10.1.4. Preloading Registry Scripts at Server Startup10.1.5. Module Initialization at Server Startup10.1.5.1. Initializing DBI.pm10.1.5.2. Initializing CGI.pm10.1.6. Memory Preallocation10.2. Forking and Executing Subprocessesfrom mod_perl10.2.1. Forking a New Process10.2.2. Freeing the Parent Process10.2.3. Detaching the Forked Process10.2.4. Avoiding Zombie Processes10.2.5. A Complete Fork Example10.2.6. Starting a Long-Running External Program10.2.7. Starting a Short-Running External Program10.2.8. Executing system( ) or exec( ) in the Right Way10.3. References
11. Tuning Performance by Tweaking Apache’s Configuration
11.1. Setting the MaxClients Directive11.2. Setting the MaxRequestsPerChild Directive11.3. Setting MinSpareServers, MaxSpareServers, and StartServers11.4. KeepAlive11.5. PerlSetupEnv11.6. Reducing the Number of stat( ) Calls Made by Apache11.7. Symbolic Links Lookup11.8. Disabling DNS Resolution11.9. Response Compressing11.10. References
12. Server Setup Strategies
12.1. mod_perl Deployment Overview12.2. Standalone mod_perl-Enabled Apache Server12.3. One Plain and One mod_perl-Enabled Apache Server12.3.1. Choosing the Target Installation Directories Layout12.3.2. Configuration and Compilation of the Sources12.3.2.1. Building the httpd_docs server12.3.2.2. Building the httpd_perl server12.3.3. Configuration of the Servers12.3.3.1. Basic httpd_docs server configuration12.3.3.2. Basic httpd_perl server configuration12.4. One Light Non-Apache and One mod_perl-Enabled Apache Server12.5. Adding a Proxy Server in httpd Accelerator Mode12.6. The Squid Server and mod_perl12.6.1. Pros and Cons12.6.2. Light Apache, mod_perl, and Squid Setup Implementation Details12.6.3. mod_perl and Squid Setup Implementation Details12.7. Apache’s mod_proxy Module12.7.1. Concepts and Configuration Directives12.7.1.1. ProxyPass12.7.1.2. ProxyPassReverse12.7.1.3. Security issues12.7.2. Knowing the Proxypassed Connection Type12.7.3. Buffering Feature12.7.4. Closing Lingering Connections with lingerd12.7.5. Caching Feature12.7.6. Build Process12.8. mod_rewrite Examples12.9. Getting the Remote Server IP in the Backend Server in the Proxy Setup12.10. Frontend/Backend Proxying with Virtual Hosts12.10.1. Virtual Host Flavors12.10.2. Dual-Server Virtual Host Configuration12.10.3. Virtual Hosts and Main Server Interaction12.10.4. Frontend Server Configuration12.10.5. Backend Server Configuration12.11. HTTP Authentication with Two Servers and a Proxy12.12. When One Machine Is Not Enough for Your RDBMS DataBase and mod_perl12.12.1. Server Requirements12.12.2. The Problem12.12.3. The Solution12.12.4. Three Machine Model12.13. Running More than One mod_perl Server on the Same Machine12.14. SSL Functionality and a mod_perl Server12.15. Uploading and Downloading Big Files12.16. References
13. TMTOWTDI: Convenience and Habit Versus Performance
13.1. Apache::Registry PerlHandler Versus Custom PerlHandler13.2. Apache::args Versus Apache::Request::param Versus CGI::param13.3. Buffered Printing and Better print( ) Techniques13.4. Interpolation, Concatenation, or List13.5. Keeping a Small Memory Footprint13.5.1. “Bloatware” Modules13.5.2. Importing Symbols13.6. Object Methods Calls Versus Function Calls13.6.1. The Overhead with Light Subroutines13.6.2. The Overhead with Heavy Subroutines13.6.3. Are All Methods Slower Than Functions?13.7. Using the Perl stat( ) Call’s Cached Results13.8. time( ) System Call Versus $r->request_time13.9. Printing Unmodified Files13.10. Caching and Pre-Caching13.11. Caching with Memoize13.12. Comparing Runtime Performance of Perl and C13.12.1. Building Perl Extensions with XS and h2xs13.12.2. The Benchmark13.12.3. Inline.pm13.12.4. Perl Extensions Conclusion13.13. References
14. Defensive Measures for Performance Enhancement
14.1. Controlling Your Memory Usage14.1.1. Defining the Minimum Shared Memory Size Threshold14.1.1.1. Potential drawbacks of memory-sharing restrictions14.1.2. Defining the Maximum Memory Size Threshold14.1.3. Defining the Maximum Unshared Memory Size Threshold14.2. Coding for a Smaller Memory Footprint14.2.1. Memory Reuse14.2.2. Big Input, Big Damage14.2.3. Small Input, Big Damage14.2.4. Think Production, Not Development14.2.5. Passing Variables14.2.6. Memory Leakage14.3. Conclusion14.4. References
15. Improving Performance Through Build Options
15.1. Server Size as a Function of Compiled-in Features15.2. mod_status and ExtendedStatus On15.3. DYNAMIC_MODULE_LIMIT Apache Build Option15.4. Perl Build Options15.5. Architecture-Specific Compile Options15.6. References
16. HTTP Headers for Optimal Performance
16.1. Date-Related Headers16.1.1. Date Header16.1.2. Last-Modified Header16.1.3. Expires and Cache-Control Headers16.2. Content Headers16.2.1. Content-Type Header16.2.2. Content-Length Header16.2.3. Entity Tags16.3. Content Negotiation16.3.1. The Vary Header16.4. HTTP Requests16.4.1. GET Requests16.4.2. Conditional GET Requests16.4.3. HEAD Requests16.4.4. POST Requests16.5. Avoiding Dealing with Headers16.6. References
III. Databases and mod_perl
17. Databases Overview
17.1. Volatile Databases17.1.1. In-Memory Databases in a Single Process17.1.2. In-Memory Databases Across Multiple Processes17.2. Non-Volatile Databases17.2.1. Flat-File Databases17.2.2. Filesystem Databases17.2.3. DBM Databases17.2.4. Relational Databases17.3. References
18. mod_perl Data-Sharing Techniques
18.1. Sharing the Read-Only Data in and Between Processes18.2. Sharing Data Between Various Handlers18.3. References
19. DBM and mod_perl
19.1. mod_perl and DBM19.2. Resource Locking19.2.1. Deadlocks19.2.2. Exclusive Locking Starvation19.3. Flawed Locking Methods19.4. Locking Wrappers Overview19.5. Tie::DB_Lock19.6. Examples19.6.1. tie( )-ing Once and Forever19.6.2. Read/Write Access19.6.3. Storing Complex Data Structures19.7. References
20. Relational Databases and mod_perl
20.1. Persistent Database Connections with Apache::DBI20.1.1. Apache::DBI Connections20.1.2. When to Use Apache::DBI (and When Not to Use It)20.1.3. Configuring Apache::DBI20.1.4. Debugging Apache::DBI20.1.5. Caveats and Troubleshooting20.1.5.1. Database locking risks20.1.5.2. Transactions20.1.5.3. Opening connections with different parameters20.1.5.4. Cannot find the DBI handler20.1.5.5. The morning bug20.1.5.6. Apache:DBI does not work20.1.5.7. Skipping connection cache during server startup20.2. Improving Performance20.2.1. Preopening DBI Connections20.2.2. Improving Speed by Skipping ping( )20.2.3. Efficient Record-Retrieval Techniques20.2.4. mysql_use_result Versus mysql_store_result Attributes20.2.5. Running Two or More Relational Databases20.2.6. Caching prepare( ) Statements20.3. DBI Debug Techniques20.4. References
IV. Debugging and Troubleshooting
21. Error Handling and Debugging
21.1. Warnings and Errors Explained21.1.1. The Importance of Warnings21.1.1.1. The diagnostics pragma21.1.2. Curing “Internal Server Error” Problems21.1.3. Making Use of the error_log21.1.4. Displaying Errors to Users21.2. Debugging Code in Single-Server Mode21.3. Tracing System Calls21.4. Tracing mod_perl-Specific Perl Calls21.5. Debugging Perl Code21.5.1. Locating and Correcting Syntax Errors21.5.2. Using Apache::FakeRequest to Debug Apache Perl Modules21.5.3. Using print( ) for Debugging21.5.4. Using print( ) and Data::Dumper for Debugging21.5.5. The Importance of a Good, Concise Coding Style21.5.6. Introduction to the Perl Debugger21.5.7. Interactive Perl Debugging Under mod_cgi21.5.8. Noninteractive Perl Debugging Under mod_perl21.5.9. Interactive mod_perl Debugging21.5.9.1. ptkdb and interactive mod_perl debugging21.6. Analyzing Dumped core Files21.6.1. Getting Ready to Debug21.6.2. Creating a Faulty Package21.6.3. Dumping the core File21.6.4. Analyzing the core File21.6.5. Extracting the Backtrace Automatically21.7. Hanging Processes: Detection and Diagnostics21.7.1. Hanging Because of an Operating System Problem21.7.2. When a Process Might Hang21.7.3. Detecting Hanging Processes21.7.4. Determination of the Reason21.7.4.1. Using the Perl trace21.7.4.2. Using the system calls trace21.7.4.3. Using the interactive debugger21.7.5. mod_perl gdb Debug Macros21.8. Useful Debug Modules21.8.1. B::Deparse21.8.2. -D Runtime Option21.8.3. Devel::Peek and Apache::Peek21.8.4. Devel::Symdump and Apache::Symdump21.8.5. Apache::Debug21.8.6. Other Debug Modules21.9. Looking Inside the Server21.9.1. Apache::Status—Embedded Interpreter Status Information21.9.1.1. Minimal configuration21.9.1.2. Extended configuration21.9.1.3. Usage21.9.2. mod_status21.10. References
22. Troubleshooting mod_perl
22.1. Configuration and Startup22.1.1. libexec/libperl.so: open failed: No such file or directory22.1.2. install_driver(Oracle) failed: Can’t load `.../DBD/Oracle/Oracle.so’ for module DBD::Oracle22.1.3. Invalid command `PerlHandler’...22.1.4. RegistryLoader: Translation of uri [...] to filename failed22.2. Code Parsing and Compilation22.2.1. Value of $x will not stay shared at - line 522.2.2. Value of $x may be unavailable at - line 522.2.3. Can’t locate loadable object for module ...22.2.4. Can’t locate object method “get_handlers” ...22.2.5. Missing right bracket at line ...22.2.6. Can’t load `.../auto/DBI/DBI.so’ for module DBI22.3. Runtime22.3.1. foo ... at /dev/null line 022.3.2. Segfaults When Using XML::Parser22.3.3. exit signal Segmentation fault (11)22.3.4. CGI Code Is Returned as Plain Text Instead of Being Executed22.3.5. rwrite returned -122.3.6. Global symbol “$foo” requires explicit package name22.3.7. Use of uninitialized value at (eval 80) line 1222.3.8. Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at22.3.9. Callback called exit22.3.10. Out of memory!22.3.11. syntax error at /dev/null line 1, near “line arguments:”22.4. Shutdown and Restart22.4.1. Evil Things Might Happen When Using PerlFreshRestart22.4.2. [warn] child process 30388 did not exit, sending another SIGHUP22.4.3. Processes Get Stuck on Graceful Restart
23. Getting Help and Online Resources
23.1. How to Report Problems23.1.1. Getting the Backtrace from Core Dumps23.1.2. Spinning Processes23.2. Mailing List Etiquette23.3. Resources23.3.1. mod_perl23.3.2. mod_perl Mailing Lists23.3.3. Perl23.3.4. Perl/CGI23.3.5. Apache23.3.6. DBI and SQL23.3.7. Squid23.3.8. CVS23.3.9. Performance and Scalability23.3.10. Web Security
V. mod_perl 2.0
24. mod_perl 2.0: Installation and Configuration
24.1. What’s New in Apache 2.024.2. What’s New in Perl 5.6.0-5.8.024.3. What’s New in mod_perl 2.024.3.1. Thread Support24.3.2. Perl Interface to the APR and Apache APIs24.3.3. Other New Features24.3.4. Improved and More Flexible Configuration24.3.5. Optimizations24.4. Installing mod_perl 2.024.4.1. Installing from Source24.4.2. Installing Binaries24.5. Configuring mod_perl 2.024.5.1. Enabling mod_perl24.5.2. Accessing the mod_perl 2.0 Modules24.5.3. Startup File24.5.4. Perl’s Command-Line Switches24.5.5. mod_perl 2.0 Core Handlers24.5.5.1. modperl24.5.5.2. perl-script24.5.5.3. A simple response handler example24.5.6. PerlOptions Directive24.5.6.1. Enable24.5.6.2. Clone24.5.6.3. Parent24.5.6.4. Perl*Handler24.5.6.5. AutoLoad24.5.6.6. GlobalRequest24.5.6.7. ParseHeaders24.5.6.8. MergeHandlers24.5.6.9. SetupEnv24.5.7. Thread-Mode-Specific Directives24.5.7.1. PerlInterpStart24.5.7.2. PerlInterpMax24.5.7.3. PerlInterpMinSpare24.5.7.4. PerlInterpMaxSpare24.5.7.5. PerlInterpMaxRequests24.5.7.6. PerlInterpScope24.5.8. Retrieving Server Startup Options24.6. Resources
25. Programming for mod_perl 2.0
25.1. Migrating to and Programming with mod_perl 2.025.1.1. The Shortest Migration Path25.1.2. Migrating Configuration Files25.1.2.1. PerlHandler25.1.2.2. PerlSendHeader25.1.2.3. PerlSetupEnv25.1.2.4. PerlTaintCheck25.1.2.5. PerlWarn25.1.2.6. PerlFreshRestart25.1.3. Code Porting25.1.4. ModPerl::Registry Family25.1.5. Method Handlers25.1.6. Apache::StatINC Replacement25.2. New Apache Phases and Corresponding Perl*Handlers25.2.1. Server Configuration and Startup Phases25.2.1.1. PerlOpenLogsHandler25.2.1.2. PerlPostConfigHandler25.2.1.3. PerlChildInitHandler25.2.1.4. PerlChildExitHandler25.2.2. Connection Phases25.2.2.1. PerlPreConnectionHandler25.2.2.2. PerlProcessConnectionHandler25.2.2.2.1. Socket-based protocol module25.2.2.2.2. Bucket brigade-based protocol module25.2.3. HTTP Request Phases25.3. I/O Filtering25.3.1. I/O Filtering Concepts25.3.1.1. Two methods for manipulating data25.3.1.2. HTTP request versus connection filters25.3.1.3. Multiple invocations of filter handlers25.3.1.4. Blocking calls25.3.2. Filter Configuration25.3.3. Input Filters25.3.3.1. Bucket brigade-based connection input filter25.3.3.2. Bucket brigade-based HTTP request input filter25.3.3.3. Stream-based HTTP request input filter25.3.4. Output Filters25.3.4.1. Stream-based HTTP request output filter25.3.4.2. Another stream-based HTTP request output filter25.3.4.3. Bucket brigade-based HTTP request output filter
VI. Appendixes
A. mod_perl Recipes
A.1. Emulating the Authentication MechanismA.2. Reusing Data from POST RequestsA.3. Redirecting POST RequestsA.4. Redirecting While Maintaining Environment VariablesA.5. Handling CookiesA.6. Sending Multiple Cookies with the mod_perl APIA.7. Sending Cookies in REDIRECT ResponsesA.8. CGI::params in the mod_perlish WayA.9. Sending Email from mod_perlA.10. mod_rewrite in PerlA.11. Setting PerlHandler Based on MIME TypeA.12. Singleton Database HandlesA.13. Terminating a Child Process on Request CompletionA.14. References
B. Apache Perl Modules
B.1. Development-Stage ModulesB.1.1. Apache::Reload—Automatically Reload Changed ModulesB.1.2. Apache::PerlVINC—Allow Module Versioning in <Location> and <VirtualHost> blocksB.1.3. Apache::DProf—Hook Devel::DProf into mod_perlB.1.4. Apache::SmallProf—Hook Devel::SmallProf into mod_perlB.1.5. Apache::FakeRequest—Fake Request Object for DebuggingB.1.6. Apache::test—Facilitate Testing of Apache::* ModulesB.2. Modules to Aid DebuggingB.2.1. Apache::DB—Hooks for the Interactive Perl DebuggerB.2.2. Apache::Debug—Utilities for Debugging Embedded Perl CodeB.2.3. Apache::DebugInfo—Send Debug Information to ClientB.2.4. Apache::Leak—Module for Tracking Memory Leaks in mod_perl CodeB.2.5. Apache::Peek—A Data Debugging Tool for the XS ProgrammerB.2.6. Apache::Symbol—Avoid the Mandatory `Subroutine Redefined’ WarningB.2.7. Apache::Symdump—Symbol Table SnapshotsB.3. Control and Monitoring ModulesB.3.1. Apache::Watchdog::RunAway—Hanging Processes Monitor and TerminatorB.3.2. Apache::VMonitor—Visual System and Apache Server MonitorB.3.3. Apache::SizeLimit—Limit Apache httpd ProcessesB.3.4. Apache::GTopLimit—Limit Apache httpd ProcessesB.3.5. Apache::TimedRedirect—Redirect URLs for a Given Time PeriodB.3.6. Apache::Resource—Limit Resources Used by httpd ChildrenB.3.7. Apache::Status—Embedded Interpreter Status InformationB.4. Server Configuration ModulesB.4.1. Apache::ModuleConfig—Interface to Configuration APIB.4.2. Apache::PerlSections—Utilities for Working with <Perl> SectionsB.4.3. Apache::httpd_conf—Generate an httpd.conf FileB.4.4. Apache::src—Methods for Locating and Parsing Bits of Apache Source CodeB.4.5. Apache::ConfigFile—Parse an Apache-Style httpd.conf Configuration FileB.5. Authentication-Phase ModulesB.6. Authorization-Phase ModulesB.7. Access-Phase ModulesB.7.1. Stonehenge::Throttle—Limit Bandwith Consumption by IP AddressB.8. Type HandlersB.8.1. Apache::MimeXML—mod_perl Mime Encoding Sniffer for XML FilesB.8.2. Apache::MIMEMapper—Associates File Extensions with PerlHandlersB.9. Trans HandlersB.9.1. Apache::AddHostPath—Adds Some or All of the Hostname and Port to the URIB.9.2. Apache::ProxyPass—implement ProxyPass in PerlB.9.3. Apache::ProxyPassThru—Skeleton for Vanilla ProxyB.9.4. Apache::Throttle—Speed-Based Content NegotiationB.9.5. Apache::TransLDAP—Trans Handler ExampleB.10. Fixup HandlersB.10.1. Apache::RefererBlock—Block Request Based Upon “Referer” HeaderB.10.2. Apache::Usertrack—Emulate the mod_usertrack Apache ModuleB.11. Generic Content-Generation ModulesB.11.1. Apache::Registry and Apache::PerlRunB.11.2. Apache::RegistryNG—Apache::Registry New GenerationB.11.3. Apache::RegistryBB—Apache::Registry Bare BonesB.11.4. Apache::Request (libapreq)—Generic Apache Request LibraryB.11.5. Apache::Dispatch—Call PerlHandlers with the Ease of Registry ScriptsB.12. Application-Specific Content-Generation ModulesB.12.1. Apache::AutoIndex—Perl Replacement for the mod_autoindex and mod_dir Apache ModulesB.12.2. Apache::WAP::AutoIndex—WAP Demonstration ModuleB.12.3. Apache::WAP::MailPeek—Demonstrate Use of WML DeliveryB.12.4. Apache::Archive—Expose Archive Files Through the Apache Web ServerB.12.5. Apache::Gateway—Implement a GatewayB.12.6. Apache::NNTPGateway—NNTP Interface for a mod_perl-Enabled Apache Web Server.B.12.7. Apache::PrettyPerl—Syntax Highlighting for Perl FilesB.12.8. Apache::PrettyText—Reformat .txt Files for Client DisplayB.12.9. Apache::RandomLocation—Random File DisplayB.12.10. Apache::Stage—Manage a Staging DirectoryB.12.11. Apache::Roaming—A mod_perl Handler for Roaming ProfilesB.12.12. Apache::Backhand—Write mod_backhand Functions in PerlB.13. Database ModulesB.13.1. Apache::DBI—Initiate a Persistent Database ConnectionB.13.2. Apache::OWA—Oracle’s PL/SQL Web Toolkit for ApacheB.13.3. Apache::Sybase::CTlib—Persistent CTlib Connection Management for ApacheB.14. Toolkits and Frameworks for Content-Generation and Other PhasesB.14.1. Apache::ASP—Active Server Pages for Apache with mod_perlB.14.2. Apache::AxKit—XML Toolkit for mod_perlB.14.3. HTML::Embperl—Embed Perl into HTMLB.14.4. Apache::EmbperlChain—Process Embedded Perl in HTML in the OutputChainB.14.5. Apache::ePerl—Embedded Perl 5 LanguageB.14.6. Apache::iNcom—E-Commerce FrameworkB.14.7. Apache::Mason—Perl-Based Web Site Development and Delivery SystemB.14.8. Apache::PageKit—Web Applications FrameworkB.14.9. Template Toolkit—Template Processing SystemB.15. Output Filters and Layering ModulesB.15.1. Apache::OutputChain—Chain Stacked Perl HandlersB.15.2. Apache::Clean—mod_perl Interface Into HTML::CleanB.15.3. Apache::Filter—Alter the Output of Previous HandlersB.15.4. Apache::GzipChain—Compress HTML (or Anything) in the OutputChainB.15.5. Apache::PassFile—Send File via OutputChainB.15.6. Apache::Gzip—Auto-Compress Web Files with gzipB.15.7. Apache::Compress—Auto-Compress Web Files with gzipB.15.8. Apache::Layer—Layer Content Tree Over One or More OthersB.15.9. Apache::Sandwich—Layered Document (Sandwich) MakerB.15.10. Apache::SimpleReplace—Simple Template FrameworkB.15.11. Apache::SSI—Implement Server-Side Includes in PerlB.16. Logging-Phase HandlersB.16.1. Apache::RedirectLogFix—Correct Status While LoggingB.16.2. Apache::DBILogConfig—Logs Access Information in a DBI DatabaseB.16.3. Apache::DBILogger—Tracks What’s Being Transferred in a DBI DatabaseB.16.4. Apache::DumpHeaders—Watch HTTP Transaction via HeadersB.16.5. Apache::Traffic—Track Hits and Bytes Transferred on a Per-User BasisB.17. Core Apache ModulesB.17.1. Apache::Module—Interface to Apache C Module StructuresB.17.2. Apache::ShowRequest—Show Phases and Module ParticipationB.17.3. Apache::SubProcess—Interface to Apache Subprocess APIB.17.4. Apache::Connection—Interface to the Apache conn_rec Data StructureB.17.5. Apache::Constants—Constants Defined in httpd.hB.17.6. Apache::ExtUtils—Utilities for Apache C/Perl GlueB.17.7. Apache::File—Advanced Functions for Manipulating Files on the Server SideB.17.8. Apache::Log—Interface to Apache LoggingB.17.9. Apache::LogFile—Interface to Apache’s Logging RoutinesB.17.10. Apache::Scoreboard—Perl Interface to Apache’s scoreboard.hB.17.11. Apache::Server—Perl Interface to the Apache server_rec StructB.17.12. Apache::Table—Perl Interface to the Apache Table StructB.17.13. Apache::URI—URI Component Parsing and UnparsingB.17.14. Apache::Util—Perl Interface to Apache C Utility FunctionsB.18. Other Miscellaneous ModulesB.18.1. Apache::Session—Maintain Session State Across HTTP RequestsB.18.2. Apache::RequestNotes—Easy, Consistent Access to Cookie and Form Data Across Each Request PhaseB.18.3. Apache::Cookie—HTTP Cookies ClassB.18.4. Apache::Icon—Look Up Icon ImagesB.18.5. Apache::Include—Utilities for mod_perl/mod_include IntegrationB.18.6. Apache::Language—Perl Transparent Language Support for Apache Modules and mod_perl ScriptsB.18.7. Apache::Mmap—Perl Interface to the mmap(2) System CallB.18.8. Apache::GD::Graph—Generate Graphs in an Apache HandlerB.18.9. Apache::Motd—Provide motd (Message of the Day) Functionality to a Web ServerB.18.10. Apache::ParseLog—Object-Oriented Perl Extension for Parsing Apache Log FilesB.18.11. Apache::RegistryLoader—Compile Apache::Registry Scripts at Server StartupB.18.12. Apache::SIG—Override Apache Signal Handlers with Perl’s Signal HandlersB.18.13. Apache::TempFile—Allocate Temporary Filenames for the Duration of a RequestB.18.14. Xmms—Perl Interface to the xmms Media PlayerB.18.15. Module::Use—Log and Load Used Perl Modules
C. ISPs Providing mod_perl Services
C.1. Users Sharing a Single Web ServerC.2. Users Sharing a Single MachineC.3. Giving Each User a Separate Machine (Colocation)C.4. Giving Each User a Virtual Machine
D. The Template Toolkit
D.1. Fetching and Installing the Template ToolkitD.2. OverviewD.3. Typical UsesD.4. Template Toolkit LanguageD.4.1. Simple Template ExampleD.5. Processing TemplatesD.6. Apache/mod_perl HandlerD.7. Apache::Template ModuleD.8. Hangman ApplicationD.8.1. Hangman CGI ScriptD.8.2. Hangman with Modular TemplatesD.8.3. Hangman Plug-inD.8.4. Self-Contained Hangman TemplateD.9. References
E. The AxKit XML Application Server
E.1. Installing and Configuring AxKitE.2. Your First AxKit PageE.2.1. If Something Goes WrongE.2.2. How it Works?E.2.3. XPathE.3. Dynamic ContentE.3.1. Handling Form ParametersE.3.2. Handling CookiesE.3.3. Sending EmailE.3.4. Handling ExceptionsE.3.5. Utilities TaglibE.3.6. Executing SQLE.4. More XPathScript DetailsE.4.1. The XPathScript APIE.4.1.1. Extracting valuesE.4.1.2. Declarative templatesE.5. XSLTE.5.1. Anatomy of an XSLT StylesheetE.5.2. Template Rules and RecursionE.5.3. Learning MoreE.6. Putting Everything TogetherE.7. More Reasons to Use AxKit
F. HTTP Status Codes
F.1. HTTP/1.0 Status CodesF.2. HTTP/1.1 Status CodesF.3. References
Index
About the Authors
Colophon
Copyright

Content preview from Practical mod_perl

Appendix D. The Template Toolkit

This appendix provides an introduction to the Template Toolkit, a fast, flexible, powerful, and extensible template processing system written in Perl.^[1] It is ideally suited for use in creating highly customized static and dynamic web pages and for building Perl-based web applications. This appendix explains how to get the best out of the Template Toolkit under mod_perl (although the Template Toolkit is in no way limited to use under mod_perl). All the example code is available for download from this book’s web site (http://www.modperl.com/).

This appendix’s goal is to give you a flavor of what the Template Toolkit can do for you and your web sites. It is by no means comprehensive, and you’re strongly urged to consult the copious documentation that is bundled with the Perl modules or available for browsing online at the Template Toolkit web site: http://template-toolkit.org/.

Fetching and Installing the Template Toolkit

You can fetch the Template Toolkit from any CPAN site. It can be found at the following URL: http://www.cpan.org/modules/by-module/Template/.

Once you’ve unzipped and untarred the distribution, installation proceeds via the usual route. For example:

panic% perl Makefile.PL
panic% make
panic% make test
panic% su
panic# make install

Alternately, you can use the CPAN.pm module to install it. Full details on installation can be found in the INSTALL file in the distribution directory. There is also a README file that is worth at least a passing ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Publisher Resources

ISBN: 0596002270Errata Page

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Practical mod_perl

by Stas Bekman, Eric Cholet

Appendix D. The Template Toolkit

Fetching and Installing the Template Toolkit

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.