• mod_perl puts a perl interpreter within the httpd server
• you can write "handlers" to alter many pieces of request processing - uri mapping, authentication, content generation, logging, ...
• more powerful and general than .cgi, and very fast
  ... though usually mod_perl cgi is plenty.
• The general idea is simple. For the details you'll need some study. The point here is to just get a taste, see what's possible, and understand the basic idea of how this approach works.

• Hello World - in action
• Hello.pm source
• configuration files
• How it works:
  1. the request url matches a <Location> directive (or <Files> or <Directory> or .htaccess specification ) in mar22.conf ( effectively part of httpd.conf )
  2. The directives
        SetHandler perl-script
   PerlHandler Mar22::Hello
     specify a "content handler", i.e. a sub handler{} for that kind of request.
  3. The Mar22::Hello.pm module has the perl code, which must have the following basic form:

      use Apache::Constants qw(:common);
      sub handler {
        my $r = shift;  # Apache request object
        # do stuff
        return OK;      # return a valid Apache status code.
      }
      1;
     

• Other notes:
  • The module must be found, as usual, in @INC. Here we add the "modules" directory to that path in startup.pl. And, also as usual, a module like Apache::Hello means a file Apache/Hello.pm anywhere in the @INC directories, either in /usr/lib/perl somewhere or in modules/ .
  • Since the .pm module is loaded when needed, the httpd sever must be restarted for changes to take effect.
  • This kind of hacking typically requires root access. Powerful, fast, versatile, and complicated.
  • There is no /hello/world file or directory anywhere...

• jims-install-mod_perl-recipe.txt - what I did September 2001 on bob
  includes apache-1.3.20 , mod_perl-1.26, mod_ssl-2.8.4
• Basically the procedure runs something like this:
  1. download and unpack sources for all 3
  2. install any other needed system libraries (i.e. OpenSSL)
  3. do ./configure; make for mod_ssl and mod_perl, which modifies apache source tree
  4. ./configure; make apache with lots of options
  5. create (or install) certificates for ssl
  6. install apache in /home/httpd
  7. edit httpd.conf
• A Royal PITA, but there you go.

• The order of events is something like
  1. postread - PerlPostReadRequestHandler or PerlInitHandler
  2. URI translation - PerlTransHandler and PerlHeaderParserHandler
  3. Access control - PerlAccessHandler
  4. Authentication - PerlAuthenHandler
  5. Authorization - PerlAuthzHandler
  6. MIME check - PerlTypeHandler
  7. PerlFixupHandler (last chance before content)
  8. Content generation
     - both "SetHandler perl-script" and PerlHandler
  9. Logging - PerlLogHandler
  10. PerlCleanupHandler (after transaction)
• The form of each handler is essentially the same as the "Hello.pm" example.
• A single request may be processed by many handlers.
• Most everything happens through the $r apache request object
• The meaning of the return value varies with the type of handler.
  For example, a PerlAccessHandler can return
  • "OK" = yes, I think we should give the client the file,
  • "FORBIDDEN" = no, don't give out the file,
  • "DECLINED" = let the next access handler deal with this,
  • "SERVER ERROR" = something weird happened
  and all of this depends on httpd.conf directives like "satisfy any".
• Handlers can push other handlers onto the stack of what this request should be give to.
• Powerful stuff, but lots of details.
• see mod_perl POD and mod_perl-refcard.pdf

• This is the one that handles your .cgi within mod_perl, basically turns a .cgi script into a PerlHandler.
• Also notices if file changes, and reloads it.

• docs/apache_API.html and mod_perl-refcard.pdf
• All information and utitilies to modify the request, including
  • get/set doc info : $r->uri, $r->content_type, etc.
  • get httpd headers
  • read POSTed data and cgi params
  • create outgoing data, $r->print()
  • get per-transaction server_port etc.
  • various levels of logging warning and errors
  • redirection, including proxy stuff, $r->internal_redirect($uri)
  • get configuration info from .conf , $r->dir_config()

• Another, more substantial and realistic content handler
• test.ehtml - in action
• test.ehtml source
• mar22.conf configuration
• ESSI-defs.pl - SSI tag definitions
• Apache::ESSI - the content handler; applies ESSI-defs.pl subroutines to test.ehtml's tags

• /fri_only - in action 1
• /weekends_only - in action 2
• somedays_only/ - "real" url
• mar22.conf configuration
• Apache::DayLimit - access handler source code
• do "tail /home/httpd/logs/error_log" to see handler's error

 <Perl>
 my $hostname = `hostname`;
 $User = 'www'    if $hostname =~ /^papa-bear/;
 $User = 'httpd'  if $hostname =~ /^momma-bear/;
 $User = 'nobody' if $hostname =~ /^goldilocks/;
 </Perl>

• Apache::VMonitor
  • config in mar22.conf
  • see apacheweek article
  • (M'boro IP addresses only)
• image modification on the fly (images)
  • config (once again) in mar22.conf
  • uses Apache::Magick (from Writing Apache Modules), which uses Image::Magick
  • (This seems to be inconsistent - I can't manage to change an image's size on the fly - but I can apply some filters and change the image type)
  • examples
    • colin.jpg rotate
    • colin.jpg netagive, framed
    • saturn.gif as jpeg quality=10
    • saturn.gif cropped 500x500+100+100 (url escaped)

• http://perl.apache.org/
• netcraft server survey
• securityspace survey of apache modules

• perl.apache.org - the official mod_perl site
  • mod_perl Guide - installation, using it, examples - the whole schmeil

• Take23 - mod_perl news and discussions
• mod_perl POD
• Apache HTTPD Server Version 1.3 docs
• Apache / mod_perl API (local copy of chap 9 from Writing Apache Modules)
• mod_perl-refcard.pdf

• Writing Apache Modules with Perl and C, the O'Reilly book by Lincoln Stein and Doug MacEachern
  • Chap 6 - Authentication and Authorization
  • Chap 7 - Other Request Phases
  • Chap 9 - Perl API Reference Guide
• mod_perl Pocket Reference - another O'Reilly book.

• If you want to do this stuff seriously, I recommend getting and reading the book. A few chapters are online which can give you a taste; see above.

  Otherwise, what you want to do is get a feel for what's out there and how its been done so you can snarf various code fragments and know basically what's going on.

  So, from the stuff above, at least peruse the examples from this lecture and the material in the mod_perl guide, http://perl.apache.org/guide/, depending on what strikes your fancy. The $r request object, Apache API, response codes and all that are described in detail in this reference chapter from the Apache Modules book; you may want to refer to that as you're looking at the examples.

• install mod_perl and any other Apache::* that strikes your fancy. (You'll need to have do this on your linux box, since playing with any of it typically means about with httpd.conf - though using .htaccess is, I suppose, a possibility on bob)
• Try any of the access control, proxy, or other examples in chap 6 or 7 of the online book.
• Install the ESSI example 2 above on your machine. Add your own tags.
• Write a handler of your own as a replacement (or supplement) to one of your .cgi scripts.