view release on metacpan or  search on metacpan

SessionManager/cookpod.pod  view on Meta::CPAN

   Multiple session values<BR>
   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]<BR>
   [% END %]<P>

   Multiple values by array ref<BR>
   [% keys = [ '_session_id', '_session_start' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]<BR>
   [% END %]

   All session values<BR>
   [% FOREACH s = my_sess.get %]
   * [% s %]<BR>
   [% END %]

   <H3>Setting session values:</H3>
   ID: [% my_sess.set('foo' => 10, 'bar' => 20, '_session_test' => 'test') %]<BR>

   </BODY>
   </HTML>  

Save both into the F</usr/local/apache/perl-scripts> directory and launch
http://localhost/perl/session.cgi

=head2 SEE ALSO

L<Apache::SessionManager|Apache::SessionManager>, L<Template Toolkit|Template>,
L<Apache|Apache>, perl(1)

=head1 Apache::SessionManager WITH AUTHENTICATION MECHANISM

=head2 INTRODUCTION

This section describes using L<Apache::SessionManager|Apache::SessionManager>
with simple authentication mechanism.  There are many ways to do it; this
document will not describe all possible configurations. 

=head2 CONFIGURATION

The idea is to write a custom authentication handler in order to verify each
request  that session is valid (the user has been already authenticaded).

=head3 CONFIGURATION VIA F<httpd.conf>

In F<httpd.conf> (or any files included by the C<Include> directive):

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager
   <Location /protected>

      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 1800
      PerlSetVar SessionManagerName SESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/"

      <Perl>
         use lib '/usr/local/apache/perl/';
      </Perl>
      PerlAuthenHandler Apache::MyAuth
      AuthName "Reserved Club"
      AuthType Basic
      require valid-user
      PerlSetVar MyAuthLogin /protected/login.html
   </Location>

We have added a C<PerlSetvar> directive in order to set C<MyAuthLogin> variable
with login form URI.

=head3 CONFIGURATION VIA F<.htaccess>

In the case you don't have access to F<httpd.conf>, you can put similar
directive  directly into an F<.htaccess> file:

   PerlModule Apache::SessionManager
   <FilesMatch "\.foo$">

      PerlHeaderParserHandler Apache::SessionManager
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 1800
      PerlSetVar SessionManagerName SESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/"

      <Perl>
         use lib '/usr/local/apache/perl/';
      </Perl>
      PerlAuthenHandler Apache::MyAuth
      AuthName "Reserved Club"
      AuthType Basic
      require valid-user
      PerlSetVar MyAuthLogin /protected/login.html
   </FilesMatch>

The only difference is that you cannot use C<Location> directive (I used
C<FilesMatch>) and you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase.

=head3 NOTES ON USING F<.htaccess> INSTEAD OF F<httpd.conf>

=over 4

=item *

In both cases it is necessary to install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing>  phase
and not into C<URI translation> phase (in this phase, F<.htaccess> hasn't yet 
been processed).

=item *

Using F<.htaccess>, it is possible to use only cookies for the session
tracking.

=back

=head2 THE AUTHENTICATION HANDLER

This simple code is the authentication handler
F</usr/local/apache/perl/Apache/MyAyth.pm>:

   package Apache::MyAuth;
   use Apache::Constants qw(:common REDIRECT);
   use Apache::SessionManager;
   use strict;

   sub handler {
      my $r = shift;
      my $session = Apache::SessionManager::get_session($r);

      # Login ok: user is already logged or login form is requested
      if ( $session->{'logged'} == 1 || $r->uri eq $r->dir_config('MyAuthLogin') ) { 
         return OK;
      }

      # user not logged in or session expired

      # store in session the destination url if not set
      $session->{'redirect'} ||= $r->uri . ( ( $r->args ) ? ('?' . $r->args) : '' );

      # verify credenitals
      unless ( verifiy_cred( ($r->args) ) ) {

         # Log error
         $r->log_error('MyAuth: access to ' . $r->uri . ' failed for ' . $r->get_remote_host);

SessionManager/cookpod.pod  view on Meta::CPAN

   %> lwp-download http://search.cpan.org/CPAN/authors/id/A/AM/AMS/Storable-2.07.tar.gz 
   %> tar -xzvf Storable-2.07.tar.gz  
   %> cd Storable-2.07   
   %> perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> make
   %> make test
   %> make install

The installation procedure for L<Digest::MD5|Digest::MD5> or
L<Apache::Cookie|Apache::Cookie> (libapreq) is almost the same.

=head2 INSTALLING Apache::Session

   %> lwp-download http://search.cpan.org/CPAN/authors/id/J/JB/JBAKER/Apache-Session-1.54.tar.gz 
   %> tar -xzvf Apache-Session-1.54.tar.gz
   %> cd Apache-Session-1.54
   %> perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> PERL5LIB=/path/to/your/perl-lib/lib make test
   %> make install

Plese note that the environment variable C<PERL5LIB> setting is necessary
before  run tests in order to append F</path/to/your/perl-lib/lib> to C<@INC>.

=head2 INSTALLING Apache::SessionManager

   %> lwp-download http://search.cpan.org/CPAN/authors/id/E/EN/ENRYS/Apache-SessionManager-0.06.tar.gz
   %> tar -xzvf Apache-SessionManager-0.06.tar.gz
   %> cd Apache-SessionManager-0.06
   %> PERL5LIB=/path/to/your/perl-lib/lib/site_perl:/path/to/your/perl-lib/lib \
      perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> make
   %> PERL5LIB=/path/to/your/perl-lib/lib/site_perl:/path/to/your/perl-lib/lib \
      make test
   %> make install

To test the installation:

   %> PERL5LIB=/path/to/your/perl-lib/lib/site_perl perldoc Apache::SessionManager 

=head2 TESTING Apache::SessionManager

Tipically, without system administration account you cannot manage Apache
F<httpd.conf>.

Also if you cannot install (or run) another C<httpd> instance even at high
ports (for example > 1024) the only possibilty to use session manager is to
configure F<.htaccess> file appropriately.

Using F<.htaccess>, you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase. Moreover, it is possible to
use only cookies for the session tracking.

This is an example of how configure F<.htaccess> file for use session (using
file system as backend datastore) with CGI scripts under 
L<Apache::Registry|Apache::Registry>:

   <IfModule mod_perl.c>
      <Perl>
         use lib '/path/to/your/perl-lib/lib/site_perl',
                 '/path/to/your/perl-lib/lib/';           # for Storable.pm
      </Perl>
      PerlModule Apache::SessionManager
      <FilesMatch "\.cgi$">
         SetHandler perl-script
         PerlHandler Apache::Registry
         PerlSendHeader On
         PerlSetupEnv On
         Options ExecCGI
         PerlHeaderParserHandler Apache::SessionManager

         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 300
         PerlSetVar SessionManagerInactivity 1800
         PerlSetVar SessionManagerName SESSIONID
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /path/to/session/data"
         PerlSetVar SessionManagerDebug 5
      </FilesMatch>
   </IfModule>   

To test session you can use this simple CGI script:

   #!/usr/bin/perl

   use Data::Dumper ();

   my $session = Apache::SessionManager::get_session(Apache->request);
   $session->{$$ . '-' . rand()} = rand; 

   print "Content-type: text/html\n\n";
   print '<PRE>' . Data::Dumper::Dumper($session) . '</PRE>'; 

Save it with a F<.cgi> extension (like F<session.cgi>) in the same directory
where you have F<.htaccess> and make it executable by web server.

=head1 USING Apache::SessionManager AND Apache::DBI 

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> with
L<Apache::DBI|Apache::DBI> when using a RDBMS for sessions back-end datastore.

L<Apache::DBI|Apache::DBI> is a useful mod_perl module that caches database
connections according to args (like DBD driver, user, password) and attributes.
So, if your application uses a different user and/or attributes to connect to a
(different) database, every connection will be cached. Also, every child could
have these cached DB's handles. L<Apache::DBI|Apache::DBI> works very well for
web applications that uses same DB user.

=head2 CONFIGURATION

There is no need of extra configuration steps to use advantage of persistent DB
connections offered by L<Apache::DBI|Apache::DBI> when using
L<Apache::SessionManager|Apache::SessionManager> with a RDBMS as session
datastore.

L<Apache::DBI|Apache::DBI> overrides DBI C<connect> and C<disconnect>  methods
and it intercepts, transparently, all related calls (including