Version: 3.14.x.x LTS

Remote caches

Remote caches usually reside in a database and are shared between multiple reverse proxy instances. The configuration for remote caches is the same for all types of caches, since the cache properties are configured in the cache itself, usually in a cache configuration table. Currently the following types of remote caches are supported: MySQL and LocalMemory.

Preconditions

Remote cache supports only session sharing between identically configured instances (in the web.xml file).

Versions and compatibility

nevisProxy versions with the same minor version number work together in a remote cache cluster. If the minor number changes, the following steps must be taken:

Stop all nevisProxies within the remote cache cluster.
Control and adjust DB according to the schema described in the reference guide the chapter Prerequisites for SQL-based remote caches.
Clean the remote cache DB.
Update nevisProxy.
Start all nevisProxies.

Cache provider configuration

A cache provider informs nevisProxy how to communicate with the remote cache. The configuration of a cache provider resembles that of a servlet. Specify an implementation class, the library in which it resides as well as a number of init-params.

Every parameter of the remote cache supports variable replacement.

Prerequisites for SQL-based remote caches

An SQL-based remote cache must contain at least the following tables: Cache configuration:

For all caches (TLS, COOKIE, and HTTPSESSION)

Fading out

Remote HTTP caches and cookie caches are elements of the Container Session Handling and as such in the process of being faded out. Do not use the Container Session Handling, including remote HTTP/cookie caches, anymore. Instead, switch to the Dynamic Session Engine. For more information on the Dynamic Session Engine, see the chapter Dynamic Session Management Engine.

MySQL

create table <ConfigTableName> (
 CACHE_NAME   VARCHAR(100) not null,
 NAME     VARCHAR(100) not null,
 VALUE     VARCHAR(255) not null
);

For TLS and cookie cache

create table <TableName> (
 SESSION_ID     VARCHAR(255) not null,
 <DataRowName>     VARCHAR(<DataRowSize>) ,
 LAST_ACCESS_TIME    integer(22) not null,
 MAX_INACTIVE_INTERVAL   integer(22) not null,
 STATUS_CD         integer(12) not null,
 PRIMARY KEY (SESSION_ID)
);

*The following values have to be saved into the cache configuration table:

INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'domain', '<the domain of the cookie. May be empty>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<SSL-TableName>', 'maxLifetime', '<maxLifetime in secs>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<SSL-TableName>', 'renegotiation', '<true | false>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<SSL-TableName>', 'maxInactiveInterval', '<maxInactiveInterval in secs>');

INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'maxLifetime', '<maxLifetime in secs>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'randomSize', '<randomSize in bytes>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'cookieName', '<the name of the cookie>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'checkIP', '<true | false>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'maxInactiveInterval', '<maxInactiveInterval in secs>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'persistent', '<true | false>');
INSERT INTO <ConfigTableName> (CACHE_NAME, NAME, VALUE) VALUES ('<CookieCache-TableName>', 'domain', '<the domain of the cookie. May be empty>');

For HttpSession-cache

CREATE TABLE <TableName> (
 SESSION_ID     VARCHAR(255) NOT NULL,
 <DataRowName>     TEXT(<DataRowSize>),
 LAST_ACCESS_TIME    integer(22) NOT NULL,
 MAX_INACTIVE_INTERVAL   integer(22) NOT NULL,
 STATUS_CD         integer(12) NOT NULL,
 PARENT_ID         VARCHAR(255),
 OWNER_ID      VARCHAR(255),
 IS_VIRTUAL     integer(1),
PRIMARY KEY(SESSION_ID)
);

For performance tuning add as well:

create index i_http_cache_is_virtual on <TableName> (parent_id);

Prepared statements: The remote cache uses prepared statements for performance reasons. 15 prepared statements per cache type per connection are needed. To calculate the total prepared statements use this formula: For every cache type you have in the MySQL database

   <calculated number of prepared statements>
   <number of instances> * <number of configured connections perinstance> * 15

And in the database you have to set the following statement to make sure you have enough prepared statements configured

set global max_prepared_stmt_count=<calculated number of prepared statements>;

