Set up a cluster of Liberators

You can define two or more Liberators as a cluster. Here’s how to do this.

For more about clustering, see Liberator clustering features and concepts.

Clustering Liberators without the Caplin Deployment Framework

Here’s an example of how to configure a Liberator cluster when you’re not using the Deployment Framework. Here we’ve assumed there are just two Liberators in the cluster, but the same approach applies when you’re clustering more.

Config for the first Liberator in the cluster
cluster-index 0
cluster-heartbeat-time        15
cluster-heartbeat-slack-time  5

add-cluster-node
   cluster-addr <First-Liberators-network-interface-address>
   cluster-port <First-Liberators-network-port-number>
end-cluster-node

add-cluster-node
   cluster-addr <Second-Liberators-network-interface-address>
   cluster-port <Second-Liberators-network-port-number>
end-cluster-node
Config for the second Liberator in the cluster
cluster-index 1
cluster-heartbeat-time        15
cluster-heartbeat-slack-time  5

add-cluster-node
   cluster-addr <First-Liberators-network-interface-address>
   cluster-port <First-Liberators-network-port-number>
end-cluster-node

add-cluster-node
   cluster-addr <Second-Liberators-network-interface-address>
   cluster-port <Second-Liberators-network-port-number>
end-cluster-node

Here’s an explanation of the configuration items that we’ve used:

  • cluster-index: Uniquely identifies this Liberator in the cluster. Make sure each Liberator in the cluster has a different cluster-index in its configuration file; in this example, the first Liberator has cluster-index 0 and the second has cluster-index 1.

    Index numbers must start at 0 and correspond to the order of the add-cluster-node items in the configuration file.

  • cluster-heartbeat-time is 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, and take appropriate action if one doesn’t respond.

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

  • add-cluster-node: Each add-cluster-node item defines a Liberator in the cluster by its network interface address and port number. You define all the Liberators in the cluster through a set of add-cluster-node items. The set must be in ascending order of the Liberators' cluster-index values. You put the add-cluster-node items in the configuration of every Liberator in the cluster, so each Liberator identifies every node in the cluster, including itself. You can see that in this example, each of the two Liberators' configurations contains the same set of two add-cluster-node items.

Clustering Liberators in the Caplin Deployment Framework

The Caplin Deployment Framework, allows you to easily define a two-Liberator cluster for failover purposes. To enable failover, see How can I…​ Set up server failover capability in the Deployment Framework pages. You set up some configuration macro definitions in the <Framework-root>/global-config/environment.conf file on the primary and secondary server machines.

  • To change the cluster-heartbeat-time, add the macro definition LIBERATOR_CLUSTER_HEARTBEAT_TIME to <Framework-root>/global-config/environment.conf

    define LIBERATOR_CLUSTER_HEARTBEAT_TIME <new value>
  • To change the cluster-heartbeat-slack-time from its default, define a value in <Framework-root>/global_config/overrides/servers/Liberator/etc/cluster.conf

    cluster-heartbeat-slack-time <new-value>
  • To change the cluster-addr settings in the add-cluster-node configuration entries:

    The configuration macros LIBERATOR${THIS_LEG}_HOST and LIBERATOR${OTHER_LEG}_HOST specify the cluster-addr values. (These macros are defined in <Framework-root>/global_config/hosts-defns.conf)

    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.

    If you want to set the cluster-addr values directly, edit them in <Framework-root>/global_config/overrides/servers/Liberator/etc/cluster.conf

  • To change the cluster-port settings in the add-cluster-node configuration entries, put new values for the configuration macros LIBERATOR${THIS_LEG}_CLUSTER_PORT and LIBERATOR${OTHER_LEG}_CLUSTER_PORT in the <Framework-root>/global_config/overrides/servers/Liberator/etc/cluster.conf file.

    For example:

    define LIBERATOR${THIS_LEG}_CLUSTER_PORT   ${THIS_LEG}6003
    define LIBERATOR${OTHER_LEG}_CLUSTER_PORT  ${OTHER_LEG}6003

    where the value 6003 is the new base port number, replacing the default value 6002.

If you want to set up a cluster of more than two Liberators within the Deployment Framework, please contact Caplin Support for advice on how to do this.

See also: