# 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
   xref:application-id[application-id]    [string]
   xref:inactivity-period[inactivity-period] [integer]
end-application-params
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `<a name="application-id"></a>application-id` | string | `NULL` | The unique identifier of a client application; for example "SLJS:CaplinTrader".  |
| `<a name="inactivity-period"></a>inactivity-period` | integer | `0` | Inactivity timeout in seconds for a session with this [application-id](#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](../streamlink/index.md) 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](../datasource/datasource-run-time-environment-configuration.md#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](liberator-rttp.md) 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](../datasource/datasource-run-time-environment-configuration.md#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](liberator-rttp.md) 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](../datasource/datasource-run-time-environment-configuration.md#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:** `rrttp/%c_%l.%i` which, for example, translates to `rttp/SL4B_JSmith.0x-ab-9`

**💡 TIP**\
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](#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](../cmc/index.md) are generated. The names of the traffic log files are defined by [rttp-log](#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](../cmc/index.md).

**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](../cmc/index.md).

## 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.

**📌 NOTE**\
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](#session-max-queue-length) and [session-max-queue-count](#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](#session-max-queue-length) and [session-max-queue-count](#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.

**📌 NOTE**\
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](../streamlink/index.md) 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)

**📌 NOTE**\
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](../datasource/datasource-run-time-environment-configuration.md#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](#session-max-queue-length). When the `session-max-queue-count` limit is reached, or the queue length exceeds [session-absolute-max-queue-length](#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](#session-max-queue-count). When the `session-max-queue-count` limit is reached, or the queue length exceeds [session-absolute-max-queue-length](#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](../datasource/datasource-datasource-monitoring-configuration-part-2.md#session-monitoring-interval) in [DataSource monitoring configuration (part 2)](../datasource/datasource-datasource-monitoring-configuration-part-2.md).

## 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

`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](#session-reconnect-timeout).