OpsWise Windows Controller Install

1. Installing the OpsWise Controller

1.1. Installation Synopsis

  • This document describes the setup procedure for installing the Univeral Automation Controller (OpsWise) on a Windows server.

  • Top level OpsWise documentation can be found here.

1.2. Install Prerequisites

  • Prerequisite details are here.

1.2.1. Java

1.2.2. Apache Tomcat

1.2.3. Database

  • SQL Server details

    1. Create the opswiseDB database.

      create database opswiseDB

    2. Create the opswise login account for the opswise DB

      use master;
create login opswise_db_admin with password = 'A-complex-passwd123';

use opswiseDB;
create user opswise_db_admin for login opswise_db_admin;
exec sp_addrolemember db_owner,opswise_db_admin;

1.2.4. Product downloads

  1. Log on to the Software Downloads section of the StoneBranch Portal.

  2. From here links are available for the Universal Controller and Universal Agent downloads.

1.3. Install

  • Review platform support and prerequisites here.

  • Review any relevant release notes here for the particular version.

  • Install

    The original Universal Controller installation instructions can be reference here.

    1. Unzip the universal-controller-7.0.0.0.zip file.

    2. Create a new file named install-controller-win.bat in the recently unzipped universal controller folder.

      Don’t overwrite the original install-controller.bat file!

    3. Update the new file with the following contents:

      Expand for install-controller-win.bat Contents 
      install-controller.bat ^
--tomcat-dir "c:\Program Files\Apache Software Foundation\Tomcat 9.0" ^
--controller-file universal-controller-7.6.0.3-build.151.war ^
--rdbms sqlserver ^
--dburl "jdbc:sqlserver://v-ubuntu-sql:1285;instanceName=SQLExpress;DatabaseName=opswiseDB;sendStringParametersAsUnicode=false" ^
--dbname opswiseDB ^
--dbuser opswise_db_admin ^
--dbpass A-complex-passwd123 ^

    4. Edit the install-controller-win.bat with updated values.

    5. Launch an elevated CMD prompt.

    6. Run the install-on-windows.bat file:

      install-controller-win.bat

      1. Confirm there is a new C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\uc.war file.

      2. Confirm the values in the C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\uc.properties config file.

    7. Start (or restart if already running) the Apache Tomcat service

      This step will take a few minutes to create the DB tables.

    8. Check the C:\Program Files\Apache Software Foundation\Tomcat 9.0\uc_logs\uc.log log file for errors.

    9. If you see the following error:

      Expand for error details 
      2024-08-19-16:33:29:399 -0400   INFO [UC.Bootstrap @@16:33:29.378736100-NC] Attempting connection to: jdbc:sqlserver://v-ubuntu-sql:1285;instanceName=SQLExpress;DatabaseName=opswiseDB;sendStringParametersAsUnicode=true with User: opswise_db_admin
2024-08-19-16:33:30:668 -0400  ERROR [UC.Bootstrap] SQLException - SQLCode: 0 SQLState: 08S01 Message: "encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target. ClientConnectionId:6c2e267c-23d4-446d-be33-7843d08a61e5 Exception Class: SQLServerException
com.microsoft.sqlserver.jdbc.SQLServerException: "encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target. ClientConnectionId:6c2e267c-23d4-446d-be33-7843d08a61e5

    10. Do the following:

      1. Shutdown the Apache Tomcat service

      2. Edit the install-controller.bat file

      3. Update the --dburl option with encrypt=false;trustServerCertificate=true;

        Expand for updated file 
        install-controller.bat ^
--tomcat-dir "c:\Program Files\Apache Software Foundation\Tomcat 9.0" ^
--controller-file universal-controller-7.6.0.3-build.151.war ^
--rdbms sqlserver ^
--dburl "jdbc:sqlserver://v-ubuntu-sql:1285;instanceName=SQLExpress;DatabaseName=opswiseDB;sendStringParametersAsUnicode=true;encrypt=false;trustServerCertificate=true;" ^ (1)
--dbname opswiseDB ^
--dbuser opswise_db_admin ^
--dbpass A-complex-passwd123 ^
        1 this is the updated line

      4. Restart the Apache Tomcat service

    11. Test by launching the Opswise interface: http://localhost:8080/uc on the server where Opswise has been installed.

    12. Log in with ops.admin administrator account and leave the password blank.

      You will immediately be prompted for a new password.

    13. Now you’ll see the initial dashboard with System Details.

      Initial Dashboard

