=head1 NAME Apache::* modules =head1 Description Overview of some of the most popular modules for mod_perl, both to use directly from your code and as mod_perl handlers. Over the time, mod_perl has collected an impressive amount of modules which are distributed in the standard Perl way, over CPAN. Found in the C namespace, these implement various functionalities you might need when creating a mod_perl-based website. For mod_perl, we can actually make a distinction between two types of modules: =over =item * Apache handlers, which handle request phases or whole requests and are standalone (C for example). =item * Convenience modules, which are like standard Perl modules, implementing some useful aspect of web programming, usually using mod_perl API for a greater performance or functionality unavailable in plain Perl. (A good example of this is C.) These modules exist under the C namespace because they can only be used under mod_perl. =back For a complete list of modules, see the L. =head1 Apache::Session - Maintain session state across HTTP requests This module provides the Apache/mod_perl user with a mechanism for storing persistent user data in a global hash, which is independent of the underlying storage mechanism. Currently you can choose from these storage mechanisms C, C, C, C. Read the man page of the mechanism you want to use for a complete reference. C provides persistence to a data structure. The data structure has an ID number, and you can retrieve it by using the ID number. In the case of Apache, you would store the ID number in a cookie or the URL to associate it with one browser, but the method of dealing with the ID is completely up to you. The flow of things is generally: Tie a session to Apache::Session. Get the ID number. Store the ID number in a cookie. End of Request 1. (time passes) Get the cookie. Restore your hash using the ID number in the cookie. Use whatever data you put in the hash. End of Request 2. Using C is easy: simply tie a hash to the session object, stick any data structure into the hash, and the data you put in automatically persists until the next invocation. Here is an example which uses cookies to track the user's session. # pull in the required packages use Apache::Session::DBI; use Apache; use strict; # read in the cookie if this is an old session my $r = Apache->request; my $cookie = $r->header_in('Cookie'); $cookie =~ s/SESSION_ID=(\w*)/$1/; # create a session object based on the cookie we got from the # browser, or a new session if we got no cookie my %session; tie %session, 'Apache::Session::DBI', $cookie, {DataSource => 'dbi:mysql:sessions', UserName => $db_user, Password => $db_pass }; # might be a new session, so lets give them their cookie back my $session_cookie = "SESSION_ID=$session{_session_id};"; $r->header_out("Set-Cookie" => $session_cookie); After setting this up, you can stick anything you want into C<%session> (except file handles and code references and using I<_session_id>), and it will still be there when the user invokes the next page. It is possible to write an Apache authentication handler using C. You can put your authentication token into the session. When a user invokes a page, you open their session, check to see if they have a valid token, and authenticate or forbid based on that. By way of comparison note that IIS's sessions are only valid on the same web server as the one that issued the session. C's session objects can be shared amongst a farm of many machines running different operating systems, including even Win32. IIS stores session information in RAM. C stores sessions in databases, file systems, or RAM. IIS's sessions are only good for storing scalars or arrays. C's sessions allow you to store arbitrarily complex objects. IIS sets up the session and automatically tracks it for you. With C, you setup and track the session yourself. IIS is proprietary. C is open-source. C can issue 400+ session requests per second on light Celeron 300A running Linux. IIS? An alternative to C is C, which has session tracking abilities. C hooks into C for you. =head1 Apache::DBI - Initiate a persistent database connection See L =head1 Apache::Watchdog::RunAway - Hanging Processes Monitor and Terminator This module monitors hanging Apache/mod_perl processes. You define the time in seconds after which the process is to be counted as I or I. When the process is considered to be I it will be killed and the event logged in a log file. Generally you should use the C program that is bundled with this module's distribution package, but you can write your own code using the module as well. See the I manpage for more information about it. Note that it requires the C module to work. Refer to the C manpage for the configuration details. =head1 Apache::VMonitor -- Visual System and Apache Server Monitor C is the next generation of L. It provides all the information mod_status provides and much more. This module emulates the reporting functions of the top(), mount(), df() and ifconfig() utilities. There is a special mode for mod_perl processes. It has visual alert capabilities and a configurable I mode. It provides a Web interface, which can be used to show or hide all the sections dynamically. The are two main modes: =over =item * Multi processes mode -- All system processes and information is shown. =item * Single process mode -- In-depth information about a single process is shown. =back The main advantage of this module is that it reduces the need to telnet to the machine in order to monitor it. Indeed it provides information about mod_perl processes that cannot be acquired from telneting to the machine. =head3 Configuration # Configuration in httpd.conf SetHandler perl-script PerlHandler Apache::VMonitor # startup file or section: use Apache::VMonitor(); $Apache::VMonitor::Config{BLINKING} = 0; # Blinking is evil $Apache::VMonitor::Config{REFRESH} = 0; $Apache::VMonitor::Config{VERBOSE} = 0; $Apache::VMonitor::Config{SYSTEM} = 1; $Apache::VMonitor::Config{APACHE} = 1; $Apache::VMonitor::Config{PROCS} = 1; $Apache::VMonitor::Config{MOUNT} = 1; $Apache::VMonitor::Config{FS_USAGE} = 1; $Apache::VMonitor::Config{NETLOAD} = 1; @Apache::VMonitor::NETDEVS = qw(lo eth0); $Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid); More information is available in the module's extensive manpage. It requires C and C to work. C in turn requires the C library but is not available for all platforms. See the docs in the source at ftp://ftp.gnome.org/pub/GNOME/stable/sources/gtop/ to check whether your platform/flavor is supported. =head1 Apache::GTopLimit - Limit Apache httpd processes This module allows you to kill off Apache processes if they grow too large or if they share too little of their memory. You can choose to set up the process size limiter to check the process size on every request: The module is thoroughly explained in the section: L =head1 Apache::Request (libapreq) - Generic Apache Request Library This package contains modules for manipulating client request data via the Apache API with Perl and C. Functionality includes: =over =item parsing of application/x-www-form-urlencoded data =item parsing of multipart/form-data =item parsing of HTTP Cookies =back The Perl modules are simply a thin xs layer on top of libapreq, making them a lighter and faster alternative to CGI.pm and CGI::Cookie. See the C and C documentation for more details and eg/perl/ for examples. C and libapreq are tied tightly to the Apache API, to which there is no access in a process running under mod_cgi. (L) =head1 Apache::RequestNotes - Allow Easy, Consistent Access to Cookie and Form Data Across Each Request Phase C provides a simple interface allowing all phases of the request cycle access to cookie or form input parameters in a consistent manner. Behind the scenes, it uses libapreq L) functions to parse request data and puts references to the data in C. Once the request is past the PerlInit phase, all other phases can have access to form input and cookie data without parsing it themselves. This relieves some strain, especially when the GET or POST data is required by numerous handlers along the way. See the C manpage for more information. =head1 Apache::PerlRun - Run unaltered CGI scripts under mod_perl See L. =head1 Apache::RegistryNG -- Apache::Registry New Generation C is the same as C, aside from using filenames instead of URIs for namespaces. This feature ensures that if the same CGI script is requested from different URIs (e.g. different hostnames) it'll be compiled and cached only once, thus saving memory. C uses an Object Oriented interface. PerlModule Apache::RegistryNG SetHandler perl-script PerlHandler Apache::RegistryNG->handler C inherits from C, but the handler() is overridden. Aside from the handler(), the rest of C contains all the functionality of C broken down into several subclass-able methods. These methods are used by C to implement the exact same functionality of C, using the C methods. There is no compelling reason to use C over C, unless you want to do add or change the functionality of the existing I or if you want to use filenames instead of URIs for namespaces. For example, C (Bare-Bones) is another subclass that skips the stat() call performed by C on each request. =head1 Apache::RegistryBB -- Apache::Registry Bare Bones It works just like C, but does not test the x bit (-x file test for executable mode), only compiles the file once (no stat() call is made per request), skips the C checks and does not C into the script parent directory. It uses the Object Oriented interface. Configuration: PerlModule Apache::RegistryBB SetHandler perl-script PerlHandler Apache::RegistryBB->handler =head1 Apache::OutputChain -- Chain Stacked Perl Handlers Apache::OutputChain was written as a way of exploring the possibilities of stacked handlers in mod_perl. It ties STDOUT to an object which catches the output and makes it easy to build a chain of modules that work on output data stream. Examples of modules that are build on this idea are C, C and C -- the first processes the SSI's in the stream, the second compresses the output on the fly, the last adds Embperl processing. The syntax goes like this: SetHandler perl-script PerlHandler Apache::OutputChain Apache::SSIChain Apache::PassHtml The modules are listed in the reverse order of their execution -- here the C module simply picks a file's content and sends it to STDOUT, then it's processed by C, which sends its output to STDOUT again. Then it's processed by C, which finally sends the result to the browser. An alternative to this approach is C, which has a more natural I configuration order and is easier to interface with other modules. It works with C as well, for example: Alias /foo /home/httpd/perl/foo SetHandler "perl-script" Options +ExecCGI PerlHandler Apache::OutputChain Apache::GzipChain Apache::Registry It's really a regular C setup, except for the added modules in the PerlHandler line. (L allows to compress the output on the fly.) =head1 Apache::Filter - Alter the output of previous handlers C, like C, allows you to chain stacked handlers. It's not very different from C, except for the way you configure the filters. A normal configuration with C would be the following: PerlModule Apache::Filter Apache::RegistryFilter Apache::SSI Apache::Gzip Alias /perl /home/httpd/perl SetHandler "perl-script" Options +ExecCGI PerlSetVar Filter On PerlHandler Apache::RegistryFilter Apache::SSI Apache::Gzip This accomplishes some things many CGI programmers want: you can output SSI code from your C scripts, have it parsed by C, and then compressed with C (see L below). Thanks to C, you can also write your own filter modules, which allow you to read in the output from the previous handler in the chain and modify it. You would do something like this in your C subroutine: $r = $r->filter_register(); # Required my $fh = $r->filter_input(); # Optional (you might not need the input FH) while (<$fh>) { s/ something / something else /; print; } Another interesting thing to do with C would be to use it for XML output from your scripts(these modules are hypothetical, this is handled much better by AxKit, Matt Seargeant's XML application server for mod_perl (see http://www.axkit.org/ ). SetHandler perl-script Options +ExecCGI PerlSetVar Filter On PerlHandler Apache::RegistryFilter Apache::XSLT As you can see, you can get a lot of freedom by using stacked handlers, allowing you to separate various parts of your programs and leave those tasks up to other modules, which may already be available from CPAN (this is much better than the CGI time when your script would have to do I itself, because you couldn't do much with its output). =head1 Apache::GzipChain - compress HTML (or anything) in the OutputChain Have you ever served a huge HTML file (e.g. a file bloated with JavaScript code) and wondered how could you send it compressed, thus dramatically cutting down the download times? After all Java applets can be compressed into a jar and benefit from faster download times. Why can't we do the same with plain ASCII (HTML, JS etc.)? ASCII text can often be compressed by a factor of 10. C comes to help you with this task. If a client (browser) understands C encoding, this module compresses the output and sends it downstream. The client decompresses the data upon receipt and renders the HTML as if it were fetching plain HTML. For example to compress all html files on the fly, do this: SetHandler perl-script PerlHandler Apache::OutputChain Apache::GzipChain Apache::PassFile Remember that it will work only if the browser claims to accept compressed input, by setting the C header. C keeps a list of user-agents, thus it also looks at the C header to check for browsers known to accept compressed output. For example if you want to return compressed files which will in addition pass through the Embperl module, you would write: SetHandler perl-script PerlHandler Apache::OutputChain Apache::GzipChain Apache::EmbperlChain Apache::PassFile Hint: Watch the I file to see how many bytes were actually sent, and compare that with the bytes sent using a regular configuration. (See also C). Notice that the rightmost PerlHandler must be a content producer. Here we are using C but you can use any module which creates output. =head1 Apache::Gzip - Auto-compress web files with Gzip Similar to C but works with C. This configuration: PerlModule Apache::Filter SetHandler perl-script PerlSetVar Filter On PerlHandler Apache::Gzip will send all the I<*.html> files compressed if the client accepts the compressed input. And this one: PerlModule Apache::Filter Alias /home/http/perl /perl SetHandler perl-script PerlSetVar Filter On PerlHandler Apache::RegistryFilter Apache::Gzip will compress the output of the C scripts. Yes, you should use C instead of C for it to work. You can use as many filters as you want: PerlModule Apache::Filter SetHandler perl-script PerlSetVar Filter On PerlHandler Filter1 Filter2 Apache::Gzip You can test that it works by either looking at the size of the response in the I or by telnet: panic% telnet localhost 8000 Trying 127.0.0.1 Connected to 127.0.0.1 Escape character is '^]'. GET /perl/test.pl HTTP 1.1 Accept-Encoding: gzip User-Agent: Mozilla And you will get the data compressed if configured correctly. =head1 Apache::PerlVINC - Allows Module Versioning in Location blocks and Virtual Hosts With this module you can have different C<@INC> for different virtual hosts, locations and equivalent configuration blocks. Suppose two versions of C are being hacked on the same server. In this configuration: PerlModule Apache::PerlVINC SetHandler perl-script PerlHandler Apache::Status PerlINC /home/httpd/dev/lib PerlFixupHandler Apache::PerlVINC PerlVersion Apache/Status.pm SetHandler perl-script PerlHandler Apache::Status PerlINC /home/httpd/prod/lib PerlFixupHandler Apache::PerlVINC PerlVersion Apache/Status.pm The C is loaded and then two different locations are specified for the same handler C, whose development version resides in I and production version in I. In case the I request is issued (the latter configuration section), the fixup handler will internally do: delete $INC{Apache/Status.pm}; unshift @INC, /home/httpd/prod/lib; require "Apache/Status.pm"; which will load the production version of the module and it'll be used to process the request. If on the other hand if the request to the I location will be issued, as configured in the former configuration section, a similar thing will happen, but a different path (I) will be prepended to C<@INC>: delete $INC{Apache/Status.pm}; unshift @INC, /home/httpd/dev/lib; require "Apache/Status.pm"; It's important to be aware that a changed C<@INC> is effective only inside the CLocationE> or a similar configuration directive. C subclasses the C directive, marking the file to be reloaded by the fixup handler, using the value of C for C<@INC>. That's local to the fixup handler, so you won't actually see C<@INC> changed in your script. In addition the modules with different versions can be unloaded at the end of request, using the C handler: SetHandler perl-script PerlHandler Apache::Status PerlINC /home/httpd/prod/lib PerlFixupHandler Apache::PerlVINC PerlCleanupHandler Apache::PerlVINC PerlVersion Apache/Status.pm Also notice that C effect things differently depending on where it was placed. If it was placed inside a CLocationE> or a similar block section, the files will only be reloaded on requests to that location. If it was placed in a server section, all requests to the server or virtual hosts will have these files reloaded. As you can guess, this module slows the response time down because it reloads some modules on a per-request basis. Hence, this module should only be used in a development environment, not a production one. =head1 Apache::LogSTDERR When Apache's builtin syslog support is used, the stderr stream is redirected to C. This means that Perl warnings, any messages from C, C, etc., will also end up in the black hole. The I directive will hook the stderr stream to a file of your choice, the default is shown in this example: PerlModule Apache::LogSTDERR HookStderr logs/stderr_log [META: see http://mathforum.org/epigone/modperl/vixquimwhen ] =head1 Apache::RedirectLogFix Because of the way mod_perl handles redirects, the status code is not properly logged. The C module works around that bug until mod_perl can deal with this. All you have to do is to enable it in the I file. PerlLogHandler Apache::RedirectLogFix For example, you will have to use it when doing: $r->status(304); and do some manual header sending, like this: $r->status(304); $r->send_http_header(); =head1 Apache::SubProcess The output of C, C, and C calls will not be sent to the browser unless your Perl was configured with C. One workaround is to use backticks: print `command here`; But a cleaner solution is provided by the C module. It overrides the exec() and system() calls with calls that work correctly under mod_perl. Let's see a few examples: use Apache::SubProcess qw(system); my $r = shift; $r->send_http_header('text/plain'); system "/bin/echo hi there"; overrides built-in system() function and sends the output to the browser. use Apache::SubProcess qw(exec); my $r = shift; $r->send_http_header('text/plain'); exec "/usr/bin/cal"; print "NOT REACHED\n"; overrides built-in exec() function and sends the output to the browser. As you can see the print statement after the exec() call will be never executed. use Apache::SubProcess (); my $r = shift; $r->send_http_header('text/plain'); my $efh = $r->spawn_child(\&env); $r->send_fd($efh); sub env { my $r = shift; $r->subprocess_env(HELLO => 'world'); $r->filename("/bin/env"); $r->call_exec; } env() is a function that sets an environment variable that can be seen by the main and sub-processes, then it executes I program via call_exec(). The main code spawn a process, and tells it to execute the env() function. This call returns an output filehandler from the spawned child process. Finally it takes the output generated by the child process and sends it to the browser via send_fd(), that expects the filehandler as an argument. use Apache::SubProcess (); my $r = shift; $r->send_http_header('text/plain'); my $fh = $r->spawn_child(\&banner); $r->send_fd($fh); sub banner { my $r = shift; # /usr/games/banner on many Unices $r->filename("/usr/bin/banner"); $r->args("-w40+Hello%20World"); $r->call_exec; } This example is very similar to the previous, but shows how can you pass arguments to the external process. It passes the string to print as a banner to via a subprocess. use Apache::SubProcess (); my $r = shift; $r->send_http_header('text/plain'); use vars qw($String); $String = "hello world"; my ($out, $in, $err) = $r->spawn_child(\&echo); print $out $String; $r->send_fd($in); sub echo { my $r = shift; $r->subprocess_env(CONTENT_LENGTH => length $String); $r->filename("/tmp/pecho"); $r->call_exec; } The last example shows how you can have a full access to STDIN, STDOUT and STDERR streams of the spawned sub process, so you can pipe data to a program and send its output to the browser. The echo() function is similar to the earlier example's env() function. The I is as follows: !/usr/bin/perl read STDIN, $buf, $ENV{CONTENT_LENGTH}; print "STDIN: `$buf' ($ENV{CONTENT_LENGTH})\n"; So in the last example a string is defined as a global variable, so it's length could be calculated in the echo() function. The subprocess reads from STDIN, to which the main process writes the string (I). It reads only a number of bytes specified by C passed to the external program via environment variable. Finally the external program prints the data that it read to STDOUT, the main program intercepts it and sends to the client's socket (browser in most cases). =head1 Module::Use - Log and Load used Perl modules C records the modules used over the course of the Perl interpreter's lifetime. If the logging module is able, the old logs are read and frequently used modules are automatically loaded. For example if configured as: use Module::Use (Counting, Logger => "Debug"); PerlChildExitHandler Module::Use it will only record the used modules when the child exists, logging everything (debug level). =head1 Apache::ConfigFile - Parse an Apache style httpd.conf config file This module parses I, or any compatible config file, and provides methods for accessing the values from the parsed file. See the module manpage for more information. =head1 Apache::Admin::Config - Object oriented access to Apache style config files C provides an object oriented interface for reading and writing Apache-like configuration files without affecting comments, indentation, or truncated lines. You can easily extract informations from the apache configuration, or manage htaccess files. See http://rs.rhapsodyk.net/devel/apache-admin-config/ for more information. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =over =item * Stas Bekman [http://stason.org/] =back =head1 Authors =over =item * Stas Bekman [http://stason.org/] =back Only the major authors are listed above. For contributors see the Changes file. =cut