<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Session Package</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="index.html" title="Apache Rivet 3.2"><link rel="up" href="index.html" title="Apache Rivet 3.2"><link rel="prev" href="diodisplay_package.html" title="DIODisplay"><link rel="next" href="form.html" title="Form: An HTML Form Fields Generation Utility"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Session Package</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="diodisplay_package.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="form.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="section"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="session_package"></a>Session Package</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3276"></a>Introduction</h3></div></div></div><p style="width:90%">
	This is session management code.  It provides an interface
	to allow you to generate and track a browser's visit as a
	"session", giving you a unique session ID and an interface
	for storing and retrieving data for that session on the
	server.
      </p><p style="width:90%">
	This is an alpha/beta release -- documentation is not in
	final form, but everything you need should be in this file.
      </p><p style="width:90%">
	Using sessions and their included ability to store and
	retrieve session-related data on the server, programmers can
	generate more secure and higher-performance websites.  For
	example, hidden fields do not have to be included in forms
	(and the risk of them being manipulated by the user
	mitigated) since data that would be stored in hidden fields
	can now be stored in the session cache on the server.  Forms
	are then faster since no hidden data is transmitted --
	hidden fields must be sent twice, once in the form to the
	broswer and once in the response from it.
      </p><p style="width:90%">
	Robust login systems, etc, can be built on top of this code.
      </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="requirements"></a>Requirements</h3></div></div></div><p style="width:90%">
	  Currently has only been tested with Postgresql, MySql and Oracle.
	  All DB interfacing is done through DIO, though, so it
	  should be relatively easy to add support for other
	  databases.
	</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3285"></a>Preparing To Use It</h3></div></div></div><p style="width:90%">Create the tables in your SQL server.  With Postgres,
	  do a <span style="font-family:monospace"><span class="command"><strong>psql www</strong></span></span> or whatever DB you
	  connect as, then a backslash-i on
	  <code class="filename">session-create.sql</code></p><p style="width:90%">(If you need to delete the tables, use <code class="filename">session-drop.sql</code>)</p><p style="width:90%">The session code by default requires a DIO handle
	  called <code class="varname">DIO</code> (the name of which can be
	  overridden).  We get it by doing a</p><pre class="programlisting">RivetServerConf ChildInitScript "package require DIO"
