/ 
Apache-SessionManager-0.02
River stage one • 1 direct dependent • 1 total dependent
/ Apache::SessionManager

NAME

Apache::SessionManager - mod_perl extension to manage sessions over HTTP requests

SYNOPSIS

In httpd.conf:

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager
	  
   <Location /my-app-with-session>
      SetHandler perl-script
      PerlHandler Apache::MyModule
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_sessions"
   </Location>  

   <Location /my-app-without-sessions>
      PerlSetVar SessionManagerTracking Off
   </Location>

DESCRIPTION

Apache::SessionManager is a mod_perl module that helps session management of a web application. This simple module is a wrapper around Apache::Session persistence framework for session data. It creates a session object and makes it available to all other handlers transparenlty by putting it in pnotes. In a mod_perl handlers you can retrieve the session object directly from pnotes with predefined key 'SESSION_MANAGER_HANDLE':

my $session = $r->pnotes('SESSION_MANAGER_HANDLE') ? $r->pnotes('SESSION_MANAGER_HANDLE') : ();

In a CGI Apache::Registry script:

my $r = Apache->request;
my $session = $r->pnotes('SESSION_MANAGER_HANDLE') ? $r->pnotes('SESSION_MANAGER_HANDLE') : ();

then it is possible to set a value in current session with:

$$session{'key'} = $value;

or read value session with:

print "$$session{'key'}";

The following functions also are provided (but not yet exported) by this module:

Apache::SessionManager::get_session(Apache->request)

Return an hash reference to current session object.

Apache::SessionManager::destroy_session(Apache->request)

Destroy the current session object.

For instance:

  package Apache::MyModule;
  use strict;
  use Apache::Constants qw(:common);

  sub handler {
     my $r = shift;

     # retrieve session
     my $session = Apache::SessionManager::get_session($r);

     # set a value in current session
     $$session{'key'} = "some value";

     # read value session
     print "$$session{'key'}";

     # destroy session explicitly
     Apache::SessionManager::destroy_session($r);
     
     ...

     return OK;
  }

INSTALLATION

In order to install and use this package you will need Perl version 5.005 or better.

Prerequisites:

  • mod_perl (of course) with the appropriate call-back hooks (PERL_TRANS=1)

  • Apache::Request >= 0.33 (libapreq) is required

  • Apache::Session >= 0.53 is required

Installation as usual:

% perl Makefile.PL
% make
% make test
% su
  Password: *******
% make install

CONFIGURATION

To enable session tracking with this module you should modify a configuration in httpd.conf by adding the following lines:

PerlModule Apache::SessionManager
PerlTransHandler Apache::SessionManager
PerlSetVar SessionManagerTracking On

This will activate the session manager over each request. It is posibible to activate this module by location or directory only:

<Location /my-app-dir>
   PerlSetVar SessionManagerTracking On
</Location>

Also, it is possible to deactivate session management per directory or per location explicitly:

<Location /my-app-dir-without>
   PerlSetVar SessionManagerTracking Off
</Location>

DIRECTIVES

You can control the behaviour of this module by configuring the following variables with PerlSetVar directive in the httpd.conf.

SessionManagerTracking On|Off

This single directive enables session traking

PerlSetVar SessionManagerTracking On

It can be placed in server config, <VirtualHost>, <Directory>, <Location>, <File> and .htaccess context. The default value is Off.

SessionManagerURITracking On|Off

This single directive enables session URI traking

PerlSetVar SessionManagerURITracking On

where the session ID is embedded in the URI. This is a possible cookieless solution to track session ID between browser and server. Please see URI TRACKING NOTES section below for more details. The default value is Off.

SessionManagerExpire number

This single directive defines global sessions expiration time (in seconds).

PerlSetVar SessionManagerExpire 900

The default value is 3600 seconds. The module put the user start session time in a special session key '_session_start'.

SessionManagerInactivity number

This single directive defines user inactivity sessions expiration time (in seconds).

PerlSetVar SessionManagerInactivity 900

If not specified no user inactivity expiration policies are applied. The module put the user timestamp in a special session key '_session_timestamp'.

SessionManagerName string

This single directive defines session cookie name

PerlSetVar SessionManagerName PSESSID

The default value is PERLSESSIONID

SessionManagerStore datastore

This single directive sets the session datastore used by Apache::Session framework

PerlSetVar SessionManagerStore File

The following datastore plugins are available with Apache::Session distribution:

  • File

    Sessions are stored in file system

  • MySQL

    Sessions are stored in MySQL database

  • Postgres

    Sessions are stored in Postgres database

  • Sybase

    Sessions are stored in Sybase database

  • Oracle

    Sessions are stored in Oracle database

  • DB_File

    Sessions are stored in DB files

In addition to datastore plugins shipped with Apache::Session, you can pass the modules you want to use as arguments to the store constructor. The Apache::Session::Whatever part is appended for you: you should not supply it. If you wish to use a module of your own making, you should make sure that it is available under the Apache::Session package namespace. For example:

PerlSetVar SessionManagerStore SharedMem

in order to use Apache::Session::SharedMem to store sessions in RAM (but you must install Apache::Session::SharedMem before!)

The default value is File.

SessionManagerLock Null|MySQL|Semaphore|File

