How to use On-Premise Bridge agents on Windows

To install and manage agents

1. Download and install the On-Premise Bridge Agent

   You must download and install the On-Premise Bridge Agent before you can add an agent in Service Management.

   Note Make sure your system meets the following requirements:

   • Supported operating systems:

     • Windows 2008 R2 SP1 64-bit
     • Windows 2012 R2 64-bit
     • Windows 7 64-bit

   • System requirements:

     • Minimum memory - 4 GB
     • Minimum free disk space required - 80 GB

     • Number of vCPUs: 4

   It is recommended to install the On-Premise Bridge on a dedicated server or VM in an established data center that has constant access to the SMAX and interfaced tool (for example, UCMDB or LDAP).

   Caution If you attempt to install the On-Premise Bridge agent on an unsupported operating system, the installer will terminate with an Invocation Target Exception error.

   1. From the main menu, select Administration > Utilities > Integration. Service Management displays the On-Premise Bridge Agents page.
   2. Click Download agent, or click the download link in the New agent dialog box.

   3. To begin the installation, double-click the downloaded opb-installation.exe file.

   4. Select the installation language and click OK to continue.
   5. Read the recommendations on the Introduction page and click Next to continue.
   6. Accept the license terms on the License agreement page and click Next to continue.

   7. Select the folder where you are installing On-Premise Bridge on the Choose installation folder page.

      If you do not want to use the default folder, click Choose to select a different folder.

      When you are finished, click Next to continue.

   8. Complete the details on the Setup authentication page.

      Field	Description
      User name	Enter the name of the user who will be logging in to Service Management. Note   This user must be assigned the OPB Remote Agent role. The On-Premise Bridge agent cannot be a federated user. It must be an integration user.
      Password	Enter the password of the user who will be logging in to Service Management.
      Use proxy server	Select this option if you will be using a proxy server, and enter the following details: Host. A valid address for the proxy server. Port. A valid port number (an integer between 1 and 65535). User name. The name of the user who will be logging in to the proxy server. Password. The password of the user who will be logging in to the proxy server.

      Click Next to continue.

   9. Review the installation details on the Pre-installation summary page.

      If all details are correct, click Install to proceed with the installation.

      To change any of the details, click Previous to return to the previous page of the installation wizard.

   10. When the installation is finished, the Installation complete page is displayed. Click Done to quit the installer.

   11. Specify credentials using the Endpoint Credentials Manager.

       In the Endpoint Credentials Manager, click New to add a new credentials record and select the required endpoint type. Enter the required user name and password for the on-premise application.

       Note If the On-Premise Bridge Agent service was running when you specified the credentials, restart the service now.

   Note The default values used when installing the On-Premise Bridge Agent are saved in the wrapper-custom.conf file in the <Agent_installation_directory>\product\conf folder:

   • wrapper.java.additional.108=-Drmi.server.port=1099

     To be able to start the agent, you must change the value of the rmi.server.port to an available port. If you do not, after several attempts to start the agent, the application will shut down and the On-Premise Bridge Agent Windows service will be stopped.

     If this port is in use by some other application, when you try to start the agent in On-Premise Bridge, the following errors are printed to log files, located in the <Agent_installation_directory>\product\log\controller folder:

     • In the wrapper.log file:

       java.rmi.server.ExportException: Port already in use: 1099

     • In the controller.log file:

       java.rmi.NotBoundException: ControllerAPI 

   • set.OPB_SERVICE_NAME= On-Premise Bridge Agent

   • configure the firewall to ensure that the RMI port is only accessible from the local machine

2. Enable a thread dump (optional)

   You can enable the Java thread dump feature which saves Java threads from the OPB operations. In the event of a problem, you can submit the threads to Support to help them resolve the issue.

   To enable the thread dump feature:

   1. In the <OPB_HOME>/product/conf folder, locate the dump.conf file.

   2. Set enableDumpThread=true (default is false).

   3. Restart the On-Premise Bridge agent.

   4. The thread dumps are saved in the <OPB_HOME>/product/log/threadDumps folder.

3. Add an agent

   1. From the main menu, select Administration > Utilities > Integration. Service Management displays the On-Premise Bridge Agents page.

   2. Click Add agent.

   3. Enter the agent details.

      Field	Description
      Name	The name that you enter is displayed in the list of agents and is used when you create endpoints.
      Description	Type a description that describes the agent.
      Enable notification	Select this check box to enable the email notifications when the agent has not reached the Service Management server for 30 minutes, 2 hours, or 1 day.
      Recipients	Specify the recipients that can receive the notifications.

   4. Click Download connection file. Copy the downloaded server-connection.conf file to the <Agent_installation_directory>/product/conf folder.

      The server-connection.conf file contains a unique agent identifier, which is used by Service Management when you create an endpoint to link between the agent and the endpoint. The identifier is also used to connect between the agent and the tasks that are routed to the agent in Service Management.

      The server-connection.conf file also contains the tenant ID and the base URL for Service Management.

4. Start or stop an agent

   You must start an agent before you can manage it in Service Management.

   To start or stop an agent:

   1. Click Start > Programs > MicroFocus > On-Premise Bridge Agent.
   2. Select Start On-Premise Bridge Agent or Stop On-Premise Bridge Agent.

5. Manage your installed agents

   Select an agent in the Agents pane to display:

   • The endpoints that are connected to the agent.
   • The three most recent events for the agent.

   You have three options for managing your agents:

   Label	Description
   Restart	Restarts the selected agent. You may want to do this if, for example, you see that server performance is not what you expect.
   Disable/Enable	Temporarily prevents tasks on the selected agent from running, or re-enables a blocked task.
   Remove	Removes the selected agent from the list of agents. You can remove an agent only if there are no tasks running on it. In addition, removing the agent also deletes all the endpoints that are configured to use it. Note To remove an On-Premise Bridge Agent, uninstall the software from its server. This does not uninstall an agent that you configured in the On-Premise Bridge.

   You can click the Refresh button to refresh the list of tasks.

6. Manage the On-Premise Bridge service

   You can manage the On-Premise Bridge service using Windows Services as follows:

   1. Run the services.msc command.
   2. Select the On-Premise Bridge Agent service.
   3. Stop or start the service as required.

   You can also manage the On-Premise Bridge service using command line instructions in one of the following ways:

   • To run On-Premise Bridge Agent in a console, execute the following command:
     <Agent_installation_directory>/bin/OpbAgent.bat console.
   • To install the On-Premise Bridge as a service, execute the following command:
     <Agent_installation_directory>/bin/OpbAgent.bat install.
   • To start the On-Premise Bridge service (after installation), execute the following command:
     <Agent_installation_directory>/bin/OpbAgent.bat start.
   • To stop the On-Premise Bridge service (after installation), execute the following command:
     <Agent_installation_directory>/bin/OpbAgent.bat stop.
   • To restart the On-Premise Bridge service (after installation), execute the following command:
     <Agent_installation_directory>/bin/OpbAgent.bat restart.
   • To remove the On-Premise Bridge service, execute the following command:
     <Agent_installation_directory>/bin/OpbAgent.bat remove.

To uninstall the On-Premise Bridge agent

You can uninstall the On-Premise Bridge Agent in one of the following ways:

• Double-click the opb-uninstall.exe file in the <Agent_installation_directory>/install directory to start the uninstallation wizard.

• Click Start > Programs > MicroFocus > On-Premise Bridge Agent > Uninstall On-Premise Bridge Agent.

• Uninstall the On-Premise Bridge Agent through the Control Panel.

Troubleshooting

• Checking log files

  There are several occasions when you should check the On-Premise Bridge log files for information.

  Agent connection errors

  • If you add an agent and the On-Premise Bridge module displays its connection status as Unknown, check the log files for possible reasons. Relevant information may be found in the following files in the <Agent_installation_directory>\product\log folder:

    • controller\controller.log
    • controller\wrapper.log
    • <Endpoint_type_name>\<Endpoint_type_name>.log
  • If you cannot log in, you may have used an incorrect user name or password.

  • If a user receives a 403 or AuthorizationException error when attempting to use the On-Premise Bridge Agent service, make sure you assign the OPB Remote Agent role to that user. For more information, see How to create a role.

