Configuring the TrueSight Orchestration on-premises connector

As an automation engineer, you configure the connector and the actions supported by the connector are displayed while creating a policy. When BMC Helix Intelligent Automation receives an event from BMC Helix AIOps or BMC Helix Operations Management for which you want to perform triage and remediation actions in TrueSight Orchestration, you can create an automation policy to execute the specified actions.

The following image shows the high-level process of configuring an on-premises connector:

Connector config process_HA.png

Before you begin

Before configuring the on-premises connector, make sure that the following prerequisites are met:

The server where you want to run and install the remote plug-in matches the minimum hardware and software requirements.
For more information, see System-requirements.
The host where the remote plug-in utility is running is accessible from the host where the endpoint automation tool is installed.
You have the permissions required to install and configure an on-premises connector.
For more information, see Roles-and-permissions.
(For Linux) The GNU Compiler Collection (GCC) G++ version is 5.4.0 or later.
Click here to do the steps before you run the plugin
1. Install and update GCC version 5.4.0 or later.
2. Run the following command to unlink the current version.
  sudo unlink /usr/lib64/libstdc++.so.6
3. Run the following command to copy the new version.
  sudo cp /usr/local/lib64/libstdc++.so.6 /usr/lib64

Task 1: To create a plug-in key

In the BMC Helix Intelligent Automation console, click Connectors > Plugin Keys tab.
Click Create Plugin Key.
The plug-in key details, the expiry date, and the default name are displayed.
(Optional) Type the plug-in name.
(Optional) Click the calendar to update the expiry date.
By default, the plug-in key expires in 90 days. You can update the date before it expires.
Click Download Plugin Key.
A creds.json file gets downloaded.
Warning
Make sure that you download the plug-in key before closing the panel. If you close the Create Plugin Key panel, you cannot download it again. You will have to create a new plug-in key.
Click Save.
The plug-in and the key are displayed on the Plugins page.

Optional Task: To reuse an existing plug-in key

If you have configured any on-premises connector, you can use the same key to configure any other on-premises connector.

Click Connectors > Available Connectors and click Configure against the connector that you want to configure.
On the configure connector page, the plug-in keys available for reuse are displayed.
Skip Task 2 and continue with Task 3 to configure the connector.

Task 2: To download the remote plug-in utility

Click Connectors > Available Connectors and click Configure against the connector.
On the Configure On-premises Connector page, click Download Plugin.
The remote-restapi-plugin.zip utility is downloaded.
Extract the downloaded ZIP file and navigate to the remote-restapi-plugin directory.
Navigate to the remote-restapi-plugin\config location and replace the creds.json file with the credential file generated in Task 1.
(For Linux) Run the following command to provide the execute permission:
chmod +x install.sh
Continue to the next step.

Optional task: To use a pass-through proxy server

If the host where you want to install and run the plug-in does not have internet access, use a proxy server to configure the connector. The host where the connector is to be configured and the automation tool must be in the same network domain.

Proxy Basic SupportGIF.gif

Navigate to the remote-restapi-plugin directory.
Run the following command to create credentials for the proxy server without any authentication.
For Linux
credential.sh create -n proxy -i <hostname:port of the proxy server> -p proxy -a noauth
For Windows
credential.bat create -n proxy -i <hostname:port of the proxy server> -p proxy -a noauth
Run the following command to create credentials for the proxy server with basic authentication.
credential.bat create -n proxy -i <hostname:port of the proxy server> -p proxy -a basic
When prompted, type the user name and password for the proxy server.
Continue to the next task.
If configuring the proxy server after a connector is installed and running, ensure that you start the connector service again.

Task 3: To create credentials by using the plugin key

A plugin requires credentials to authenticate and execute various actions on the target applications that are defined in an automation policy. The credential CLI utility enables you to create, search, update, and delete credentials for a plugin.

The current release supports the credential CLI utility only on Linux. This server should be accessible from the server where the on-premise application is installed.

Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.
The remote-restapi-plugin directory contains credential.sh.
Ensure that the credential.sh file has the execute permission.
Run the following create switch command to create credentials.
Whenever credentials are created, a unique credential provider ID is assigned to it.
Sample command for Microsoft Windows
credential.bat create -n <credentialsName> -i <http://host:port> -p <provider> -a <AuthenticationType>
Sample command for Linux
./credential.sh create -n <credentialsName> -i <http://host:port> -p <provider> -a <AuthenticationType>
./credential.sh create -n tsoCreds -i "http://myTSO.abc.com:8340" -p tso -a apikey
In the example:
- tsoCreds is the name of the credentials.
- http://myTSO.abc.com:8340 is the TrueSight Orchestration server URL.
  Note
  Ensure that you do not provide the same URL while configuring any other connector.
- tso is the credential provider ID.
- apikey is the authentication mechanism.

Enter the values for the following parameters when prompted:

Parameter	Value
api key	Enter $.headers.authentication-token
login required	Enter y
login URL	Enter http://myTSO.abc.com:8340/baocdp/rest/login
username	Enter the TrueSight Orchestration username
password	Enter password for the user
authentication parameter	Enter Authentication-Token
location ("header", "query", or "cookie")	Enter header

If the credentials are created successfully, a message appears.

