# Tuning configuration

These Liberator configuration items enable you to tune Liberator’s performance.

For links to more tuning related configuration, see the related links at the foot of this page.

## buf-cache-size

`buf-cache-size` specifies the overall size of Liberator’s buffer cache in megabytes.

**📌 NOTE**\
We suggest a maximum value of 512 megabytes

**Syntax:** `buf-cache-size <size-in-megabytes>`

**Type:** integer

**Default value:** `16` megabytes

## buf-elem-len

`buf-elem-len` specifies the length of of a standard buffer element, in bytes. Increasing this improves performance if using very large messages, but it will considerably affect memory usage.

**📌 NOTE**\
We recommend using the default value of 4096 bytes.

**Syntax:** `buf-elem-len <length-in-bytes>`

**Type:** integer

**Default value:** `4096` bytes

## container-yield-size

`container-yield-size` specifies the maximum number of records that can be served from a container before the operation yields possession of the session thread and is moved to the back of the session thread’s work queue. Serving containers in batches of rows prevents the serving of a large container from delaying the processing of other operations in a session thread’s queue. This increases the perceived responsiveness of a client application, at the expense of a small overhead in switching between operations.

**❗ IMPORTANT**\
When setting a window size for a StreamLink subscription to a container ([Subscription.setContainerWindow](https://docs.caplin.com/developer/api/streamlinkjs/latest/caplin.streamlink.Subscription.html#setContainerWindow)), set the window size to a value less than the value of `container-yield-size`.

**Since**: Liberator 7

**Syntax:** `container-yield-size <size-in-entries>`

**Type**: integer

**Default value**: `100`

**Values accepted**: `1–_n_` (where n is the maximum value of an integer on the platform)

## disable-monitoring

`disable-monitoring` is used to disable specific types of Liberator monitoring. It can be used to disable a combination of object, session, and listener (subscription) monitoring.

If you disable object or session monitoring (or both), listener monitoring is also disabled.

**Syntax:** `disable-monitoring <option>[|...]`

**Options    **

|     |     |
| --- | --- |
| **Option** | **Description** |
| none | Disable nothing |
| objects | Disable object and listener monitoring |
| sessions | Disable session and listener monitoring |
| listeners | Disable listener monitoring |

**Type:** string

**Default value:** `none`

**Examples:**

**Disable object and listener monitoring**

```
disable-monitoring objects
```

**Disable object, session, and listener monitoring**

```
disable-monitoring objects|sessions
```

## json-yield-size

`json-yield-size` is the maximum number of bytes of a JSON message (a chunk) that can be added to an outbound queue in one go before the operation yields possession of the session thread and is moved to the back of the session thread’s work queue. Serving JSON messages in chunks prevents the serving of a large JSON object from delaying the processing of other operations in a session thread’s queue. This increases the perceived responsiveness of a client application, at the expense of a small overhead in switching between operations.

**Since**: Liberator 7.1.8

**Syntax**: `json-yield-size <size-in-bytes>`

**Type**: integer

**Valid values**: `80` to `2147483647`

**Default value**: 

* Liberator 7.1.33+: `65536` (64KB)
* Liberator 7.1.8–7.1.32: `16384` (16KB)

## json-yield-retry-time

`json-yield-retry-time` is the amount of time in seconds to back off after yielding.

**Since**: Liberator 7.1.8

**Syntax**: `json-yield-retry-time <time-in-seconds>`

**Type**: integer

**Default value**: `0.01`

## object-hash-size

`object-hash-size` specifies the size of the hashtable that Liberator uses to manage its objects. Increasing this item makes Liberator use extra memory, but it speeds up updates and requests if the value is high enough to ensure there aren’t too many hash collisions.

In addition to requested objects, Liberator allocates an internal object for each client session. So, at a minimum, set `object-hash-size` to: `max_num_objects + max_concurrent_users`.

We recommend that you set `object-hash-size` to _twice_ the maximum number of objects that Liberator is likely to handle. 

**Syntax:** `object-hash-size <size-in-table-entries>`

**Type:** integer

**Default value:** `16384`

## output-queue-size

`output-queue-size` specifies the number of update messages the Liberator stores per client. The main use for this item is when a client loses its connection to Liberator; while the connection is down, Liberator stores updates that are received for the client’s subscriptions and sends them to the client when the connection is re-established.

**💡 TIP**\
Increase the queue size if there are lots of reconnects, or if the data updates fast and the queue fills up quickly.

**Syntax:** `output-queue-size <size-in-messages>`

**Type:** integer

**Default value:** `64` messages

**Values accepted:** Maximum `4096` messages

## response-batch-size

`response-batch-size` specifies the maximum size in bytes of RTTP response messages. It only applies when the StreamLink connection type is "Streaming JavaScript via IFrame" ("type 5" connections).

**Syntax:** `response-batch-size <size-in-bytes>`

**Type:** integer

**Default value:** `0` (no maximum size is set)

## system-max-files

`system-max-files` specifies the maximum number of file descriptors that Liberator’s process may create. Liberator requires file descriptors for user sessions, log files, connections with DataSource peers, and HTTP requests.

On start up, Liberator adjusts the file descriptor limit for its process to `system-max-files`, or the licensed number of users plus a margin of 512, whichever is the greater of the two values. If Liberator is licensed for an unlimited number of users, only the value of `system-max-files` is used.

On a Liberator licensed for an unlimited number of users, set `system-max-files` to the _expected_ number of users plus a margin of 512.

If Liberator is started as an unprivileged user, it cannot set a file descriptor limit greater than the user’s hard limit (the output of `ulimit -H -n`). In Red Hat Enterprise Linux 7, the default user hard-limit for open file descriptors is 4096. If Liberator fails to set a file descriptor limit, it writes `NOTIFY: Failed to set system-max-files to _value_` to the event log, and retries with successively lower values until it succeeds, halving the value with each attempt.

To avoid the restriction of the user hard-limit for file descriptors, use one of the options below:

* Start Liberator as root. After Liberator has used root privileges to set its file descriptor limit and bind to TCP/IP ports, Liberator runs as the user specified by the [runtime-user](../datasource/datasource-run-time-environment-configuration.md#runtime-user) configuration item.
* Increase the file descriptor hard-limit for the user that Liberator runs as. See [How to set ulimit values](https://access.redhat.com/solutions/61334).

**Syntax**: `system-max-files <max-number>`

**Type**: integer

**Default value**: `1024`

## threads-num

`threads-num` specifies the number of client threads (session threads) that Liberator should use to serve RTTP clients.

When the contention between threads for CPU cores is low, increasing the number of Liberator’s session threads can increase the number of clients Liberator can service.

For Liberator deployments managed by the Deployment Framework, don’t edit the `threads-num` configuration item directly. Instead, edit the `LIBERATOR${THIS_LEG}_THREADS_NUM` configuration variable in the Deployment Framework file `global_config/environment.conf`.

If you assign `threads-num` a value outside the range of valid values, then Liberator logs a warning to the console and to the event log, and reduces the number of client threads to 1.

Liberator also uses additional threads for DataSource peer connections. See How can I... [Configure threads for peer communication](../datasource/datasource-configure-threads-for-peer-communication.md).

**Syntax:** `threads-num <max-number>`

**Type:** integer

**Default value:** `1`

**Values accepted:**

* Liberator 7.0.1 and later versions: `1–64`
* Liberator 6.2.15 and later versions: `1–64`
* Liberator 6.2.14 and earlier versions: `1–10`

## thread-queue-notify-always

`thread-queue-notify-always` is a boolean item that, when set to `TRUE`, causes Liberator to record the size of Liberator’s threads queue in the event log every [thread-queue-notify-period](#thread-queue-notify-period) seconds.

**📌 NOTE**\
Only set this item when debugging a Liberator installation.

Alternatively, you can just configure Liberator to log the size of the threads queue when it exceeds a given size – see [thread-queue-notify-levels](#thread-queue-notify-levels).

An event log entry about the threads queue, typically looks like this:

```
2014/11/24-16:33:41.123 +0000: NOTIFY: Thread 0: Queue size is 0
```

**Syntax:** `thread-queue-notify-always <boolean>`

**Type:** boolean

**Default value:** `FALSE` (no time-based logging of the threads queue)

For more about the event log, see [Liberator logging](liberator-logging.md).

## thread-queue-notify-levels

`thread-queue-notify-levels` specifies an array of queue sizes at which Liberator logs information about the size of Liberator’s threads queue to the event log.

For example:

```
thread-queue-notify-levels 10 100
```

With the above configuration, Liberator reports the initial size of the threads queue, and if the size subsequently exceeds `10` entries, it logs the size. If after this, the queue size exceeds `100` entries, it logs the size again.

**📌 NOTE**\
Only set this item when debugging a Liberator installation.

Alternatively, you can just configure Liberator to log the size of the threads queue at regular intervals by setting [thread-queue-notify-always](#thread-queue-notify-always) and [thread-queue-notify-period](#thread-queue-notify-period).

If you specify `thread-queue-notify-levels` together with `thread-queue-notify-always` and `thread-queue-notify-period`, Liberator first logs the queue size when it exceeds the first level in `thread-queue-notify-levels`, and then writes log entries every `thread-queue-notify-period`.

**Syntax:** `thread-queue-notify-levels level-1 level-2 level-3 ...`

**Type:** integer

**Default value:** `10000 100000 1000000`

For more about the event log, see [Liberator logging](liberator-logging.md).

## thread-queue-notify-period

`thread-queue-notify-period` specifies the interval at which Liberator records the size of Liberator’s threads queue in the event log when [thread-queue-notify-always](#thread-queue-notify-always) is `TRUE`.

**📌 NOTE**\
Only set this item when debugging a Liberator installation.

**Syntax:** `thread-queue-notify-period <interval-in-seconds>`

**Type:** float

**Default value:** `0` seconds (timer is disabled)

For more about the event log, see [Liberator logging](liberator-logging.md).

## user-hash-size

`user-hash-size` specifies the size of the user hashtable for authorizing users who log in to Liberator.

**💡 TIP**\
We recommend setting `user-hash-size` to twice the expected maximum number of usernames.

**Syntax:** `user-hash-size <size-in-table-entries>`

**Type:** integer

**Default value:** `8192` entries

---

**See also:**

* [burst-increment](liberator-bursting-configuration.md#burst-increment) (in [Bursting configuration](liberator-bursting-configuration.md))
* [burst-max](liberator-bursting-configuration.md#burst-max) (in [Bursting configuration](liberator-bursting-configuration.md))
* [burst-min](liberator-bursting-configuration.md#burst-min) (in [Bursting configuration](liberator-bursting-configuration.md))
* [datasrc-tcp-nodelay-off](../datasource/datasource-datasource-peers-configuration-part-2.md#datasrc-tcp-nodelay-off) (in [DataSource peers configuration](../datasource/datasource-datasource-peers-configuration-part-2.md))
* [direct-tcp-nodelay-off](liberator-direct-connections-configuration.md#direct-tcp-nodelay-off) (in [Direct connections configuration](liberator-direct-connections-configuration.md))
* [http-tcp-nodelay-off](liberator-http-configuration-part-1.md#http-tcp-nodelay-off) (in [HTTP configuration](liberator-http-configuration-part-1.md))
* [object-delete-batchtime](liberator-object-configuration-part-2.md#object-delete-batchtime) (in [Object configuration](liberator-object-configuration-part-2.md))
* [object-delete-time](liberator-object-configuration-part-2.md#object-delete-time) (in [Object configuration](liberator-object-configuration-part-2.md))
* [object-throttle-default-level](liberator-throttling-configuration.md#object-throttle-default-level) (in [Throttling configuration](liberator-throttling-configuration.md))
* [object-throttle-off](liberator-throttling-configuration.md#object-throttle-off) (in [Throttling configuration](liberator-throttling-configuration.md))
* [object-throttle-times](liberator-throttling-configuration.md#object-throttle-times) (in [Throttling configuration](liberator-throttling-configuration.md))
* [peer-thread-pool-size](../datasource/datasource-datasource-peers-configuration-part-2.md#peer-thread-pool-size) (in [DataSource peers configuration](../datasource/datasource-datasource-peers-configuration-part-2.md))
* [session-absolute-max-queue-length](liberator-session-configuration.md#session-absolute-max-queue-length) (in [Session configuration](liberator-session-configuration.md))
* [session-hash-size](liberator-session-configuration.md#session-hash-size) (in [Session configuration](liberator-session-configuration.md))
* [session-max-queue-count](liberator-session-configuration.md#session-max-queue-count) (in [Session configuration](liberator-session-configuration.md))
* [session-max-queue-length](liberator-session-configuration.md#session-max-queue-length) (in [Session configuration](liberator-session-configuration.md))
* [thread-name](../datasource/datasource-datasource-peers-configuration-part-1.md#thread-name) option of [add-peer](../datasource/datasource-datasource-peers-configuration-part-1.md#add-peer) (in [DataSource peers configuration](../datasource/datasource-datasource-peers-configuration-part-1.md))