• Updating Windows service properties

  By default, the On-Premise Bridge Agent service is run using the Windows Local System user. If you need to enable a specific endpoint type flow, you can modify the Local System user to include additional required access rights.

How to import certificates into an On-Premise Bridge

When you create an integration to Service Management Automation with a remote system that has an SSL address, the certificate of the remote server might need to be imported into the trusted keystore file of the On-Premise Bridge. The cacerts file stores public certificates of the root Certificate Authority (CA). If there is a problem with the connection between the OPB and the remote system, you can check the controller.log file of the OPB for the error defined below. If the error exists, then you may be required to follow the procedure in this section.

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Find the location of the Service Management OPB controller log

The default location of the controller.log file is in the C:\ProgramData\MicroFocus\On-Premise Bridge Agent\product\log\controller directory. Once the log file is located, search the log file for the HandshakeException error. If the error appears, the fully qualified domain name will be logged, which allows you to verify that the endpoint in question is indeed the one that is giving the error.

Find the location of the Service Management OPB trusted keystore

The default OPB trusted keystore file is named cacerts and is located in the C:\ProgramData\MicroFocus\On-Premise Bridge Agent\product\util\3rd-party\jre\lib\security directory. The OPB has its own trusted keystore file, which should not be confused with that of any other Java installation on the machine.

Obtain the certificate of the remote server

In most cases, there is a company-created certificate available and the server administrator is able to send it to you. In cases where the certificate is not available, it is also possible to use a Web browser to export the certificate so that it can be imported into the OPB’s trusted keystore.

Add the certificate to the trusted keystore

The java keytool utility is used to import certificates into the trusted keystore. To run the utility, open a command windows and navigate to the C:\ProgramData\MicroFocus\On-Premise Bridge Agent\product\util\3rd-party\jre\bin directory. The command format is:

keytool -importcert -keystore ..\lib\security\cacerts -alias "new Alias" –file myCert.crt

In this example, the myCert.crt file is the certificate of the remote server, cacerts is the trusted keystore, and the alias is a label set for the certificate. When prompted, the default password is “changeit”.

Confirm that the certificate is present

Java uses a tool called keytool to list or import any certificates in the trusted keystore file. Using this tool allows you to list all of the certificates that were imported into the keystore.

Open a command window and navigate to the C:\ProgramData\MicroFocus\On-Premise Bridge Agent\product\util\3rd-party\jre\bin directory. Run the keytool while pointing to the cacerts file. Syntax for the command is:

keytool –list –v –keystore ..\lib\security\cacerts > c:\contents.txt

The default password for the keystore is “changeit”. Once executed, a file named C:\contents.txt will list the entire content of the keystore. It is possible to search through this file using a text editor to confirm that the certificate for the remote server to confirm was loaded correctly.

How to specify credentials using a command line tool

This command line tool enables you to create and manage client-side endpoint credentials. With this tool, you can:

• List credentials, filtered by endpoint type name
• Create new credentials for a specified endpoint type
• Update existing credentials
• Delete existing credentials

To run the tool:

Run the credentials_mng_console.bat file in the <Agent_installation_directory>\product\util\opb folder.

list

Lists available credentials, filtered by endpoint type name.

Usage:

credentials_mng_console list –endpoint <ENDPOINT TYPE>

Parameters:

Result:

======================
Endpoint type  : sample-endpoint-type-12.5
ID             : 9460b7
Name           : sample credentials record
User           : sample username
Password       : ******
Parameters     :
Key | Value
-----------
sample.secret.property | ******
sample.url.property | 123

listEndpointTypes

Lists available endpoint types, filtered by endpoint type name.

Usage:

credentials_mng_console listEndpointTypes –endpoint <ENDPOINT TYPE>

Parameters:

Result:

Endpoint types  :
   1. indexing-domain
   2. ucmdb-10.20

