Clustering configuration

add-cluster-node identifies a Transformer (a "node") in the cluster.

Syntax:

The options for add-cluster-node are:

always-auto-distribute specifies a space-separated list of subject names for which this Transformer automatically distributes updates to all other Transformers in the cluster. A subject name can be a Linux shell wildcard pattern, in which case updates for all subject names that match the pattern are forwarded. The pattern can contain any of the following wildcards in an appropriate combination:

Also see always-auto-distribute-ignore

Syntax: always-auto-distribute <subject-1> <subject-2> …​ <subject-n>

Type: array of strings

Default value: (none, but this configuration item is optional)

always-auto-distribute-ignore specifies a space-separated list of subject names that are excluded from the patterns specified in always-auto-distribute. Updates are for subjects specified in always-auto-distribute-ignore are therefore not automatically distributed to any other Transformers in the cluster.

A subject name in the list can be a Linux shell wildcard pattern, as specified in always-auto-distribute

Syntax: always-auto-distribute-ignore <subject-1> <subject-2> …​ <subject-n>

Type: array of strings

Default value: (none, but this configuration item is optional)

Example:

In this example, all updates whose subjects have names of the form /I/<NAME>.L are automatically distributed to the other Transformers in the cluster, except updates for the subject /I/VOD.L

auto-distribute specifies a space-separated list of subject names for which all updates are automatically distributed to all other Transformers in the cluster, provided this Transformer is the primary node in the cluster.

A subject name in the list can be a Linux shell wildcard pattern, as specified in always-auto-distribute

Also see auto-distribute-ignore

Syntax: auto-distribute <subject-1> <subject-2> …​ <subject-n>

Type: array of strings

Default value: (none, but this configuration item is optional)

auto-distribute-ignore specifies a space-separated list of subject names that are excluded from the patterns specified in auto-distribute and for which updates are therefore not automatically distributed to any other Transformers in the cluster when this Transformer is the primary node of the cluster.

A subject name in the list can be a Linux shell wildcard pattern, as specified in always-auto-distribute

Syntax: auto-distribute-ignore <subject-1> <subject-2> …​ <subject-n>

Type: array of strings

Default value: (none, but this configuration item is optional)

Example:

In this example, all updates whose subjects have names of the form /I/<NAME>.L are automatically distributed to the other Transformers in the cluster when this Transformer is the primary node of the cluster, except updates for the subject /I/VOD.L

check-period specifies the interval in seconds at which the status of the cluster’s primary node is checked. The status is exposed in the Transformer’s JMX monitoring interface.

Also, at the end of every check-period this Transformer marks any auto-distributed data (see auto-distribute) that has changed since the last check-period, so that the updated data is saved to the object cache file at the end of the current write-cache-period. (The data’s only saved if this Transformer is the primary cluster node, or if it’s a secondary node and cluster-nosave-on-secondary is FALSE.)

Syntax: check-period <interval-in-seconds>

Type: float

Default value: 1.0 second

cluster-connect-timeout specifies this Transformer’s timeout on an attempt to connect to another Transformer in the cluster; for example, when this Transformer starts up. When the timeout expires, this Transformer waits one second and then attempts to reconnect. After ten attempts at reconnecting, the Transformer doubles the wait time before trying again. It doubles the delay every ten attempts up to a maximum delay of 32 seconds. after which it stops attempting to connect to the other Transformer.

Syntax: cluster-connect-timeout <timeout-in-seconds>

Type: float

Default value: 10 seconds

cluster-index specifies the index number of this Transformer cluster node. The index number uniquely identifies this Transformer 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.

Syntax: cluster-index <index-number>

Type: integer

Default value: -1 (This transformer is not part of a cluster)

cluster-nosave-on-secondary specifies when TRUE that if this Transformer is a secondary cluster node (that is, not the primary node), it won’t save updates for it’s auto-distributed data (see auto-distribute) to the object cache file (see check-period and write-cache-period).

If this Transformer is the primary cluster node, it always saves these updates to the object cache file, regardless of the setting of this configuration item.

Syntax: cluster-nosave-on-secondary <boolean>

Type: boolean

Default value: FALSE (this Transformer’s auto-distributed data is always saved to the object cache file)

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

The filename can contain the parameter %a, which is replaced at run-time by this Transformer’s DataSource application-name. The log file is located in Transformer’s var directory; in the Deployment Framework, the full directory path is <Framework-root>/servers/Transformer/var where <Framework-root> is the Deployment Framework’s topmost directory.

The log file’s (binary) format is the same as that of 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.

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)

Set cluster-global-ssl-enable to TRUE to enable all Transformer nodes to accept incoming SSL connections from other Transformer nodes.

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

Since: Transformer 8.0.4

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

Type: boolean

Default value: FALSE (incoming SSL connections not accepted)

Specifies one or more certificates accepted (trusted) by this Transformer node. This option is used for for certificate pinning when an SSL connection is being established.

cluster-ssl-accept-certificate specifies the path to and filename of the certificate file.

The directory path can contain the following substitution parameters:

Since: Transformer 8.0.4

Syntax: cluster-ssl-accept-certificate <path-to-ssl-certificate-pem-file> …​

Type: array of strings

Default value: none

Specifies the TLS certificate that identifies this Transformer node. When this Transformer node initiates a TLS connection with another Transformer node in the cluster, this certificate plays the role of the 'client certificate'. When this Transformer node accepts a TLS connection from a Transformer node in the cluster, this certificate plays the role of the 'server certificate'.

cluster-ssl-present-certificate specifies the path to and filename of the certificate file in PEM format.

The directory path can contain the following substitution parameters:

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

Since: Transformer 8.0.4

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

Type: string

Default value: none

cluster-ssl-cipherlist configures the SSL/TLS ciphers supported by the Transformer node for secure communications with other nodes in the cluster. You should 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: Transformer 8.0.4

Syntax: cluster-ssl-cipherlist <cipher>[:<cipher>]…​

Type: string

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

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

The directory path can contain the following substitution parameters:

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

Since: Transformer 8.0.4

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

Type: string

Default value: [none]

cluster-ssl-password specifies the plain text (unencrypted) password used to access private key files, 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 it is used and any cluster-ssl-passwordfile that is configured is ignored.

Since: Transformer 8.0.4

Syntax: cluster-ssl-password <password>

Type: string

Default value: [none]

cluster-ssl-privatekey specifies the path to and filename of the SSL private key that this Transformer node uses to decrypt the symmetric session key received from another Transformer 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:

Since: Transformer 8.0.4

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

Type: string

Default value: [none]

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

Since: Transformer 8.0.4

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:

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

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

Since: Transformer 8.0.4

Syntax: cluster-ssl-debug <boolean>

Type: boolean

Default value: FALSE

connect-sync specifies a space-separated list of subject names for which a snapshot of the each subject’s current data held by this Transformer is sent on to another Transformer in the cluster when that Transformer connects to this one. The data is only sent to a connecting node when either this Transformer is the primary node of the cluster, or connect-sync-always is specified as TRUE.

A subject name in the list can be a Linux shell wildcard pattern, as specified in always-auto-distribute

Also see connect-sync-ignore

Syntax: connect-sync <subject-1> <subject-2> …​ <subject-n>

Type: array of strings

Default value: (none, but this configuration item is optional)

connect-sync-always specifies that this Transformer must always send to another Transformer in the cluster that connects to it a snapshot of the current data for each subject specified by connect-sync (and filtered by connect-sync-ignore), even if this Transformer is not the primary node in the cluster.

Syntax: connect-sync-always <boolean>

Type: boolean

Default value: FALSE (data is only sent to a connecting Transformer if this Transformer is the primary node of the cluster)

connect-sync-ignore specifies a space-separated list of subject names that are excluded from the patterns specified in connect-sync Therefore, a snapshot of the current data for these subjects held by this Transformer is not sent on to any other Transformer in the cluster when that Transformer that connects to this one.

A subject name in the list can be a Linux shell wildcard pattern, as specified in always-auto-distribute

Syntax: connect-sync-ignore <subject-1> <subject-2> …​ <subject-n>

Type: array of strings

Default value: (none, but this configuration item is optional)

Example:

In this example, the current data for all subjects with names of the form /I/<NAME>.L is automatically distributed to another connecting Transformer in the cluster, except the data for the subject /I/VOD.L

force-primary specifies that this Transformer is forced to be the default primary node in the cluster. This configuration item only applies when primary-method has the value forced.

Once set to TRUE, the value of force-primary can subsequently be changed to FALSE if a JMX monitoring command is used to force a different Transformer in the cluster to become the primary; for more about this see primary-config-file.

Syntax: force-primary <boolean>

Type: boolean

Default value: FALSE (the cluster’s primary node is either selected at run time by the method specified by primary-method, or, when primary-method is set to forced, by the configuration for some other Transformer in the cluster having force-primary set to TRUE)

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

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

Syntax: heartbeat-slack-time <slack-time-in-seconds>

Type: integer

Default value: 5 seconds

heartbeat-time specifies the time in seconds between each cluster heartbeat. The Transformers 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 Transformer waits heartbeat-slack-time and then disconnects from the cluster and tries to reconnect to it.

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

Syntax: heartbeat-time <heartbeat-time-in-seconds>

Type: integer

Default value: 15 seconds

The minimum allowed value is 1 second.

logfile specifies the name of the file to which cluster-related events are logged.

The filename can contain the parameters %a and %h At run time, %a is replaced by the Transformer’s application name (see the DataSource configuration item application-name), and %h is replaced by the host name of the machine on which the Transformer is running.

Syntax: logfile <log-file-name>

Type: string

Default value: cluster.log

log-level specifies the severity of the errors and events that this Transformer reports to the cluster-related events log file (see logfile).

Syntax: log-level <log-level-name>

Type: string

Default value: INFO

Values accepted:

primary-config-file specifies the name, and optionally the directory path of the Transformer configuration file that records that this Transformer has been forced to become the primary node.

When this Transformer becomes the primary node in the cluster, it sends a message to all the other Transformers in the cluster to inform them of this. If you force this Transformer to become the primary node by sending it a JMX monitoring command (see the forced method in primary-method), the Transformer creates a file defined by primary-config-file that contains the following configuration:

When this Transformer is restarted, this configuration file ensures that the Transformer resumes the role of primary node. When another Transformer in the cluster receives this Transformer’s "I am now primary" message, it marks itself as a secondary node and clears out its own primary-config-file.

This procedure ensures that once the administrators of a Transformer cluster have established a particular node as the primary, when the cluster is restarted, that node will continue to be the primary one.

You can manually configure one Transformer of the cluster to be the primary, but still allow the primary to subsequently be changed through JMX. To do this:

The primary-config-file filename can contain the parameters %a and %h At run time, %a is replaced by the Transformer’s application name (see the DataSource configuration item application-name), and %h is replaced by the host name of the machine on which the Transformer is running. The directory path can contain the parameter %r, which is replaced at run time by the root directory (application-root) under which the Transformer application runs,

Syntax: primary-config-file <filename-and-path>

Type: string

Default value: %r/etc/cluster-primary.conf

primary-method specifies how to determine which Transformer ("node") in the cluster takes on the role of the primary.

Syntax: primary-method <method-name>

Type: string

Default value: order

Values accepted:

stable-time specifies the minimum time that this Transformer has to have been running in order to be considered for promotion to the cluster’s primary node.

Syntax: stable-time <time-interval-in-seconds>

Type: integer

Default value: 5 seconds

See also: