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
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.
The log filename can contain the parameters %a and %h At run time, %a is replaced by the Liberator’s application name (see the DataSource configuration item application-name), and %h is replaced by the host name of the machine on which the Liberator is running.
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.
The log filename can contain the parameters %a and %h At run time, %a is replaced by the Liberator’s application name (see the DataSource configuration item application-name), and %h is replaced by the host name of the machine on which the Liberator is running.
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 name of the RTTP traffic log file that records the RTTP traffic between a client and the Liberator.
The log filename can contain the parameters %a, %h, %c, %l, and %i. At run time these parameters are replaced as follows:
| Parameter | Replaced by |
|---|---|
|
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. |
Syntax: rttp-log <log-file-name>
Type: string
Default value: rrttp/%c_%l.%i which, for example, translates to rttp/SL4B_JSmith.0x-ab-9
We strongly recommend that the name of the RTTP traffic log file contains at least the %l (user name) and %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: absolute-session-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 characters
Values accepted:
-
Maximum:
255
session-log
session-log specifies the name of the session log file.
The log filename can contain the parameters %a and %h At run time, %a is replaced by the Liberator’s application name (see the DataSource configuration item application-name), and %h is replaced by the host name of the machine on which the Liberator is running.
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-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-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.