2. Configure Firewall

  1. Open the following Ports on the server that hosts the Opswise Controller:

    1. 8080 for the web portal

    2. 7878 for the OMS Server

  2. Launch an elevated CMD prompt window.

  3. Open port 80 for the web portal.

    netsh advfirewall firewall add rule name = UAC-Web dir = in protocol = tcp action = allow localport = 80 remoteip = localsubnet profile = DOMAIN

  4. Open port 443 for the web portal using SSL.

    netsh advfirewall firewall add rule name = UAC-WebSSL dir = in protocol = tcp action = allow localport = 443 remoteip = localsubnet profile = DOMAIN

  5. Open port 7878 for the OMS Server

    netsh advfirewall firewall add rule name = UAC-OMS dir = in protocol = tcp action = allow localport = 7878 remoteip = localsubnet profile = DOMAIN

  6. Open port 8080 for the Opswise web API.

    netsh advfirewall firewall add rule name = UAC-WebAPI dir = in protocol = tcp action = allow localport = 8080 remoteip = localsubnet profile = DOMAIN

  7. Test by launching the Opswise API: http://v-serv2022-UAC:8080/uc/resources/user/list on any host other than the server where Opswise has been installed.

    This will result in an XML list of user accounts.

3. Install OMS

4. Add OMS Config

  1. Click on the System  OMS Servers menu link

    OMS Servers

  2. Provide Name of the Server that hosts the OMS.

    OMS Server Config

  3. Click the Save button.

    Save OMS button

  4. The OMS should transition into the Connected state:

    Save OMS button

5. LDAP Setup

5.1. Configure LDAP

  1. Click on the Administration  LDAP Settings menu link.

    LDAP Settings Menu Link

  2. Configure the following LDAP related values:

    LDAP Settings

  3. Test the configuration with the Test Connection button.

    LDAP Test button

  4. Click the Update button to save the config.

    LDAP Update Settings button

5.2. Enable LDAP Synchronization

  1. Click on the Administration  Properties menu link.

    Properties Menu Link

  2. Search for the LDAP Synchronization Enabled property and then set its value to true.

    LDAP Sync Enabled

5.3. Perform an Immediate LDAP Refresh

  1. Click on the Administration  Server Operations menu link.

    LDAP Settings Menu Link

  2. Select LDAP_Refresh from the dropdown menu:

    LDAP Refresh

  3. Now click the Run button to start the LDAP Refresh Operation:

    LDAP Refresh

  4. Click the Run button to confirm the LDAP Refresh Operation:

    Confirm LDAP Refresh

  5. Confirmation of the LDAP Refresh Operation:

    Confirmation of the LDAP Refresh

6. Install Built-In Universal Templates

These templates are included with the UAC but are not available immediately upon install. They need an additional step.

  • Original doc is here

7. Uninstalling the Opswise Controller

7.1. Uninstallation Synopsis

This section is Incomplete!

  • This part of the document describes the procedure for un-installing the Universal Automation Controller (OpsWise) on a Windows server.

  • You might consider uninstalling Opswise in order to remove a trial instance of the product.

7.2. Uninstall the Controller

  1. Log on to the server that hosts your UAC instance.

  2. Run the following in a cmd window:

    msiexec.exe /x SetupPath\UECtlr.msi

8. Administration

8.1. Universal Tasks

Universal tasks can be downloaded from the Stonebranch Market Place.

9. Misc

9.1. Changing the Opswise DB Password

Changing the opswise DB password involves:

  • changing the password on the DB server that hosts the DB.

  • updating the uc.properties file with the new passord.

  • restarting the Opswise Controller(s)

Here is the general process:

  1. Update the password for the opswise login account on the DB server.

    At this time you do not need to shutdown the already running Opswise Controller(s). This will be done later.

  2. Update the uc.properties file

    1. Connect to the server that hosts the Opswise Controller.

    2. Edit the C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\uc.properties file.

    3. Add a new property named uc.db.password containing your new password:

      uc.db.password.encrypted=oT3pHpvCdWfLplAabtelL/uKxcr2ccfsNS8fQlm/4Xg=:kc4ZJPSydOVk9v5MFM6O9g==
uc.db.password=A-New-Password123 (1)
      1 This is a new property/value pair for the recently updated password.

    4. Save the updated uc.properties file.

    5. Plan a restart of Opswise which will entail restarting the Apache Tomcat 9.0 service.

      Ideally you should plan to restart the Opswise Controller ASAP since the opswise DB login account’s password will be stored as unencrypted plain-text within the uc.properties file.

    6. After the service has been restarted, the uc.properties file will be updated where:

      1. the uc.db.password property will be removed.

      2. the uc.db.password.encrypted property will be updated with the encrypted version of the new password:

        uc.db.password.encrypted=BcTQwZO+BHv3JayzAOQXKw==:LvHkia+TScHTmRC97U+eMg== (1)
        1 Encrypted version of the new password,

    7. Check the log file: C:\Program Files\Apache Software Foundation\Tomcat 9.0\uc_logs\uc.log and if you see the following, then there’s an issue with the password or you’ve restarted the Controller prior to updating the uc.properties file:

      2021-03-30-10:46:31:893 -0400  ERROR [http-nio-8080-exec-37] SQLException - SQLCode: 18456 SQLState: S0001 Message: Login failed for user 'opswise' ClientConnectionId:3c18f46d-41b5-48b4-bf9d-3f72e61cd614 Exception Class: SQLServerException
com.microsoft.sqlserver.jdbc.SQLServerException: Login failed for user 'opswise'.