Enable the Dynamic Session Engine

Currently, the Nevis product nevisProxy provides two concepts of session handling: the Container Session Handling and the Dynamic Session Management Engine (in short, Dynamic Session Engine). The Container Session Handling offers one set of session handling rules for all sessions. The (newer) Dynamic Session Engine supports the definition of different session management rules for different applications and/or types of requests. This allows for a more flexible and fine-grained way of session handling.

The Dynamic Session Engine replaces the Container Session Handling, which is therefore in the process of being faded out. For all new setups, always use the Dynamic Session Engine. Also for existing setups, switch to the Dynamic Session Engine, if possible.

This chapter explains how to enable the Dynamic Session Engine and to disable the legacy Container Session Handling with nevisAdmin. For more detailed information on the Dynamic Session Management Engine, see the nevisProxy reference guide.

tip

To disable the legacy Container Session Handling and to enable the Dynamic Session Engine with nevisAdmin, you need a nevisProxy version 3.12.19.3 or higher.

The enabling of the Dynamic Session Management consists of the following steps:

1. Disable the legacy Container Session Handling (see the chapter Disable the legacy Container Session Handling).
2. Set the parameters of the DefaultSessionManagementFilter, if required (see the chapter Set the parameters of the DefaultSessionManagementFilter).
3. Set the parameters of the DefaultSessionManagementLocalServlet, if required (see the chapter Set the parameters of the DefaultSessionManagementLocalServlet).
4. See the chapter Remote session cache on how to use a remote database for session storage.

Disable the legacy Container Session Handling

You disable the legacy Container Session Handling on environment level. Perform the next steps:

1. In the navigation pane of the Configuration tab, select the relevant environment (no. 1 in the figure below). The Environments view opens on the right, displaying the settings of the environment (no. 2).
2. Disable the checkbox Legacy session management (as in the figure, no. 3).
3. Click Update to save the new setting (no. 4).

By disabling the legacy Container Session Handling you in fact enable the Dynamic Session Engine. Upon enabling the Dynamic Session Engine, nevisAdmin creates two resources: the DefaultSessionManagementFilter and the DefaultSessionManagementLocalServlet. The Dynamic Session Engine needs these default filter and servlet to perform correctly. You can modify or add the parameters of the filter or servlet if required. For more information, see the chapter: Set the parameters of the DefaultSessionManagementFilterand the chapter: Set the parameters of the DefaultSessionManagementLocalServlet.

info

nevisAdmin manages the DefaultSessionManagementFilter and the DefaultSessionManagementLocalServlet automatically. You cannot assign these resources to a mapping.

Set the parameters of the DefaultSessionManagementFilter

Upon enabling the Dynamic Session Engine, nevisAdmin automatically creates the DefaultSessionManagementFilter with default settings. If required, you can change the default settings and also add new parameters. Perform the following steps:

1. In the navigation pane of the Configuration tab, select the relevant environment and go to Resources > Filters > Session > DefaultSessionManagementFilter (no. 1 in the figure below). The DefaultSessionManagementFilter view opens on the right, displaying the filter settings (no. 2).

2. These parameters are set by default: Cookie.Name, Identification, MaxInactiveInterval, Servlet.

   See the section below for a description of the parameters.

   1. To modify the value of one of these parameters, click the parameter entry in the field Parameter name on the left (no. 3 in the figure). The parameter's settings appear in the Parameter settings section on the right. Modify the parameter's value in the Value field (no. 4).
   2. Click Update to save the new setting.

3. To add a new parameter to the filter,

   1. Select the parameter from the Select name drop-down list in the section Add parameter from template (no. 5 in the figure).
   2. Set the parameter value in the Value field, which appears on the right after you selected the new parameter from the list.
   3. Click Add to add the new parameter.

Parameters

The section below describes the parameters that are set by default for the DefaultSessionManagementFilter. For a description of all available filter parameters, see the nevisProxy reference guide, chapter SessionManagementFilter.

Cookie.Name

• Type: string

• Usage constraints: optional, mandatory if the Identification parameter is of type "COOKIE"

• Default: NPSession

• Description: Sets the name of the cookie that is sent to the client browser.

  The default name of the cookie for the new Dynamic Session Engine is "NPSession". In the "old" Container Session Handling, however, the default cookie name was "Navajo". If you want to continue using "Navajo", change the cookie name to "Navajo" in the Value field (no. 4 in the figure above.)

  Be aware that the session cookie for the new Dynamic Session Engine must have a different name than the one used by the Container Session Handling. This is especially relevant if you have customized the name of the session cookie in the "old" Container Session Handling. In this case, be sure to give the session cookie of the Dynamic Session Engine a new name. Alternatively, you can alter the name of the old cookie. Therefore, reset the cookieName attribute in the CookieCache part of the navajo.xml file, e.g., by adding "Legacy" to the name: <Cookiename>Legacy.

Identification

• Type: string (enum): COOKIE, CUSTOM, SSL

• Usage constraints: required

• Default: COOKIE

• Description: Identifies the type of session (that is, defines the method of session binding). Depending on the session type, you may have to set other parameters.

  If you want to use SSL identification instead of the default identification with a cookie, configure the SSL cache in the navajo.xml file. For detailed information, see the nevisProxy reference guide, chapters "SSL Cache Configuration" and "RemoteSSLCache".

