This document describes how to set up PhenixID Server in a cluster. The cluster configuration will be used to share configuration and sessions between two or more nodes. Please note that additional network components might be required in order to achieve failover and load balancing.

Recommendation is that nodes to be part in cluster has clear communication paths. No port restrictions in firewall etc.

If the clustering is added to an existing configuration, special preparation needs to be done. Please read the section below.

The reader of this document should have basic knowledge about Phenix Server.

System Requirements

  • Phenix Server installed on two or more machines
  • Communication needs to be open between the hosts on the port specified for the cluster. By default required ports are 5701, 5702, 2424 & 47000.
  • Any port binding in configuration must be set to (RADIUS_CONFIGURATIONS ip must be set to since this is replicated between the nodes, "ip" : "". So no specific ip for the node/nodes should be set here. A specific ip will make the RADIUS listener unable to bind on subsequent nodes.


This is a summary of the tasks that will be handled in this document

1. Install with cluster service

2. Converting single server to cluster node

3. Starting the cluster

4. Verify cluster

5. Database preparation when adding a node or reconfiguration of existing environment

6. Clustering in environments with multiple NICs

Install with cluster service

In order to enable cluster, this option must be selected at the time of installation. Follow the instructions in the installer.

On Windows, the installed service will handle the arguments automatically. 

Starting the cluster requires additional arguments, if running on a Linux environment:

sudo ./ -cluster -cluster-host <ip_address_of_local_machine> -cluster-port 47000
Click to copy

Converting single server to cluster node

When converting a single node server to a cluster node a reinstall/upgrade has to be performed. The cluster options mentioned above will then have to be configured.

Starting the cluster

The first node that is started in the cluster will read the configuration from the configuration file and load it to the "shared cluster memory". When the subsequent nodes are started they will read configuration from the "shared cluster memory" only.

Verify cluster

Verify that configuration is replicated between nodes. This is done by comparing phenix-store.json.The file should be identical on all nodes.

In addition, it is a good idea to verify that cluster nodes have the features properly configured. For HA clusters simply turn one node offline and verify functionality.

Database preparation when adding a node or reconfiguration of existing environment

When adding nodes or converting a non cluster installation to a cluster installation you have to make sure to prepare the database for this.

  1. Install the subsequent cluster node, but do not start the service
  2. Remove the content of /data from the subsequent node
  3. Stop the first node
  4. Copy the content from /data from the first node to the same folder on the subsequent node
  5. Start the first node
  6. Verify that the first node is up and running
  7. Start the subsequent node
  8. Verify by viewing the logfile, that the database delta is synchronized from the first node.

Clustering in environments with multiple NICs

The default configuration might have problem to handle environments with multiple NICs. If that is the case, the following modifications has to be made:

Replace the listeners tag with the following in config/orientdb-server-config.xml
            <listener protocol="binary" socket="default" port-range="2424" ip-address=""/>
            <listener protocol="binary" socket="default" port-range="2424" ip-address=""/>