The end of life (EOL) date for this module is on 31 January, 2020.

Configuration

Network settings

Before starting each node needs to have its network settings configured in its config/application.conf file.

The external hostname or IP address of the machine must be set, in addition to a port:

akka {
    remote.netty.tcp {
        hostname = "myhost.com"        port = 2551
    }
    cluster {
        seed-nodes = ["akka.tcp://ClusterSystem@myhost.com:2551"]
    }
}

Warning

In the case of a single node, be careful to make sure that akka.remote.netty.tcp.hostname, akka.remote.netty.tcp.port and at least one seed-nodes entry have the same value! If they are not the same, the node will not start correctly!

In the above example the hostname is myhost.com the port is 2551 and the seed node is akka.tcp://ClusterSystem@myhost.com:2551.

The seed-nodes setting is used to join cluster nodes together. In a single-node cluster it should contain the node itself as shown above. In a multi-node cluster the seed-nodes should be two nodes that will be started first:

seed-nodes = ["akka.tcp://ClusterSystem@myhost.com:2551", "akka.tcp://ClusterSystem@myotherhost.com:2552"]

Note: The same seed-nodes should be specified on all nodes.

Configure a running cluster

The cluster has these configuration sections

gateways - See Gateway Connections
auth - See User Authentication
permissions - See Data Permissions
blacklists - See Black Lists

These sections can be modified at runtime by editing config/settings.conf on any node.

After the file is changed and saved on one node it is replicated to every other cluster node and applied.

If the settings file is changed simultaneously on two nodes, only the change that is received first is applied. We therefore recommend that changes are made on the same node every time, for example the first seed node.

Note that configuration cannot be changed if there are less than min-nr-of-members nodes in the cluster. See Specifying a minimum number of nodes.

Specifying a minimum number of nodes

In a multi-node cluster we recommend setting a minimum number of nodes in config/application.conf:

akka.cluster.min-nr-of-members = <n>

The cluster won’t start connecting to gateways until at least n nodes are running and connected. This is useful to ensure that enough computing power is present in the cluster before connecting to large sets of gateways.

More than n nodes can be added to the cluster to ensure fault tolerance. Any extra nodes will pick up a subset of all gateway connections to balance the load. If an extra node fails or is disconnected from the network, the remaining nodes will take over its gateway connections and resume publishing data. In order to maximise the availability of the cluster it is recommended to run n-1 extra nodes, but no more than that.

If less than n nodes are left in the cluster, only a subset of all gateways will be available for querying. It is also not possible to change cluster configuration in this state (e.g. add gateways). Once n nodes are back up, the missing gateways will be reconnected.

Note: nodes need to be restarted for this setting to be applied.

Restarting the cluster

When the whole cluster is restarted from scratch, settings are read from the first node in the seed-nodes configuration.

Debugging Port

Cluster nodes have an EMF2 debugging feature built-in, similar to ORB diagnostics on a Gateway2 or Netprobe. By default, this is bound to a random port on start-up.

To always use the same port, set the following in config/application.conf:

geneos.emf.listenPort = <port number>