Skip to main content
Version: 4.6.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:

  1. Stop all nevisProxies within the remote cache cluster.
  2. Control and adjust DB according to the schema described in the reference guide the chapter Prerequisites for SQL-based remote caches.
  3. Clean the remote cache DB.
  4. Update nevisProxy.
  5. 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 MySQL table: Cache configuration:

  • For all caches (TLS, COOKIE, and HTTPSESSION):

    Deprecated

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.

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 nameType, usage constraints, defaultsDescription
ConfigTableNamestring required, basicThe init-param ConfigTableName configures the name of the table holding the remote cache configuration (e.g. max. lifetime, max. inactivity time)
TableNamestring required, basicThe init-param TableName configures the name of the table holding the cache rows.
DataRowNamestring array required, basicThe 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.
DataRowSizeintegerrequired, basicThe size of the column DataRowName in the MySQL database.
UserNamestring required, basicThe init-param UserName configures the username used for connecting to the database.
PassWordstring required, basicThe init-param PassWord configures the password used for connecting to the database.
ConnectStringstring required, basicThe init-param ConnectString configures the MySQL connect string used for connecting to the database.
MinConnintegerrequired, basicThe init-param MinConn configures the minimum number of connections for the MySQL connection pool. These connections will be established on startup.
MaxConnintegerrequired, basicThe init-param MaxConn configures the maximum number of connections for the MySQL connection pool.
IncrConnintegerrequired, basicThe init-param IncrConn configures the number of new connections that should be opened if the connection pool is exhausted.
TimeOutintegerrequired, basicThe init-param TimeOut configures the MySQL connection pool timeout.
ConnectionErrorCodesinteger array required, basicThe init-param ConnectionErrorCodes configures the (comma-separated) MySQL error codes that should trigger a reinitialization of the connection pool.

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, that is, the column names and types.

Column nameType, Usage Constraints, DefaultsDescription
cache_namestringName of the cache table. This is the value of the TableName init-param of the respective cache provider
namestringName of the config parameter (key)
valuestringValue of the config parameter

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

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):

Config parameterType, Usage Constraints, DefaultsDescription
maxLifetimeintegerSame semantics as SSLCache.maxLifetime.
renegotiationbooleanSame semantics as SSLCache.renegotiation.
maxInactiveIntervalintegerSame semantics as SSLCache.maxInactiveInterval.

RemoteCookieCache configuration

Deprecated

Remote cookie caches are elements of the Container Session Handling and as such have been deprecated. 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 parameterType, usage constraints, defaultsDescription
maxLifetimeintegerSame semantics as CookieCache.maxLifetime
randomSizeintegerSame semantics as CookieCache.randomSize
cookieNamestringSame semantics as CookieCache.cookieName
checkIPbooleanSame semantics as CookieCache.checkIP
maxInactiveIntervalintegerSame semantics as CookieCache.maxInactiveInterval

RemoteHttpSession

Deprecated

Remote HTTP caches/sessions are elements of the Container Session Handling and as such have been deprecated. 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 parameterType, Usage Constraints, DefaultsDescription
maxInactiveIntervalintegerSame semantics as HttpSession.maxInactiveInterval
maxEntrySizeintegerSame semantics as HttpSession.maxEntrySize
maxAttributesintegerSame semantics as HttpSession.maxAttributes
clientTypeCheckbooleanSame semantics as HttpSession.clientTypeCheck
maxLifeTimeCheckboolean optional, advanced default: falseSame semantics as HttpSession.maxLifeTimeCheck
limitMaxInactiveIntervalintegerSame semantics as HttpSession.limitMaxInactiveInterval