Adding a Cluster Node

Overview

When you install Universal Controller, you create a single instance (cluster node) of the Controller. To operate Universal Automation Center in a High Availability (HA) environment, you must add one or more cluster nodes. Each cluster node should be installed on a separate machine.

This page tells you how to add one or more cluster nodes.

Requirements for Adding a Cluster Node

Each cluster node in an HA environment must connect to the same Universal Controller database. If one of the cluster nodes stops processing, another cluster node continues processing with the same data.

Each cluster node in an HA environment must be the same version and build of the Controller. To ensure this, you can either:

  • Install the downloaded version of the Controller on a second machine.
  • Download a new version of the Controller software, update the current version, and then install the new version on a second machine.

It is strongly recommended that an HA environment has at least two OMS Servers, although you do not need an OMS Server for every cluster node if your HA environment contains three or more cluster nodes.

Procedure for Adding a Cluster Node

This page describes the following procedure:

This procedure assumes you already have performed any required Pre-Installation Procedure steps for the cluster node being added.

Copy and Unpack the Universal Controller Distribution File

Copy the downloaded distribution file, which was used to install the current, single instance of Universal Controller, from its current location to the machine on which you want to install a new instance of the Controller.

To unpack the Universal Controller distribution file, use the following method appropriate for your platform:

Linux/Unix

tar xvf uc-controller-N.N.N.N.tar

Windows

Use an appropriate archiving / unzipping product.

Install the Controller

To install the Controller, issue the following command that is appropriate for your platform:

Linux

> sh install-controller.sh 

Windows

> install-controller.bat

You must include command line switches that specify information the Controller needs to access the Tomcat installation directory, the war file, and the database. You can include additional command line switches, but they are not required.

If a required command line switch is missing from the command line, an error message will identify it during the installation process.

The Controller installation process writes the values for some command line switches to the Universal Controller Start-up Properties (uc.properties), uc.properties (see the table, below). For any of those command line switches that are not required and, in fact, are not included on the command line, the Controller installation process writes their default value to uc.properties.

Command Line Switches

The following table describes the command line switches for the Controller installation process and identifies which are required.

For command line switches that have their value written to the Universal Controller Start-up Properties (uc.properties), uc.properties, the table also identifies the property in that file to which the value is written.

Note

All command line switches are case-sensitive.

Command Line Switch

Description

Default

Required

Controller Property

--controller-file

Full path of the Universal Controller war file from the downloaded Universal Controller package.

none

Yes


--dbname

Universal Controller database name.

The property uc.db.name should be set to the name of the database being connected to. It can be seen in the System Details widget under Database information as well as in the uc.log.


  • Oracle
    •     For Oracle, the uc.db.name property is for informational purposes only.
  • SQL Server
    • If the uc.db.url property contains the attribute "DatabaseName" then the uc.db.name property is for informational purposes only, similar to Oracle.
    •     If however, the uc.db.url does not contain the database name, then the uc.db.name will be used to connect to the database by issuing the SQL "USE dbname", where dbname is the value of the uc.db.name property.
  • MySQL
    • MySQL should not contain the database name in the uc.db.url property.
    •     MySQL will use the uc.db.name property to connect to the database specficied by also issuing the SQL "USE dbname" statement where dbname is the value of the uc.db.name property.

uc

No

uc.db.name=

--dbpass

Database user's password.

none

Yes

uc.db.password=

--dburl

JDBC connection URL.
 
Format:   jdbc:<jdbc vendor>:<other jdbc vendor data>
 
Examples (for MS SQLServer, uc is the database name; for Oracle, XE is the SID):
 

MySQL

jdbc:mysql://localhost:3306/

MS SQL Server

jdbc:sqlserver://localhost:1433;DatabaseName=uc

MS SQL Server JTDS

jdbc:jtds:sqlserver://localhost:1433/uc

Oracle

jdbc:oracle:thin:@//localhost:1521/ServiceName
or
jdbc:oracle:thin:@localhost:1521:XE

jdbc:mysql://localhost

No

uc.db.url=

--dbuser

Database user name.

none

Yes

uc.db.user=

--port

Used by the Universal Controller to generate a unique Cluster Node Node Id in the format of hostname:port-dbname.

Note

This is meant to represent the value of the Tomcat HTTP/1.1 Connector port configured in the server.xml.

It is used solely for Node Id generation and does not impact the Tomcat HTTP/1.1 Connector configuration.

8080

No

uc.servlet.port

--rdbms

Database type.
 
Valid values are:

  • mysql
  • sqlserver
  • oracle

* --rdbms is required if --dburl is used in the command.

