Configuring Liberty session persistence to a database

When session data must be maintained across a server restart or an unexpected server failure, you can configure Liberty to persist the session data to a database. This configuration allows multiple servers to share the same session data, and session data can be recovered in the event of a failover.

1. Define a shared session management configuration that you can reuse among all of your servers. You must complete the following steps, as a minimum requirement:
   1. Enable the sessionDatabase-1.0 feature.
   2. Define a data source:

      <dataSource id="SessionDS" ... />

   3. Refer to the data source from the session database configuration.

      <httpSessionDatabase id="SessionDB" dataSourceRef="SessionDS" ... />

   4. Refer to the persistent storage location from the session management configuration.

      <httpSession storageRef="SessionDB" ... />

   Note: The storageRef attribute of the httpSession element and the id attribute of the httpSessionDatabase element are not mandatory. If the sessionDatabase-1.0 feature is enabled and the httpSessionDatabase element references a valid data source, session persistence is enabled even if the storageRef attribute is not set.

   See Database Session Persistence for details about the httpSession and httpSessionDatabase elements.

   For example, you can create a file named ${shared.config.dir}/httpSessionPersistence.xml as follows:

   <server description="Demonstrates HTTP Session Persistence Configuration">
   
       <featureManager>
           <feature>sessionDatabase-1.0</feature>
           <feature>servlet-3.0</feature>
       </featureManager>
   
       <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="${httpPort}">
           <tcpOptions soReuseAddr="true"/>
       </httpEndpoint>
   
       <fileset id="DerbyFiles" includes="*.jar" dir="${shared.resource.dir}/derby/client"/>
       <library id="DerbyLib" filesetRef="DerbyFiles"/>
       <jdbcDriver id="DerbyDriver" libraryRef="DerbyLib"/>
       <dataSource id="SessionDS" jdbcDriverRef="DerbyDriver">
           <properties.derby.client user="user1" password="password1" 
                                    databaseName="${shared.resource.dir}/databases/SessionDB" 
                                    createDatabase="create"/>
       </dataSource>
   
       <httpSessionDatabase id="SessionDB" dataSourceRef="SessionDS"/>
       <httpSession storageRef="SessionDB" cloneId="${cloneId}"/>
   
       <application id="test" name="test" type="ear" location="${shared.app.dir}/test.ear"/>    
   
   </server>

   Note: When multiple servers are configured to persist session data to the same database, those servers must share the same session management configuration. Any other configuration is not supported. For example, it is not possible for one server to use a multi-row schema while another server uses a single-row schema.

   The HTTP server plugin uses the clone ID that is inserted into the response/request header to maintain session affinity between requests. While the clone ID is normally unchanging, in Liberty, the clone ID is generated when you start a server for the first time and it is regenerated if you start the server with the --clean option. For production use, manually assigning a clone ID will ensure that the ID is stable and that request affinity is correctly maintained. The clone ID must be unique for each server and can be 8 to 9 alphanumeric characters in length and is specified in step 3.

2. Include the shared session management configuration in each of your servers. For example, create two server.xml files for server instances named s1 and s2, as follows:
   • ${wlp.user.dir}/servers/s1/server.xml
   • ${wlp.user.dir}/servers/s2/server.xml

   <server description="Example Server">
       <include location="${shared.config.dir}/httpSessionPersistence.xml"/>
   </server>

   See Using include elements in configuration files.

3. Specify unique variables in the bootstrap.properties file of each server.
   • ${wlp.user.dir}/servers/s1/bootstrap.properties

     httpPort=9081
     cloneId=s1

   • ${wlp.user.dir}/servers/s2/bootstrap.properties

     httpPort=9082
     cloneId=s2

4. Create a table for session persistence before you start the servers.
   • If you want to change the default row size, table name, or table space name, see Database Session Persistence for details about the httpSessionDatabase element.
   • No additional action is required if your server is installed on one of the distributed operating systems. The server automatically creates the table.
   • If your server is using DB2® for session persistence, you can increase the page size to optimize performance for writing large amounts of data to the database.
5. Synchronize the system clocks of all machines that host Liberty servers. If the system clocks are not synchronized, session invalidation can occur prematurely
6. Optional: If required, integrate HTTP sessions and security in Liberty. By default, after a session is created and accessed within a protected resource with security enabled, only the originating owner of that session can access it. Session security (security integration) is enabled by default.
7. Optional: If required, Install and configure the web server plug-in to route requests to each of the servers you configured. The session affinity is only maintained if your plug-in configuration specifies clone IDs that match the clone IDs defined in the server configuration.