# Clustering configuration

The following configuration items define how Liberator participates in a cluster.

Want to know more about clustering? [See here](liberator-clustering.md).

**📌 NOTE**\
"_this Liberator_" means the Liberator for which you are defining the configuration. "_this node_" means the cluster node that this Liberator represents.

## add-cluster-node

`add-cluster-node` identifies a Liberator in the cluster.

**💡 TIP**\
For more about how to use `add-cluster-node`, see [Clustering Liberators without the Caplin Deployment Framework](liberator-set-up-a-cluster-of-liberators.md#clustering-liberators-without-the-caplin-deployment-framework) in How can I.. [Set up a cluster of Liberators](liberator-set-up-a-cluster-of-liberators.md).

**Syntax:**

```
add-cluster-node
   xref:cluster-addr[cluster-addr] [string]
   xref:cluster-port[cluster-port] [integer]
end-cluster-node
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `<a name="cluster-addr"></a>cluster-addr` | string | `127.0.0.1` | The network interface address or hostname of the cluster node. In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), the configuration macros `LIBERATOR${THIS_LEG}_HOST` and `LIBERATOR${OTHER_LEG}_HOST` specify the `cluster-addr` values. Clustering is used in the Deployment Framework to support failover capability. You normally use the [`./dfw hosts`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#hosts) command to set up the hostnames in the macros. See [Configuring server hostnames](../deployment-framework/cdf-set-up-server-failover-capability.md#configuring-server-hostnames) in How can I... [Set up server failover capability](../deployment-framework/cdf-set-up-server-failover-capability.md), and [Change server hostnames](../deployment-framework/cdf-change-server-specific-configuration.md#change-server-hostnames) in How can I ... [Change server-specific configuration](../deployment-framework/cdf-change-server-specific-configuration.md). Also see Deployment Framework [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). |
| `<a name="cluster-port"></a>cluster-port` | integer | `2333` | The network port number of the cluster node. This port is used for cluster-related communication between the Liberator and the other Liberators in the cluster. In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), the configuration macros `LIBERATOR${THIS_LEG}_CLUSTER_PORT` and `LIBERATOR${OTHER_LEG}_CLUSTER_PORT` specify the `cluster-port` values. See [Clustering Liberators in the Caplin Deployment Framework](liberator-set-up-a-cluster-of-liberators.md#clustering-liberators-in-the-caplin-deployment-framework) in How can I ... [Set up a cluster of Liberators](liberator-set-up-a-cluster-of-liberators.md). Also see Deployment Framework [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md). |

## cluster-heartbeat-slack-time

`cluster-heartbeat-slack-time` When this Liberator doesn’t receive an expected cluster heartbeat (see [cluster-heartbeat-time](#cluster-heartbeat-time)) from another Liberator in the cluster, it waits `cluster-heartbeat-slack-time` seconds before disconnecting from the cluster and trying to reconnect to it.

Unlike `cluster-heartbeat-time`, the value of `cluster-heartbeat-slack-time` is not compared by the Liberators in the cluster.

**Syntax:** `cluster-heartbeat-slack-time <slack-time-in-seconds>`

**Type:** integer

**Default value:** `5` seconds

## cluster-heartbeat-time

`cluster-heartbeat-time` specifies the time in seconds between each cluster heartbeat. The Liberators forming a cluster exchange heartbeat messages at regular intervals, allowing each of them to check that all the others are still present. If the cluster heartbeat times out, this Liberator waits [cluster-heartbeat-slack-time](#cluster-heartbeat-slack-time) and then disconnects from the cluster and tries to reconnect to it.

When all the Liberators in the cluster have initially connected, they compare their `cluster-heartbeat-time` values and use the lowest.

**📌 NOTE**\
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), you use a configuration macro `LIBERATOR_CLUSTER_HEARTBEAT_TIME` to specify Liberator’s `cluster-heartbeat-time`. See [Clustering Liberators in the Caplin Deployment Framework](liberator-set-up-a-cluster-of-liberators.md#clustering-liberators-in-the-caplin-deployment-framework) in How can I ... [Set up a cluster of Liberators](liberator-set-up-a-cluster-of-liberators.md), and Deployment Framework [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md).

**Syntax:** `cluster-heartbeat-time <heartbeat-time-in-seconds>`

**Type:** integer

**Default value:** `15` seconds

The minimum allowed value is 1 second.

## cluster-index

`cluster-index` specifies the index number of this cluster node. The index number uniquely identifies this Liberator within the cluster. It states which of the [add-cluster-node](#add-cluster-node) items this node represents. Index numbers start at 0 and correspond to the order of the [add-cluster-node](#add-cluster-node) items in the configuration file.

**📌 NOTE**\
In the [Caplin Platform Deployment Framework](../deployment-framework/index.md), you use a configuration macro `LIBERATOR_CLUSTER_NODE_INDEX` to specify Liberator’s `cluster-index`. See [Clustering Liberators in the Caplin Deployment Framework](liberator-set-up-a-cluster-of-liberators.md#clustering-liberators-in-the-caplin-deployment-framework) in How can I ... [Set up a cluster of Liberators](liberator-set-up-a-cluster-of-liberators.md), and Deployment Framework [Configuration macros and items](../deployment-framework/cdf-configuration-macros-and-items.md).

**Syntax:** `cluster-index <index-number>`

**Type:** integer

**Default value:** `0`

## cluster-packet-logfile

`cluster-packet-logfile` specifies the name of the log file in which message packets passed between this Liberator and other nodes in the Liberator cluster are recorded.

The filename can contain the parameter `%a`, which is replaced at run-time by this Liberator’s DataSource [`application-name`](../datasource/datasource-run-time-environment-configuration.md#application-name). The log file is located in Liberator’s `var` directory (the `<Framework-root>/servers/Liberator/var` directory in the Deployment Framework).

The log file’s format is the same binary format used for the standard DataSource packet log (see [`datasrc-pkt-log`](../datasource/datasource-datasource-peers-configuration-part-2.md#datasrc-pkt-log) in [DataSource peers configuration part 2](../datasource/datasource-datasource-peers-configuration-part-2.md)), so you need to use the [logcat utility](../datasource/datasource-view-packet-logs-using-logcat.md) to read it.

**⚠️ WARNING**\
Only configure `cluster-packet-logfile` when you need to troubleshoot your Liberator cluster. Cluster packet logs can quite quickly become very large, so you should only enable logging of this information for debugging purposes.

**Syntax:** `cluster-packet-logfile <log-file-name>`

**Type:** string

**Default value:** (none, but this configuration item is optional - if it’s not present then cluster packets aren’t logged)

## cluster-global-ssl-enable

Set `cluster-global-ssl-enable` to `TRUE` to enable ***all*** Liberator nodes to _accept_ incoming SSL connections from other Liberator nodes.

If you set `cluster-global-ssl-enable` to `TRUE`, remember to specify values for the following configuration items:

* [cluster-ssl-accept-certificate](#cluster-ssl-accept-certificate)
* [cluster-ssl-present-certificate](#cluster-ssl-present-certificate)
* [cluster-ssl-privatekey](#cluster-ssl-privatekey)

**Since**: Liberator 8.0.7

**Syntax:** `cluster-global-ssl-enable <boolean>`

**Type:** boolean

**Default value:** `FALSE` (incoming SSL connections not accepted)

## cluster-ssl-accept-certificate

Specifies the path and filename of one or more TLS certificates accepted (trusted) by this Liberator node. This option is used for for [certificate pinning](https://en.wikipedia.org/wiki/Certificate_pinning#certificate-pinning) when an SSL connection is being established.

The directory path can contain the following substitution parameters:

| Token | Description |
| --- | --- |
| %r | This Liberator node’s [application-root](../datasource/datasource-run-time-environment-configuration.md#application-root) |
| %a | This Liberator node’s [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name) |

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-accept-certificate <path-to-ssl-certificate-pem-file> ...`

**Type:** array of strings

**Default value:** _none_

## cluster-ssl-present-certificate

Specifies the path and filename of a PEM format certificate that identifies this Liberator node. When this Liberator node initiates a TLS connection with another Liberator node in the cluster, this certificate plays the role of the 'client certificate'. When this Liberator node accepts a TLS connection from a Liberator node in the cluster, this certificate plays the role of the 'server certificate'.

The directory path can contain the following substitution parameters:

| Token | Description |
| --- | --- |
| %r | This Liberator node’s [application-root](../datasource/datasource-run-time-environment-configuration.md#application-root) |
| %a | This Liberator node’s [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name) |

The Liberator won’t start if cluster SSL is enabled (see [cluster-global-ssl-enable](#cluster-global-ssl-enable)) and `cluster-ssl-present-certificate` doesn’t point to a valid certificate.

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-present-certificate <path-to-ssl-certificate-pem-file>`

**Type:** string

**Default value:** _none_

## cluster-ssl-cipherlist

`cluster-ssl-cipherlist` configures the SSL/TLS ciphers supported by the Liberator node for secure communications with other nodes in the cluster. Configure this item in conjunction with `cluster-ssl-ssloptions`, and review both regularly as part of your security policy.

This configuration item takes one value: an OpenSSL cipher list. For a description of the cipher list format, see [Cipher List Format](https://docs.openssl.org/1.1.1/man1/ciphers/#CIPHER-LIST-FORMAT) on the OpenSSL website.

To successfully establish an SSL connection, the SSL client and the SSL server must have at least one enabled cipher in common.

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-cipherlist <cipher>[:<cipher>]...`

**Type:** string

**Default value:** `DEFAULT:!RC4-SHA:!RC4-MD5:!DES-CBC3-SHA`

## cluster-ssl-passwordfile

`cluster-ssl-passwordfile` specifies the path and filename of a text file containing the unencrypted password used to access private key files and certificate files.

The directory path can contain the following substitution parameters:

| Token | Description |
| --- | --- |
| %r | This Liberator node’s [application-root](../datasource/datasource-run-time-environment-configuration.md#application-root) |
| %a | This Liberator node’s [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name) |

The password provides access to the password-protected private key file that’s defined by [cluster-ssl-privatekey](#cluster-ssl-privatekey).

**⚠️ WARNING**\
We strongly recommend that you password protect your private key files.

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-passwordfile <path-to-password-file>`

**Type:** string

**Default value:** +[none]+

## cluster-ssl-password

`cluster-ssl-password` specifies the password (unencrypted) used to access private key files and certificate files.

The password provides access to the password-protected private key file that’s defined by [cluster-ssl-privatekey](#cluster-ssl-privatekey).

If `cluster-ssl-password` is configured then [cluster-ssl-passwordfile](#cluster-ssl-passwordfile) is ignored.

**⚠️ WARNING**\
We strongly recommend that you password protect your private key files.

<dl><dt><strong>💡 TIP</strong></dt><dd>

To avoid including a password directly in a configuration file, you can instead reference the value of an environment variable by using the `${ENV:<variable>}` configuration macro. For example, to reference the environment variable `MYPASSWORD`, use the configuration below:

```
cluster-ssl-password ${ENV:MYPASSWORD}
```
</dd></dl>

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-password <password>`

**Type:** string

**Default value:** +[none]+

## cluster-ssl-privatekey

`cluster-ssl-privatekey` specifies the path and filename of the SSL private key that this Liberator node uses to decrypt the symmetric session key received from another Liberator node in the cluster. The file must be in PEM format.

If SSL is enabled ([cluster-global-ssl-enable](#cluster-global-ssl-enable) is `TRUE`), you must specify a `cluster-ssl-privatekey`.

The directory path can contain the following substitution parameters: 

[options="autowidth"] 
| Token | Description |
| --- | --- |
| %r | This DataSource’s [application-root](../datasource/datasource-run-time-environment-configuration.md#application-root) |
| %a | This DataSource’s [application-name](../datasource/datasource-run-time-environment-configuration.md#application-name) |

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-privatekey <PEM-file-path-and-name>`

**Type:** string

**Default value:** [none]

## cluster-ssl-ssloptions

`cluster-ssl-ssloptions` specifies the levels of the SSL protocol that are supported for SSL connections used by this Liberator node.

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-ssloptions <supported-SSL-levels>`

**Type:** string

**Default value:** `SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1`

**Values accepted:**

| Value | Meaning |
| --- | --- |
| `SSL_OP_ALL` | Enable all of OpenSSL’s workarounds for known bugs in client implementations of SSL. For the full list of workarounds enabled by this option, see [SSL_CTX_set_options](https://docs.openssl.org/1.1.1/man3/SSL_CTX_set_options/) on the OpenSSL website. |
| `SSL_OP_NO_SSLv2` | Disable support for SSLv2. |
| `SSL_OP_NO_SSLv3` | Disable support for SSLv3. |
| `SSL_OP_NO_TLSv1` | Disable support for TLSv1. |
| `SSL_OP_NO_TLSv1_1` | Disable support for TLSv1.1. |
| `SSL_OP_NO_TLSv1_2` | Disable support for TLSv1.2. |
| `SSL_OP_NO_TLSv1_3` | Disable support for TLSv1.3. |
| `SSL_OP_CIPHER_SERVER_PREFERENCE` | In a TLS handshake, the TLS client presents the DataSource with a list of the ciphers it supports in priority order, and the DataSource chooses a cipher from the list. By default, and in accordance with the TLS specification, the DataSource chooses the client’s most preferred cipher from the ciphers they have in common. When `SSL_OP_CIPHER_SERVER_PREFERENCE` is set, the DataSource chooses its most preferred cipher from the ciphers they have in common. This breaks with the TLS specification. The DataSource’s cipher preferences are determined by the order of ciphers in [`cluster-ssl-cipherlist`](#cluster-ssl-cipherlist). Ciphers are listed in descending order of preference, most preferred cipher first. |

You can specify multiple values using the `|` operator. In the example below, support for SSLv2, SSLv3, and TLSv1 has been disabled:

```
cluster-ssl-ssloptions SSL_OP_NO_SSLv2|SSL_OP_NO_SSLv3|SSL_OP_NO_TLSv1
```

## cluster-ssl-debug

`cluster-ssl-debug` enables SSL debugging output for secure Liberator node connections. The SSL handshake details are written to stderr and as DEBUG level entries in this Liberator node’s event log.

**Since**: Liberator 8.0.7

**Syntax:** `cluster-ssl-debug <boolean>`

**Type:** boolean

**Default value:** `FALSE`

---

**See also:**

* How can I... [Set up a cluster of Liberators](liberator-set-up-a-cluster-of-liberators.md)
* [Liberator clustering features and concepts](liberator-clustering.md)