Introduction%20to%20mod_perl

1
Introduction to mod_perl

• Issac Goldstand
• Mirimar Networks
• www.mirimar.net
• margol_at_beamartyr.net

2
mod_what?

• Apache module which exposes the entire Apache API
  via Perl
• Allows us to write handlers and filters
• mod_perl is for Apache 1.3, mod_perl2 is for
  Apache 2.x

3
CGI on Steroids

• Classic known use of mod_perl is to simply cache
  compiled Perl code in memory
• Dont put this down its been known to be up to
  100 times faster than CGI scripts with mod_cgi
• (In mod_perl2, this is accomplished by using
  ModPerlRegistry to handle all CGI scripts)
• But Thats barely scratching the surface of
  mod_perls abilities

4
Whats your handle?

• Apache defines a request chain which each request
  must pass through
• Along this chain are various hooks
• A module defines a handler which intercepts the
  request at a specific hook and decides how to
  handle the request

5
I/O Filters

• Perl modules exist to capture STDOUT stream
• Limited to STDOUT only
• Not the easiest interfaces in the world
• Can only capture output from other Perl code
• Apache 2.0 introduces I/O filters for both
  incoming requests and outgoing responses.

6
Protocol Handlers

• Apache 2.0 is designed to be a more generic
  server which can handle protocols other than HTTP
• Simple implementation of SMTP exists in Perl
  (ApacheSMTP)
• You can write your own custom protocols
• This is somewhat beyond the scope of this lecture

7
(No Transcript)
8
PostReadRequest

• Hook that comes immediately after request is read
  by Apache and headers are processed
• Useful for preprocessing that needs to be done
  once per request
• Example Set special Perl variable T
  (BASETIME) for use with M A and C filetests

9
Trans(lation)

• Used to manipulate (or translate) the requested
  URI
• Many standard modules, such as mod_alias and
  mod_rewrite use this heavily
• Useful to rewrite a magic URI into a more
  standard query-string
• Example http//news.com/stories/27/02/2006/005.ht
  ml becomes http//news.com/cgi-bin/story?day27mo
  nth02year2006story005

10
MapToStorage

• Used to map final URI to a physical file
• In Apache 1.3, this was part of Trans phase
• Normally, default behavior is what youll want
  here mod_alias will usually do anything fancy
  you could want
• Useful for shaving some time off the request by
  bypassing Apaches attempt to find a physical
  file if you have a custom response handler

11
HeaderParser

• Similar to PostReadRequest, except now we have
  mapped the request to its final ltLocationgt,
  ltDirectorygt, ltFilegt, etc containers
• Useful to determine if we need to do anything
  special with the requests before processing the
  heavy-lifting parts of the request phase

12
Init

• Special shortcut handler that points to either
  PostReadRequest or HeaderParser, depending on
  its context
• In ltLocationgt or other blocks that refer to a
  specific URI, physical path or filename, it will
  be HeaderParser
• Anywhere else, it will be PostReadRequest
• Regardless, it is guaranteed to be the first
  handler called for its given context

13
Access

• First of the AAA series
• Used for access restrictions
• IP Based
• Time/Date based
• Other global, and external factors not
  connected to the specific user
• Useful if we want to deny access to all users
  based on certain criteria

14
Authentication (Authen)

• Second AAA handler
• Used to verify the credentials presented by a
  user
• Perform login
• Validate existing session/ticket/cookie
• Only performed when the requested resource is
  marked as password protected meaning well need
  AuthName, AuthType and at least one require
  directive (or their custom equivalents)

15
Authorization (Authz)

• Final AAA phase
• Decides whether the credentials validated in the
  Authentication phase can access the requested
  resource
• Closely linked to Authen phase, and will only run
  after a successful Authen handler

16
Type

• Used to set the proper MIME type (Content-Type)
  for the response
• Typically, also sets other type information, such
  as content language
• Tends not to be overly used, as its an all or
  nothing scenario, and things can still be
  changed in the Fixup phase

17
Fixup

• Last chance to change things before the response
  is generated
• A good chance to populate the environment with
  variables (such as mod_env, and mod_ssl in Apache
  1)
• Useful for passing information in an arbitrary
  manner to the response handler (which may be an
  external process, such as with mod_cgi, or in a
  non-apache specific language, such as Registry
  scripts, PHP, Ruby, Python, etc)

18
Response

• The most popularly used handler phase
• Arguably the most important phase
• Used to generate and return the response to the
  client
• Well use this handler when (time permitting) we
  show an example

19
Log

• Just because weve satisfied the client doesnt
  mean our work is done!
• Used to log the information known about the
  request, user and response
• Executed regardless of what happens in the
  previous handlers
• Can be used to add custom information to the logs
  (ads displayed, cookie values, etc)

20
Cleanup

• The last phase
• Actually, exists only in mod_perl and not in
  Apache itself
