Session configuration

When a user logs into Liberator, a client session is established. The following configuration items define how Liberator handles client sessions.

Contents:

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
application-id string NULL

The unique identifier of a client application; for example "SLJS:CaplinTrader". 

inactivity-period integer 0

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
%a The Liberator's application name (see the DataSource configuration item application-name). 
%h The host name of the machine on which the Liberator is running.
%c The client application id (for example, "SLJS:CaplinTrader").
%l  The user name (Liberator login name) associated with the session.
%i The RTTP session id.

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

Tip: 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.

Tip: 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: 1255

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

See session-monitoring-interval in DataSource monitoring configuration (part 2).

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.