This single directive set lock manager for Apache::Session::Flex. The default value is Null.

SessionManagerGenerate MD5|ModUniqueId|ModUsertrack

This single directive set session ID generator for Apache::Session::Flex. The default value is MD5.

SessionManagerSerialize Storable|Base64|UUEncode

This single directive set serializer for Apache::Session::Flex. The default value is Storable.

SessionManagerStoreArgs

With this directive you must provide whatever arguments are expected by the backing store and lock manager that you've chosen. The arguments are passed as comma-separated list of name/value pairs.

For instance if you use File for your datastore, you need to pass store and lock directories:

PerlSetVar SessionManagerStoreArgs "Directory     => /tmp/apache_sessions, \
                                    LockDirectory => /tmp/apache_sessions/lock"

If you use MySQL for your datastore, you need to pass database connection informations:

PerlSetVar SessionManagerStoreArgs "DataSource => dbi:mysql:sessions, \
                                    UserName   => user, \
                                    Password   => password"

Please see the documentation for store/lock modules in order to pass right arguments.

SessionManagerItemExclude string|regex

This single directive defines the exclusion string. For example:

PerlSetVar SessionManagerItemExclude exclude_string

All the HTTP requests containing the 'exclude_string' string will be declined. Also is possible to use regex:

PerlSetVar SessionManagerItemExclude "\.m.*$"

and all the request (URI) ending by ".mpeg", ".mpg" or ".mp3" will be declined.

The default value is:

(\.gif|\.jpe?g|\.png|\.mpe?g|\.css|\.js|\.txt|\.mp3|\.wav|\.swf|\.avi|\.au|\.ra?m)$

SessionManagerSetEnv On|Off

This single directive set the SESSION_MANAGER_SID environment variable with the current (valid) session ID:

PerlSetVar SessionManagerSetEnv On

It makes session ID available to CGI scripts for use in absolute links or redirects. The default value is Off.

SessionManagerDebug level

This single directive set debug level.

PerlSetVar SessionManagerDebug 3

If greather than zero, debug informations will be print to STDERR. The default value is 0 (no debug information will be print).

URI TRACKING NOTES

There are some considerations and issues in order to use the session ID embedded in the URI. In fact, this is a possible cookieless solution to track session ID between browser and server.

If you enable session ID URI tracking you must place all the PerlSetVar directives you need in server config context (that is outside of <Directory> or <Location> sections) otherwise the handler will not work for these requests. The reason of this is that the URI will be rewrite with session ID on the left and all <Location> that you've defined will match no longer.

Alternatively it is possible to use <LocationMatch> section. For instance:

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager
		
   <LocationMatch "^/([0-9a-h]+/)?my-app-dir">
      SetHandler perl-script
      PerlHandler MyModule
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerURITracking On
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_sessions"
   </LocationMatch>

to match also URI with embedded session ID.

Another issue is if you use a front-end/middle-end architecture with a reverse proxy front-end server in front (for static content) and a mod_perl enabled server in middle tier to serve dynamic contents. If you use Apache as reverse proxy it became impossible to set the ProxyPass directive either because it can be palced only in server config and/or <VirtualHost> context, either because it isn't support for regex to match session ID embedded in the URI.

In this case, you can use the proxy support available via the mod_rewrite Apache module by putting in front-end server's httpd.conf:

ProxyPass /my-app-dir http://middle-end.server.com:9000/my-app-dir
ProxyPassReverse / http://middle-end.server.com:9000/

RewriteEngine On
RewriteRule (^/([0-9a-h]+/)?my-app-dir.*) http://middle-end.server.com:9000$1 [P,L]

Take careful to make all links to static content as non relative link (use "http://myhost.com/images/foo.gif" or "/images/foo.gif") or the rewrite engine will proxy these requests to mod_perl server.

TODO

  • Add the possibility of auto-switch session ID tracking from cookie to URI in cookieless situation. The code from Greg Cope session manager implementation could be integrated.

  • Add the query string param support (other than cookie and URI) to track session ID between browser and server.

  • Include into the distro the session cleanup script (the scripts I use for cleanup actually)

  • Embed the cleanup policies not in a extern scripts but in a register_cleanup method

  • Update test suite to run correclty under Win32 platform

  • Test, test ,test

AUTHORS

Enrico Sorcinelli <enrico@sorcinelli.it>

THANKS

A particular thanks to Greg Cope <gjjc@rubberplant.freeserve.co.uk> for freeing Apache::SessionManager namespace from his RFC (October 2000). His SessionManager project can be found at http://sourceforge.net/projects/sessionmanager

BUGS

This library has been tested by the author with Perl versions 5.005, 5.6.0 and 5.6.1 on different platforms: Linux 2.2 and 2.4, Solaris 2.6 and 2.7 and Windows 98.

Send bug reports and comments to: enrico@sorcinelli.it In each report please include the version module, the Perl version, the Apache, the mod_perl version and your SO. If the problem is browser dependent please include also browser name and version. Patches are welcome and I'll update the module if any problems will be found.

SEE ALSO

Apache::Session, Apache::Session::Flex, Apache::Request, Apache, perl(1)

COPYRIGHT AND LICENSE

Copyright (C) 2001,2002 Enrico Sorcinelli. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.