• Happens after the client is disconnected, but
  before request object is destroyed
• Used to cleanup anything after the request (temp
  files, locks, etc)
• While the client wont have to wait for this,
  Apache will not re-queue the Perl interpreter
  until it finishes!

21
Example Hello World

• The moment weve all been waiting for!

fileMyApache2/Hello.pm package
MyApache2Hello use strict use warnings use
Apache2RequestRec () use Apache2RequestIO
() use Apache2Const -compile gt 'OK' sub
handler my r shift
r-gtcontent_type('text/plain')
r-gtprint('Hello, Apache2/mod_perl World!')
return Apache2ConstOK 1
22
Preparing httpd.conf
Dont forget to AddModule perl_module
modules/mod_perl.so PerlModule MyApache2Hello lt
Location /hellogt SetHandler modperl
PerlResponseHandler MyApache2Hello lt/Locationgt
23
Response
Hello, Apache2/mod_perl World!
24
I/O Filters

• Used to make transformations to the request and
  response without modifying the core handler
  code
• Multiple filters can be used in conjunction with
  one another
• Example Content compression, obfuscation,
  machine translation (eg, English -gt German)

25
Buckets and Bucket Brigades

• In the filter implementation, chunks of data,
  called buckets, are passed between the various
  filters
• The pipeline of buckets is called a bucket brigade

26
Disclaimer

• I dont like the picture on the next slide
• Its the picture used on the mod_perl website
  (and the most popular and only useful picture in
  google images when searching for bucket brigades)
• I personally find it to be somewhat inaccurate,
  but since lots of other people seem to find it
  helpful, well look (or at least glance) at it
  anyway

27
(No Transcript)
28
My humble version
? From request handler
To network ?
29
Modifying data
? From request handler
To network ?
30
Adding data
? From request handler
To network ?
31
Removing data
? From request handler
To network ?
32
Bucket brigade code sample
fileMyApache2/InputRequestFilterLC.pm package
MyApache2InputRequestFilterLC use strict use
warnings use base qw(Apache2Filter) use
Apache2Connection () use APRBrigade () use
APRBucket () use Apache2Const -compile gt
'OK' use APRConst -compile gt 'common'
33
sub handler FilterRequestHandler my (f,
bb, mode, block, readbytes) _at__ my c
f-gtc my bb_ctx APRBrigade-gtnew(c-gtpool
, c-gtbucket_alloc) my rv
f-gtnext-gtget_brigade(bb_ctx, mode, block,
readbytes) return rv unless rv
APRConstSUCCESS while (!bb_ctx-gtis_empty
) my b bb_ctx-gtfirst if
(b-gtis_eos) bb-gtinsert_tail(b)
last my len
b-gtread(my data) b
APRBucket-gtnew(bb-gtbucket_alloc, lc data) if
len b-gtremove
bb-gtinsert_tail(b)
Apache2ConstOK 1
34
Looks fun, eh?

• Filters are expected to manage their own state
• Filters are expected to take care of the buckets
  and brigades they are connected to
• Filters are expected to obey special buckets,
  like flush or EOS (end of stream)

35
mod_perl to the rescue!

• mod_perl provides an alternate stream oriented
  filter scheme, for the weak of heart
• In this scheme, two methods, read() and print()
  do the bulk of the work
• mod_perl manipulates the bucket brigades for us
  behind the scenes

36
Stream oriented filter sample
fileMyApache2/FilterReverse1.pm package
MyApache2FilterReverse1 use strict use
warnings use base qw(Apache2Filter) use
Apache2Const -compile gt qw(OK) use constant
BUFF_LEN gt 1024 sub handler
FilterRequestHandler my f shift
while (f-gtread(my buffer, BUFF_LEN))
for (split "\n", buffer)
f-gtprint(scalar reverse _)
f-gtprint("\n")
Apache2ConstOK 1
37
Setup in httpd.conf
Dont forget to AddModule perl_module
modules/mod_perl.so PerlModule MyApache2Hello Pe
rlModule MyApache2FilterReverse1 ltLocation
/hellogt SetHandler modperl
PerlResponseHandler MyApache2Hello
PerlOutputFilterHandler MyApache2FilterReverse1
lt/Locationgt
38
Response
!dlroW lrep_dom/2ehcapA ,olleH
39
Summary

• Apache 2.0 provides a very rich API
• Handlers to customize various phases of the
  connection and request cycles
• I/O filters for on-the-fly data modification,
  both in and out of Apache
• mod_perl exposes this API for us, and in many
  ways tries to simplify it and make it feel
  somewhat more natural for Perl programmers

40
For more information

• perl.apache.org
• modperl_at_perl.apache.org
• Several books authored by mod_perls authors
  published OReilly (Some of which may be
  auctioned tomorrow!)

41
Thank You!

For more information Issac Goldstand
margol_at_mirimar.net http//www.beamartyr.net/ http
//www.mirimar.net/