You are on page 1of 342

Tutorial Slides: mod_perl 2.

0 By Example

by Stas Bekman http://stason.org/ <stas@stason.org>

OSCON US 2005 Mon, August 1 2005 Portland, Oregon, USA

Tutorial Slides: mod_perl 2.0 By Example

Slide 1

Stas Bekman

This talk is available from: http://stason.org/talks/

Tutorial Slides: mod_perl 2.0 By Example

Slide 2

Stas Bekman

Tutorial Slides: mod_perl 2.0 By Example

Slide 3

Stas Bekman

Last modified Fri Jul 22 14:05:25 2005 GMT

Tutorial Slides: mod_perl 2.0 By Example

Slide 4

Stas Bekman

Getting Your Feet Wet With mod_perl 2.0

Slide 5

Stas Bekman

1 Getting Your Feet Wet With mod_perl 2.0

Getting Your Feet Wet With mod_perl 2.0

Slide 6

Stas Bekman

1.0 Slide 7 Stas Bekman .1About Prerequisites Installation Configuration Server Launch and Shutdown Registry Scripts Handler Modules Getting Your Feet Wet With mod_perl 2.

0. mod_perl DSO: 2.1.0 Slide 8 Stas Bekman .8.47 static mod_perl: 2.2Prerequisites Apache 2.6.51 Perl.1 (no ithreads required) threaded: 5. depending on MPM: prefork: 5.0 is required.0.0 w/ithreads The installation details are in the handouts Getting Your Feet Wet With mod_perl 2.

Static prefork build 5.6.2 or higher w/o ithreads Static threaded build 5.1 or higher w/ithreads enabled Getting Your Feet Wet With mod_perl 2.pm Perl 5.1 or higher w/ ithreads 5.8.0 Slide 9 Stas Bekman .8.8.0 or higher w/ ithreads threads.

tar.0 Slide 10 Stas Bekman .0.x.gz % tar -xvzf mod_perl-2.xx.PL MP_APXS=$HOME/httpd/bin/apxs % make && make test && make install MP_APXS is a full path to the apxs executable Getting Your Feet Wet With mod_perl 2.3mod_perl Installation % lwp-download \ http://perl.0 % perl Makefile.gz % cd modperl-2.tar.org/dist/mod_perl-2.apache.1.01.

0 compatibility layer PerlModule Apache2::compat Getting Your Feet Wet With mod_perl 2.so Enable the 1.4Configuration Enable DSO: LoadModule perl_module modules/mod_perl.1.0 Slide 11 Stas Bekman .

9.5Server Launch and Shutdown Start: % $HOME/httpd/prefork/bin/apachectl start % tail -f $HOME/httpd/prefork/logs/error_log [Fri Jul 22 09:39:55 2005] [notice] Apache/2.55-dev OpenSSL/0.7 configured -.8.55-dev (Unix) mod_ssl/2.1.resuming normal operations Stop: Getting Your Feet Wet With mod_perl 2.7e DAV/2 mod_perl/2.0.2-dev Perl/v5.0 Slide 12 Stas Bekman .0.0.

0 Slide 13 Stas Bekman .% $HOME/httpd/prefork/bin/apachectl stop Getting Your Feet Wet With mod_perl 2.

1.0 Slide 14 Stas Bekman .0/perl/ <Location /perl/> SetHandler perl-script PerlResponseHandler ModPerl::Registry PerlOptions +ParseHeaders Options +ExecCGI </Location> Restart the server Getting Your Feet Wet With mod_perl 2.6Registry Scripts Configuration Alias /perl/ /home/httpd/httpd-2.

A simple script: #!/usr/bin/perl print "Content-type: text/plain\n\n".pl Request: % lwp-request http://localhost/perl/rock.0 rocks! Getting Your Feet Wet With mod_perl 2. Make it executable and readable: % chmod a+rx /home/httpd/httpd-2.0 rocks!\n".0/perl/rock.pl mod_perl 2.0 Slide 15 Stas Bekman . print "mod_perl 2.

use strict. use Apache2::Const -compile => qw(OK).0/perl/MyApache2/Rocks.0 Slide 16 Stas Bekman . use Apache2::RequestIO (). $r->content_type(’text/plain’). # Getting Your Feet Wet With mod_perl 2. sub handler { my $r = shift. return Apache2::Const::OK. } 1.7Handler Modules # /home/httpd/httpd-2. use warnings. print "mod_perl 2.0 rocks!\n".pm package MyApache2::Rocks. use Apache2::RequestRec ().1.

0/perl).Adjust @INC via a startup file use lib qw(/home/httpd/httpd-2.0/perl/startup.pl Configure: <Location /rocks> SetHandler perl-script PerlResponseHandler MyApache2::Rocks </Location> Restart server Getting Your Feet Wet With mod_perl 2. loaded from httpd.0 Slide 17 Stas Bekman .conf: PerlRequire /home/httpd/httpd-2.

0 rocks! Getting Your Feet Wet With mod_perl 2.0 Slide 18 Stas Bekman .Issue request: % lwp-request http://localhost/rocks mod_perl 2.

New Concepts Slide 19 Stas Bekman .

2 New Concepts New Concepts Slide 20 Stas Bekman .

2.1About Exceptions Bucket Brigades New Concepts Slide 21 Stas Bekman .

2Exceptions Apache and APR API return a status code for almost all methods In C you must check return value of each call It makes it really hard/slow to prototype things It makes the code hard to read It’s easy to forget to check the return values -.2.causing problems later It complicates the API. when you may want to return other values New Concepts Slide 22 Stas Bekman .

we throw exceptions New Concepts Slide 23 Stas Bekman . Instead of returning status codes. while leaving you in control.APR::Error handles APR/Apache/mod_perl exceptions for you.

1024). Perl will intercept the exception object and die() with a proper error message../TestError/runtime. [Wed Jun 09 07:25:25 2004] [error] [client 127. everything works transparently my $rlen = $sock->recv(my $buff.0.pm line 124 New Concepts Slide 24 Stas Bekman .0..1] APR::Socket::recv: (11) Resource temporarily unavailable at .If you don’t catch those exceptions.

if ($tries++ < 3) { # sleep 250msec select undef. 0.. undef.25. # .. SIZE) }. undef. use APR::Status ().you can. goto RETRY. RETRY: my $rlen = eval { $sock->recv(my $buffer. my $tries = 0.. if ($@) { die $@ unless ref $@ && APR::Status::is_EAGAIN($@). } else { # do something else } } warn "read $rlen bytes\n" # New Concepts Slide 25 Stas Bekman .If you want to catch an exception -.

APR::Status::is_FOO($@) is for complicated cases most of the time it’ll be a simple compare: use APR::Const -compile => qw(TIMEUP); # some code throwing an exception if ($@ && ref $@ && $@ == APR::Const::TIMEUP) { # do something }

New Concepts

Slide 26

Stas Bekman

APR::Error uses Perl operator overloading: in boolean and numerical contexts -- gives the status code in the string context -- the full error message it is called APR::Error as it is used by mod_perl APR apps written in Perl

New Concepts

Slide 27

Stas Bekman

2.3Bucket Brigades

New Concepts

Slide 28

Stas Bekman

Apache 2.0 implements request and response data flow filtering Modules can filter each other’s output No need to modify Apache to accomodate SSL, compressions, transformation filters. The Bucket Brigades technology was introduced to make IO filtering efficient and avoid unnecessary copying.

New Concepts

Slide 29

Stas Bekman

Buckets: A bucket represents a chunk of data. Buckets linked together comprise a brigade. Each bucket in a brigade can be modified, removed and replaced with another bucket. Bucket types: files, data blocks, flush and end of stream indicators, pools, etc. To manipulate a bucket one doesn’t need to know its internal representation.

New Concepts

Slide 30

Stas Bekman

Bucket Brigades: A stream of data is represented by bucket brigades. Filters manipulate brigades one by one (adding/modifying/removing buckets) ... and pass the brigade to the next filter on the stack

New Concepts

Slide 31

Stas Bekman

Here’s an imaginary bucket brigade after it has passed through several filters. New Concepts Slide 32 Stas Bekman .

More about BBs when we talk about protocols and filters New Concepts Slide 33 Stas Bekman .

Introducing mod_perl Handlers Slide 34 Stas Bekman .

3 Introducing mod_perl Handlers Introducing mod_perl Handlers Slide 35 Stas Bekman .

3.1About Handler Anatomy mod_perl Handlers Categories Single Phase’s Multiple Handlers Behavior Introducing mod_perl Handlers Slide 36 Stas Bekman .

PerlResponseHandler configures the response callback.3.2Handler Anatomy Apache distinguishes between numerous phases Each phase provides a hook: ap_hook_<phase_name> These hooks are used by modules to alter the default Apache behavior Hooks are usually referred to as handlers or callbacks Naming convention: PerlFooHandler e. Introducing mod_perl Handlers Slide 37 Stas Bekman .g.

"\n"). use Apache2::RequestIO (). $r->print("The time is: " . use warnings. } 1. scalar(localtime) . use Apache2::RequestRec (). use Apache2::Const -compile => qw(OK). use strict. sub handler { my $r = shift. return Apache2::Const::OK. Introducing mod_perl Handlers Slide 38 Stas Bekman . $r->content_type(’text/plain’).package MyApache2::CurrentTime.

Configuring the response handler: PerlModule MyApache2::CurrentTime <Location /time> SetHandler modperl PerlResponseHandler MyApache2::CurrentTime </Location> A request to http://localhost/time returns the curent time Introducing mod_perl Handlers Slide 39 Stas Bekman .

3.3mod_perl Handler Categories The mod_perl handlers can be divided by their application scope in several categories: Server life cycle PerlOpenLogsHandler PerlPostConfigHandler PerlChildInitHandler PerlChildExitHandler Protocols PerlPreConnectionHandler PerlProcessConnectionHandler Introducing mod_perl Handlers Slide 40 Stas Bekman .

Filters PerlInputFilterHandler PerlOutputFilterHandler HTTP Protocol PerlPostReadRequestHandler PerlTransHandler PerlMapToStorageHandler PerlInitHandler PerlHeaderParserHandler PerlAccessHandler PerlAuthenHandler PerlAuthzHandler PerlTypeHandler PerlFixupHandler PerlResponseHandler PerlLogHandler PerlCleanupHandler Introducing mod_perl Handlers Slide 41 Stas Bekman .

3.4Stacked Handlers Phases’ behavior varies when there is more then one handler registered to run for the same phase. The following table specifies each handler’s behavior in this situation: Introducing mod_perl Handlers Slide 42 Stas Bekman .

Directive Type -------------------------------------PerlOpenLogsHandler RUN_ALL PerlPostConfigHandler RUN_ALL PerlChildInitHandler VOID PerlChildExitHandler VOID PerlPreConnectionHandler RUN_ALL PerlProcessConnectionHandler RUN_FIRST PerlPostReadRequestHandler PerlTransHandler PerlMapToStorageHandler PerlInitHandler PerlHeaderParserHandler PerlAccessHandler PerlAuthenHandler PerlAuthzHandler PerlTypeHandler PerlFixupHandler PerlResponseHandler PerlLogHandler PerlCleanupHandler PerlInputFilterHandler PerlOutputFilterHandler RUN_ALL RUN_FIRST RUN_FIRST RUN_ALL RUN_ALL RUN_ALL RUN_FIRST RUN_FIRST RUN_FIRST RUN_ALL RUN_FIRST RUN_ALL RUN_ALL VOID VOID # Introducing mod_perl Handlers Slide 43 Stas Bekman .

The types: VOID Executed in the order they have been registered disregarding their return values. Though in mod_perl they are expected to return Apache2::Const::OK. Introducing mod_perl Handlers Slide 44 Stas Bekman . RUN_ALL Executed in the order they have been registered until the first handler that returns something other than Apache2::Const::OK or Apache2::Const::DECLINED.

RUN_FIRST Executed in the order they have been registered until the first handler that returns something other than Apache2::Const::DECLINED. the next handler in the chain will be run. Introducing mod_perl Handlers Slide 45 Stas Bekman . If the return value is Apache2::Const::OK the next phase will start. In all other cases the execution will be aborted. If the return value is Apache2::Const::DECLINED.

Server Life Cycle Handlers Slide 46 Stas Bekman .

4 Server Life Cycle Handlers Server Life Cycle Handlers Slide 47 Stas Bekman .

1About Server Life Cycle Startup Phases Demonstration Module PerlOpenLogsHandler PerlPostConfigHandler PerlChildInitHandler PerlChildExitHandler Server Life Cycle Handlers Slide 48 Stas Bekman .4.

2Apache 2.0 Server Life Cycle Server Life Cycle Handlers Slide 49 Stas Bekman .4.

Server Life Cycle Handlers Slide 50 Stas Bekman .

Shutdown: child_exit Server Life Cycle Handlers Slide 51 Stas Bekman .1. open_logs. threads. Spawn workers: procs. Restart to test graceful restarts 3. open_logs. Parse the configuration file. post_config 4. mix Run child_init for each spawned process 5. Process requests over connections 6. post_config 2. Parse the configuration file.

use File::Spec::Functions.4. use warnings. use Apache2::ServerUtil (). "startup_log". use Fcntl qw(:flock). use Apache2::Log (). use Apache2::Const -compile => ’OK’. # Server Life Cycle Handlers Slide 52 Stas Bekman . "logs".1Startup Phases Demonstration Module package MyApache2::StartupLog. my $log_path = catfile Apache2::ServerUtil::server_root. my $log_fh.2. use strict.

$s->warn("opening the log file: $log_path"). } sub child_init { my($child_pool. say("process $$ is born to reproduce"). my $oldfh = select($log_fh). say("process $$ is born to serve"). return Apache2::Const::OK. $s) = @_. select($oldfh). $log_pool. } sub post_config { my($conf_pool. open $log_fh. $temp_pool. $| = 1. say("configuration is completed"). $temp_pool. } # Server Life Cycle Handlers Slide 53 Stas Bekman . return Apache2::Const::OK. $s) = @_. return Apache2::Const::OK. $s) = @_.sub open_logs { my($conf_pool. $log_pool. ">>$log_path" or die "can’t open $log_path: $!".

" says: $_[0]\n". $caller. } } # Server Life Cycle Handlers Slide 54 Stas Bekman . say("process $$ now exits"). scalar(localtime). } else { # when the log file is not open warn __PACKAGE__ .sub child_exit { my($child_pool.%-11s: %s\n". if (defined $log_fh) { flock $log_fh. $s) = @_. $_[0]. printf $log_fh "[%s] . LOCK_EX. } sub say { my($caller) = (caller(1))[3] =~ /([^:]+)$/. return Apache2::Const::OK. LOCK_UN. flock $log_fh.

} 1. END { my $msg = "process $$ is shutdown". # Server Life Cycle Handlers Slide 55 Stas Bekman . say($msg). "-" x 20 if $$ == $parent_pid.= "\n". $msg .my $parent_pid = $$.

conf configuration section: PerlModule PerlOpenLogsHandler PerlPostConfigHandler PerlChildInitHandler PerlChildExitHandler MyApache2::StartupLog MyApache2::StartupLog::open_logs MyApache2::StartupLog::post_config MyApache2::StartupLog::child_init MyApache2::StartupLog::child_exit Server Life Cycle Handlers Slide 56 Stas Bekman .And the httpd.

post_config: configuration is completed 2004] .open_logs : process 24189 is born to reproduce 2004] .END : process 24189 is shutdown 2004] 2004] 2004] 2004] 2004] 2004] open_logs : post_config: child_init : child_init : child_init : child_init : process 24190 configuration process 24192 process 24193 process 24194 process 24195 is is is is is is born to reproduce completed born to serve born to serve born to serve born to serve Apache restarts itself Server Life Cycle Handlers Slide 57 Stas Bekman .% bin/apachectl start # logs/startup_log>: [Sun Jun 6 01:50:06 [Sun Jun 6 01:50:06 [Sun Jun 6 01:50:07 -------------------[Sun Jun 6 01:50:08 [Sun Jun 6 01:50:08 [Sun Jun 6 01:50:09 [Sun Jun 6 01:50:09 [Sun Jun 6 01:50:09 [Sun Jun 6 01:50:09 2004] .

% bin/apachectl stop [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 [Sun Jun 6 01:50:10 -------------------2004] 2004] 2004] 2004] 2004] 2004] 2004] 2004] 2004] child_exit END child_exit END child_exit child_exit END END END : : : : : : : : : process process process process process process process process process 24193 24193 24194 24194 24195 24192 24192 24195 24190 now exits is shutdown now exits is shutdown now exits now exits is shutdown is shutdown is shutdown All processes run the END block on shutdown Server Life Cycle Handlers Slide 58 Stas Bekman .

may run open_logs and post_config more than once the END blocks may be run more times. The only sure thing -. I used prefork MPM for this demo MPMs.each of these phases runs at least once Server Life Cycle Handlers Slide 59 Stas Bekman . when threads are involved. like winnt.The presented behavior varies from MPM to MPM.

Protocol Handlers Slide 60 Stas Bekman .

5 Protocol Handlers Protocol Handlers Slide 61 Stas Bekman .

1About Connection Cycle Phases PerlPreConnectionHandler PerlProcessConnectionHandler Socket-based Protocol Module Bucket Brigades-based Protocol Module Protocol Handlers Slide 62 Stas Bekman .5.

POP3. several HTTP requests can be served over a single connection.g.5. when a response includes several images. HTTP. Each connection may be served by different connection protocols.g.2Connection Cycle Phases Each child server is engaged in processing connections.. SMTP.. Protocol Handlers Slide 63 Stas Bekman . etc. e. e. Each connection may include more than one request.

Connection Life Cycle diagram: Protocol Handlers Slide 64 Stas Bekman .

Protocol Handlers Slide 65 Stas Bekman .

5. but before it is handed off to a protocol module to be served.2. Protocol Handlers Slide 66 Stas Bekman .1PerlPreConnectionHandler The pre_connection phase happens just after the server accepts the connection.

The core server uses this phase to setup the connection record based on the type of connection that is being used. mod_perl itself uses this phase to register the connection input and output filters.It gives modules an opportunity to modify the connection as soon as possible and insert filters if needed. Protocol Handlers Slide 67 Stas Bekman .

0 pre_connection is the earliest general phase So now we can invoke the Apache2::Reload handler during the pre_connection phase if the interpreter’s scope is: PerlInterpScope connection Protocol Handlers Slide 68 Stas Bekman . It was invoked during post_read_request. In mod_perl 2.0 Apache::Reload was used to automatically reload modified since the last request Perl modules. the first HTTP request’s phase.Apache2::Reload: In mod_perl 1.

Protocol Handlers Slide 69 Stas Bekman . where there are several requests coming on the same connection and only one handled by mod_perl and the others by the default images handler the Perl interpreter won’t be available to other threads while the images are being served.Though this is not good for a production server.

} A pre_connection handler accepts one argument: connection record Protocol Handlers Slide 70 Stas Bekman .Skeleton: sub handler { my $c = shift... # . return Apache2::Const::OK.

use Apache2::Connection (). if (exists $bad_ips{$ip}) { warn "IP $ip is blocked\n". sub handler { my $c = shift.0. my %bad_ips = map {$_ => 1} qw(127. # Protocol Handlers Slide 71 Stas Bekman .0.0.1 10. use Apache2::Const -compile => qw(FORBIDDEN OK). return Apache2::Const::FORBIDDEN.0.Block by IP example: package MyApache2::BlockIP2. } return Apache2::Const::OK. } 1.4). my $ip = $c->remote_ip.

Configuration PerlPreConnectionHandler MyApache2::BlockIP2 Apache simply drops the connection if the IP is blacklisted Almost no resources are wasted Protocol Handlers Slide 72 Stas Bekman .

5. Protocol Handlers Slide 73 Stas Bekman .2PerlProcessConnectionHandler The process_connection phase is used to process incoming connections.2.

POP3.Only protocol modules should assign handlers for this phase.). Protocol Handlers Slide 74 Stas Bekman .. etc. FTP.g. The only way to run protocol servers different than the core HTTP is inside dedicated virtual hosts. as it gives them an opportunity to replace the standard HTTP processing with processing for some other protocols (e.

return Apache2::Const::OK. # ... $sock->opt_set(APR::Const::SO_NONBLOCK. 0). my $sock = $c->client_socket. } arg1: a connection record object a socket object: retrieved from $c must set the socket to blocking IO mode Protocol Handlers Slide 75 Stas Bekman .process_connection skeleton: sub handler { my ($c) = @_.

Using the connection socket to read and write the data.Let’s look at the following two examples of connection handlers: 1. 2. Protocol Handlers Slide 76 Stas Bekman . Using bucket brigades to accomplish the same and allow for connection filters to do their work.

5. Protocol Handlers Slide 77 Stas Bekman .1Socket-based Protocol Module The MyApache2::EchoSocket module simply echoes the data read back to the client. This module’s implementation works directly with the connection socket and therefore bypasses connection filters if any.2.2.

Configuration: Listen 8010 <VirtualHost _default_:8010> PerlModule MyApache2::EchoSocket PerlProcessConnectionHandler MyApache2::EchoSocket </VirtualHost> use the Listen and <VirtualHost> directives to bind to the non-standard port 8010: Protocol Handlers Slide 78 Stas Bekman .

Hello Hello fOo BaR fOo BaR Connection closed by foreign host.0.1.0.. Escape character is ’^]’.0. Protocol Handlers Slide 79 Stas Bekman .0.Demo: panic% httpd panic% telnet localhost 8010 Trying 127. Connected to localhost (127..1).

use Apache2::Connection (). use strict. use APR::Socket (). use Apache2::Const -compile => ’OK’. use APR::Const -compile => ’SO_NONBLOCK’. use warnings FATAL => ’all’. use constant BUFF_LEN => 1024. # Protocol Handlers Slide 80 Stas Bekman .The code: package MyApache2::EchoSocket.

$sock->opt_set(APR::Const::SO_NONBLOCK => 0). $sock->send($buff).sub handler { my $c = shift. my $sock = $c->client_socket. } Apache2::Const::OK. # Protocol Handlers Slide 81 Stas Bekman . BUFF_LEN)) { last if $buff =~ /^[\r\n]+$/. while ($sock->recv(my $buff. } 1.

5.2. but this time implemented by manipulating bucket brigades.2Bucket Brigades-based Protocol Module The same module. Protocol Handlers Slide 82 Stas Bekman .2. and which runs its output through a connection output filter that turns all uppercase characters into their lowercase equivalents.

Configuration: Listen 8011 <VirtualHost _default_:8011> PerlModule MyApache2::EchoBB PerlProcessConnectionHandler MyApache2::EchoBB PerlOutputFilterHandler MyApache2::EchoBB::lowercase_filter </VirtualHost> Protocol Handlers Slide 83 Stas Bekman .

. because of the output filter. Hello hello fOo BaR foo bar As you can see the response now was all in lower case.1).0.0.0. Protocol Handlers Slide 84 Stas Bekman .1..0. Escape character is ’^]’.Demo: panic% httpd panic% telnet localhost 8011 Trying 127. Connected to localhost (127.

APR::Bucket (). use strict. Protocol Handlers Slide 85 Stas Bekman . # use APR::Const -compile => qw(SUCCESS SO_NONBLOCK). APR::Status (). use use use use use use Apache2::Connection ().The code: package MyApache2::EchoBB. APR::Socket (). APR::Brigade (). APR::Error (). use warnings FATAL => ’all’. use Apache2::Const -compile => qw(OK MODE_GETLINE).

# my $last = 0. die APR::Error::strerror($rc) unless $rc == APR::Const::SUCCESS. $c->bucket_alloc). $c->bucket_alloc). while (1) { my $rc = $c->input_filters->get_brigade($bb_in. $c->client_socket->opt_set(APR::Const::SO_NONBLOCK => 0). Protocol Handlers Slide 86 Stas Bekman . last if APR::Status::is_EOF($rc). my $bb_out = APR::Brigade->new($c->pool. Apache2::Const::MODE_GETLINE). my $bb_in = APR::Brigade->new($c->pool.sub handler { my $c = shift.

} $bb_out->insert_tail($b). $data).while (!$bb_in->empty) { my $b = $bb_in->first. last. # could do some transformation on data here $b = APR::Bucket->new($bb_out->bucket_alloc. $b->remove. } # if ($b->read(my $data)) { $last++ if $data =~ /^[\r\n]+$/. if ($b->is_eos) { $bb_out->insert_tail($b). } Protocol Handlers Slide 87 Stas Bekman .

last if $last. Apache2::Const::OK. $bb_out->destroy.my $fb = APR::Bucket::flush_create($c->bucket_alloc). } # Protocol Handlers Slide 88 Stas Bekman . $bb_out->insert_tail($fb). $c->output_filters->pass_brigade($bb_out). } $bb_in->destroy.

