2.2. Settings
Each setting can be supplied in three ways — web.xml (or addInitParameter), an environment variable, or a JVM system property. The result is the same whichever you use.
The "Settings and Defaults" section below lists the names as they appear in web.xml. The names to use for environment variables and system properties are in the "Name Mapping" table that follows.
If more than one is used at the same time, they take precedence in this order.
1. Environment variable KSM_SESSION_TIMEOUT ← strongest
2. System property ksm.session.timeout
3. web.xml <param-name>sessionTimeout
This is useful when the same image is deployed to several environments (development, staging, production). You can adjust behavior by changing only the environment variables, leaving the application untouched.
The renaming rule is to insert a separator at word boundaries — sessionTimeout → KSM_SESSION_TIMEOUT (environment variable) → ksm.session.timeout (system property).
The values in web.xml can themselves use ${variable:default}. For example, <param-value>${session.timeout:30}</param-value> uses the value of the system property session.timeout if it exists, and 30 otherwise.
Settings and Defaults
The defaults are those in KhanSessionFilter.getSessionFilterConfig() in the source. If you omit a setting, this value is used.
Store Connection
| Setting name | Description | Default |
|---|---|---|
| configFile | Name of the file holding the session store connection information (the file created in step 2) | None — you must provide it. Without it, startup fails with an error |
| infinispanCache | Name of the cache holding session metadata | KHAN_SESSION |
| infinispanLoginCache | Name of the cache holding session data | KHAN_SESSION_LOGIN |
| namespace | Prefix added to store keys. Distinguishes systems when several share one store | KHAN |
Cookies
| Setting name | Description | Default |
|---|---|---|
| sessionId | Name of the cookie that identifies the session. The WAS JSESSIONID is left as it is and this cookie is added; this value is what is used to find the session in the data grid | __KSMSID__ |
| domain | Domain across which the session is shared. Hosts that differ only by subdomain can share it (for example, login.openmaru.io and www.openmaru.io) | (none) |
| path | Path across which the session is shared. Set it to / to share between different web applications | / |
| secure | The cookie's Secure flag. Sends the cookie over HTTPS only | false |
| httpOnly | The cookie's HttpOnly flag. Prevents JavaScript from reading the cookie | false |
| sameSite | The cookie's SameSite attribute | (none) |
Session Behavior
| Setting name | Description | Default |
|---|---|---|
| sessionTimeout | Session timeout in minutes. A non-numeric value falls back to the default and an error is recorded in the log | 10 |
| sessionSaveDelay | How long to defer writing the session to the store, in seconds. 0 means no delay | 0 |
| excludeRegExp | Request paths for which no session is created (regular expression). Prevents sessions from being created for static files such as images and CSS | (none — if omitted, a session is created for every request) |
| enableImmediateSave | When true, saves to the store immediately on every setAttribute() call | false |
| enableImmediateRead | When true, reads directly from the store every time a session value is read | false |
| useLibraryMode | Runs in library mode. Not used in remote data grid mode | false |
| useAuthenticator | Uses WAS authentication integration | false |
Duplicate Login
| Setting name | Description | Default |
|---|---|---|
| allowDuplicateLogin | Whether duplicate logins are allowed. The default is false, so duplicate login prevention is on from the start. Set true to allow them | false |
| duplicateLoginPolicy | Duplicate login policy. none does nothing, legacy logs out the previously logged-in user, and custom manages duplicates as a list of sessions. If allowDuplicateLogin is true, this value is ignored and fixed at legacy | legacy |
| invalidateDuplicateLogin | Whether to invalidate the existing session automatically when a duplicate login is found. When false, the session is kept and the user is only sent to the logout URL | false |
| duplicateLoginExclustionType | User types excluded from the duplicate login check. Separate several with commas | (none) |
| logoutUrl | Logout URL to send the user to when a duplicate login is found. If left empty, the user is not redirected | (empty string) |
Monitoring
| Setting name | Description | Default |
|---|---|---|
| enableStatistics | Exposes session metrics as MBeans. On by default. Set false to turn it off | true |
| enableMemoryStatistics | Also measures session memory usage. Requires the Java agent to be configured | false |
Name Mapping
These are the names to use when supplying the same setting as an environment variable or a JVM system property.
| Setting name (web.xml) | Environment variable | JVM system property |
|---|---|---|
| configFile | KSM_CONFIG_FILE | ksm.config.file |
| namespace | KSM_NAMESPACE | ksm.namespace |
| infinispanCache | KSM_INFINISPAN_CACHE | ksm.infinispan.cache |
| infinispanLoginCache | KSM_INFINISPAN_LOGIN_CACHE | ksm.infinispan.login.cache |
| sessionId | KSM_SESSION_ID | ksm.session.id |
| domain | KSM_DOMAIN | ksm.domain |
| path | KSM_PATH | ksm.path |
| secure | KSM_SECURE | ksm.secure |
| httpOnly | KSM_HTTP_ONLY | ksm.http.only |
| sameSite | KSM_SAME_SITE | ksm.same.site |
| sessionTimeout | KSM_SESSION_TIMEOUT | ksm.session.timeout |
| sessionSaveDelay | KSM_SESSION_SAVE_DELAY | ksm.session.save.delay |
| excludeRegExp | KSM_EXCLUDE_REG_EXP | ksm.exclude.reg.exp |
| allowDuplicateLogin | KSM_ALLOW_DUPLICATE_LOGIN | ksm.allow.duplicate.login |
| duplicateLoginPolicy | KSM_DUPLICATE_LOGIN_POLICY | ksm.duplicate.login.policy |
| invalidateDuplicateLogin | KSM_INVALIDATE_DUPLICATE_LOGIN | ksm.invalidate.duplicate.login |
| duplicateLoginExclustionType | KSM_DUPLICATE_LOGIN_EXCLUSTION_TYPE | ksm.duplicate.login.exclustion.type |
| logoutUrl | KSM_LOGOUT_URL | ksm.logout.url |
| enableImmediateSave | KSM_ENABLE_IMMEDIATE_SAVE | ksm.enable.immediate.save |
| enableStatistics | KSM_ENABLE_STATISTICS | ksm.enable.statistics |
| enableMemoryStatistics | KSM_ENABLE_MEMORY_STATISTICS | ksm.enable.memory.statistics |
| enableImmediateRead | KSM_ENABLE_IMMEDIATE_READ | ksm.enable.immediate.read |
| useLibraryMode | KSM_USE_LIBRARY_MODE | ksm.use.library.mode |
| useAuthenticator | KSM_USE_AUTHENTICATOR | ksm.use.authenticator |
configFile can also be specified through the OPENMARU_CONFIG_FILE environment variable.