PostgreSQLSessionStoreServlet

The PostgreSQLSessionStoreServlet facilitates the remote storage of session information into a Postgres database, within the context of the Dynamic Session Management Engine.

You can only use the PostgreSQLSessionStoreServlet in combination with the SessionManagementFilter. The SessionManagementFilter defines the method of session binding, for example, by means of cookies. The filter also creates and handles the session. The PostgreSQLSessionStoreServlet loads and stores the session data in the remote session store, that is, into the remote Postgres database. In particular, the PostgreSQLSessionStoreServlet stores the data that is required to identify and control the user sessions in the Postgres data table.

Compared to the LocalSessionStoreServlet, the PostgreSQLSessionStoreServlet preserves existing sessions when restarting the proxy. It also allows sharing sessions among multiple proxy instances. However, using the PostgreSQLSessionStoreServlet implies separating the proxy from its session store, which will extend the communication time between them. This can also impact the overall performance negatively, compared to using the LocalSessionStoreServlet.

note

The servlet is experimental.

Limitations

All web.xmlfiles that define a PostgreSQLSessionStoreServlet and share the same database (tables) must meet the following conditions:

• All separate web.xml files used by the same nevisProxy instance, which configures a shared remote session store, must have different application ID configured.
• Each nevisProxy instance, which shares one (or multiple) PostgreSQLSessionStore, must use the same (set of) web.xml file(s) configured for the shared remote session store(s). The other web.xml files, which does not configure a shared remote session store, can differ from each other.
• All web.xml files with the same application ID must fulfill the following conditions:
  • They must have equally configured Esauth4ConnectorServlets.
  • They must have equally configured WebSocketServlets.
  • All LuaFilters including a defined Script.NotifySessionInvalidateFunctionName or Script.GlobalStoreAttributeTimeoutFunctionName attribute must be configured in the same way.
  • All SessionManagementFilters with a custom session type must be configured in the same way. The session type is defined by the filter attribute Identification.
  • All HttpConnectorServlets with a set logout URI must be configured in the same way. The logout URI is defined by the servlet attribute LogoutURI.
  • All SessionFilters where the attribute UseSessionToStoreToken is set to false must be configured in the same way.

To set an Application ID, you have to configure it in the web.xml, for example:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "/var/opt/nevisproxy/verification/conf/web-app_2_3.dtd">
  <!-- $Id$ -->
  <web-app>
  <!--Configuring application ID-->
    <context-param>
        <param-name>application-id</param-name>
        <param-value>proxySampleConf</param-value>
    </context-param>
  <!-- rest of the configuration -->
  ...
  </web-app>

Classname

ch::nevis::nevisproxy::servlet::cache::postgresql::PostgreSQLSessionStoreServlet

Library

libPostgreSQLSessionStoreServlets.so.1

Configuration

ConnectString

Type: string
Usage Constraints: required

Sets the Postgres database connect string. The usual format is:

postgresql://[userspec@][hostspec][/dbname][?paramspec]

where userspec is:

user[:password]

and hostspec is:

[host][:port][,...]

and paramspec is:

name=value[&...]

See also https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING

note

When using SSL, the private key file (configured with sslkey param in the connection string) must have permissions u=rw (0600) or less if owned by the proxy user, or permissions u=rw,g=r (0640) or less if owned by root.

SessionsTableName

Type: string
Default: session

Sets the name of the table that holds the proxy sessions.

AttributesTableName

Type: string
Default: attribute

Sets the name of the table that holds the proxy attributes.

KeyToIdMapTableName

Type: string
Default: key_id_map

Sets the name of the table that holds the proxy key-ID map.

ConfigurationsTableName

Type: string
Default: conf

Sets the name of the table that holds the proxy configuration.

MaxConnections

Type: integer
Default: 100
Range: min: 10

Sets the maximum number of open connections.

MaxConnections.WaitTimeout

Type: integer
Unit: milliseconds
Default: 5000
Range: min: 10

Sets the timeout to wait until a connection can be reused again if all the available connections are in used. If no connection can be reused within this time, an error will occur.

EnableMetrics

Type: boolean
Usage Constraints: optional
Default: true

Controls the OpenTelemetry metrics generation of the servlet. If disabled, the servlet won't forward the session statistics as metrics.

Database Configuration

You need to create the following tables in your database:

-- Database setup for session management engine.

CREATE TABLE session (
    SESSION_ID VARCHAR(255) PRIMARY KEY,
    CREATION_TIME INTEGER NOT NULL,
    LAST_ACCESS_TIME INTEGER NOT NULL,
    INACTIVE_TIMEOUT INTEGER NOT NULL,
    FINAL_TIMEOUT INTEGER NOT NULL,
    OWNER_ID BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX owner_id ON session (OWNER_ID);

CREATE TABLE key_id_map (
    KEY_ID VARCHAR(255) PRIMARY KEY,
    SESSION_ID VARCHAR(255) NOT NULL,
    FOREIGN KEY(SESSION_ID) REFERENCES session(SESSION_ID) ON DELETE CASCADE
);

CREATE TABLE attribute (
    SESSION_ID VARCHAR(255) NOT NULL,
    NAME VARCHAR(200) NOT NULL,
    VALUE BYTEA,
    VALUE_SHA BYTEA,
    FOREIGN KEY(SESSION_ID) REFERENCES session(SESSION_ID) ON DELETE CASCADE
);
alter table attribute add constraint uc_id_name unique (SESSION_ID, NAME);

CREATE TABLE conf (
    CACHENAME VARCHAR(100) not null,
    PARAMETER VARCHAR(100) not null,
    VALUE VARCHAR(255) not null
);

insert into conf (CACHENAME, PARAMETER, VALUE) values('session', 'VERSION', '5.7.0.0');
insert into conf (CACHENAME, PARAMETER, VALUE) values('session', 'REAPER', '0');
insert into conf (CACHENAME, PARAMETER, VALUE) values('session', 'INACTIVE_TIMEOUT', '300');
insert into conf (CACHENAME, PARAMETER, VALUE) values('session', 'FINAL_TIMEOUT', '43100');

You need to grant all privileges to the use configured in the ConnectString. For ex.:

GRANT ALL PRIVILEGES ON TABLE session TO <user>;
GRANT ALL PRIVILEGES ON TABLE key_id_map TO <user>;
GRANT ALL PRIVILEGES ON TABLE conf TO <user>;
GRANT ALL PRIVILEGES ON TABLE attribute TO <user>;