Configuring session persistence for the Liberty profile

When session data must be maintained across a server restart or an unexpected server failure, you can configure the Liberty profile 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 Liberty profile: Configuration elements in the server.xml file 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" jndiName="jdbc/sessions">
           <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.

   Best Practice: If session affinity is important to your application, explicitly define a unique clone ID for each server. In that way, you do not have to depend on the default clone ID generated by the server, and you can be certain that the value of the clone ID never changes.
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 Liberty profile: Configuration elements in the server.xml file 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 the Liberty profile. 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.