mysql

No *

uc.db.rdbms=

--tomcat-dir

Path to the Tomcat installation directory (contains the directories:/bin, /conf, /logs, webapps).

none

Yes


Examples

Shown below are sample commands for installing the Controller on Linux and Windows platforms, using defaults for the database:

Linux

sh install-controller.sh --tomcat-dir ~/tomcat --controller-file ./uc-controller-N.N.N.N-build.N.war --dbuser root --dbpass userpass

Windows

install-controller.bat --tomcat-dir "c:\Program Files\Apache Software Foundation\Tomcat 8.5"
--controller-file uc-controller-N.N.N.N-build.N.war --dbuser root --dbpass userpass

Note

In the Tomcat directory (--tomcat-dir), when quoting the directory is necessary due to spaces, do not use a single backslash before the ending quotation mark; use either a double backslash or no backslash to avoid the command shell from treating \" as an escape character.

Deploy the Controller

In this procedure, you will start Tomcat, which starts the Controller and builds your database tables. This process takes several minutes. When it is complete, the Controller is started and ready to use.

If Tomcat already was running when you installed the Controller, you do not need to stop and restart it; this process will occur automatically after you start the installation.
 

Step 1

Start Tomcat as follows:
 
Linux
Start the Tomcat daemon using the script placed in the /etc/init.d directory for Tomcat.
 

service [name of Tomcat service] start

 
Windows
We recommend you use Windows Services to start Tomcat. Or, you can start Tomcat from the command line as follows:
 

net start [name of Tomcat service]

 
Linux or Windows
You can start the service using the $CATALINA_HOME/bin/startup.bat or $CATALINA_HOME/bin/startup.sh scripts.

Step 2

You can view details of the start-up in the Tomcat window or monitor the Controller log, as described below:
 
Linux/Unix
Users can tail the uc.log to monitor the deployment process, as follows:
 

tail -f $TOMCAT_DIR/uc_logs/uc.log

 
Windows
Users can use a third-party tailing utility or open the log file using Notepad or other editor and scroll to the bottom to view the latest activity.
 

$TOMCAT_DIR/uc_logs/uc.log

Step 3

When you see the following, the Controller is ready:

  • INFO [Ops.Cluster.Monitor.0] Server is now Running in Passive mode.
  • INFO [Ops.Cluster.Monitor.0] Setting server to PASSIVE.

Step 4

AIX and z/Linux only: Follow this procedure to change two default values in the Universal Controller Start-up Properties (uc.properties), uc.properties, which is read by the Controller.
 
(The uc.properties file resides in <tomcat directory>/webapps/uc/WEB-INF/properties).
 

  1. Change the following two properties from their default value to the AIX - z/Linux value:
     
    • uc.trustmanager.algorithm= (Java trust manager algorithm)
      • Default value = SunX509
      • AIX - z/Linux value = IbmX509
         
    • uc.trustmanager.provider= (Java trust manager provider)
      • Default value = SunJSSE
      • AIX - z/Linux value = IBMJSSE2
         
  2. Restart Tomcat.

You now have completed the install process and the Controller is running.

Verify the Installation

To make sure the new cluster node is installed and running properly:

Step 1

Log in to the originally installed Controller.

Step 2

Verify that the Cluster Node Status Widgets illustrates an Active and a Passive cluster node.

Step 3

For detailed information on the new (and original) cluster nodes, select Resources > System > Cluster Nodes.

Note

The Apply the License Key for the installed Universal Controller applies to all instances (cluster nodes) of that Controller; no additional licensing is required.

Configure System Notifications configured for the installed Universal Controller apply to all instances (cluster nodes) of that Controller; no additional system notifications have to be configured.

Adding an OMS Server

To add a second OMS Server to an HA environment (which creates an OMS cluster), you must install Universal Agent on a machine where one of the additional cluster nodes has been added.

Add OMS Server to OMS Server Record

You must specify all members of an OMS cluster in your HA environment in the same Creating OMS Server Records.

The OMS Servers list screen will contain a single entry for all OMS cluster members defined in the record. (The OMS Servers list screen could have additional entries for an OMS Server or OMS cluster outside of your HA environment. For example, OMS Servers outside a firewall would connect to a different message database and serve different Agents, but would connect to to the same Controller.)

OMS Server Message Database

Members of an OMS cluster in an HA environment must use the same OMS Server Message Database.

The OMS SPOOL_DIRECTORY - OMS configuration option configuration option specifies the name of the directory where the OMS maintains its message database. For each OMS Server, you must set this option to a location shared by all of the OMS Servers in the HA environment.