_configureOnPremConnector

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

To configure an on-premises connector, download the remote-restapi-plugin utility from the BMC Helix Intelligent Automation console. By using the utility, you install the connector, configure credentials, and run the plug-in as a service. You can use the same utility to install and configure any on-premises connectors, however, we recommend downloading the latest package when you want to configure a new connector. 

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 latest version.

     sudo cp /usr/local/lib64/libstdc++.so.6 /usr/lib64

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 latest version.

     sudo cp /usr/local/lib64/libstdc++.so.6 /usr/lib64

Task 1: To create a plug-in key

1. Log in to BMC Helix Intelligent Automation console, and click Connectors > Plugin Keys.
2. Click Create Plugin Key.
   The plug-in key details, the expiry date, and the default name are displayed. 
3. (Optional) Type the plug-in name.
4. (Optional) Click the calendar icon to update the expiry date.
   By default, the plug-in key expires in 90 days. 

5. Click Download Plugin Key.
   The creds.json file is downloaded. 

   Error

   Warning

   Download the plug-in key before closing the panel. If the panel is closed, the key cannot be downloaded again, and you will need to create a new one. 

   

6. Click Save.
   The plug-in key is displayed on the Plugins page with the status as Active. 

   Warning

   Important

   You can use one plug-in key for multiple on-premises connectors. For more information about working with plug-in keys, see Editing, disabling, and deleting plugin keys.

7. Continue with Task 2: To download the remote plug-in utility.

Optional Task: To reuse an existing plug-in key

If you have configured any on-premises connectors, you can use the same key to configure other on-premises connectors for a different automation tool. 

1. 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.
   
2. Skip Task 2 and continue with Task 3 to configure the connector.

Task 2: To download the remote plug-in utility

1. Click Connectors > Available Connectors and click Configure against the connector.
2. On the Configure On-premises Connector page, click Download Plugin.
   The remote-restapi-plugin.zip utility is downloaded.
3. Extract the downloaded ZIP file and navigate to the remote-restapi-plugin directory.
4. Navigate to the remote-restapi-plugin\config location and replace the creds.json file with the credential file generated in Task 1.

5. (For Linux only) Run the following command to provide the execute permission:

   chmod +x install.sh
6. Continue with Task 3: To create credentials for the connector. 

(Optional) Task 3: 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. 

1. Navigate to the remote-restapi-plugin directory.

2. 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 

3. 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.

4. 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 5: 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:

1. 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.
2. Copy and place the certificate in the server-certs directory located in the remote-restapi-plugin directory.
3. 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

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

For Microsoft Windows and Linux-based operating systems

1. 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>
2. Specify the path to the folder where the certificate and key files are located.

3. 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
4. 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:

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

2. 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

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

   Warning

   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

4. 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. 

1. 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.
2. 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. If you have configured multiple connectors for the same target ID, test each plugin instance separately to ensure correct routing and execution. 

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

To troubleshoot the installation

If you encounter any problems while installing or running the remote-restapi-plugin utility, use the install.log file to troubleshoot the installation.

To configure the connector for high availability

Setting up on-premises connectors in a high-availability deployment ensures that your connection with the automation tool is maintained in case of any failure. Automation policies run even if a single instance of the connector is available and remediation actions are not impacted. For more information, see Configuring high availability for on-premises connectors. 

1. Navigate to the location on the host where you downloaded and extracted the remote-restapi-plugin.zip file.

   Information

   If I already had an on-premises connector, do I need to download the latest remote-restapi-plugin.zip file?

   You can configure the connector by using the remote plug-in utility that you already used to install the previous connector. However, to avoid discrepancies between the plug-in versions, BMC recommends that you download the latest remote plug-in utility and configure all instances of the connectors. If you are using new credentials, then you must use the latest remote plug-in utility to configure both connectors. 

2. Run the following command to create credentials for the connector:

   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>

3. When prompted, type the credentials, such as the username, password, header, and so on. 

   Success

   Tip

   To avoid errors while configuring the credentials, copy the ia_remote_plugins from the credentials database and place it in the appropriate folder on the second host:

   OS	Credentials database on host 1	Credentials database on host 2
   Microsoft Windows	C:/ProgramData/BMC/ia_remote_plugins/database/	C:/ProgramData/BMC/ia_remote_plugins/database/
   Linux	/var/lib/bmc/ia_remote_plugins/database/	/var/lib/bmc/ia_remote_plugins/database/

4. Run the following command to install and run the connector as a service:
   • Microsoft Windows: install.bat install
   • Linux: ./install.sh install
5. Verify whether the service is running successfully. 
6. To verify the connector status, log on to the BMC Helix Intelligent Automation console and click Connectors.
7. On the Configured Connectors page, click the (Info) to view the status.
   The status of both connectors is displayed. Expand the host to view the host name, the plugin's IP address, and the last poll time. This information helps diagnose the issue and restart the plugin in case of connection failure.