/
Installing Universal Controller

Installing Universal Controller

Jul 08, 2025

Introduction

This page tells you how to install Universal Controller.

The procedure is the same, unless otherwise noted, for both Windows and UNIX (Linux or AIX).

It assumes you already have performed all required Pre-Installation Procedure:

Installation Procedure

To install Universal Controller:

1

Unpack the Downloaded Distribution File

2

Install the Controller

3

Deploy the Controller

4

Update the Universal Controller Start-up Properties

5

Verify the Installation

6

Apply the License Key

7

Enable LDAP Synchronization

8

Configure System Notifications

Unpack the Universal Controller Distribution File

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

Linux/Unix

tar -xvf universal-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

The installation process writes the war file (universal-controller-N.N.N.N-build.N.war) to the Tomcat installation directory and renames it uc.war.

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 (opswise.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.

When the install script is run, the uc.properties file is created and owned by the current user. This user will have write permission for the uc.properties file.

It is important that the user starting Tomcat has both read and write access for the uc.properties file.  The Controller cannot operate without read access, and without write access, the Controller cannot update the uc.properties to encrypt passwords and remove one-time use 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

Command Line Switch

Description

Default

Required

Controller Property

--agentonly

For an Agent-Only deployment

If --agentonly is true, Universal Controller Start-up Properties (uc.properties) is deployed with an Agent-Only demonstration license.

false

No

 

--controller-file

Full path of the Universal Controller war file (universal-controller-N.N.N.N-build.N.war) 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 connect URL.
 
Format:   jdbc:[database type]://localhost
 
Examples (for MS SQLServer and Oracle, uc is the database name):
 

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

 

Note

Enclose the URL in quotation marks to guard against any special characters (for example: ; > < &) which are treated by the shell uniquely.

  • Unix
    Enclose the URL in single quotation marks; for example: 'jdbc:sqlserver://dbserver.local;instanceName=IN01;DatabaseName=uc'

  • Windows
    Enclose the URL in double quotation marks; for example: "jdbc:sqlserver://dbserver.local;instanceName=IN01;DatabaseName=uc"

 
Refer to the jdbc documentation from your database supplier for specific jdbc driver URL parameters or options that might be needed for your environment. You may want to consult with your local DBA to discuss these parameters and options.
 
Refer to Installing a Database in this documentation for more information about suggested connection parameters, database configuration, and setup.

jdbc:mysql://localhost:3306/

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

  • sqlserver-jtds

  • oracle

  • postgres

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

Note

Customers have reported difficulty establishing secure SQL connections using the jTDS open source JDBC driver for Microsoft SQL Server (--rdbms sqlserver-jtds) when SSL/TLS is enabled on the server.

We have received feedback that the issue can be resolved by installing a patched version of the jTDS driver from bug report https://sourceforge.net/p/jtds/bugs/725/.

Stonebranch only bundles the official jTDS release, currently 1.3.1, with the Universal Controller.

We do not include unofficial patches, and if you decide to use them, you do so at your own risk.

mysql

No *

uc.db.rdbms

--tomcat-dir

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

Note

Enclose the path in quotes to guard against spaces or any special characters (for example: ; > < &), which are treated by the shell uniquely.

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 ./universal-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 9.0" --controller-file universal-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

During this initial startup, the Controller builds the database tables, a process that takes several minutes. You can view details 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

 
Do not continue until you see output in the log similar to the following:
 

2014-09-15-11:16:17:775 -0400 INFO [Ops.Cluster.Monitor.0] Cluster Monitor / ClusterWatchDog started (16951472) 2014-09-15-11:16:17:778 -0400 INFO [Ops.Cluster.Monitor.0] No active node found. sb-server:8080-ops6100 becoming Active node. 2014-09-15-11:16:17:778 -0400 INFO [Ops.Cluster.Monitor.0] Loading time zones 2014-09-15-11:16:17:810 -0400 INFO [Ops.Cluster.Monitor.0] Setting System time zone to "America/New_York" 2014-09-15-11:16:17:810 -0400 INFO [Ops.Cluster.Monitor.0] Initialize PubSubController 2014-09-15-11:16:17:813 -0400 INFO [Ops.Cluster.Monitor.0] PubSubController Active Start Load: 0 Subscriptions 2014-09-15-11:16:17:813 -0400 INFO [Ops.Cluster.Monitor.0] Server is now Running in Active mode. Previous mode was Passive 2014-09-15-11:16:17:813 -0400 INFO [Ops.Cluster.Monitor.0] Setting server to ACTIVE. 2014-09-15-11:16:17:814 -0400 INFO [Ops.Cluster.Monitor.0] Releasing lock and ending transaction 2014-09-15-11:16:18:147 -0400 INFO [Ops.Cluster.Monitor.0] 617 database statements took 0 Seconds 2014-09-15-11:16:18:149 -0400 INFO [Ops.Cluster.Monitor.0] Lock released and transaction ended 2014-09-15-11:16:18:149 -0400 INFO [Ops.Cluster.Monitor.0] Creating OmsServerWatchDog 2014-09-15-11:16:18:150 -0400 INFO [Ops.Cluster.Monitor.0] Creating AgentWatchDog 2014-09-15-11:16:18:150 -0400 INFO [Ops.Cluster.Monitor.0] Creating ApplicationWatchDog

Step 3

When you see the following, the Controller is ready:

  • INFO [Ops.Cluster.Monitor.0] Server is now Running in Active mode. Previous mode was Passive

  • INFO [Ops.Cluster.Monitor.0] Setting server to ACTIVE.

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

Update the Universal Controller Start-up Properties (uc.properties)

For 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>/conf).

