Persistent session failover in JRun

JRun can be configured to enable session persistence, meaning that all session data is saved (persisted) upon the completion of every request. When a server that is servicing a client's session goes down, the client's active session data can be retrieved intact from a common data store (such as a JDBC database) by another server. When the client attempts to continue its active session and presents its session ID to the replacement server, its session data is restored from the repository, completing the session failover.

This feature is called session swapping. The client's session state is effectively swapped from one server to another when the first fails.

Session swapping overview

The following are required to use failover for persistent sessions with ClusterCATS:

Session swapping must be enabled in JRun and ClusterCATS. For more information, see "Configuring JRun for session swapping" and "Configuring ClusterCATS for session swapping", respectively.
Session-aware load balancing must be enabled. Because only one server can be responsible for a session at a time, JRun session swapping must be used in conjunction with the ClusterCATS session-aware load-balancing feature. This ensures that multiple servers do not have concurrent access to the same session data. For more information, see "Session-aware load balancing".
A repository used for persistent session data must be shared among the JRun servers in a cluster. For information, see "Using shared files for session swapping". For an example of using JDBC to connect to a shared repository of session information, see "Using JDBC for session swapping".
Cookies must have domain scope for proper session swapping. For more information, see "Configuring JRun for session swapping".

Configuring JRun for session swapping

To enable session swapping in JRun, the following properties must be set in the JRun server's local.properties file:

session.swapping=true
session.maxresident=0

The local.properties file must enable domain scope for cookies by including the following property:

session.cookie.domain=yourdomain.com

The repository used for session swapping can be a shared file or a shared JDBC database. For information, see "Using shared files for session swapping" and "Using JDBC for session swapping".

Configuring ClusterCATS for session swapping

ClusterCATS must be configured to allow session swapping to function properly. The following platform-specific procedures explain how to enable session swapping in ClusterCATS.

To enable session swapping on Windows:

Edit the registry (using regedit) and open the following key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BrightTiger\
Parameters

Add the following REG_DWORD value:
```
SessionSwapping    1
```
Close the registry editor.
Repeat this procedure for every server in the cluster.

To enable session swapping on UNIX:

Log in as the super user (root).
Stop ClusterCATS by issuing the following command:
```
# /usr/lib/btcats/btadmin stop all
```
Edit the file /usr/lib/btcats/database/bt.registry with a text editor.
Search for the following string:
```
hkey_local_machine\system\currentcontrolset\services\brighttiger\
parameters:5
```
Under the following entry:
Advertise: 0x2; REG_DWORD
Add the following line:
SessionSwapping: 0x1 ; REG_DWORD
Save the file and exit your text editor.
Restart ClusterCATS with the following command:
```
# /usr/lib/btcats/btadmin start all
```
Repeat this procedure for every server in the cluster.

Using shared files for session swapping

To use file swapping, the JRun server's local.properties file should contain the following properties:

session.persistence.service=file
session.persistence.file.class=allaire.jrun.session.FileSessionStorage
# See the following paragraph for more on this property.
session.persistence.file.path=/mnt/myothermachine/sessionpool

The session.persistence.file.path property must specify a shared path that all computers can read and write to. For example, on UNIX, you must have server1 export /sessionpool and server1's file.path=/sessionpool. Now server2 should mount server1:/sessionpool to some mount point - for example, /mnt/sessionpool - and set server2's file.path=/mnt/sessionpool. This assumes that server2 has write permission.

Note: If JRun runs as an NT service, and you use a mapped drive, JRun does not have permissions to write to the drive. To correct this problem, edit the properties for the JRun Service and change the user account for the service to be a user with the necessary privileges to write to the mapped drive.

Using JDBC for session swapping

To use JDBC for session swapping, the JRun server's local.properties file should contain the following properties:

session.persistence.service=jdbc
session.persistence.jdbc.class=allaire.jrun.session.JDBCSessionStorage
session.persistence.jdbc.JDBCDriver=sun.jdbc.odbc.JdbcOdbcDriver
session.persistence.jdbc.JDBCConnectionURL=jdbc:odbc:JRunSessions
session.persistence.jdbc.JDBCSessionTable=sessions
session.persistence.jdbc.JDBCSessionIDColumn=id
session.persistence.jdbc.JDBCSessionDataColumn=data

JDBC swapping requires that you have a valid JDBC driver that can successfully connect to the database. You must create a table in your database with an id column and a data column. This example uses a table named sessions, an IDColumn named id, and a DataColumn named data. Define the id column as varchar(255) and the data column as binary data.

Using ClusterCATS
Configuring Clusters