Clustering configuration

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

Want to know more about clustering? See here.

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

For more about how to use add-cluster-node, see Clustering Liberators without the Caplin Deployment Framework in How can I.. Set up a cluster of Liberators.

Syntax:

add-cluster-node
   cluster-addr [string]
   cluster-port [integer]
end-cluster-node
Option Type Default Description

cluster-addr

string

127.0.0.1

The network interface address or hostname of the cluster node.

In the Caplin Platform Deployment Framework, 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 command to set up the hostnames in the macros. See Configuring server hostnames in How can I…​ Set up server failover capability, and Change server hostnames in How can I …​ Change server-specific configuration.

Also see Deployment Framework Configuration macros and items.

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, 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 in How can I …​ Set up a cluster of Liberators.

Also see Deployment Framework Configuration macros and items.

cluster-heartbeat-slack-time

cluster-heartbeat-slack-time When this Liberator doesn’t receive an expected cluster heartbeat (see 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 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.

In the Caplin Platform Deployment Framework, you use a configuration macro LIBERATOR_CLUSTER_HEARTBEAT_TIME to specify Liberator’s cluster-heartbeat-time. See Clustering Liberators in the Caplin Deployment Framework in How can I …​ Set up a cluster of Liberators, and Deployment Framework Configuration macros and items.

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 items this node represents. Index numbers start at 0 and correspond to the order of the add-cluster-node items in the configuration file.

In the Caplin Platform Deployment Framework, you use a configuration macro LIBERATOR_CLUSTER_NODE_INDEX to specify Liberator’s cluster-index. See Clustering Liberators in the Caplin Deployment Framework in How can I …​ Set up a cluster of Liberators, and Deployment Framework Configuration macros and items.

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. 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 in DataSource peers configuration part 2), so you need to use the logcat utility to read it.

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:

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

%a

This Liberator node’s 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

%a

This Liberator node’s application-name

The Liberator won’t start if cluster SSL is enabled (see 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 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

%a

This Liberator node’s application-name

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

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.

If cluster-ssl-password is configured then cluster-ssl-passwordfile is ignored.

We strongly recommend that you password protect your private key files.

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}

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 is TRUE), you must specify a cluster-ssl-privatekey.

The directory path can contain the following substitution parameters:

Token Description

%r

This DataSource’s application-root

%a

This DataSource’s 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 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. 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: