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

**Supported substitution tokens**

| Token | Description |
| --- | --- |
| %a | The DataSource [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name). |
| %h | 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](../datasource/datasource-logging-configuration.md#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](liberator-rttp.md) request made to Liberator.

**Supported substitution tokens**

| Token | Description |
| --- | --- |
| %a | The DataSource [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name). |
| %h | 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](../datasource/datasource-logging-configuration.md#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](../datasource/datasource-logging-configuration.md#log-dir)). The RTTP log records the [RTTP](liberator-rttp.md) traffic between a client and the Liberator.

**Supported substitution tokens**

| Token | Description |
| --- | --- |
| %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. |

The value of `rttp-log` must be a valid existing path relative to the Liberator’s root directory (see [log-dir](../datasource/datasource-logging-configuration.md#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](../datasource/datasource-logging-configuration.md#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`

**💡 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](#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.

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:** `session-absolute-max-queue-length <queue-length-in-bytes>`

**Type:** integer

**Default value:** `1073741824`

**Since:** Liberator 6.2.5

Also see [session-max-queue-length](#session-max-queue-length) and [session-max-queue-count](#session-max-queue-count)

## session-check-queue-length-time

`session-check-queue-length-time` specifies the number of seconds that a session queue length needs to have exceeded the [session-max-queue-length](#session-max-queue-length) size 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.

If this item is configured to a value greater than 0, then any [session-max-queue-count](#session-max-queue-count) configuration is ignored and session chuckout is decided based only on this configuration.

This configuration defaults to 0 which disables this method of managing session chuck out.

**Syntax:** `session-check-queue-length-time <time-in_seconds>`

**Type:** integer

**Default value:** `0`

**Since:** Liberator 7.1.35

Also see [session-max-queue-length](#session-max-queue-length).

## 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` (Liberator 6) or `22` (Liberator 7)

**Values accepted:** `1`–`255`

## session-log

`session-log` specifies the name of the session log file.

**Supported substitution tokens**

| Token | Description |
| --- | --- |
| %a | The DataSource [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name). |
| %h | 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](../datasource/datasource-logging-configuration.md#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](#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

`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-timeout).

## session-requires-services

`session-requires-services` determines when the [`required-state`](../datasource/datasource-data-services-configuration.md#required-state) option of `add-data-service` is enforced.

When `session-requires-services` is set to `false` (the default), the [`required-state`](../datasource/datasource-data-services-configuration.md#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`](../datasource/datasource-data-services-configuration.md#required-state) option is always enforced. If the service level of a data service falls below the level specified in its [`required-state`](../datasource/datasource-data-services-configuration.md#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](#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`](liberator-http-configuration-part-1.md#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](#session-reconnect-timeout).