(Optional) To create credentials in a single step, create a JSON file, which contains all the credentials required for configuring the connector and run the following command:
credential.bat create -n <ConnectorName> -i <loginURL> -p tso -a apikey -f C:\\TSO_auth.json

Click here to view a sample credentials JSON file

{
"auth": {
   "access_token": "$.headers.authentication-token",
   "bearer_parameter": "header",
   "login_action": {
     "<LOGING_URL>": {
       "post": {
         "parameters": [
          ],
         "body": {
           "content": {
             "application/json": {
               "username": credential.params.username,
"password": credential.params.password
             }
           }
         }
       }
     }
   }
}
}

If the credentials are created successfully, a message appears.

Task 4: To provide a server-side SSL certificate

BMC Helix Intelligent Automation requires certificates to establish a secure connection with the endpoint automation tool. If your automation tool runs on CA-signed certificates, skip this step. However, if you are using self-signed certificates, you must perform these steps for a secure and trusted connection.

To configure the plug-in to connect to any of the automation tools running on HTTPS/SSL, do the following steps:

Download the server-side certificate and convert it into a .PEM format.
For multiple products, convert and merge all individual certificates into a single .PEM file.
Copy and place the certificate in the server-certs directory located in the remote-restapi-plugin directory.
Continue to the next step to start and run the plug-in.

Optional task: To start or run the plug-in by using HTTPS

When you start or run the plug-in, by default, the plug-in runs by using the HTTP protocol. To run it on the HTTPS protocol, you must generate the client-side certificates and update the properties in the plugin.properties file to enable the support. On Linux-based operating systems, client-side certificates are automatically generated and added to a client-certs folder.

If you want to run it on the HTTPS protocol, perform the following steps:

For Microsoft Windows only

Navigate to the remote-restapi-plugin directory.
Create a new folder with and name it client-certs.
Generate a client certificate and the key of the host, in a PEM format, where the plug-in will run.
Copy the certificate to the client-certs folder.

For Microsoft Windows and Linux-based operating systems

Navigate to the remote-restapi-plugin\config and open the plugin.properties file.
The file contains the following new properties:
Sample
config.sslEnabled=false
config.sslPort=8443
config.sslCertPath=<pathToTheClientCertificate.pem file>
config.sslCertKeyPath=<pathToTheClientKey.pem file>
Specify the path to the folder where the certificate and key files are located.
Specify config.sslEnabled as true.
Example
config.sslEnabled=true
config.sslPort=8443
config.sslCertPath=client-certs/client_cert.pem
config.sslCertKeyPath=client-certs/client_key.pem
Save changes and continue to the next step.
When you start the plug-in, it runs by using an HTTPS server.

Task 5: To start and run the plug-in as a service

If a remote plug-in is installed as a service, you can start, stop, or restart it as any other service. We recommend that you run the plug-in as a service instead of running it as a batch or shell process.

Before running a plug-in as a service, make sure that the following prerequisites are fulfilled:

The host where the plug-in is available is also accessible from the host where the application is installed.
(For Linux) Run the following command to provide the execute permission:
chmod +x install.sh

To run the plug-in as a service:

Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.

Run the install.bat (for Microsoft Windows) or install.sh (for Linux) command.
The following table lists the commands used to perform service-related actions:

Command	Microsoft Windows	Linux
Install	install.bat install	./install.sh install
Start	install.bat start	./install.sh start
Stop	install.bat stop	./install.sh stop
Status	install.bat status	./install.sh status
Uninstall	install.bat uninstall	./install.sh uninstall

When prompted, type the location for the credentials database.
If skipped, the database is stored at the default location.

Note

The credentials database is stored at a new location. To ensure backward compatibility, copy the credential.db file from your previous location and place it in the new database location.

OS	Old location	New location
Microsoft Windows	C:\Users\Public\bmc\ia_remote_plugins\database	C:/ProgramData/BMC/ia_remote_plugins/database/
Linux	/root/.bmc/ia_remote_plugins/database/	{USER_HOME}/bmc/ia_remote_plugins/database

Run the following command to start the service:
- Microsoft Windows: install.bat start
- Linux: ./install.sh start
  If a service is installed successfully, in the list of services available in the Microsoft Windows Service Manager, the remote restapi plugin service is displayed. On Linux servers, if you run the install.sh status command, a system process with the name BMC remote-restapi-plugin appears.

Optional: To start the plug-in as a batch or shell process

After successfully creating the credentials, run the plug-in to enable the connector.

Navigate to the remote-restapi-plugin/config directory, and replace the creds.json file with the creds.json file that you have downloaded while creating the plugin key.
Run the run.sh script to start the plugin.

Task 6: To test the plug-in

We recommend that you test whether the plug-in is able to connect to the automation tool successfully before creating automation policies.

In the BMC Helix Intelligent Automation console, click Connectors > PluginKeys.
Click Actions > Test against the plug-in that is used to configure the connector.
The

The TrueSight Orchestration is configured and appears in the Configured Connectors tab with the status as Connected.

If the connector is not successfully connected, the status appears as Disconnected. Click the icon to view the error message and fix the configuration issue.

Where to go from here

To configure the connector for high availability, see Configuring-high-availability-for-on-premises-connectors.
To create automation policies to run actions supported by TrueSight Orchestration, see Executing-a-workflow.