sub lowercase_filter : FilterConnectionHandler { my $filter = shift. # Protocol Handlers Slide 89 Stas Bekman . } return Apache2::Const::OK.use base qw(Apache2::Filter). use constant BUFF_LEN => 1024. while ($filter->read(my $buffer. BUFF_LEN)) { $filter->print(lc $buffer). } 1.

A simplified pseudo-code handler: while ($bb_in = get_brigade()) { while ($b_in = $bb_in->get_bucket()) { $b_in->read(my $data). } $bb_out->insert_tail($flush_bucket). # do something with $data $b_out = new_bucket($data). } # Protocol Handlers Slide 90 Stas Bekman . $bb_out->insert_tail($b_out). pass_brigade($bb_out).

$bb_out->insert_tail($fb). $c->output_filters->pass_brigade($bb_out).replace: my $fb = APR::Bucket::flush_create($c->bucket_alloc). # Protocol Handlers Slide 91 Stas Bekman . # with just one line: $c->output_filters->fflush($bb_out).Use fflush -.

The same handler using a single bucket brigade sub handler { my $c = shift. $b. 0). $b = $bb->next($b)) { last if $b->is_eos. Apache2::Const::MODE_GETLINE). $c->client_socket->opt_set(APR::Const::SO_NONBLOCK. while (1) { my $rc = $c->input_filters->get_brigade($bb. $b->remove. } } $c->output_filters->fflush($bb). die APR::Error::strerror($rc) unless $rc == APR::Const::SUCCESS. } Protocol Handlers Slide 92 Stas Bekman .. $data).->tail $b->insert_before($nb). $c->bucket_alloc). my $bb = APR::Brigade->new($c->pool. if ($b->read(my $data)) { last if $data =~ /^[\r\n]+$/.. last if APR::Status::is_EOF($rc). my $nb = APR::Bucket->new($bb->bucket_alloc.. # head->.->$nb->$b ->.. for (my $b = $bb->first.

} Protocol Handlers Slide 93 Stas Bekman .$bb->destroy. Apache2::Const::OK.

} $bb->destroy. die APR::Error::strerror($rc) unless $rc == APR::Const::SUCCESS. since /[\r\n]/ that we type to end the line will keep this loop running forever Protocol Handlers Slide 94 Stas Bekman . but it won’t work in the telnet mode. Apache2::Const::MODE_GETLINE). while (1) { my $rc = $c->input_filters->get_brigade($bb. my $bb = APR::Brigade->new($c->pool. $c->bucket_alloc). since we don’t modify the data. last if APR::Status::is_EOF($rc). $c->client_socket->opt_set(APR::Const::SO_NONBLOCK => 0). $c->output_filters->fflush($bb).This handler could be much simpler.

last if $data =~ /^[\r\n]+$/. } $bb->destroy. next unless $bb->flatten(my $data). Protocol Handlers Slide 95 Stas Bekman .And here is another version which slurps all the data and works with telnet my $bb = APR::Brigade->new($c->pool. $c->bucket_alloc). last if APR::Status::is_EOF($rc). $data). my $b = APR::Bucket->new($bb->bucket_alloc. $c->output_filters->fflush($bb). $bb->insert_tail($b). Apache2::Const::MODE_GETLINE). die APR::Error::strerror($rc) unless $rc == APR::Const::SUCCESS. $bb->cleanup. while (1) { my $rc = $c->input_filters->get_brigade($bb.

We will discuss the filters next Protocol Handlers Slide 96 Stas Bekman .

Input and Output Filters Slide 97 Stas Bekman .

6 Input and Output Filters Input and Output Filters Slide 98 Stas Bekman .

6.1About Your First Filter I/O Filtering Concepts Two Methods for Manipulating Data HTTP Request Versus Connection Filters Multiple Invocations of Filter Handlers Blocking Calls Input and Output Filters Slide 99 Stas Bekman .

Connection Filters Filter Initialization Phase Input and Output Filters Slide 100 Stas Bekman .mod_perl Filters Declaration and Configuration Filter Priority Types PerlInputFilterHandler PerlOutputFilterHandler PerlSetInputFilter PerlSetOutputFilter HTTP Request vs.

All-in-One Filter Input Filters Examples Output Filters Examples Input and Output Filters Slide 101 Stas Bekman .

That’s because you encounter filters so often in real life. Input and Output Filters Slide 102 Stas Bekman .6.2Your First Filter You certainly already know how filters work.

Input and Output Filters Slide 103 Stas Bekman .

Input and Output Filters Slide 104 Stas Bekman .

Input and Output Filters Slide 105 Stas Bekman .

Input and Output Filters Slide 106 Stas Bekman .

Input and Output Filters Slide 107 Stas Bekman .

Input and Output Filters Slide 108 Stas Bekman .

Input and Output Filters Slide 109 Stas Bekman .

Why using I/O filters? Instead of making the response handler code complex adjust its output with filters: each doing a simple transformation and can be: stacked repeated added/removed dynamically at run-time Input and Output Filters Slide 110 Stas Bekman .

> PerlOutputFilterHandler Modulename::handlername </Location> Input and Output Filters Slide 111 Stas Bekman .6...3A Few Quick Examples A typical Configuration <Location .

sub filter { #warn __PACKAGE__ . use warnings FATAL => ’all’. use strict. return Apache2::Const::DECLINED.The simplest pass through filter package MyApache2::FilterTryPassThrough. use Apache2::Const -compile => qw(DECLINED). # Input and Output Filters Slide 112 Stas Bekman . ": filter called\n". } 1.

use warnings FATAL => ’all’. # Input and Output Filters Slide 113 Stas Bekman . sub filter { my $f = shift. } return Apache2::Const::OK. use Apache2::Filter (). } 1. use strict.Another pass through filter package MyApache2::FilterTryPassThrough2. 1024)){ $f->print($buffer). use Apache2::Const -compile => qw(OK). while ($f->read(my $buffer.

A lowercase filter convert: <HTML><body></body></HTML> to: <html><body></body></html> Input and Output Filters Slide 114 Stas Bekman .

sub filter { my $f = shift. while ($f->read(my $buffer. use strict. use Apache2::Filter (). } 1. 1024)){ $f->print(lc $buffer). # Input and Output Filters Slide 115 Stas Bekman . use Apache2::Const -compile => qw(OK).package MyApache2::FilterTryLC. use warnings FATAL => ’all’. } return Apache2::Const::OK.

png"> </body> </html> into: <html> <body> </body> </html> Input and Output Filters Slide 116 Stas Bekman .A simple web ad blocker filter turn: <html> <body> <img src="ad.

# Input and Output Filters Slide 117 Stas Bekman . use Apache2::RequestRec ().package MyApache2::FilterTryAdBlock. use strict. use warnings FATAL => ’all’. use Apache2::Const -compile => qw(OK). use APR::Table (). use Apache2::Filter ().

} while ($f->read(my $buffer. # Input and Output Filters Slide 118 Stas Bekman .sub filter { my $f = shift. } 1. unless ($f->ctx) { $f->r->headers_out->unset(’Content-Length’). $f->print($buffer). $f->ctx(1). 1024)) { $buffer =~ s|<img[^>]+>||ig. } return Apache2::Const::OK.

png"> </body> </html> Input and Output Filters Slide 119 Stas Bekman .A more robust simple web ad blocker filter deal with "sliced" input <html> <body> <img followed by: src="ad.

use strict. Apache2::Const -compile => qw(OK). APR::Table (). # Input and Output Filters Slide 120 Stas Bekman . use use use use Apache2::Filter (). Apache2::RequestRec (). use warnings FATAL => ’all’.package MyApache2::FilterTryAdBlockAdv.

$f->print($data) if defined $data.= $buffer if defined $buffer. # Input and Output Filters Slide 121 Stas Bekman . } else { $f->ctx($data) if defined $data. } 1. } if ($f->seen_eos) { $data =~ s|<img[^>]+>||ig. $data = "" unless defined $data. $f->r->headers_out->unset(’Content-Length’).sub filter { my $f = shift. } return Apache2::Const::OK. my $data = $f->ctx. 1024)) { $data . while ($f->read(my $buffer.

my $len = defined $data ? length $data : 0.. $len).. $f->print($data) if defined $data. instead of deleting the C-L header. we can set it to the correct value: if ($f->seen_eos) { $data =~ s|<img[^>]+>||ig. $f->r->headers_out->set(’Content-Length’. Input and Output Filters Slide 122 Stas Bekman . } .since we have buffered the data up.

Input and Output Filters Slide 123 Stas Bekman .The same filter using bucket brigades package MyApache2::FilterTryAdBlockBB. APR::Bucket (). use use use use use Apache2::Filter (). use strict. Apache2::RequestRec (). APR::Table (). use warnings FATAL => ’all’. # use Apache2::Const -compile => qw(OK). APR::Brigade ().

push @data. my @data. $bdata. } return (join(’’. for (my $b = $bb->first.sub bb_data_n_eos { my $bb = shift. last if $b->is_eos. $seen_eos). $b = $bb->next($b)) { $seen_eos++. } # Input and Output Filters Slide 124 Stas Bekman . $b->read(my $bdata). $b. my $seen_eos = 0. @data).

= $buffer if defined $buffer. $data = "" unless defined $data. my $data = $f->ctx. $f->r->headers_out->unset(’Content-Length’). if ($seen_eos) { $data =~ s|<img[^>]+>||ig. my($buffer. # Input and Output Filters Slide 125 Stas Bekman . $bb) = @_. $data . } return Apache2::Const::OK. $f->print($data) if defined $data. } 1.sub filter { my($f. $seen_eos) = bb_data_n_eos($bb). } else { $f->ctx($data) if defined $data.

.6.. Input and Output Filters Slide 126 Stas Bekman .4I/O Filtering Concepts Before getting to the real filter examples a few concepts to help you wrap your head around .

Input and Output Filters Slide 127 Stas Bekman . filter the data in bucket brigades.12 Ways to Manipulate Data Apache 2. which form bucket brigades. These data chunks are stored in buckets. disregarding their kind and source or storage methods.4.6. Both input and output filters.0 considers all incoming and outgoing data as chunks of information.

Input and Output Filters Slide 128 Stas Bekman .

0 filters can: directly manipulate the bucket brigades use a simplified streaming interface the filter object acts similar to a filehandle. Input and Output Filters Slide 129 Stas Bekman .mod_perl 2. which can be read from and printed to.

4. Input and Output Filters Slide 130 Stas Bekman .6.2HTTP Request vs Connection Filters HTTP Request filters are applied on: HTTP requests body (POST) (if consumed by the content handler) HTTP response body HTTP headers are not passed through the HTTP Request filters.

Input and Output Filters Slide 131 Stas Bekman .

including HTTP headers if HTTP protocol is used Input and Output Filters Slide 132 Stas Bekman . can modify all the incoming and outgoing data.Connections filters: are applied at the connection level.

Input and Output Filters Slide 133 Stas Bekman .

Apache generates 3 bucket brigades => 3 filter invocations Input and Output Filters Slide 134 Stas Bekman . $r->print("bar"). buffered STDOUT ($|==0): $r->print("foo").6. Response handler example. $r->rflush.3Multiple Invocations of Filter Handlers a filter gets invoked as many times as the number of bucket brigades sent from an upstream filter or a content provider.4.

print and rflush => two buckets: bucket type data ---------------------1st transient foo 2nd flush print => one bucket: bucket type data ---------------------1st transient bar when the response handler returns => one bucket: bucket type data ---------------------1st eos Input and Output Filters Slide 135 Stas Bekman .

EOS may come as a last bucket in bb with data Input and Output Filters Slide 136 Stas Bekman .

Three Filter Stages: Input and Output Filters Slide 137 Stas Bekman .

# runs on the first invocation # runs on all invocations if ($f->seen_eos) { # runs on the last invocation finalize($f). $f->ctx(1). } return Apache2::Const::OK. } Input and Output Filters Slide 138 Stas Bekman .Filter skeleton demonstrating all 3 stages: sub handler { my $f = shift. unless ($f->ctx) { init($f). } process($f).

$f->ctx(1). } Input and Output Filters Slide 139 Stas Bekman .Init example: response filters changing data length have to unset the C-L header (runs once) unless ($f->ctx) { $f->r->headers_out->unset(’Content-Length’).

Processing example: lower the data case (runs on all invocations) while ($f->read(my $data. } in complex cases may need to store data in context between filter invocations Input and Output Filters Slide 140 Stas Bekman . 1024)) { $f->print(lc $data).

# store while ($f->read(my $data. READ_SIZE)) { $f->print(lc $data).Finalization example: After all data was sent out. $f->ctx($ctx). print how many times the filter was invoked my $ctx = $f->ctx. $ctx->{invoked}++. } if ($f->seen_eos) { $f->print("Filter invocated $ctx->{invoked} times"). } Input and Output Filters Slide 141 Stas Bekman .

4.6.4Blocking Calls Data propogates in stages through the filter chain (there is no pipeline) The input filter’s get_brigade() call blocks Input and Output Filters Slide 142 Stas Bekman .

The output filter’s pass_brigade() call blocks Input and Output Filters Slide 143 Stas Bekman .

return Apache2::Const::OK. my $rv = $f->next->pass_brigade($bb). my $rv = $f->next->get_brigade($bb. return Apache2::Const::OK. # Input and Output Filters Slide 144 Stas Bekman . $block. $mode.Transparent input filter: sub in { my ($f. return $rv unless $rv == APR::Const::SUCCESS. } Transparent output filter: sub out { my ($f. $bb. $mode. $readbytes) = @_. $block. return $rv unless $rv == APR::Const::SUCCESS. $bb) = @_. $readbytes). } 1.

5mod_perl Filters Declaration and Configuration Now let’s see how mod_perl filters are declared and configured. Input and Output Filters Slide 145 Stas Bekman .6.

5.1Filter Priority Types Filters are inserted into the filter chain based on their priority mod_perl provides 2 filters types: Handler Priority Value ------------------------------------------------FilterRequestHandler AP_FTYPE_RESOURCE 10 FilterConnectionHandler AP_FTYPE_PROTOCOL 30 Apache provides others as well Input and Output Filters Slide 146 Stas Bekman .6.

6.2PerlInputFilterHandler The PerlInputFilterHandler handler: registers a filter for input filtering and inserts it into the input filters chain.5. automatically AutoLoaded: PerlInputFilterHandler MyApache2::FilterTest PerlInputFilterHandler MyApache2::FilterTest::lc avoid autoloading: PerlInputFilterHandler -MyApache2::FilterTest::lc Input and Output Filters Slide 147 Stas Bekman .

automatically AutoLoaded like PerlInputFilterHandler Input and Output Filters Slide 148 Stas Bekman .6.3PerlOutputFilterHandler The PerlOutputFilterHandler handler: registers an output filter and inserts it into the output filters chain.5.

5.6.4PerlSetInputFilter mod_perl equivalent for SetInputFilter makes sure that mod_perl and non-mod_perl input filters of the same priority get inserted in the order they are configured Input and Output Filters Slide 149 Stas Bekman .

For example: PerlSetInputFilter FILTER_FOO PerlInputFilterHandler MyApache2::FilterInputFoo response handler /\ FILTER_FOO /\ MyApache2::FilterInputFoo /\ core input filters /\ network Input and Output Filters Slide 150 Stas Bekman .

6.5PerlSetOutputFilter mod_perl equivalent for SetOutputFilter makes sure that mod_perl and non-mod_perl output filters of the same priority get inserted in the order they are configured Input and Output Filters Slide 151 Stas Bekman .5.

For example: PerlSetOutputFilter INCLUDES PerlOutputFilterHandler MyApache2::FilterOutputFoo response handler \/ INCLUDES \/ MyApache2::FilterOutputFoo \/ core output filters \/ network Input and Output Filters Slide 152 Stas Bekman .

If filters have different priorities the insertion order might be different: PerlSetOutputFilter DEFLATE PerlSetOutputFilter INCLUDES PerlOutputFilterHandler MyApache2::FilterOutputFoo response handler \/ INCLUDES \/ MyApache2::FilterOutputFoo \/ DEFLATE \/ core output filters \/ network Input and Output Filters Slide 153 Stas Bekman .

add an output filter at fixup phase <Files *\.html > PerlFixupHandler MyApache2::AddFilterDyn </Files> package MyApache2::AddFilterDyn.g.5. use Apache2::Const -compile => qw(OK). use Apache2::Filter. use MyApache2::FilterObfuscate. sub handler { Input and Output Filters Slide 154 Stas Bekman .6Adding OutputFilters Dynamically one can push filter callbacks at request time e.6.

} 1. $r->add_output_filter(\&MyApache2::FilterObfuscate::handler). Input and Output Filters Slide 155 Stas Bekman .my $r = shift. return Apache2::Const::OK.

6.7HTTP Request vs....5. } Input and Output Filters Slide 156 Stas Bekman . Connection Filters method attributes set the filter type: sub handler : FilterRequestHandler { .. } sub handler : FilterConnectionHandler { .

HTTP Request filter handlers are declared using the FilterRequestHandler attribute. HTTP request input and output filters skeleton:
package MyApache2::FilterRequestFoo; use base qw(Apache2::Filter); sub input : FilterRequestHandler { my($f, $bb, $mode, $block, $readbytes) = @_; #... } sub output : FilterRequestHandler { my($f, $bb) = @_; #... } 1;
Input and Output Filters Slide 157 Stas Bekman

If the attribute is not specified, the default FilterRequestHandler attribute is assumed. Filters specifying subroutine attributes must sub-class Apache2::Filter, others only need to: use Apache2::Filter ();

Input and Output Filters

Slide 158

Stas Bekman

Request filters are usually configured in the <Location> or equivalent sections:
PerlModule MyApache2::FilterRequestFoo PerlModule MyApache2::NiceResponse <Location /filter_foo> SetHandler modperl PerlResponseHandler MyApache2::NiceResponse PerlInputFilterHandler MyApache2::FilterRequestFoo::input PerlOutputFilterHandler MyApache2::FilterRequestFoo::output </Location>

Input and Output Filters

Slide 159

Stas Bekman

Connection filter handlers are declared using the FilterConnectionHandler attribute. Connection input and output filters skeleton:
package MyApache2::FilterConnectionBar; use base qw(Apache2::Filter); sub input : FilterConnectionHandler { my($f, $bb, $mode, $block, $readbytes) = @_; #... } sub output : FilterConnectionHandler { my($f, $bb) = @_; #... } 1;
Input and Output Filters Slide 160 Stas Bekman

This time the configuration must be done outside the <Location> or equivalent sections, usually within the <VirtualHost> or the global server configuration:
Listen 8005 <VirtualHost _default_:8005> PerlModule MyApache2::FilterConnectionBar PerlModule MyApache2::NiceResponse PerlInputFilterHandler MyApache2::FilterConnectionBar::input PerlOutputFilterHandler MyApache2::FilterConnectionBar::output <Location /> SetHandler modperl PerlResponseHandler MyApache2::NiceResponse </Location> </VirtualHost>

Input and Output Filters

Slide 161

Stas Bekman

For HTTP requests the only difference between connection filters and request filters is that the former see everything: the headers and the body, whereas the latter see only the body. mod_perl provides two interfaces to filtering: a direct mapping to buckets and bucket brigades and a simpler, stream-oriented interface Following examples will explain the difference

Input and Output Filters

Slide 162

Stas Bekman

Input and Output Filters Slide 163 Stas Bekman .8Filter Initialization Phase There is a special attribute duet FilterHasInitHandler/FilterInitHandler but it’s left for your offline reading.6.5.

in the input and output modes. Slide 164 Stas Bekman Input and Output Filters . use warnings FATAL => ’all’. use use use use Apache2::RequestRec (). use strict. Apache2::Filter (). First let’s develop a simple response handler that simply dumps the request’s args and content as strings: package MyApache2::Dump. Apache2::RequestIO ().6.6All-in-One Filter The MyApache2::FilterSnoop handler silently snoops on the data that goes through request and connection filters. APR::Brigade ().

$r->content_type(’text/plain’). sub handler { my $r = shift. "\n").use APR::Bucket (). $r->args. if ($r->method_number == Apache2::Const::M_POST) { my $data = content($r). } return Apache2::Const::OK. use Apache2::Const -compile => qw(OK M_POST). $r->print("content:\n$data\n"). $r->print("args:\n". } Input and Output Filters Slide 165 Stas Bekman .

the details are unimportant here } 1. Input and Output Filters Slide 166 Stas Bekman .sub content { # see your handouts.

which is configured as: PerlModule MyApache2::Dump <Location /dump> SetHandler modperl PerlResponseHandler MyApache2::Dump </Location> Input and Output Filters Slide 167 Stas Bekman .

If we issue the following request: % echo "mod_perl rules" | POST ’http://localhost:8002/dump?foo=1&bar=2’ the response will be: args: foo=1&bar=2 content: mod_perl rules As you can see it simply dumped the query string and the posted data. Input and Output Filters Slide 168 Stas Bekman .

use Apache2::Const -compile => qw(OK DECLINED). use warnings. @_) } sub request : FilterRequestHandler { snoop("request". use strict. APR::Brigade (). Apache2::FilterRec (). APR::BucketType ().Now let’s write the snooping filter: package MyApache2::FilterSnoop. @_) } Input and Output Filters Slide 169 Stas Bekman . sub connection : FilterConnectionHandler { snoop("connection". use use use use use base qw(Apache2::Filter). APR::Bucket (). use APR::Const -compile => ’:common’.

# filter args # $mode. $bb). my $rv = $f->next->pass_brigade($bb). } return Apache2::Const::OK. $block. } Input and Output Filters Slide 170 Stas Bekman . bb_dump($type. $mode. $bb.sub snoop { my $type = shift. # read the data and pass-through the bucket brigades unchanged if (defined $mode) { # input filter my $rv = $f->next->get_brigade($bb. return $rv unless $rv == APR::Const::SUCCESS. return $rv unless $rv == APR::Const::SUCCESS. $stream. my($f. $block. } else { # output filter bb_dump($type. $readbytes). $block. $stream. $bb). $readbytes) = @_. $mode. $readbytes are passed only for input filters my $stream = defined $mode ? "input" : "output".

$bb) = @_. my @data. $c++.sub bb_dump { my($type. 2) { print STDERR " o bucket $c: $btype\n". 0. $b->type->name. push @data. $bdata. } # send the sniffed info to STDERR so not to interfere with normal # output my $direction = $stream eq ’output’ ? ">>>" : "<<<". $b = $bb->next($b)) { $b->read(my $bdata). for (my $b = $bb->first. print STDERR "[$data]\n". my $c = 1. $b. Input and Output Filters Slide 171 Stas Bekman . while (my($btype. $data) = splice @data. $stream. print STDERR "\n$direction $type $stream filter\n". } } 1.

We want to use this somewhat complicated filter to visualize how various kind of filters work. Input and Output Filters Slide 172 Stas Bekman . Since this module combines several kind of filters it’s the best to try to understand its implementation after you understand standalone filters’ implementation. At this stage what’s important is to see it at work.

Let’s snoop on connection and request filter levels in both directions by applying the following configuration: Listen 8008 <VirtualHost _default_:8008> PerlModule MyApache2::FilterSnoop PerlModule MyApache2::Dump # Connection filters PerlInputFilterHandler MyApache2::FilterSnoop::connection PerlOutputFilterHandler MyApache2::FilterSnoop::connection <Location /dump> SetHandler modperl PerlResponseHandler MyApache2::Dump # Request filters PerlInputFilterHandler MyApache2::FilterSnoop::request PerlOutputFilterHandler MyApache2::FilterSnoop::request </Location> </VirtualHost> Input and Output Filters Slide 173 Stas Bekman .

If we issue the following request: % echo "mod_perl rules" | POST ’http://localhost:8008/dump?foo=1&bar=2’ the response doesn’t get affected by the snooping filter though we can see all the diagnostics in error_log Input and Output Filters Slide 174 Stas Bekman .

q=0. The data is conveniently enclosed by [] so you can see the new line characters as well.First we can see the connection input filter at work.3 ] Input and Output Filters Slide 175 Stas Bekman .gzip. as it processes the HTTP headers. We can see that for this request each header is put into a separate brigade with a single bucket. <<< connection input filter o bucket 1: HEAP [POST /dump?foo=1&bar=2 HTTP/1.1 ] <<< connection input filter o bucket 1: HEAP [TE: deflate.

close ] <<< connection input filter o bucket 1: HEAP [Host: localhost:8008 ] <<< connection input filter o bucket 1: HEAP [User-Agent: lwp-request/2.<<< connection input filter o bucket 1: HEAP [Connection: TE.01 ] <<< connection input filter o bucket 1: HEAP Input and Output Filters Slide 176 Stas Bekman .

[Content-Length: 14 ] <<< connection input filter o bucket 1: HEAP [Content-Type: application/x-www-form-urlencoded ] <<< connection input filter o bucket 1: HEAP [ ] Here the HTTP header has been terminated by a double new line. Input and Output Filters Slide 177 Stas Bekman .

as it has been consumed by the last core connection filter. Input and Output Filters Slide 178 Stas Bekman . meaning that they were allocated from the heap memory. Notice that the HTTP request input filters will never see the bucket brigades with HTTP headers.So far all the buckets were of the HEAP type.

The following two entries are generated when MyApache2::Dump::handler reads the POSTed content: <<< connection input filter o bucket 1: HEAP [mod_perl rules] <<< request input filter o bucket 1: HEAP [mod_perl rules] o bucket 2: EOS [] The connection input filter is run before the request input filter. Input and Output Filters Slide 179 Stas Bekman .

Both filters see the same data. since they don’t modify it The bucket of type EOS indicates the end of stream. Input and Output Filters Slide 180 Stas Bekman .

However only the request output filter is filtering it at this point: >>> request output filter o bucket 1: TRANSIENT [args: foo=1&bar=2 content: mod_perl rules ] Input and Output Filters Slide 181 Stas Bekman .Next we can see that MyApache2::Dump::handler has generated its response.

Next.8.0.7c DAV/2 Connection: close Transfer-Encoding: chunked Content-Type: text/plain. Apache injects the HTTP headers: >>> connection output filter o bucket 1: HEAP [HTTP/1. 04 Jun 2004 09:13:26 GMT Server: Apache/2. charset=ISO-8859-1 ] Input and Output Filters Slide 182 Stas Bekman .1 200 OK Date: Fri.0.50-dev (Unix) mod_perl/1.4 mod_ssl/2.99_15-dev Perl/v5.9.50-dev OpenSSL/0.

the first response body’s brigade inside the connection output filter: >>> connection output filter o bucket 1: TRANSIENT [2b ] o bucket 2: TRANSIENT [args: foo=1&bar=2 content: mod_perl rules ] o bucket 3: IMMORTAL [ ] Input and Output Filters Slide 183 Stas Bekman .

Finally the output is flushed. to make sure that any buffered output is sent to the client: >>> connection output filter o bucket 1: IMMORTAL [0 ] o bucket 2: EOS [] Input and Output Filters Slide 184 Stas Bekman .

It’s called for each bucket brigade. the request input filter won’t be called. the HTTP request input filter is called only if there is some POSTed data to read If you run the same request without POSTing any data or simply running a GET request. Input and Output Filters Slide 185 Stas Bekman .This module helps to understand that each filter handler can be called many time during each request and connection.

6.7Input Filters mod_perl supports 2 kinds of input filters: 1. Connection input filters 2. HTTP Request input filters Input and Output Filters Slide 186 Stas Bekman .

pl HTTP/1.7.1Connection Input Filters Let’s write a poor man’s s/GET/HEAD/ rewrite handler The handler looks for the data like: GET /perl/test.1 and turns it into: HEAD /perl/test.6.pl HTTP/1.1 Input and Output Filters Slide 187 Stas Bekman .

use APR::Brigade ().package MyApache2::InputFilterGET2HEAD. use Apache2::Const -compile => ’OK’. use strict. use APR::Const -compile => ’:common’. use base qw(Apache2::Filter). use APR::Bucket (). # Input and Output Filters Slide 188 Stas Bekman . use warnings.

$b->remove. $readbytes) = @_. # Input and Output Filters Slide 189 Stas Bekman . for (my $b = $bb->first. if ($data and $data =~ s|^GET|HEAD|) { my $nb = APR::Bucket->new($bb->bucket_alloc. $b = $bb->next($b)) { $b->read(my $data). } 1. $bb. $b->insert_after($nb). # no longer needed $f->ctx(1). return $rv unless $rv == APR::Const::SUCCESS. $readbytes). my $rv = $f->next->get_brigade($bb. # flag that that we have done the job last. $data).sub handler : FilterConnectionHandler { my($f. $mode. $b. return Apache2::Const::DECLINED if $f->ctx. $mode. $block. warn("data: $data\n"). $block. } } Apache2::Const::OK.

consider the following response handler: package MyApache2::RequestType. $r->print($response). Apache2::Const::OK. use Apache2::Const -compile => ’OK’.For example. use Apache2::Response (). $r->content_type(’text/plain’). $r->method. Input and Output Filters Slide 190 Stas Bekman # . $r->set_content_length(length $response). use Apache2::RequestRec (). my $response = "the request type was " . sub handler { my $r = shift. use Apache2::RequestIO (). } 1.

but it’ll will still set the correct Content-Length header. In the case of the HEAD request Apache will discard the response body. Input and Output Filters Slide 191 Stas Bekman . which will be 24 in case of the GET request and 25 for HEAD.which returns to the client the request type it has issued.

$r->content’ 24: the request type was GET Input and Output Filters Slide 192 Stas Bekman .Therefore if this response handler is configured as: Listen 8005 <VirtualHost _default_:8005> <Location /> SetHandler modperl PerlResponseHandler +MyApache2::RequestType </Location> </VirtualHost> and a GET request is issued to /: panic% perl -MLWP::UserAgent -le \ ’$r = LWP::UserAgent->new()->get("http://localhost:8005/"). ": ". \ print $r->headers->content_length .

where the response’s body is: the request type was GET And the Content-Length header is set to 24. Input and Output Filters Slide 193 Stas Bekman .

However if we enable the MyApache2::InputFilterGET2HEAD input connection filter:
Listen 8005 <VirtualHost _default_:8005> PerlInputFilterHandler +MyApache2::InputFilterGET2HEAD <Location /> SetHandler modperl PerlResponseHandler +MyApache2::RequestType </Location> </VirtualHost>

And issue the same GET request, we get only: 25:

Input and Output Filters

Slide 194

Stas Bekman

which means that the body was discarded by Apache, because our filter turned the GET request into a HEAD request. If Apache wasn’t discarding the body on HEAD, the response would be: the request type was HEAD that’s why the content length is reported as 25 and not 24 as in the real GET request.

Input and Output Filters

Slide 195

Stas Bekman

6.7.2HTTP Request Input Filters
Request filters are similar to connection filters, but have an access to a request object and they don’t see the headers.

Input and Output Filters

Slide 196

Stas Bekman

6.7.3Bucket Brigade-based Input Filters
Here is the request input filter that lowercases the request’s body:
package MyApache2::InputRequestFilterLC; use strict; use warnings; use base qw(Apache2::Filter); use Apache2::Connection (); use APR::Brigade (); use APR::Bucket (); use Apache2::Const -compile => ’OK’; use APR::Const -compile => ’:common’; #

Input and Output Filters

Slide 197

Stas Bekman

sub handler : FilterRequestHandler { my($f, $bb, $mode, $block, $readbytes) = @_; my $c = $f->c; my $bb_ctx = APR::Brigade->new($c->pool, $c->bucket_alloc); my $rv = $f->next->get_brigade($bb_ctx, $mode, $block, $readbytes); return $rv unless $rv == APR::Const::SUCCESS; while (!$bb_ctx->is_empty) { my $b = $bb_ctx->first; if ($b->is_eos) { $bb->insert_tail($b); last; } my $len = $b->read(my $data); $b = APR::Bucket->new($bb->bucket_alloc, lc $data) if $len; $b->remove; $bb->insert_tail($b); }

Input and Output Filters

Slide 198

Stas Bekman

Apache2::Const::OK; } 1;

Input and Output Filters

Slide 199

Stas Bekman

the MyApache2::Dump response handler dumps the query string and the content body as a response Using the following configuration: <Location /lc_input> SetHandler modperl PerlResponseHandler +MyApache2::Dump PerlInputFilterHandler +MyApache2::InputRequestFilterLC </Location> Input and Output Filters Slide 200 Stas Bekman .

before the content handler received it. The query string didn’t change.When issuing a POST request: % echo "mOd_pErl RuLeS" | POST ’http://localhost:8002/lc_input?FoO=1&BAR=2’ we get a response: args: FoO=1&BAR=2 content: mod_perl rules Indeed we can see that our filter has lowercased the POSTed body. Input and Output Filters Slide 201 Stas Bekman . since the filter didn’t operate on headers.

7.6. } 1. } Apache2::Const::OK. sub handler : FilterRequestHandler { my $f = shift.4Stream-oriented Input Filters package MyApache2::InputRequestFilterLC2. use Apache2::Const -compile => ’OK’. use base qw(Apache2::Filter). 1024)) { $f->print(lc $buffer). while ($f->read(my $buffer. # Input and Output Filters Slide 202 Stas Bekman .

Configuration: <Location /lc_input2> SetHandler modperl PerlResponseHandler +MyApache2::Dump PerlInputFilterHandler +MyApache2::InputRequestFilterLC2 </Location> We get the same results as from using the bucket brigades filter Input and Output Filters Slide 203 Stas Bekman .

Connection input filters 2.6.8Output Filters mod_perl supports 2 kinds of output filters: 1. HTTP Request input filters Input and Output Filters Slide 204 Stas Bekman .

6.1Connection Output Filters Connection filters are similar to HTTP Request filters. We will concentrate on HTTP request filters Input and Output Filters Slide 205 Stas Bekman . but can see all the data that is going through the server.8.

the English alphabet Input and Output Filters Slide 206 Stas Bekman . Here is a response handler that send two lines of output in a single string: 1.8.2HTTP Request Output Filters Output filters can be written using the bucket brigades manipulation or the simplified stream-oriented interface.6. numerals: 1234567890 2.

use Apache2::Const -compile => qw(OK). Apache2::Const::OK. $r->print(1. } 1. "\n"). $r->content_type(’text/plain’). Input and Output Filters Slide 207 Stas Bekman . # sub handler { my $r = shift.9..’z’. "0\n").. $r->print(’a’. use Apache2::RequestRec (). use Apache2::RequestIO ().package MyApache2::SendAlphaNum.

Since we want to reverse characters only in the response body we will use the HTTP request output filter. Input and Output Filters Slide 208 Stas Bekman .The purpose of our request output filter is to reverse every line of the response. preserving the new line characters in their places.

$f->print("\n"). while ($f->read(my $buffer.3Stream-oriented Output Filter package MyApache2::FilterReverse1.8. } } Apache2::Const::OK. sub handler : FilterRequestHandler { my $f = shift. use Apache2::Filter (). use Apache2::Const -compile => qw(OK). $buffer) { $f->print(scalar reverse $_). Input and Output Filters Slide 209 Stas Bekman # . 1024)) { for (split "\n".6. } 1.

Add the following configuration to httpd.conf: PerlModule MyApache2::FilterReverse1 PerlModule MyApache2::SendAlphaNum <Location /reverse1> SetHandler modperl PerlResponseHandler MyApache2::SendAlphaNum PerlOutputFilterHandler MyApache2::FilterReverse1 </Location> Input and Output Filters Slide 210 Stas Bekman .

so the client gets: 0987654321 zyxwvutsrqponmlkjihgfedcba Input and Output Filters Slide 211 Stas Bekman . the response handler MyApache2::SendAlphaNum::handler() sends: 1234567890 abcdefghijklmnopqrstuvwxyz as a response and the output filter handler MyApache2::FilterReverse1::handler reverses the lines.Now when a request to /reverse1 is made.

use strict. use base qw(Apache2::Filter). use Apache2::Const -compile => ’OK’. use APR::Brigade (). use APR::Const -compile => ’:common’. sub handler : FilterRequestHandler { my($f.6. use warnings.8. # Input and Output Filters Slide 212 Stas Bekman . $bb) = @_. use APR::Bucket ().4Bucket Brigade-based Output Filters The bucket brigades filtering API implementation: package MyApache2::FilterReverse2.

Apache2::Const::OK. return $rv unless $rv == APR::Const::SUCCESS. "\n"} split "\n". $b->remove. last. } $bb_ctx->insert_tail($b). $f->c->bucket_alloc). $data).my $bb_ctx = APR::Brigade->new($f->c->pool. if ($b->is_eos) { $bb_ctx->insert_tail($b). } 1. $b = APR::Bucket->new($bb->bucket_alloc. map {scalar(reverse $_). } if ($b->read(my $data)) { $data = join "". while (!$bb->is_empty) { my $b = $bb->first. $data. # Input and Output Filters Slide 213 Stas Bekman . } my $rv = $f->next->pass_brigade($bb_ctx).

And the corresponding configuration: PerlModule MyApache2::FilterReverse2 PerlModule MyApache2::SendAlphaNum <Location /reverse2> SetHandler modperl PerlResponseHandler MyApache2::SendAlphaNum PerlOutputFilterHandler MyApache2::FilterReverse2 </Location> Input and Output Filters Slide 214 Stas Bekman .

the client gets: 0987654321 zyxwvutsrqponmlkjihgfedcba as expected.Now when a request to /reverse2 is made. Input and Output Filters Slide 215 Stas Bekman .

HTTP Handlers Slide 216 Stas Bekman .

7 HTTP Handlers HTTP Handlers Slide 217 Stas Bekman .

1About HTTP Request Cycle Phases PerlPostReadRequestHandler PerlTransHandler PerlMapToStorageHandler PerlHeaderParserHandler PerlInitHandler PerlAccessHandler HTTP Handlers Slide 218 Stas Bekman .7.

PerlAuthenHandler PerlAuthzHandler PerlTypeHandler PerlFixupHandler PerlResponseHandler PerlLogHandler PerlCleanupHandler HTTP Handlers Slide 219 Stas Bekman .

sub handler { my $r = shift.2HTTP Request Handler Skeleton All HTTP Request handlers have the following structure: package MyApache2::MyHandlerName. # load modules that are going to be used use ... # compile (or import) constants use Apache2::Const -compile => qw(OK). # handler code comes here HTTP Handlers Slide 220 Stas Bekman ..7.

return Apache2::Const::OK. HTTP Handlers Slide 221 Stas Bekman . # or another status constant } 1.

HTTP Handlers Slide 222 Stas Bekman .If the handler is declared as a method handler: sub handler : method { my($class. $r) = @_.

7.0: HTTP Handlers Slide 223 Stas Bekman . The differences are: new phase: PerlMapToStorageHandler rename: PerlHandler => PerlResponseHandler PerlResponseHandler now includes filtering Here is the HTTP request life cycle in mod_perl 2.0.3HTTP Request Cycle Phases Almost identical to mod_perl 1.

HTTP Handlers Slide 224 Stas Bekman .

PerlAccessHandler 6. PerlHeaderParserHandler (PerlInitHandler) 5. PerlAuthenHandler 7.an HTTP request is processed by 12 phases: 1. PerlAuthzHandler HTTP Handlers Slide 225 Stas Bekman . PerlMapToStorageHandler 4. PerlPostReadRequestHandler (PerlInitHandler) 2. PerlTransHandler 3.

PerlFixupHandler 10.8. PerlCleanupHandler HTTP Handlers Slide 226 Stas Bekman . PerlResponseHandler 11. PerlLogHandler 12. PerlTypeHandler 9.

1PerlPostReadRequestHandler HTTP Handlers Slide 227 Stas Bekman .7.3.

HTTP Handlers Slide 228 Stas Bekman .

This phase is usually used to do processing that must happen once per request. For example Apache2::Reload is usually invoked at this phase to reload modified Perl modules.The post_read_request phase is the first request phase and happens immediately after the request has been read and HTTP headers were parsed. HTTP Handlers Slide 229 Stas Bekman .

2f minutes old\n". "conf". 60*24*(-M $conf_file). HTTP Handlers Slide 230 Stas Bekman . "httpd. compared to the start of the request process time: use strict. $r->content_type(’text/plain’).The following ModPerl::Registry script prints when the last time httpd. use warnings. use Apache2::RequestIO ().conf". my $r = shift.conf has been modified. use File::Spec::Functions qw(catfile). printf "$conf_file is %0. use Apache2::ServerUtil (). my $conf_file = catfile Apache2::ServerUtil::server_root.

The script reports incorrect time most of the time Because -M reports the difference between file’s modification time and $^T Under mod_perl $^T is set when the process starts and doesn’t change after that. Solution: Reset $^T on each request HTTP Handlers Slide 231 Stas Bekman .

sub handler { my $r = shift. use warnings. return Apache2::Const::OK. use Apache2::RequestRec (). $^T = $r->request_time. use Apache2::Const -compile => ’OK’.package MyApache2::TimeReset. } 1. HTTP Handlers Slide 232 Stas Bekman . use strict.

HTTP Handlers Slide 233 Stas Bekman . But $r->request_time already stores the request’s start time. so we get it without performing an additional system call.We could do: $^T = time().

To enable it just add to httpd. or to the <VirtualHost> section if you want this handler to be run only for a specific virtual host. HTTP Handlers Slide 234 Stas Bekman .conf: PerlPostReadRequestHandler MyApache2::TimeReset either to the global section.

7.2PerlTransHandler HTTP Handlers Slide 235 Stas Bekman .3.

HTTP Handlers Slide 236 Stas Bekman .

) will continue to be used. Also used to modify the URI itself and the request method. mod_rewrite. Alias directives. This is also a good place to register new handlers for the following phases based on the URI. HTTP Handlers Slide 237 Stas Bekman .g. etc. the server’s standard translation rules (e..The translate phase is used to manipulate a request’s URI If no custom handler is provided.

if the previously static pages are now autogenerated.com/perl/news.pl and users HTTP Handlers Slide 238 Stas Bekman . transparent to news.html _ is now handled by: http://example.pl?date=20021031.com/news/20021031/09/index.mod_rewrite ala mod_perl: e. and http://example.g.id=09.page=index.html we can keep using the old URI.

} 1.package MyApache2::RewriteURI. use warnings. $page) = $r->uri =~ m|^/news/(\d+)/(\d+)/(. use Apache2::RequestRec (). $r->args("date=$date.*)|.id=$id. use strict. sub handler { my $r = shift. HTTP Handlers Slide 239 Stas Bekman . return Apache2::Const::DECLINED. use Apache2::Const -compile => qw(DECLINED). my($date.pl"). $id. $r->uri("/perl/news.page=$page").

conf: PerlTransHandler +MyApache2::RewriteURI HTTP Handlers Slide 240 Stas Bekman .To configure this module simply add to httpd.

7.3PerlMapToStorageHandler HTTP Handlers Slide 241 Stas Bekman .3.

HTTP Handlers Slide 242 Stas Bekman .

most likely you want to shortcut this phase for mod_perl HTTP Handlers Slide 243 Stas Bekman .The map_to_storage phase is used to translate request’s URI into a corresponding filename If no custom handler is provided. the server will try to walk the filesystem trying to find what file or directory corresponds to the request’s URI.

# skip ap_directory_walk stat() calls return Apache2::Const::OK. # config: PerlMapToStorageHandler MyApache2::NoTranslation HTTP Handlers Slide 244 Stas Bekman .The Don’t-waste-time handler: package MyApache2::NoTranslation. } 1. sub handler { my $r = shift. use Apache2::Const -compile => qw(OK). use strict. use warnings FATAL => ’all’.

conf too! PerlMapToStorageHandler Apache2::Const::OK If you haven’t already compiled Apache2::Const::OK elsewhere. </Perl> HTTP Handlers Slide 245 Stas Bekman . you should add: <Perl> use Apache2::Const -compile => qw(OK).But this can be done from httpd.

same handler but support TRACE calls package MyApache2::NoTranslation2. # skip ap_directory_walk stat() calls return Apache2::Const::OK. return Apache2::Const::DECLINED if $r->method_number == Apache2::Const::M_TRACE. use warnings FATAL => ’all’. use Apache2::RequestRec (). sub handler { my $r = shift. # use Apache2::Const -compile => qw(DECLINED OK M_TRACE). use strict. } 1. HTTP Handlers Slide 246 Stas Bekman .

Another way to prevent the core translation: $r->filename(__FILE__). this can be done in PerlTransHandler as well HTTP Handlers Slide 247 Stas Bekman .

3.7.4PerlHeaderParserHandler HTTP Handlers Slide 248 Stas Bekman .

HTTP Handlers

Slide 249

Stas Bekman

The header_parser phase is the first phase to happen after the request has been mapped to its <Location> (or an equivalent container). At this phase the handler can examine the request headers and to take a special action based on these. e.g., this phase can be used to block evil clients targeting certain resources, while few resources were wasted so far.

HTTP Handlers

Slide 250

Stas Bekman

Apache handles the HEAD, GET, POST and several other HTTP methods. But you can invent your own methods and make Apache accept them. e.g., emails are very similar to HTTP messages: they have a set of headers and a body, sometimes a multi-part body. MyApache2::SendEmail extends HTTP by adding a support for the EMAIL method. It enables the new extension and pushes the real content handler during the PerlHeaderParserHandler phase:
<Location /email> PerlHeaderParserHandler MyApache2::SendEmail </Location>
HTTP Handlers Slide 251 Stas Bekman

package MyApache2::SendEmail; use strict; use warnings; use use use use use use use Apache2::RequestRec (); Apache2::RequestIO (); Apache2::RequestUtil (); Apache2::Server (); Apache2::ServerRec (); Apache2::Process (); APR::Table ();

#

use Apache2::Const -compile => qw(DECLINED OK); use constant SMTP_HOSTNAME => "localhost";

HTTP Handlers

Slide 252

Stas Bekman

sub handler { my $r = shift; return Apache2::Const::DECLINED unless $r->method eq ’EMAIL’; $r->server->method_register(’EMAIL’); $r->handler("perl-script"); $r->push_handlers(PerlResponseHandler => \&send_email_handler); return Apache2::Const::OK; } sub send_email_handler { my $r = shift; my %headers = map {$_ => $r->headers_in->get($_)} qw(To From Subject); my $content = content($r); my $status = send_email(\%headers, \$content); $r->content_type(’text/plain’); $r->print($status ? "ACK" : "NACK"); return Apache2::Const::OK; }

#

#

HTTP Handlers

Slide 253

Stas Bekman

sub send_email { my($rh_headers, $r_body) = @_; require MIME::Lite; MIME::Lite->send("smtp", SMTP_HOSTNAME, Timeout => 60); my $msg = MIME::Lite->new(%$rh_headers, Data => $$r_body); $msg->send; } sub content { my $r = shift; # unimportant here, see your handouts return $buf; } 1;

#

#

HTTP Handlers

Slide 254

Stas Bekman

So here is a simple client that uses LWP::UserAgent to issue an EMAIL method request over HTTP protocol: HTTP Handlers Slide 255 Stas Bekman .when you extend an HTTP protocol you need to have a client that knows how to use the extension.

com’. $headers. => ’example@example. but could use HTTP so I’m sending it over HTTP EOI my $headers = HTTP::Headers->new(%headers). # my $content = <<EOI. my $res = LWP::UserAgent->new->request($req). HTTP Handlers Slide 256 Stas Bekman . => ’3 weeks in Tibet’.require LWP::UserAgent. print $res->is_success ? $res->content : "failed". my %headers From To Subject ).com’. = ( => ’example@example. $url. $content). my $req = HTTP::Request->new("EMAIL". I didn’t have an email software. my $url = "http://localhost:8000/email/".

7.3.5PerlInitHandler HTTP Handlers Slide 257 Stas Bekman .

HTTP Handlers Slide 258 Stas Bekman .

HTTP Handlers Slide 259 Stas Bekman . this handler is an alias for PerlHeaderParserHandler. For example if Apache2::Reload is configured as: PerlInitHandler Apache2::Reload PerlSetVar ReloadAll Off PerlSetVar ReloadModules "MyApache2::*" then it will always monitor and reload all MyApache2::* modules that have been modified since the last HTTP request. It is the first handler to be invoked when serving a request. except <VirtualHost>.If configured inside any container directive.

However if we move the global configuration into a <Location> container: <Location /devel> PerlInitHandler Apache2::Reload PerlSetVar ReloadAll Off PerlSetVar ReloadModules "MyApache2::*" SetHandler perl-script PerlResponseHandler ModPerl::Registry Options +ExecCGI </Location> it acts as an alias for PerlPostReadRequestHandler therefore Apache2::Reload will reload the modified modules. only when a request to the /devel namespace is made HTTP Handlers Slide 260 Stas Bekman .

3.7.6PerlAccessHandler HTTP Handlers Slide 261 Stas Bekman .

HTTP Handlers Slide 262 Stas Bekman .

The access_checker phase is the first of three handlers that are involved in what’s known as AAA: Authentication and Authorization. HTTP Handlers Slide 263 Stas Bekman . time of the day or any other rule not connected to the user’s identity. and Access control. This phase can be used to restrict access from a certain IP address.

The concept behind access checker handler is very simple: return Apache2::Const::FORBIDDEN if the access is not allowed. HTTP Handlers Slide 264 Stas Bekman . otherwise return Apache2::Const::OK.

use Apache2::Connection ().0. } 1. use Apache2::Const -compile => qw(FORBIDDEN OK). sub handler { my $r = shift. return exists $bad_ips{$r->connection->remote_ip} ? Apache2::Const::FORBIDDEN : Apache2::Const::OK.This handler denies requests made from IPs on the blacklist: package MyApache2::BlockByIP.1 10. my %bad_ips = map {$_ => 1} qw(127.0.4).0.0. # HTTP Handlers Slide 265 Stas Bekman . use Apache2::RequestRec ().

To enable the handler simply add it to the container that needs to be protected. For example to protect an access to the registry scripts executed from the base location /perl add: <Location /perl/> SetHandler perl-script PerlResponseHandler ModPerl::Registry PerlAccessHandler MyApache2::BlockByIP Options +ExecCGI </Location> HTTP Handlers Slide 266 Stas Bekman .

7PerlAuthenHandler HTTP Handlers Slide 267 Stas Bekman .3.7.

HTTP Handlers Slide 268 Stas Bekman .

requires that the directory be associated with AuthName. AuthType and at least one require directive. This. in turn. to defer the decision: Apache2::Const::DECLINED Otherwise the handler returns Apache2::Const::HTTP_UNAUTHORIZED to indicate that the user has not authenticated successfully.The check_user_id (authen) phase is called whenever the requested file or directory is password protected. the handler should return Apache2::Const::OK. This phase is usually used to verify a user’s identification credentials. If the credentials are verified to be correct. HTTP Handlers Slide 269 Stas Bekman .

When Apache sends the HTTP header with this code. $username. $password. the browser will normally pop up a dialog box that prompts the user for login information. HTTP Handlers Slide 270 Stas Bekman . The following example handler verifies that: SECRET_LENGTH == length join " ".

package MyApache2::SecretLengthAuth. return Apache2::Const::OK if SECRET_LENGTH == length join " ". $password. $r->note_basic_auth_failure. use Apache2::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED). # HTTP Handlers Slide 271 Stas Bekman . my ($status. $password) = $r->get_basic_auth_pw. use constant SECRET_LENGTH => 14. use Apache2::RequestUtil (). use Apache2::Access (). } 1. sub handler { my $r = shift. $r->user. return $status unless $status == Apache2::Const::OK. return Apache2::Const::HTTP_UNAUTHORIZED.

HTTP Handlers Slide 272 Stas Bekman . If you set it to valid-user any username will do.To enable this handler you have to tell Apache: what authentication scheme to use (AuthType: Basic or Digest) what’s the authentication realm (AuthName: any string) the Require directive is needed to specify which usernames are allowed to authenticate.

<Location /perl/> SetHandler perl-script PerlResponseHandler ModPerl::Registry PerlAuthenHandler MyApache2::SecretLengthAuth Options +ExecCGI AuthType Basic AuthName "The Gate" Require valid-user </Location> HTTP Handlers Slide 273 Stas Bekman .

8PerlAuthzHandler HTTP Handlers Slide 274 Stas Bekman .3.7.

HTTP Handlers Slide 275 Stas Bekman .

similar to the auth phase. As this phase is tightly connected to the authentication phase. This phase requires a successful authentication from the previous phase. because a username is needed in order to decide whether a user is authorized to access the requested resource. HTTP Handlers Slide 276 Stas Bekman .The auth_checker (authz) phase is used for authorization control. The handler is expected to return: Apache2::Const::DECLINED to defer the decision. the handlers registered for this phase are only called when the requested resource is password protected.

or Apache2::Const::HTTP_UNAUTHORIZED to indicate that the user is not authorized to access the requested document.Apache2::Const::OK to indicate its acceptance of the user’s authorization. HTTP Handlers Slide 277 Stas Bekman .

use warnings. # HTTP Handlers Slide 278 Stas Bekman . use Apache2::Const -compile => qw(OK HTTP_UNAUTHORIZED). ). my %protected = ( ’admin’ => [’stas’]. ’report’ => [qw(stas boss)]. use Apache2::RequestUtil (). use strict.The MyApache2::SecretResourceAuthz handler grants access to certain resources only to certain users who have already properly authenticated: package MyApache2::SecretResourceAuthz. use Apache2::Access ().

return Apache2::Const::OK if grep { $_ eq $user } @$users. # my $user = $r->user. HTTP Handlers Slide 279 Stas Bekman . if ($user) { my($section) = $r->uri =~ m|^/company/(\w+)/|.sub handler { my $r = shift. } } $r->note_basic_auth_failure. return Apache2::Const::HTTP_UNAUTHORIZED. } 1. } else { return Apache2::Const::OK. if (defined $section && exists $protected{$section}) { my $users = $protected{$section}.

Alias /company/ /home/httpd/httpd-2. The rest doesn’t change.0/perl/ <Location /company/> SetHandler perl-script PerlResponseHandler ModPerl::Registry PerlAuthenHandler MyApache2::SecretLengthAuth PerlAuthzHandler MyApache2::SecretResourceAuthz Options +ExecCGI AuthType Basic AuthName "The Secret Gate" Require valid-user </Location> HTTP Handlers Slide 280 Stas Bekman . this time we just add the PerlAuthzHandler setting.The configuration is similar to PerlAuthenHandler.

9PerlTypeHandler HTTP Handlers Slide 281 Stas Bekman .7.3.

HTTP Handlers Slide 282 Stas Bekman .

e. which is usually the mod_mime handler. Of course later phases may override the mime type set in this phase. mod_autoindex. don’t forget to set the response handler: HTTP Handlers Slide 283 Stas Bekman . uses this phase to map the filename extensions to the corresponding icons which will be later used in the listing of files.g. When overriding the default type_checker handler. which performs automatic directory indexing..The type_checker phase is used to set the response MIME type (Content-type) and sometimes other bits of document type information like the document language.

# or $r->handler(’modperl’).$r->handler(’perl-script’). It’s the easiest to leave this stage alone and do any desired settings in the fixups phase. $r->set_handlers(PerlResponseHandler => \&handler). HTTP Handlers Slide 284 Stas Bekman .

7.3.10PerlFixupHandler HTTP Handlers Slide 285 Stas Bekman .

HTTP Handlers Slide 286 Stas Bekman .

The fixups phase is happening just before the content handling phase. For example in this phase mod_env populates the environment with variables configured with SetEnv and PassEnv directives. It gives the last chance to do things before the response is generated. HTTP Handlers Slide 287 Stas Bekman .

use warnings. undef ]. use Apache2::RequestIO (). \&tt_handler ].This fixup handler tells Apache at run time which handler and callback should be used to process the request based on the file extension of the request’s URI. use constant CALLBACK => 1. package MyApache2::FileExtDispatch. use Apache2::RequestRec (). use constant HANDLER => 0. HTTP Handlers Slide 288 Stas Bekman . \&pl_handler ]. [’default-handler’. # \&cgi_handler]. ( [’perl-script’. [’modperl’. my %exts = cgi => pl => tt => txt => ). [’perl-script’. use Apache2::RequestUtil (). use strict. use Apache2::Const -compile => ’OK’.

$r->handler($exts{$ext}->[HANDLER]). $ext = ’txt’ unless defined $ext and exists $exts{$ext}.sub handler { my $r = shift. # if (defined $exts{$ext}->[CALLBACK]) { $r->set_handlers(PerlResponseHandler => $exts{$ext}->[CALLBACK]). } HTTP Handlers Slide 289 Stas Bekman . my($ext) = $r->uri =~ /\. } return Apache2::Const::OK.(\w+)$/.

return Apache2::Const::OK. ’cgi’) } sub pl_handler { content_handler($_[0]. # HTTP Handlers Slide 290 Stas Bekman . $r->print("A handler of type ’$type’ was called"). $r->content_type(’text/plain’). ’pl’) } sub tt_handler { content_handler($_[0]. ’tt’) } sub content_handler { my($r. $type) = @_.sub cgi_handler { content_handler($_[0]. } 1.

It applies the rest of the settings dynamically at run-time. but the fixup handler.Here is how this handler is configured: Alias /dispatch/ /home/httpd/httpd-2.0/htdocs/ <Location /dispatch/> PerlFixupHandler MyApache2::FileExtDispatch </Location> Notice that there is no need to specify anything. HTTP Handlers Slide 291 Stas Bekman .

11PerlResponseHandler HTTP Handlers Slide 292 Stas Bekman .7.3.

HTTP Handlers Slide 293 Stas Bekman .

This is arguably the most important phase and most of the existing Apache modules do most of their work at this phase. This is the only phase that requires two directives under mod_perl: <Location /perl> SetHandler perl-script PerlResponseHandler MyApache2::WorldDomination </Location> SetHandler set to perl-script or modperl tells Apache that mod_perl is going to handle the response generation. HTTP Handlers Slide 294 Stas Bekman .The handler (response) phase is used for generating the response.

PerlResponseHandler tells mod_perl which callback is going to do the job. HTTP Handlers Slide 295 Stas Bekman .

use B::Deparse (). use Apache2::RequestIO (). use strict. use Apache2::RequestRec (). $r->print(’sub handler ’. $r->content_type(’text/plain’). B::Deparse->new->coderef2text(\&handler)). } 1. sub handler { my $r = shift. use warnings.This handler prints itself: package MyApache2::Deparse. HTTP Handlers Slide 296 Stas Bekman . return Apache2::Const::OK. use Apache2::Const -compile => ’OK’.

To enable this handler add to httpd.conf: <Location /deparse> SetHandler modperl PerlResponseHandler MyApache2::Deparse </Location> HTTP Handlers Slide 297 Stas Bekman .

use warnings. B::Deparse is fun to play with! HTTP Handlers Slide 298 Stas Bekman . my $r = shift @_. it’s pretty much the same code. ’B::Deparse’->new->coderef2text(\&handler)). $r->content_type(’text/plain’).Now when the server is restarted and we issue a request to http://localhost/deparse we get the following response: sub handler { package MyApache2::Deparse. return 0. $r->print(’sub handler ’. use strict ’refs’. } If you compare it to the source code.

3.7.12PerlLogHandler HTTP Handlers Slide 299 Stas Bekman .

HTTP Handlers Slide 300 Stas Bekman .

HTTP Handlers Slide 301 Stas Bekman . At this phase log handlers usually log various information about the request and the response.The log_transaction phase is always executed. Even if the previous phases were aborted.

use Apache2::Connection (). use Apache2::Const -compile => qw(OK DECLINED). # HTTP Handlers Slide 302 Stas Bekman . use Apache2::RequestRec ().The following handler logs the request data into user-specific files. use strict. We assume that all URIs include the username in the form of: /~username/ package MyApache2::LogPerUser. use File::Spec::Functions qw(catfile). use Fcntl qw(:flock). use warnings.

"logs". "$username. $r->bytes_sent. flock $fh. my $log_path = catfile Apache2::ServerUtil::server_root. print $fh $entry. } 1. ">>$log_path" or die "can’t open $log_path: $!". $r->connection->remote_ip. open my $fh. my($username) = $r->uri =~ m|^/~([^/]+)|. return Apache2::Const::OK.sub handler { my $r = shift. scalar(localtime). $r->status. return Apache2::Const::DECLINED unless defined $username. my $entry = sprintf qq(%s [%s] "%s" %d %d\n). LOCK_EX. $r->uri.log". close $fh. # HTTP Handlers Slide 303 Stas Bekman .

Configuration: <LocationMatch "^/~"> SetHandler perl-script PerlResponseHandler ModPerl::Registry PerlLogHandler MyApache2::LogPerUser Options +ExecCGI </LocationMatch> HTTP Handlers Slide 304 Stas Bekman .

0.0.0.pl" 200 8 HTTP Handlers Slide 305 Stas Bekman .pl" 200 8 127.1 [Sat Aug 31 01:50:39 2002] "/~eric/test.0.pl" 200 44 and to logs/eric.pl http://localhost/~eric/test.pl http://localhost/~stas/date.pl The MyApache2::LogPerUser handler will append to logs/stas.log: 127.1 [Sat Aug 31 01:50:38 2002] "/~stas/test.log: 127.0.1 [Sat Aug 31 01:50:40 2002] "/~stas/date.0.After restarting the server and issuing requests to the following URIs: http://localhost/~stas/test.

3.13PerlCleanupHandler HTTP Handlers Slide 306 Stas Bekman .7.

HTTP Handlers Slide 307 Stas Bekman .

It’s a mod_perl convenience invention It runs immediately after the request has been served and before the request object is destroyed.There is no cleanup Apache phase. Used to run cleanup code or to do some time consuming work after the client has gone HTTP Handlers Slide 308 Stas Bekman .

HTTP Handlers Slide 309 Stas Bekman .Usage: a cleanup() callback accepts $r as its only argument. PerlCleanupHandler MyApache2::Cleanup or: $r->push_handlers(PerlCleanupHandler => \&cleanup). $arg). a cleanup() callback accepts an optional arbitrary argument $r->pool->cleanup_register(\&cleanup.

use Apache2::RequestUtil (). use strict. use Apache2::RequestIO ().Example: delete a temporary file in the cleanup handler package MyApache2::Cleanup1. use Apache2::Const -compile => qw(OK DECLINED). use File::Spec::Functions qw(catfile). # HTTP Handlers Slide 310 Stas Bekman . my $file = catfile "/tmp". use Apache2::RequestRec (). use APR::Const -compile => ’SUCCESS’. use warnings FATAL => ’all’. "data".

die "Can’t find file: $file" unless -e $file. unlink $file or die "failed to unlink $file". return Apache2::Const::OK. local @ENV{qw(PATH BASH_ENV)}. $r->content_type(’text/plain’). } 1. return Apache2::Const::OK. # my $status = $r->sendfile($file). $r->push_handlers(PerlCleanupHandler => \&cleanup). HTTP Handlers Slide 311 Stas Bekman . qx(/bin/ls -l > $file).sub handler { my $r = shift. die "sendfile has failed" unless $status == APR::Const::SUCCESS. } sub cleanup { my $r = shift.

Next we add the following configuration: <Location /cleanup1> SetHandler modperl PerlResponseHandler MyApache2::Cleanup1 </Location> Now when requesting /cleanup1 the contents of the current directory will be printed and once the request is over the temporary file is deleted. HTTP Handlers Slide 312 Stas Bekman .

APR::UUID But how do we pass the filename to the cleanup handler? MyApache2::Cleanup2 solves the problem with: $r->pool->cleanup_register(\&cleanup. $file). HTTP Handlers Slide 313 Stas Bekman .The problem in Multi-processes/threads env MyApache2::Cleanup1 is problematic for it uses the same filename Better use a unique filename ($$ + APR::OS::current_thread_id()) Even better. use a non-predictable name: rand.

APR::Pool (). # use Apache2::Const -compile => qw(OK DECLINED). use warnings FATAL => ’all’. use File::Spec::Functions qw(catfile). use use use use use Apache2::RequestRec (). Apache2::RequestUtil (). use APR::Const -compile => ’SUCCESS’. my $file_base = catfile "/tmp". "data-". Apache2::RequestIO ().package MyApache2::Cleanup2. HTTP Handlers Slide 314 Stas Bekman . use strict. APR::UUID ().

local @ENV{qw(PATH BASH_ENV)}. $r->pool->cleanup_register(\&cleanup. unlink $file or die "failed to unlink $file". die "Can’t find file: $file" unless -e $file. $file). qx(/bin/ls -l > $file). return Apache2::Const::OK. $r->content_type(’text/plain’). } sub cleanup { my $file = shift. die "sendfile has failed" unless $status == APR::Const::SUCCESS.sub handler { my $r = shift. return Apache2::Const::OK. HTTP Handlers Slide 315 Stas Bekman . } 1. my $file = $file_base . APR::UUID->new->format. # my $status = $r->sendfile($file).

we add the configuration: <Location /cleanup2> SetHandler modperl PerlResponseHandler MyApache2::Cleanup2 </Location> HTTP Handlers Slide 316 Stas Bekman .Similarly to the first handler.

mod_perl 1.0 to mod_perl 2.0 Migration Slide 317 Stas Bekman .

0 Migration Slide 318 Stas Bekman .8 mod_perl 1.0 to mod_perl 2.0 Migration mod_perl 1.0 to mod_perl 2.

8.0 Migration Slide 319 Stas Bekman .1About Configuration Directives Changes mod_perl API Changes mod_perl Modules Changes mod_perl 1.0 to mod_perl 2.

renamed.0 to mod_perl 2. . But there is a back-compatibility layer! mod_perl 1.0 Migration Slide 320 Stas Bekman .0 Some configuration directives were renamed or removed Several APIs have changed..0 to mod_perl 2.. or moved to new packages. removed.2Migrating from mod_perl 1.8.

Certain Configuration directives and APIs have changed See http://perl.apache.3The Shortest Migration Path from 1.8.html mod_perl 1.0 Migration Slide 321 Stas Bekman .0/user/compat/compat.org/docs/2.0 to mod_perl 2.0 use Apache2::compat.

0 Migration Slide 322 Stas Bekman . mod_perl 1.4Migrating Configuration Files Several configuration directives are deprecated in 2.0 but still available for backwards compatibility Otherwise. consider using the directives that have replaced them.0 to mod_perl 2.8.

0 to mod_perl 2.4.1PerlHandler PerlHandler => PerlResponseHandler mod_perl 1.0 Migration Slide 323 Stas Bekman .8.

0 Migration Slide 324 Stas Bekman .8.2PerlSendHeader PerlSendHeader On => PerlOptions +ParseHeaders PerlSendHeader Off => PerlOptions -ParseHeaders mod_perl 1.4.0 to mod_perl 2.

4.8.3PerlSetupEnv PerlSetupEnv On => PerlOptions +SetupEnv PerlSetupEnv Off => PerlOptions -SetupEnv mod_perl 1.0 to mod_perl 2.0 Migration Slide 325 Stas Bekman .

0 Migration Slide 326 Stas Bekman .8.4PerlTaintCheck The taint mode now can be turned on with: PerlSwitches -T It’s disabled by default. mod_perl 1. You cannot disable it once it’s enabled.0 to mod_perl 2.4.

8.0 Migration Slide 327 Stas Bekman .5PerlWarn Warnings now can be enabled globally with: PerlSwitches -w mod_perl 1.4.0 to mod_perl 2.

6PerlFreshRestart PerlFreshRestart is a mod_perl 1.0: <IfDefine !MODPERL2> PerlFreshRestart </IfDefine> mod_perl 1.0 Migration Slide 328 Stas Bekman .0 and 2.0 legacy In mod_perl 2. To reuse the same httpd.4.conf for 1.0 a full tear-down and startup of interpreters is done on restart.8.0 to mod_perl 2.

5Code Porting Certain APIs couldn’t be preserved in 2.0.0 Migration Slide 329 Stas Bekman . which is slower.0 to mod_perl 2. because it’s implemented in Perl. since some APIs can’t be backported Consider getting rid of using the compat layer mod_perl 1. hence: use Apache2::compat.8. it’s also incomplete.

5.1Finding Which Modules Need To Be Loaded The Poison: $r->content_type(’text/plain’). the execution fails with: can’t find method ’content_type’ ..8. One has to load modules containing mod_perl methods before they can be used mod_perl 1.0 to mod_perl 2. $r->print("Hello cruel world!")..0 Migration Slide 330 Stas Bekman .

0 to mod_perl 2.The Remedy: % perl -MModPerl::MethodLookup -e print_method content_type to use method ’content_type’ add: use Apache2::RequestRec ().0 Migration Slide 331 Stas Bekman . mod_perl 1. Alias: # c-style shell % alias lookup "perl -MModPerl::MethodLookup -e print_method" # bash-style shell % alias lookup="perl -MModPerl::MethodLookup -e print_method" % lookup content_type to use method ’content_type’ add: use Apache2::RequestRec ().

0 to mod_perl 2. which affects all threads: use ModPerl::RegistryPrefork or ModPerl::PerlRunPrefork mod_perl 1. mp2 should work the same everywhere Issues with chdir().6ModPerl::Registry Family s/Apache::Registry/ModPerl::Registry/ Alias /perl/ /home/httpd/perl/ <Location /perl> SetHandler perl-script PerlResponseHandler ModPerl::Registry Options +ExecCGI PerlOptions +ParseHeaders </Location> MPM doesn’t matter.0 Migration Slide 332 Stas Bekman .8.

Cook your own registry with ModPerl::RegistryCooker is-a: Subclass one of the classes has-a: Build your own using aliasing mod_perl 1.0 Migration Slide 333 Stas Bekman .0 to mod_perl 2.

0 to mod_perl 2. mod_perl 1. @ISA = qw(Eagle). $r) = @_..8. } See the attributes manpage.7Method Handlers $$ doesn’t work since some callbacks accepts more than 2 args package Bird.. sub handler : method { my($class.. .0 Migration Slide 334 Stas Bekman .

8. mod_perl 1.0 to mod_perl 2.8Apache::StatINC Replacement Replace: PerlInitHandler Apache::StatINC with: PerlInitHandler Apache2::Reload Apache2::Reload provides an extra functionality See the module’s manpage.0 Migration Slide 335 Stas Bekman .

That’s all folks! Slide 336 Stas Bekman .

9 That’s all folks! That’s all folks! Slide 337 Stas Bekman .

1Thanks Thanks to TicketMaster for sponsoring my work on mod_perl That’s all folks! Slide 338 Stas Bekman .9.

9.2References mod_perl 2.apache.apache.0/ Further Questions? Grab me at the corridor and demand answers Ask at modperl@perl.org That’s all folks! Slide 339 Stas Bekman .org/docs/2.0 information can be found at: http://perl.

9.3A Shameless Plug That’s all folks! Slide 340 Stas Bekman .

That’s all folks! Slide 341 Stas Bekman .

Get it from http://modperlbook.Now available under Creative Commons license: download modify distribute sell etc.org/ That’s all folks! Slide 342 Stas Bekman .