Skip to main content
Version: 7.2405.x.x LTS

Setting up the MultiLevelSessionStoreServlet

Description of the use case​

This chapter explains how to set up the MultiLevelSessionStoreServlet. The setup consists of two nevisProxy instances storing the sessions in their own local store with a backup in a common remote store hosted by a MariaDB database. This hybrid configuration aims at providing optimal performance in the normal operation mode while enabling session retrieval in a failover scenario. To this end, the MultiLevelSessionStoreServlet combines a LocalSessionStoreServlet with a MySQLSessionStoreServlet. The setup is tested with MariaDB version 10.3.16.

Prerequisites​

The following conditions must be fulfilled for the MultiLevelSessionStoreServlet to work correctly:

  • The sessions must be handled by the SessionManagementFilter of the Dynamic Session Engine.
  • The client must be identified by a cookie (see the Identification parameter of the SessionManagementFilter).
  • The load balancer must be session-sticky.
  • In case of a failover from proxy A to proxy B, the load balancer must continue routing existing clients to proxy B after proxy A is back online.
  • The same limitations that are valid for the MySQLSessionStoreServlet also apply here.

Instructions​

In this explanation, there are two nevisProxy instances called "host-proxy1" and "host-proxy2". The database host is called "host-db1".

Setup of the shared session store​

The shared session store is hosted by a MariaDB database. The database setup is the same as the single-node session store for the MySQLSessionStoreServlet.

Setup of nevisProxy​

The following components are needed in your nevisProxy configuration for both instances. Unless otherwise stated, the configuration elements are part of the web.xml file.

SessionManagementFilter​

In the SessionManagementFilter, the Servlet parameter must point to the MultiLevelSessionStoreServlet, and the Identification parameter must be set to "Cookie". The other parameters can be set to your convenience.

SessionManagementFilter​
<filter>
    <filter-name>CookieBasedSessionManagementFilter</filter-name>
    <filter-class>ch::nevis::nevisproxy::filter::session::SessionManagementFilter</filter-class>
    <init-param>
            <param-name>Servlet</param-name>
            <param-value>MultiLevelSessionStoreServlet</param-value>
    </init-param>
    <init-param>
            <param-name>Identification</param-name>
            <param-value>Cookie</param-value>
    </init-param>
    <init-param>
            <param-name>Cookie.Secure</param-name>
            <param-value>false</param-value>
    </init-param>
    <init-param>
            <param-name>Cookie.HttpOnly</param-name>
            <param-value>true</param-value>
    </init-param>
    <init-param>
            <param-name>Cookie.Name</param-name>
            <param-value>NPSession</param-value>
    </init-param>
    <init-param>
        <param-name>UpdateTimeStampMinInterval</param-name>
        <param-value>30</param-value>
    </init-param>
</filter>

As usual, map the SessionManagementFilter to the path for which it should provide sessions. For instance:

SessionManagementFilterMapping​
<filter-mapping>
    <filter-name>CookieBasedSessionManagementFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

MultiLevelSessionStoreServlet​

The MultiLevelSessionStoreServlet acts as the go-between between the local and the backup session stores. Configure it with the MainServlet parameter pointing to the LocalSessionStoreServlet and the BackupServlet parameter pointing to the MySQLSessionStoreServlet:

MultiLevelSessionStoreServlet​
<servlet>
    <servlet-name>MultiLevelSessionStoreServlet</servlet-name>
    <servlet-class>ch::nevis::nevisproxy::servlet::cache::multilevel::MultiLevelSessionStoreServlet</servlet-class>
    <init-param>
        <param-name>MainServlet</param-name>
        <param-value>LocalSessionStoreServlet</param-value>
    </init-param>
    <init-param>
        <param-name>BackupServlet</param-name>
        <param-value>MySQLSessionStoreServlet</param-value>
    </init-param>
    <init-param>
        <param-name>BackupThreads</param-name>
        <param-value>10</param-value>
    </init-param>
</servlet>

Session Store Servlets​

The next code blocks show sample configurations for the session store servlets. They are basically standard LocalSessionStoreServlet and MySQLSessionStoreServlet servlets that you can configure to your convenience.

LocalSessionStoreServlet​
<servlet>
    <servlet-name>LocalSessionStoreServlet</servlet-name>
    <servlet-class>ch::nevis::nevisproxy::servlet::cache::local::LocalSessionStoreServlet</servlet-class>
    <servlet-lib>libLocalSessionStoreServlets.so.1</servlet-lib>
    <init-param>
        <param-name>MemorySize</param-name>
        <param-value>1073741824</param-value>
    </init-param>
    <init-param>
        <param-name>MaxLifetime</param-name>
        <param-value>1800</param-value>
    </init-param>
    <init-param>
        <param-name>MaxInactiveInterval</param-name>
        <param-value>1800</param-value>
    </init-param>
</servlet>

The values of the MaxLifetime and MaxInactiveInterval parameters of the LocalSessionStoreServlet above are only examples. They configure the same time-outs as the database parameters in the conf table:

  • MaxInactiveInterval <=> INACTIVE_TIMEOUT (from DB conf table)
  • MaxLifetime <=> FINAL_TIMEOUT (from DB conf table)

We suggest that you use the same values for the corresponding parameters in the LocalSessionStoreServlet and the database configuration.

MySQLSessionStoreServlet​
<servlet>
    <servlet-name>MySQLSessionStoreServlet</servlet-name>
    <servlet-class>ch::nevis::nevisproxy::servlet::cache::mysql::MySQLSessionStoreServlet</servlet-class>
    <init-param>
        <param-name>UserName</param-name>
        <param-value>nevisproxyuser</param-value>
    </init-param>
    <init-param>
        <param-name>Password</param-name>
        <param-value>nevisproxypassword</param-value>
    </init-param>
    <init-param>
        <param-name>ConnectString</param-name>
        <param-value>//host-db1:port1/single_node_session_store?connect_timeout=10&amp;ping_timeout=1</param-value>
    </init-param>
    <init-param>
        <param-name>TimeOut</param-name>
        <param-value>3000</param-value>
    </init-param>
</servlet>

Compatibility with the fail-safe remote session store​

The MultiLevelSessionStoreServlet is compatible with the fail-safe remote session store. If you want to combine both setups, configure the MultiLevelSessionStoreServletas described here and the database replication as explained in the section Setting up a fail-safe session store using data replication with MariaDB.

When using this combined setup, both proxy instances should list the MariaDB hosts in the same order in the ConnectString parameter of their MySQLConnectorServlet. For instance:

ConnectString for combined setup​

<init-param>
    <param-name>ConnectString</param-name>
    <param-value>replication://host-db1:port1,host-db2:port2/replicated_session_store?connect_timeout=10&amp;ping_timeout=1</param-value>
</init-param>