Session configuration
When a user logs into Liberator, a client session is established. The following configuration items define how Liberator handles client sessions.
- add-application-params
- object-log
- request-log
- rttp-log
- rttp-log-users
- session-absolute-max-queue-length
- session-hash-size
- session-heartbeat
- session-id-len
- session-log
- session-max-queue-count
- session-max-queue-length
- session-monitoring-interval
- session-reconnect-timeout
- session-requires-services
- session-timeout
add-application-params
add-application-params specifies an application ID and other parameters that are associated with a particular client application for licencing purposes.
When a client application attempts to log in to Liberator on a user’s behalf, it sends its ID to Liberator via StreamLink. Liberator can keep a count of the number of users allowed to simultaneously connect to Liberator from that particular application, and reject new login attempts once the application’s licenced user limit is reached. The login limit for the application is defined in the Liberator’s licence file.
Syntax:
add-application-params application-id [string] inactivity-period [integer] end-application-params
| Option | Type | Default | Description |
|---|---|---|---|
string |
|
The unique identifier of a client application; for example "SLJS:CaplinTrader". |
|
integer |
|
Inactivity timeout in seconds for a session with this application-id. If Liberator hasn’t detected any user-activity on this session during the timeout period, it kills the session. You only need to define this for applications that use versions of StreamLink earlier than 6.0.2. Make sure the period is greater than the NOOP/SYNC period configured in the StreamLink client, otherwise an excess number of reconnections may occur. |
object-log
object-log specifies the name of the object log file that keeps a record of all request and discard commands for objects, and whether those commands were successful.
| Token | Description |
|---|---|
|
The DataSource application-name. |
|
The host name of the machine on which this DataSource application is running. |
Log files are written to the location specified by the log-dir configuration item.
Syntax: object-log <log-file-name>
Type: string
Default value: object-%a.log which, by default, translates to object-rttpd.log
request-log
request-log specifies the name of the log file that contains a record of each RTTP request made to Liberator.
| Token | Description |
|---|---|
|
The DataSource application-name. |
|
The host name of the machine on which this DataSource application is running. |
Log files are written to the location specified by the log-dir configuration item.
Syntax: request-log <log-file-name>
Type: string
Default value: request-%a.log which, by default, translates to request-rttpd.log
rttp-log
rttp-log specifies the path of the RTTP traffic log file, relative to Liberator’s log directory (see log-dir). The RTTP log records the RTTP traffic between a client and the Liberator.
| Token | Description |
|---|---|
|
The Liberator’s application name (see the DataSource configuration item application-name). |
|
The host name of the machine on which the Liberator is running. |
|
The client application id (for example, "SLJS:CaplinTrader"). |
|
The user name (Liberator login name) associated with the session. |
|
The RTTP session id. |
The value of rttp-log must be a valid existing path relative to the Liberator’s root directory (see log-dir). If any directories in the path are missing, then the Liberator will not create the missing directories automatically and will not log RTTP traffic.
The default value of rttp-log is rttp/%c_%l.%i.log. The directory in this path, rttp, has been created for you in the Liberator kit at var/rttp and in the Deployment Framework at servers/Liberator/var/rttp.
If you change the path in log-dir or in rttp-log, then check the new path is valid and create any missing directories manually.
Syntax: rttp-log <log-file-name>
Type: string
Default value: rttp/%c_%l.%i.log, which, for example, translates to rttp/SL4B_JSmith.0x-ab-9.log
We strongly recommend that the name of the RTTP traffic log file contains at least the %l (user name) and the %i (RTTP session id) parameters, so that a separate log file is generated for each session for each user named in rttp-log-users. If these markers are absent, the log entries for all RTTP sessions will be mixed together in the same file, making it difficult to determine which messages came from which sessions and users.
|
rttp-log-users
rttp-log-users specifies a space-separated list of Liberator users (Liberator login names) for whom RTTP traffic logs are to be generated. If this configuration entry is absent or empty, only RTTP traffic logs that have been specified using the Caplin Management Console are generated. The names of the traffic log files are defined by rttp-log.
Only use the rttp-log-users configuration item for debugging test installations. It permanently enables traffic logging for the specified users, and the users' traffic will be logged even after Liberator is restarted. Logging can only be turned off by stopping the Liberator and changing the rttp-log-users configuration item to an empty string or by removing it from the configuration. In a live system you should normally turn RTTP logging on and off using the Caplin Management Console.
|
Syntax: rttp-log-users <user-name-1> <user-name-2> <user-name-3> …
You can also specify multiple instances of rttp-log-users like this:
rttp-log-users Alf rttp-log-users Bill rttp-log-users Carl
Type: array of strings
Default value: [Empty string] No RTTP traffic is logged other than that specified using the Caplin Management Console.
session-absolute-max-queue-length
session-absolute-max-queue-length specifies the size in bytes that a client session’s message queue has to reach before Liberator drops the connection to the client. When the connection is dropped, a CLOSE event with the reason "CHUCKOUT" is recorded in Liberator’s session log.
| This configuration item is available from Liberator version 6.2.5. |
This configuration item sets an absolute limit on the size of a session queue. The configuration items session-max-queue-length and session-max-queue-count constitute the first-level check against the session queue becoming too large, but session-absolute-max-queue-length always overrides their settings.
If you need to change the default of session-absolute-max-queue-length you should set it to a higher value than session-max-queue-length.
Syntax: session-absolute-max-queue-length <queue-length-in-bytes>
Type: integer
Default value: 1073741824
Also see session-max-queue-length and session-max-queue-count
session-hash-size
session-hash-size specifies the size of Liberator’s session hashtable. We recommend that you set this to twice the expected maximum number of number of concurrent users.
Increasing session-hash-size will result in more memory usage.
|
Syntax: session-hash-size <size-in-table-entries>
Type: integer
Default value: 8192 entries
session-heartbeat
session-heartbeat specifies the interval in seconds between heartbeats sent from Liberator to a StreamLink client. Heartbeat messages allow Liberator to detect when a client connection has been lost even in situations where the operating system can’t, or doesn’t, inform Liberator that this has happened. They also synchronise the client and Liberator clock settings so that message latency calculations are more accurate.
Syntax: session-heartbeat <interval-in-seconds>
Type: integer
Default value: 0 seconds (no heartbeats sent)
| StreamLink automatically turns on session heartbeats on behalf of its client application, by sending a request to Liberator. |
session-id-len
session-id-len specifies the length in characters of the unique identifier for a session. For added security use this option to increase the size of the session id.
Syntax: session-id-len <length-in-chars>
Type: integer
Default value: 12 (Liberator 6) or 22 (Liberator 7)
Values accepted: 1–255
session-log
session-log specifies the name of the session log file.
| Token | Description |
|---|---|
|
The DataSource application-name. |
|
The host name of the machine on which this DataSource application is running. |
Log files are written to the location specified by the log-dir configuration item.
Syntax: session-log <log-filename>
Type: string
Default value: session-%a.log which, by default, translates to session-rttpd.log
session-max-queue-count
session-max-queue-count specifies the maximum number of consecutive times the length of a client’s session queue can increase once its length has exceeded session-max-queue-length. When the session-max-queue-count limit is reached, or the queue length exceeds session-absolute-max-queue-length (whichever occurs first), the connection to the client is dropped and a CLOSE event with the reason "CHUCKOUT" is recorded in Liberator’s session log.
Syntax: session-max-queue-count <count>
Type: integer
Default value: 10 times
session-max-queue-length
session-max-queue-length specifies the size in bytes that a client session’s message queue has to reach before Liberator starts counting the number of consecutive increases to the queue length and tests this count against session-max-queue-count. When the session-max-queue-count limit is reached, or the queue length exceeds session-absolute-max-queue-length (whichever occurs first), the connection to the client is dropped and a CLOSE event with the reason "CHUCKOUT" is recorded in Liberator’s session log.
If you need to change the default of session-max-queue-length you should set it to a lower value than session-absolute-max-queue-length.
Syntax: session-max-queue-length <queue-length-in-bytes>
Type: integer
Default value: 5242880
session-monitoring-interval
session-monitoring-interval defines the time interval in seconds at which Liberator monitors the state of its sessions.
To disable session monitoring, set this item to -1.0 (the default).
Use in: C (Liberator only)
Syntax: session-monitoring-interval <interval-in-seconds>
Type: float
Default value: -1.0
session-reconnect-timeout
session-reconnect-timeout specifies the time in seconds for which Liberator maintains a session when the client has disconnected. If the client reconnects within this time, the session is resumed, but with a new (different) session id.
Syntax: session-reconnect-timeout <time-in-seconds>
Type: integer
Default value: 30 seconds
Also see session-timeout.
session-requires-services
session-requires-services determines when the required-state option of add-data-service is enforced.
When session-requires-services is set to false (the default), the required-state option is enforced from when Liberator starts up to when all data services have reached their required state. Thereafter, required-state is not enforced, even if data services subsequently fall below their required service state.
When session-requires-services is set to true, the required-state option is always enforced. If the service level of a data service falls below the level specified in its required-state option, then the Liberator closes any existing client connections and does not accept new client connections (HTTP 503, "Service unavailable") until the specified service level has been restored. Sessions for closed connections are retained for session-timeout seconds and may be resumed if service levels are restored within this time.
To customise the HTTP 503 error page, see http-error-file-503.
Syntax: session-requires-services <boolean>
Since: Liberator 7.1.19
Type: boolean
Default value: false
session-timeout
session-timeout specifies the time in seconds for which Liberator maintains a session if a user has connected but not managed to log in.
Syntax: session-timeout <time-in-seconds>
Type: integer
Default value: 60 seconds
Also see session-reconnect-timeout.