If you see the following error in the navajo.log

2017 01 09 10:50:18.704 isi3web NavajoMysq 17208.139795399653120.5500aaa3-4338-15ac4151-15982a2b634-0003511b 3-ERROR :
MysqlConnector_1_0::connectToDatabase: could not prepare statement-cache for '<your SQL statement>'
(Error: Can't create more than max_prepared_stmt_count statements (current value: 16382))

then this is because the max_prepared_stmt_count is too low for your setup.

Connection timeout parameters: You can configure mysql to close opened connections after a certain amount of time. The default value is 28800 sec (8 hours). If you want to reduce this time, insert these two settings into MySql configuration file (/etc/my.cnf) in group.

   wait_timeout=<time in seconds>
interactive_timeout=<time in seconds>

You can also achieve this by issuing the next MySql commands to set the variables in MySql console:

   set global wait_timeout=<time in seconds>;
 set global interactive_timeout=<time in seconds>;

The following details the configuration of the MySql cache provider.

The update of the last-access-time can be a very time-expensive operation. To reduce the number of operations, the bc-property 'ch.nevis.navajo.cache.provider.mysql.InactiveTimeoutInterval' may be set. If the value is set to '>0', the last-access-time will only be updated, if more than 'ch.nevis.navajo.cache.provider.mysql.InactiveTimeoutInterval' seconds have expired since the last update. Be aware that with this setup, the maximal inactive timeout may be reduced by 'ch.nevis.navajo.cache.provider.mysql.InactiveTimeoutInterval' in a worst-case-scenario.

init-param name	Type, usage constraints, defaults	Description
ConfigTableName	string required, basic	The init-param ‘ConfigTableName’ configures the name of the table holding the remote cache configuration (e.g. max. lifetime, max. inactivity time)
TableName	string required, basic	The init-param ‘TableName’ configures the name of the table holding the cache rows.
DataRowName	string array required, basic	The init-param ‘DataRowName’ configures the name of the column used to store the data. If multiple names are given (separated by commas), multiple columns will be used for holding the data.
DataRowSize	integerrequired, basic	The size of the column ‘DataRowName’ in the MySql-Database.
UserName	string required, basic	The init-param ‘UserName’ configures the username used for connecting to the database.
PassWord	string required, basic	The init-param ‘PassWord’ configures the password used for connecting to the database.
ConnectString	string required, basic	The init-param ‘ConnectString’ configures the MySql connect string used for connecting to the database.
MinConn	integerrequired, basic	The init-param ‘MinConn’ configures the minimum number of connections for the MySql connection pool. These connections will be established on startup.
MaxConn	integerrequired, basic	The init-param ‘MaxConn’ configures the maximum number of connections for the MySql connection pool.
IncrConn	integerrequired, basic	The init-param ‘IncrConn’ configures the number of new connections that should be opened if the connection pool is exhausted.
TimeOut	integerrequired, basic	The init-param ‘TimeOut’ configures the MySql connection pool timeout.
ConnectionErrorCodes	integer array required, basic	The init-param ‘ConnectionErrorCodes’ configures the (comma-separated) MySql error codes that should trigger a reinitialization of the connection pool.

The following details the configuration of the Local-Memory cache provider.

Deprecated

The Local-Memory cache provider is deprecated and will be removed. Instead, use the SessionManagementFilter with the LocalSessionStore.

init-param name	Type, usage constraints, defaults	Description
MemoryType	enum required: heap or shared	The init-param 'MemoryType configures type of memory to use for saving the data. If 'shared' is used, the init-param 'MemorySize' has to be set as well
MemorySize	integer required if MemoryType=shared	The size of memory to reserve for shared memory.

Note that the MySql provider does not contain any semantic configuration of the cache, it is only a means for abstracting the communication. The cache configuration is held in the database, in the table referenced by the 'ConfigTableName' init-param. The following table illustrates the format of this table, i.e. the column names and types.

Column name	Type, Usage Constraints, Defaults	Description
cache_name	string	Name of the cache table. This is the value of the 'TableName' init-param of the respective cache provider
name	string	Name of the config parameter (key)
value	string	Value of the config parameter

In the following chapters we will thus only describe the contents of this table for the different types of caches.

For the Local-Memory cache provider those values are set as init parameters as well.

RemoteSSLCache

A RemoteSSLCache can be configured wherever an SSLCache may be configured. For a RemoteSSLCache, the following configuration parameters must exist in the config table (MySql) or as init-parameter (Local-Memory):

Config parameter	Type, Usage Constraints, Defaults	Description
maxLifetime	integer	Same semantics as SSLCache.maxLifetime.
renegotiation	boolean	Same semantics as SSLCache.renegotiation.
maxInactiveInterval	integer	Same semantics as SSLCache.maxInactiveInterval.

The example below shows the configuration of a remote TLS cache (or technically RemoteSSLCache) using a Local-Memory cache provider.

Deprecated

The Local-Memory cache provider is deprecated and will be removed. Instead, use the SessionManagementFilter with the LocalSessionStore.

<RemoteSSLCache>
 <CacheProvider>
 <provider-class>
ch::nevis::navajo::cache::provider::localMemory::LocalMemoryCacheProvider
 </provider-class>
 <provider-lib>libnavajo_inmem_provider.so.1</provider-lib>
 <init-param>
 <!-- 'heap' or 'shared' -->
 <param-name>MemoryType</param-name>
 <param-value>shared</param-value>
 </init-param>
 <init-param>
 <!-- MemorySize: size of the shared memory. Will be ignored
 if MemoryType is 'heap' -->
 <param-name>MemorySize</param-name>
 <param-value>1500000</param-value>
 </init-param>
 <init-param>
 <!-- maxInactiveInterval: maximal inactive interval in secs -->
 <param-name>maxInactiveInterval</param-name>
 <param-value>300</param-value>
 </init-param>
 <init-param>
 <!-- renegotiation: enable renegotiation, true or false -->
 <param-name>renegotiation</param-name>
 <param-value>true</param-value>
 </init-param>
 <init-param>
 <!-- maxLifetime: maximal lifetime in secs -->
 <param-name>maxLifetime</param-name>
 <param-value>36000</param-value>
 </init-param>
 </CacheProvider>
</RemoteSSLCache>

RemoteCookieCache configuration

Fading out

Remote cookie caches are elements of the Container Session Handling and as such in the process of being faded out. Do not use the Container Session Handling, including remote cookie caches, anymore. Instead, switch to the Dynamic Session Engine. For more information on the Dynamic Session Engine, see chapter Dynamic Session Management Engine:

Configuration parameter	Type, usage constraints, defaults	Description
maxLifetime	integer	Same semantics as CookieCache.maxLifetime
randomSize	integer	Same semantics as CookieCache.randomSize
cookieName	string	Same semantics as CookieCache.cookieName
checkIP	boolean	Same semantics as CookieCache.checkIP
maxInactiveInterval	integer	Same semantics as CookieCache.maxInactiveInterval

RemoteHttpSession

Fading out

Remote HTTP caches/sessions are elements of the Container Session Handling and as such in the process of being faded out. Do not use the Container Session Handling, including remote HTTP caches/sessions, anymore. Instead, switch to the Dynamic Session Engine. For more information on the Dynamic Session Engine, see the chapter Dynamic Session Management Engine:

Config parameter	Type, Usage Constraints, Defaults	Description
maxInactiveInterval	integer	Same semantics as HttpSession.maxInactiveInterval
maxEntrySize	integer	Same semantics as HttpSession.maxEntrySize
maxAttributes	integer	Same semantics as HttpSession.maxAttributes
clientTypeCheck	boolean	Same semantics as HttpSession.clientTypeCheck
maxLifeTimeCheck	boolean optional, advanced default: false	Same semantics as HttpSession.maxLifeTimeCheck
limitMaxInactiveInterval	integer	Same semantics as HttpSession.limitMaxInactiveInterval

Remote caches

Prerequisites for SQL-based remote caches​

Prerequisites for SQL-based remote caches