RivetServerConf ChildInitScript "::DIO::handle Postgresql DIO -user www"</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3295"></a>Example Usage</h3></div></div></div><p style="width:90%">In your httpd.conf, add:</p><pre class="programlisting">RivetServerConf ChildInitScript "package require Session; Session SESSION"</pre><p style="width:90%">
	  This tells Rivet you want to create a session object named
	  SESSION in every child process Apache creates.</p><p style="width:90%">
	  You can configure the session at this point using numerous
	  key-value pairs (which are defined later in this doc).
	  Here's a quick example:</p><pre class="programlisting">RivetServerConf ChildInitScript "package require Session; Session SESSION \
  -cookieLifetime 120 -debugMode 1"</pre><p style="width:90%">
	  Turn debugging on -debugMode 1 to figure
	  out what's going on -- it's really useful, if
	  verbose.</p><p style="width:90%">
	  In your .rvt file, when you're generating the &lt;HEAD&gt;
	  section:
	</p><pre class="programlisting">SESSION activate</pre><p style="width:90%">
	  Activate handles everything for you with respect to
	  creating new sessions, and for locating, validating, and
	  updating existing sessions.  Activate will either locate
	  an existing session, or create a new one.  Sessions will
	  automatically be refreshed (their lifetimes extended) as
	  additional requests are received during the session, all
	  under the control of the key-value pairs controlling the
	  session object.
	</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3307"></a>Using Sessions From Your Code</h3></div></div></div><p style="width:90%">The main methods your code will use are:</p><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION</span> <span style="font-weight:bold ; font-family:monospace">id</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		After doing a <span style="font-family:monospace"><span class="command"><strong>SESSION activate</strong></span></span>,
		this will return a 32-byte ASCII-encoded random
		hexadecimal string.  Every time this browser comes
		to us with a request within the timeout period, this
		same string will be returned (assuming they have
		cookies enabled).
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION</span> <span style="font-weight:bold ; font-family:monospace">is_new_session</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">returns 1 if it's a new session or 0 if it has
		previously existed (i.e. it's a zero if this request
		represents a "return" or subsequent visit to a
		current session.)</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION new_session_reason</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		This will return why this request is the first
		request of a new session, either "no_cookie" saying
		the browser didn't give us a session cookie,
		"no_session" indicating we got a cookie but couldn't
		find it in our session table, or "timeout" where
		they had a cookie and we found the matching session
		but the session has timed out.
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION store</span>  ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>data</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Given the name of a package, a key, and some data.
		Stores the data in the rivet session cache table.
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION fetch</span>  ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Given a package name and a key, return the data
		stored by the store method, or an empty string if
		none was set.  (Status is set to the DIO error that
		occurred, it can be fetched using the status
		method.)
	      </div></div></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3353"></a>Session Configuration Options</h3></div></div></div><p style="width:90%">The following key-value pairs can be specified when a
	  session object (like SESSION above) is created:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">sessionLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">how many seconds the session will live for.
		7200 == 2 hours
	      </div></div></dd><dt><span class="term">sessionRefreshInterval</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
		If a request is processed for a browser that
		currently has a session and this long has elapsed
		since the session update time was last updated,
		update it.  900 == 15 minutes.  so if at least 15
		minutes has elapsed and we've gotten a new request
		for a page, update the session update time,
		extending the session lifetime (sessions that are in
		use keep getting extended).
	      </div></div></dd><dt><span class="term">cookieName</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"></div>
	      name of the cookie stored on the user's web browser
	      default rivetSession
	    </div></dd><dt><span class="term">dioObject</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
		The name of the DIO object we'll use to access the
		database (default DIO)
	      </div></div></dd><dt><span class="term">gcProbability</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
		The probability that garbage collection will occur
		in percent.  (default 1%, i.e. 1)</div></div></dd><dt><span class="term">gcMaxLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">the number of seconds after which
		data will be seen as "garbage" and cleaned up --
		defaults to 1 day (86400)</div></div></dd><dt><span class="term">refererCheck</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The substring you want to check each
		HTTP referer for.  If the referer was sent by the
		browser and the substring is not found, the session
		will be deleted. (not coded yet)</div></div></dd><dt><span class="term">entropyFile</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The
		name of a file that random binary data can be read
		from.  (<code class="filename">/dev/urandom</code>) Data will
		be used from this file to help generate a
		super-hard-to-guess session ID.</div></div></dd><dt><span class="term">entropyLength</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The number of bytes which will be
		read from the entropy file.  If 0, the entropy file
		will not be read (default 0)</div></div></dd><dt><span class="term">scrambleCode</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
		Set the scramble code to something unique for the
		site or your app or whatever, to slightly increase
		the unguessability of session ids (default "some
		random string")</div></div></dd><dt><span class="term">cookieLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The lifetime of the cookie in
		minutes.  0 means until the browser is closed (I
		think). (default 0)</div></div></dd><dt><span class="term">cookiePath</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The
		webserver subpath that the session cookie applies to
		(defaults to
		<code class="filename">/</code>)</div></div></dd><dt><span class="term">cookieSecure</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Specifies whether the cookie should
		only be sent over secure connections, 0 = any, 1 =
		secure connections only (default
		0)</div></div></dd><dt><span class="term">sessionTable</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The name of the table that session
		info will be stored in (default
		<code class="varname">rivet_session</code>)</div></div></dd><dt><span class="term">sessionCacheTable</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The name of the table that contains
		cached session data (default
		<code class="varname">rivet_session_cache</code>)</div></div></dd><dt><span class="term">debugMode</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Set
		debug mode to 1 to trace through and see the session
		object do its thing (default 0)</div></div></dd><dt><span class="term">debugFile</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The
		file handle that debugging messages will be written
		to (default
		<code class="varname">stdout</code>)
	      </div></div></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3431"></a>Session Methods</h3></div></div></div><p style="width:90%">
	  The following methods can be invoked to find out
	  information about the current session, store and fetch
	  server data identified with this session, etc:
	</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION status</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Return the status of the last operation
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION id</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Get the session ID of the current browser.  Returns
		an empty string if there's no session (will not
		happen is SESSION activate has been issued.)
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION new_session_reason</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Returns the reason why there wasn't a previous
		session, either "no_cookie" saying the browser
		didn't give us a session cookie, "no_session"
		indicating we got a cookie but couldn't find it in
		the session table, or "timeout" when we had a cookie
		and a session but the session had timed out.
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION store</span>  ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>data</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Given a package name, a key string, and a data
		string, store the data in the rivet session
		cache.
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION fetch</span>  ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Given a package name and a key, return the data
		stored by the store method, or an empty string if
		none was set.  Status is set to the DIO error that
		occurred, it can be fetched using the status
		method.
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION delete</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Given a user ID and looking at their IP address we
		inherited from the environment (thanks, Apache),
		remove them from the session table.  (the session
		table is how the server remembers stuff about
		sessions). If the session ID was not specified the
		current session is deleted.
	      </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex;   word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION activate</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">
		Find and validate the session ID if they have one.
		If they don't have one or it isn't valid (timed out,
		etc), create a session and drop a cookie on
		them.
	      </div></div></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idm3487"></a>Getting Additional Randomness From The Entropy File</h3></div></div></div><pre class="programlisting">RivetServerConf ChildInitScript "Session SESSION -entropyFile /dev/urandom \
  -entropyLength 10 -debugMode 1"</pre><p style="width:90%">
	  This options say we want to get randomness from an entropy
	  file (random data pseudo-device) of /dev/urandom, to get ten
	  bytes of random data from that entropy device, and to turn
	  on debug mode, which will cause the SESSION object to output
	  all manner of debugging information as it does stuff.  This
	  has been tested on FreeBSD and appears to work.
      </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="diodisplay_package.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="form.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">DIODisplay </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Form: An HTML Form Fields Generation Utility</td></tr></table></div></body></html>