listCredentialIds

Lists all credential IDs and the endpoint type related to each credential ID.

Usage:

credentials_mng_console listCredentialIds –endpoint <ENDPOINT TYPE>

Parameters:

Result:

====================
Endpoint type : indexing-domain
Name | ID :
1. sample credentials record name | 11e7

====================
Endpoint type : ucmdb-10.20
Name | ID :
1. sample credentials record name | 21e0
2. sample credentials record #2 name | 7e0

listEndpointTypeParams

Lists the specific parameters required for saving credentials for each endpoint type.

Usage:

credentials_mng_console listEndpointTypeParams –endpoint <ENDPOINT TYPE>

Parameters:

Result:

======================
Endpoint type : indexing-domain-12.5
Output format:
Parameter:
Label:
Description:
Mandatory:
--------------------------------------------
Endpoint type specific parameters:
Parameter: sample.url.property
Label: Server URL
Description: URL address for sample server
Mandatory: true
Parameter: sample.secret.property
Label: Secret key
Description: Secret key for sample server
Mandatory: false
Usage example:
credentials_mng_console create -endpointType indexing-domain-12.5 -name <NAME_VALUE> -user <USER_VALUE> -pass <PASSWORD_VALUE> -param sample.url.property <PARAMETER_VALUE> -param sample.secret.property <PARAMETER_VALUE>

create

Creates a credentials record.

Usage:

credentials_mng_console create –file <path to data file> –user <USER> –pass <PASSWORD> -endpoint <ENDPOINT TYPE> -name <CREDENTIALS NAME> -param <KEY> <VALUE> –param <KEY> <VALUE>

Usage example

Parameters:

The property file is a text file that describes the credential's properties. The file format is:

endpoint=
name=
user=
pass=
customParam1=value1
customParam2=value2

Result:

endpoint=ALM_12.5
name=Build-Jenkins-Master
customParam1=value1
customParam2=value2

update

Updates an existing credentials record.

Usage:

credentials_mng_console update –file <path to data file> –user <USER> –pass <PASSWORD> -endpoint <ENDPOINT TYPE> -name <CREDENTIALS NAME> -param <KEY> <VALUE> –param <KEY> <VALUE> -replace

Parameters:

delete

Deletes a credential.

Usage:

credentials_mng_console delete –endpoint <ENDPOINT TYPE> -credentialsId <CREDENTIALS ID>

Parameters:

help

Provides help for the current topic.

Usage:

credentials_mng_console help

How to set credentials for Service Management and proxy configuration

Service Management credentials are encrypted and stored on your site in the agentCredentialsStore.xml file, located in the <Agent_installation_directory>/product/conf folder.

Use a command line tool to configure Service Management credentials and proxy configurations.

Run one of the following files:

To run the tool for Service Management credentials:

Run the agentAuthentication.bat file in the <Agent_installation_directory>/product/util/opb folder.

For the Service Management configuration, the following command is relevant:

setAuth (for Service Management credentials)

Saves credentials connecting to a Service Management service.

Usage:

AgentAuthentication setAuth –user <USER NAME> -pass <PASSWORD>

Parameters:

To run the tool for proxy configuration:

Run the proxyConfiguration.bat file in the <Agent_installation_directory>/product/util/opb folder.

For the proxy configuration, the following commands are relevant:

setAddress

Saves the proxy host and port configuration.

Usage:

ProxyConfiguration setAddress -host <PROXY HOST> -port <PROXY PORT>

Parameters:

removeProxyConfiguration

Deletes the configuration of a proxy server.

Usage:

ProxyConfiguration removeProxyConfiguration

setAuth (for a proxy server)

Saves credentials for a proxy server.

Usage:

ProxyConfiguration setAuth –user <USER NAME> -pass <PASSWORD >

Parameters:

removeAuth

Deletes the credentials for connecting to a proxy server.

Usage:

ProxyConfiguration removeAuth

Related topics

• How to use endpoints

• On-Premise Bridge download center

• On-Premise Bridge security additional information