Apache::SessionManager - mod_perl 1.0/2.0 session manager extension to manage sessions over HTTP requests
In httpd.conf (mod_perl 1):
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>
In httpd.conf (mod_perl 2):
PerlModule Apache2 PerlModule Apache::SessionManager PerlTransHandler Apache::SessionManager <Location /my-app-with-session> SetHandler perl-script PerlResponseHandler Apache::MyModule PerlSetVar SessionManagerTracking On PerlSetVar SessionManagerExpire 3600 PerlSetVar SessionManagerInactivity 900 PerlSetVar SessionManagerStore File PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_sessions" </Location>
In a mod_perl module handler:
sub handler { my $r = shift; my $session = Apache::SessionManager::get_session($r); ... }
Apache::SessionManager is a mod_perl (1.0 and 2.0) module that helps session management of a web application. This 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:
SESSION_MANAGER_HANDLE
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; # same as $session->{'key'} = $value;
or it is possible to read value session with:
print "$$session{'key'}"; # same as print $session->{'key'};
Apache::SessionManager is intended also to use within thirdy part packages. See Apache::SessionManager::cookpod for more info.
Since version 1, Apache::SessionManager is fully compatible with both mod_perl generations 1.0 and 2.0.
If you have mod_perl 1.0 and 2.0 installed on the same system and the two uses the same per libraries directory, to use mod_perl 2.0 version make sure to load first Apache2 module which will perform the necessary adjustements to @INC:
Apache2
@INC
PerlModule Apache2 PerlModule Apache::SessionManager
Of course, notice that if you use mod_perl 2.0, there is no need to pre-load the Apache::compat compatibility layer.
Versions of Apache::SessionManager less than 1.00 are mod_perl 1.0 only, so its works fine with mod_perl 2.0 only under Apache::compat.
Apache::SessionManager offers two kinds of interfaces: functional and object oriented. For a detailed description for the last one, see "METHODS" section.
The following functions are provided (but not exported) by this module:
Apache::SessionManager::get_session(Apache->request)
Return an hash reference to current session object.
In a CGI Apache::Registry script:
my $session = Apache::SessionManager::get_session(Apache->request);
Apache::SessionManager::destroy_session(Apache->request)
Destroy the current session object.
sub handler { my $r = shift; ... Apache::SessionManager::destroy_session($r); ... }
Apache::SessionManager::destroy_session(Apache->request);
Apache::SessionManager also provides an object oriented interface described in this section. Apache::SessionManager subclass $r Apache request object by adding following methods:
$r
my $r = new Apache::SessionManager(Apache->request)
Tipically, in a mod_perl module handler:
sub handler { my $r = new Apache::SessionManager(shift); ... }
$r->get_session
my $session = $r->get_session;
It is the equivalent of Apache::SessionManager::get_session functional approach.
Apache::SessionManager::get_session
$r->get_session_param( $session_key,...)
Returns an array containing session values correspondent to keys passed as arguments.
my @values = $r->get_session_param('foo', 'baz');
Called with no args, return all session values.
In a scalar context return the stringyfied version of array.
$r->set_session_param( %args );
Set session values:
$r->set_session_param( foo => $foo, baz => \%baz );
Called with no arguments, has no effects.
$r->delete_session_param( $session_key,...)
Delete session values:
$r->delete_session_param('foo', 'baz');
$r->destroy_session
Destroy the current session object. It is the equivalent of Apache::SessionManager::destroy_session functional approach.
Apache::SessionManager::destroy_session
In order to install and use this package you will need Perl version 5.005 or better.
Prerequisites:
mod_perl 1.0 or 2.0 is required (of course) with the appropriate call-back hooks (PERL_TRANS=1 PERL_HEADER_PARSER=1)
Apache::Session >= 0.53 is required
Apache::Cookie >= 0.33 (libapreq) is preferred but not required (CGI::Cookie will be used instead)
CGI::Cookie (used only if Apache::Request isn't installed)
Installation as usual:
% perl Makefile.PL % make % make test % su Password: ******* % make install
To enable session tracking with this module you could modify httpd.conf or .htaccess files.
To enable session tracking with this module via httpd.conf (or any files included by the Include directive) you must add the following lines:
Include
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 only in certain locations:
<Location /my-app-dir> PerlSetVar SessionManagerTracking On </Location>
Also, it is possible to deactivate session management explicitly:
<Location /my-app-dir-without> PerlSetVar SessionManagerTracking Off </Location>
Note: If you want to control session management by directory, you cannot use PerlTransHandler, but you must install the module in a phase where the mapping of URI->filename has been made. Generally Header parsing phase is a good place:
PerlTransHandler
Header parsing
PerlModule Apache::SessionManager <Directory /usr/local/apache/htdocs/perl> <FilesMatch "\.perl$"> SetHandler perl-script PerlHandler Apache::Registry PerlSendHeader On PerlSetupEnv On Options ExecCGI PerlHeaderParserHandler Apache::SessionManager PerlSetVar SessionManagerTracking On PerlSetVar SessionManagerExpire 3600 PerlSetVar SessionManagerInactivity 900 PerlSetVar SessionManagerName REGISTRY_SESSIONID PerlSetVar SessionManagerStore File PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_sessions" </FilesMatch> </Directory>
In the case you don't have access to httpd.conf or you want work with .htaccess files only , you can put similar directives directly into an .htaccess file:
<FilesMatch "\.(cgi|pl)$"> PerlHeaderParserHandler Apache::SessionManager PerlSetVar SessionManagerTracking On PerlSetVar SessionManagerExpire 3600 PerlSetVar SessionManagerInactivity 900 PerlSetVar SessionManagerName PERLSESSIONID PerlSetVar SessionManagerStore File PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session" PerlSetVar SessionManagerDebug 5 </FilesMatch>
The only difference is that you cannot use Location directive (I used FilesMatch) and you must install Apache::SessionManager in Header parsing phase of Apache request instead of URI translation phase.
Location
FilesMatch
URI translation
In this cases it is necessary to install Apache::SessionManager in Header parsing phase and not into URI translation phase (in this phase, .htaccess hasn't yet been processed).
Using .htaccess, it is possible to use only cookies for the session tracking.
See Apache::SessionManager::cookpod for more info about module configuration and use within thirdy part packages.
You can control the behaviour of this module by configuring the following variables with PerlSetVar directive in the httpd.conf (or .htaccess files)
PerlSetVar
SessionManagerTracking
This single directive enables session traking
PerlSetVar SessionManagerTracking On
It can be placed in server config, <VirtualHost>, <Directory>, <Location>, <Files> and .htaccess context. The default value is Off.
Off
SessionManagerURITracking
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
This single directive defines global sessions expiration time (in seconds).
PerlSetVar SessionManagerExpire 900
If non set, the default value is 3600 seconds. A 0 explicit value means no expiration time session control, and the session will die when the user will close the browser.
3600
0
Because both mod_perl 1 (to 1.29) and 2 (to 1.99_11, fixed in 1.99_12-dev) has a bug which with "PerlSetVar Foo 0", $->dir_config('Foo') return undef instead of 0, there are the aliases none or no or disabled which can be used instead of 0:
PerlSetVar Foo 0
$->dir_config('Foo')
undef
none
no
disabled
PerlSetVar SessionManagerExpire none
The module put the user start session time in a special session key _session_start.
_session_start
SessionManagerInactivity
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.
_session_timestamp
SessionManagerName
This single directive defines session cookie name
PerlSetVar SessionManagerName PSESSID
The default value is PERLSESSIONID
PERLSESSIONID
SessionManagerCookieArgs
With this directive you can provide optional arguments for cookie attributes setting. The arguments are passed as comma-separated list of name/value pairs. The only attributes accepted are:
Domain
Set the domain for the cookie.
Path
Set the path for the cookie.
Secure
Set the secure flag for the cookie.
Expires
Set expire time for the cookie.
For instance:
PerlSetVar SessionManagerCookieArgs "Path => /some-path, \ Domain => .yourdomain.com, \ Secure => 1"
Please see the documentation for Apache::Cookie or CGI::Cookie in order to see more cookie arguments details.
SessionManagerStore
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
This single directive set lock manager for Apache::Session::Flex. The default value is Null.
Null
SessionManagerGenerate
This single directive set session ID generator for Apache::Session::Flex. The default value is MD5.
MD5
SessionManagerSerialize
This single directive set serializer for Apache::Session::Flex. The default value is Storable.
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
This single directive defines the exclusion string. For example:
PerlSetVar SessionManagerItemExclude exclude_string
All the HTTP requests containing the 'exclude_string' string in the URI 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.
If SessionManagerItemExclude isn't defined, the default value is:
(\.gif|\.jpe?g|\.png|\.mpe?g|\.css|\.js|\.txt|\.mp3|\.wav|\.swf|\.avi|\.au|\.ra?m)$
Note If you want process each request, you can set SessionManagerItemExclude with:
PerlSetVar SessionManagerItemExclude "^$"
SessionManagerHeaderExclude
This directive allows to define HTTP headers contents in order to decline requests that match them. For example:
PerlSetVar SessionManagerHeaderExclude "User-Agent => SomeBot"
All the HTTP requests containing the 'SomeBot' string in the HTTP User-Agent header will be declined. Also is possible to use regex:
User-Agent
PerlSetVar SessionManagerHeaderExclude "User-Agent => SomeBot\s*/\*\d+\.\d+"
All HTTP headers are available (case sensitive) to use in the exclusion rules.
In order to set more than one rule you must use PerlAddVar directive:
PerlAddVar
PerlSetVar SessionManagerHeaderExclude "User-Agent => SomeBot\s*/\*\d+\.\d+" PerlAddVar SessionManagerHeaderExclude "User-Agent => GoogleBot" PerlAddVar SessionManagerHeaderExclude "Referer => ^http:\/\/some\.host\.com"
Why could be useful to decline request based on HTTP headers check? If you store session ID in the URI, this prevent bot search engines to index URL with the session ID.
SessionManagerIPExclude
Matchs client IP addresses against IP list and declines request. It's possible to set an IP address and optionally a bitmask:
233.76.193.0/24
233.76.193.1/32 (or simply 233.76.193.1)
For example:
PerlSetVar SessionManagerIPExclude "127.0.0.0/8 192.168.0.0/16 195.31.218.3"
Note that since 1.03 Apache::SessionManager version, non dotted-quad IP will be skipped.
1.03
SessionManagerSetEnv
Sets the SESSION_MANAGER_SID environment variable with the current (valid) session ID:
SESSION_MANAGER_SID
PerlSetVar SessionManagerSetEnv On
It makes session ID available to CGI scripts for use in absolute links or redirects. The default value is Off.
To retrieve the SESSION_MANAGER_SID environment variabile you can do, for instance:
mod_perl
print $r->subprocess_env('SESSION_MANAGER_SID');
CGI
print $ENV{'SESSION_MANAGER_SID'};
Server Side Includes
<!--#echo var="SESSION_MANAGER_SID" -->
SessionManagerDebug
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).
SessionManagerEnableModBackhand
This single directive enable mod_backhand sticky session load balancing support. Someone asked me this feature, so I've added it.
PerlSetVar SessionManagerEnableModBackhand On
A few words on mod_backhand. mod_backhand is a load balancing Apache module. mod_backhand can attempt to find a cookie in order to hex decodes the first 8 bytes of its content into an IPv4 style IP address. It will attempt to find this IP address in the list of candidates and if it is found it will make the server in question the only remaining candidate. This can be used to implement sticky user sessions -- where a given user will always be delivered to the same server once a session has been established. Simply turning on this directive, you add hex IP address in front to session_id. See mod_backhand docs for more details (http://www.backhand.org/mod_backhand).
The default value is Off.
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:
mod_rewrite
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.
This is a simple mod_perl handler Apache/MyModule.pm:
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"; # same as $session->{'key'} = "some value"; # read value session print $$session{'key'}; # same as print $session->{'key'}; # destroy session explicitly Apache::SessionManager::destroy_session($r); ... return OK; }
and the correspondent configuration lines in httpd.conf:
PerlModule Apache::SessionManager PerlTransHandler Apache::SessionManager <Location /mymodule> 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>
See also t/lib directory of this distribution for more examples used in Apache live tests.
Use Apache::Test instead of Apache::testold for testing
Add the possibility of auto-switch session ID tracking from cookie to URI in cookieless situation.
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 external scripts but in a register_cleanup method
Test, test ,test ;-)
Enrico Sorcinelli <enrico at sorcinelli.it>
A particular thanks to Greg Cope <gjjc at 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
This library has been tested by the author with Perl versions 5.005, 5.6.x and 5.8.x on different platforms: Linux 2.2 and 2.4, Solaris 2.6 and 2.7 and Windows 98/XP.
Please submit bugs to CPAN RT system at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache-SessionManager or by email at bug-apache-sessionmanager@rt.cpan.org
Patches are welcome and I'll update the module if any problems will be found.
Version 1.03
Apache::SessionManager::cookpod, Apache::Session, Apache::Session::Flex, Apache::Request, Apache::Cookie, CGI::Cookie, Apache, perl(1)
Copyright (C) 2001-2004 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.
To install Apache::SessionManager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::SessionManager
CPAN shell
perl -MCPAN -e shell install Apache::SessionManager
For more information on module installation, please visit the detailed CPAN module installation guide.