Step 1

Change the following two properties from their default value to the IBM AIX value:

  • uc.trustmanager.algorithm= (Java trust manager algorithm)

    • Default value = SunX509

    • IBM AIX = IbmX509
       

  • uc.trustmanager.provider= (Java trust manager provider)

    • Default value = SunJSSE

    • IBM AIX value = IBMJSSE2

Step 2

Restart Tomcat.

Verify the Installation

To make sure the Controller is installed, running, and communication with Universal Agent and Universal Message Service (OMS):

Step 1

Starting and Stopping Universal Controller.

Step 2

From your browser, access the Universal Controller user interface.
 

http://localhost:8080/uc

localhost represents the machine name where you installed the server.

Step 3

Log in with user ops.admin and no password. A Change Password dialog displays.
 

Step 4

Enter a password in the New Password and Confirm New Password fields (the Current Password field should remain empty) and click Change Password. The Universal Controller Home Dashboard displays.

Step 5

The System Details Widgets provides current system information. Check the Release information to verify that the latest version number is displayed, as shown in the following example.
 

Step 6

From the Agents and Connections navigation pane, select Agents > All Agents or Agents > <type of Agent>. You will see a list similar to the following example. Make sure the Status of the Agent is Active.
 

Step 7

From the Agents and Connections navigation pane, select System > OMS Servers. You will see a list similar to the following example. Make sure the Status of the OMS Servers are Connected.
 

Step 8

For more information about these components in the Universal Controller user interface, see:

Apply the License Key

Although you do not normally need to enter a license key immediately after installation, at some point you will need to follow these steps to enter your key:

Step 1

From the Services, select Properties. The Properties list displays.

Step 2

Click the License Key property Value field and enter your encrypted license key.

Step 3

Return to the System Details Widgets and review the License field to verify that the terms of your license are correct.

Step 4

Optionally, configure the Controller so that your system administrator receives notifications regarding System Notifications for License Violations and Expirations

License Information

The License field in the System Details widget (view the system-defined Home Dashboard or, on the Reporting navigation pane, click Widgets) identifies license information for:

  • Expiry Date

  • Distributed Agents

  • z/OS Agents

  • Tasks

  • Monthly Executions

  • Cluster Nodes

  • UPPS

  • USAP

  • Customer

  • Environment

Enable LDAP Synchronization

In order to log in to the Controller using Credentials for Running Tasks Authentication, you must set the LDAP Synchronization Enabled Universal Controller System property (Administration > Configuration > Properties in the Controller user interface) to true.

Configure System Notifications

System Notifications are emails sent to one or more Universal Controller system administrators based on either:

Note

System Notifications are not the same as Email Notifications. Please refer to the following sections for explicitly defining Email Notifications.

 

In order for a system administrator to receive system notifications, you must configure the Controller for system notifications:

Step 1

Select an Email Connections on which the notifications will be sent and enable the Use for System Notifications field.