Configuring the Ansible Automation Platform on-premises 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 new version.

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

Task 1: To create a plug-in key

1. In the BMC Helix Intelligent Automation console, click Connectors > Plugin Keys tab.
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 to update the expiry date.
   By default, the plug-in key expires in 90 days. You can update the date before it expires.

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

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

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) Run the following command to provide the execute permission:

   chmod +x install.sh
6. 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. 

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

This server should be accessible from the server where the on-premise application is installed.

1. Navigate to the directory where you have extracted the remote-restapi-plugin.zip file.
   The remote-restapi-plugin directory contains credential.sh/credential.bat.
2. Ensure that the credential.sh file has the execute permission.

3. Run the following create switch command to create credentials.
   Whenever credentials are created, a unique credential 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>

   Example for Ansible Tower by using basic authentication

   ./credential.sh create -n ansibleCreds -i https://172.20.65.241:6443 -p ansible_tower -a basic

   Example for Ansible Tower credentials by using bearer authentication

   ./credential.sh create -n ansibleCreds -i https://172.20.65.241:6443 -p ansible_tower -a bearer

   In the example:
   

   Field	Description	Sample value
   credentialsName	Type a unique name for the credentials. A name can contain a maximum of 30 characters. Enclose the name in double quotes if it contains spaces.	AnsibleTowerCredentials
   credentialsTargetID	Type the target identifier based on the credentials provider. Note: Ensure that you do not provide the same target ID while configuring any other connector.	https://172.20.65.241:6443
   credentialsProviderID	Type ansible_tower	-
   authenticationType	Type one of the supported authentication mechanisms:  basic: Requires a user name and a password bearer: Requires the access token generated from Ansible Automation Platform	Bearer: 1ZmDqTScGhe6SHct7vF5To6Pp3Vf3h

4. For Login required, type n.
   Credentials are created successfully. 

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

   Sample command for Microsoft Windows

   credential.bat create -n <ConnectorName> -i <hostname> -p ansible_tower -a bearer -f C:\\Users\\Administrator\\Downloads\\auth_json_file.json

   Credentials are created successfully. The following figure shows a sample output: 

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:

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. 

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. 

   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.

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. 

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 

The Ansible Automation Platform connector is configured and is displayed in the Configured Connectors tab with the status as Connected. 

If the connector is not successfully connected, the status is displayed 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 Ansible Automation Platform, see Restarting-PATROL-Agent-on-a-server.