MaxInactiveInterval

• Type: integer
• Usage constraints: optional
• Default: 300 (seconds)
• Description: Sets the inactivity interval in seconds. After <MaxInactiveInterval> seconds of inactivity, the system stops and removes the session.

Servlet

• Type: string

• Usage constraints: required

• Defaults: DefaultSessionManagement LocalServlet

• Description: Sets the (name of the) session store servlet that stores the session data. The DefaultSessionManagementFilter contacts the session store through the session store servlet.

  The default is DefaultSessionManagementLocalServlet, which nevisAdmin creates automatically upon enabling the Dynamic Session Engine. But nevisAdmin also supports the use of customized session store servlets. If you want to use a customized session store servlet instead of the default DefaultSessionManagementLocalServlet, enter the correct servlet name here. To create a customized session store servlet with nevisAdmin, see the chapter "Various functions". Select the template Simple servlet template > LocalSessionStoreServlet/ MySQLSessionStoreServlet. For more information, see the nevisProxy reference guide.

Set the parameters of the DefaultSessionManagementLocalServlet

Upon enabling the Dynamic Session Engine, nevisAdmin automatically creates the DefaultSessionManagementLocalServlet with default settings. If required, you can change the default settings and also add new parameters. Perform the following steps:

1. In the navigation pane of the Configuration tab, select the relevant environment and go to Resources > Filters > Servlet > DefaultSessionManagementLocalServlet (no. 1 in the figure below). The DefaultSessionManagementLocalServlet view opens on the right, displaying the servlet settings (no. 2).
2. These parameters are set by default: MaxInactiveInterval, MaxLifetime, MemorySize. See the section below for a description of the parameters.
   1. To modify the value of one of these parameters, click the parameter entry in the field Parameter name on the left (no. 3 in the figure). The parameter's settings appear in the Parameter settings section on the right. Modify the parameter's value in the Value field (no. 4).
   2. Click Update to save the new setting.
3. To add a new parameter to the servlet,
   1. Select the parameter from the Select name drop-down list in the section Add parameter from template (no. 5 in the figure).
   2. Set the parameter value in the Value field, which appears on the right after you selected the new parameter from the list.
   3. Click Add to add the new parameter.

Parameters

MaxInactiveInterval

• Type: integer

• Usage constraints: required

• Default: 300 (seconds)

• Description: Sets the maximum period of inactivity (in seconds) of a session in the session store. After <MaxInactiveInterval> seconds of inactivity, the system stops and removes the session.

  The parameter MaxInactiveInterval of the DefaultSessionManagementFilter overrides this parameter, to allow fine-tuning in the creation of sessions.

MaxLifetime

• Type: integer
• Usage constraints: required
• Default: 7200 (seconds)
• Description: Sets the maximum lifetime of a new session in the session store, in seconds.

MemorySize

• Type: integer

• Usage constraints: required

• Default: The system derives the default value of the MemorySize parameter from the configured environment size.

• Description: Sets the number of bytes available in the session store for local session storage. Maximum value: 4294973847 bytes, which is ca. 4 GB.

  If 90% of the memory is used, it is not possible anymore to create a new session. If 95% of the memory is used, it is not possible anymore to modify a session. In both cases, the system traces an ERROR.

NumMutexes

• Type: integer
• Usage constraints: optional, advanced
• Default: 1000
• Description: With the help of mutexes, it is possible to reduce the risk of unintended session overwrites. This parameter sets the maximum number of mutexes to use.

ReaperTimeOut

• Type: integer
• Usage constraints: optional
• Default: 120
• Description: Sets the maximum time in seconds that the session reaper needs for one run. If the session reaper needs more time than defined here, the system assumes that there are serious performance issues with the session store. In this case, the system traces an error event LC01.

Technical implications

This is what happens technically when you commit your modifications and nevisAdmin generates the new Dynamic Session Engine configuration:

• To disable the legacy Container Session Handling, nevisAdmin sets the HTTP session parameter maxEntries to "0" in the HttpSession part of the navajo.xml file.
• Additionally, nevisAdmin writes the settings of the DefaultSessionManagementFilter and the DefaultSessionManagementLocalServlet into the web.xml file.
• nevisAdmin also renames the session cookie of the "old" Container Session Handling, from "Navajo" to "NavajoLegacy" (by resetting the cookieName attribute in the CookieCache part of the navajo.xml file). This allows you to continue using the name "Navajo" for your session cookie in the new Dynamic Session Engine, if required.

note

nevisAdmin does not reset the cookieName attribute if its value differs from the default "Navajo". That is, if you have changed the name of the session cookie according to your requirements. In this case, nevisAdmin leaves the customized cookie name as it is in the navajo.xml file, to avoid interference with a custom configuration.

However, the session cookie must not have the same name for both methods of session handling. When you used a customized cookie name for the legacy Container Session Handling, be sure to use a different name for the cookie in the Dynamic Session Engine. Also, nevisAdmin maps the DefaultSessionManagementFilter to the root /* (if there is no custom session management filter mapped to the root yet).