Skip to main content
Version: 8.2405.x.x RR

Appendix E - SessionStore configuration changes introduced with 4.38.0.12

nevisAdmin4 managed instances

The following migration instructions do not apply to nevisAuth instances managed by nevisAdmin4, as no manual migration is required.

The configuration restructuring is implemented as follows:

  • Session attribute configurations are moved to the SessionCoordinator element.
  • Indexing configuration of sessions are moved to the SessionIndexing element.
  • Local session store related configurations are moved to the LocalSessionStore element.
  • Remote session store related configurations are moved to the RemoteSessionStore element.

Detailed example

Most of the changes consist of adding a prefix for easier identification and moving the attribute or property to different elements. For sake of readability, the following examples keep the element order in both configuration examples.

The following additional changes have taken place:

  • The size attribute is renamed to maxSessions.
  • The idPregenerate attribute is renamed to sessionIdPreGenerate. Notice that the G is capital now.
  • The enableIndexing attribute is removed, use the SessionIndexing element instead.
    • The previous value on is no longer required, to turn on session indexing, the element SessionIndexing has to exist.
    • The previous value off is no longer required, to turn off session indexing, remove the element SessionIndexing.
    • The previous value your.session.attribute can be defined in the attribute attribute of the SessionIndexing element. In case the attribute is not defined, the default value is ch.nevis.session.loginid as before, when specifying on.
  • The attribute failSafe is removed as it is not necessary anymore. The purpose of it was to turn on or off the remote session store. To configure the remote session, define a RemoteSessionStore element or remove it if it is not needed.
  • The property syncMaxConnectionKeepAlive is renamed to connectionMaxLifeTime to better reflect its usage.

Hints

  • All new attributes are validated, therefore nevisAuth will not start until all issues are fixed.
  • The behaviour of the session store did not change, just the configuration attributes.
    • SessionIndexing is optional.
    • LocalSessionStore is required.
    • RemoteSessionStore is optional.

Old configuration snippet:

Old configuration snippet
<SessionCoordinator>
<SessionCache
initialInactivityTimeout="300"
inactivityTimeout="86400"
initialMaxLifetime="900"
maxLifetime="86400"
idRandomBytes="32"
idPregenerate="true"
enableIndexing="your.session.attribute"
size="100000"
reaperPeriod="60"
failSafe="true">

<property name="syncProvider" value="jdbc"/>
<property name="syncUser" value="nss_auth"/>
<property name="syncPassword" value="nss_auth"/>
<property name="syncTarget" value="jdbc:mariadb://localhost:3306/NSS"/>
<property name="syncMaxConnectionKeepAlive" value="60000" />
<property name="syncMaxConnectionPoolSize" value="20"/>
<property name="syncMaxRetry" value="2"/>
<property name="syncRemoteSessionReaperPeriod" value="60" />
<property name="syncRemoteSessionReaperInitialDelay" value="30" />
<property name="syncRemoteSessionReaperThreads" value="1" />
<property name="syncRemoteSessionAbsToTolerance" value="10"/>
<property name="syncRemoteSessionIndexFormat" value="normal" />
<property name="syncPullInitial" value="false"/>
<property name="syncFailRetryPeriod" value="0"/>
<property name="syncFailRetryCount" value="0"/>
<property name="syncUnauthenticSessions" value="true"/>
</SessionCache>
...
</SessionCoordinator>

New configuration snippet:

New configuration snippet
<SessionCoordinator
sessionInitialInactivityTimeout="300"
sessionInactivityTimeout="86400"
sessionInitialMaxLifetime="900"
sessionMaxLifetime="86400"
sessionIdRandomBytes="32"
sessionIdPreGenerate="true">

<SessionIndexing
attribute="your.session.attribute"
attributeMapping="none" />

<LocalSessionStore
maxSessions="100000"
reaperPeriod="60" />

<RemoteSessionStore
provider="jdbc"
connectionUser="nss_auth"
connectionPassword="nss_auth"
connectionUrl="jdbc:mariadb://localhost:3306/NSS"
connectionMaxLifeTime="60000"
connectionMaxPoolSize="20"
connectionMaxRetry="2"
reaperPeriod="60"
reaperInitialDelay="30"
reaperThreads="1"
reaperTimeoutTolerance="10"
syncPullInitial="false"
syncFailRetryPeriod="0"
syncFailRetryCount="0"
storeUnauthenticatedSessions="true"/>
...
</SessionCoordinator>

Changes in default values

In case nothing is set in the esauth4.xml.

SessionCoordinator

attributeoldnew
sessionInitialInactivityTimeout300600
sessionInactivityTimeout8640028800
sessionInitialMaxLifetime9001200
sessionMaxLifetime8640028800
sessionIdRandomBytes1632
sessionIdPreGeneratefalsetrue

LocalSessionStore

attributeoldnew
maxSessions1024100000

RemoteSessionStore

attributeoldnew
reaperTimeoutTolerance180010% of MaxLifetime
syncPullInitialtruefalse
syncFailRetryPeriod20000100
syncFailRetryCount31
storeUnauthenticatedSessionsfalsetrue

Deprecated properties:

attributeoldnew
syncDelay10000
syncRefreshInterval-10
syncThreads15

TokenAssembler.TokenSpec

attributeoldnew
ttl720028800

Troubleshooting

Startup errors

In case you have some invalid element in the configuration, an error will occur during the startup of nevisAuth. In the following example, the SessionCoordinator had a name attribute which is not valid.

Note, that the error message has reverse logic, it says you have an unexpected element which should be defined in the schema. What, in fact needs to be done is to remove the name attribute.

Caused by: java.lang.IllegalStateException: AuthenticationManagerOperationsSkeleton: initialization failed (ch.nevis.esauth.BadConfigurationException: org.jdom2.input.JDOMParseException: Error on line 6 of document file:/var/opt/nevisauth/default/conf/esauth4.xml:
Attribute "name" must be declared for element type "SessionCoordinator".)

Wrong default values

The default values are based on the esauth4.dtd. In case you have an older instance you might have a local esauth4.dtd in your instance directory. For example: /var/opt/nevisauth/<instance>/conf/esauth4.dtd. Make sure to change your esauth4.xml DOCTYPE section to point to /opt/nevisauth/dtd/esauth4.dtd.