Search for	Example	Results
A single word	`cat`	Topics that contain the word "cat". You will also find its grammatical variations, such as "cats".
A phrase. You can specify that the search results contain a specific phrase.	`"cat food"` (quotation marks)	Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase.

Search for	Operator	Example
Two or more words in the same topic	`AND` `and` `+` (plus symbol) `&` (ampersand)	`cat AND dog` `"cat food"+milk` `"cat food"&"dog food"`
Either word in a topic	`OR` `or` `\|` (pipe)	`cat OR dog` `cat \| dog`
Topics that do not contain a specific word or phrase	`NOT` `not` `!` (exclamation point)	`NOT cat` `! dog`
Topics that contain one string and do not contain another	`^` (caret)	`cat ^ mouse`
A combination of search types	`( )` parentheses	`cat + (dog \| mouse)` `cat \| dog + (! mouse)`

Service Management

Integrate > On-Premise Bridge Agents and Endpoints > How to use On-Premise Bridge agents on Linux

How to use On-Premise Bridge agents on Linux

To install and manage agents

Note To install the On-Premise Bridge, you must have the following permissions:

Read, write, and execute permissions in the On-Premise Bridge installation folder
Sudo permission to install and uninstall the OpbAgent service

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: RHEL 64 bit 6.4 and 7.2
- 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 the agent and select the Linux icon to download the agent for Linux.
3. Create a folder under /opt (for example, /opt/<Agent_installation_directory>) and grant it permission.
4. Upload the OPB agent for Linux installer to the /opt/<Agent_installation_directory> folder and change the execution permission.
5. Go to the /opt/<Agent_installation_directory> folder and install the OPB agent using the following commands:
  
  sh opb-installation.bin -i silent -DUSER_INSTALL_DIR=/opt/<Agent_installation_directory> -Dmaas.user.name=<username> -Dmaas.user.password=<password>
  
  If you are using a proxy server, use the following commands:
  
  sh opb-installation.bin -i silent -DUSER_INSTALL_DIR=/opt/<Agent_installation_directory> -Dmaas.user.name=<username> -Dmaas.user.password=<password> -Dproxy.host=<proxy_server_address> -Dproxy.port=<proxy_port_ID -Dproxy.user.name=<proxy_username> -Dproxy.user.password=<proxy_password>
  
  Note This section describes the OPB agent installation using a command line, for the installation using a graphical user interface, refer to On-Premise Bridge Installation document for Windows.
6. 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.
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.

Add an agent

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

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.

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.

Start or stop an agent

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

To start or stop an agent, use service <agent_service_name> start/stop.

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.

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.

To uninstall the On-Premise Bridge agent

You need to uninstall the On-Premise Bridge agent service before uninstalling the On-Premise Bridge agent.

To uninstall the On-Premise Bridge agent service, use sudo service <agent_service_name> remove.
To uninstall the On-Premise Bridge agent, use sh opb-uninstall.

Note When you uninstall the On-Premise Bridge Agent, the following occurs:

All data is deleted, except for credentials that you created.
Properties that you customized in the <Agent_installation_directory>/product/conf/wrapper-maas.conf file are deleted. However, this information is backed up in the wrapper-custom.conf.bak and wrapper-maas.bak files. To use this information, you must rename these backup files and then copy them to the corresponding folder in a new installation.

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.

How to import certificates into an On-Premise Bridge

Note Skip this section if you have replaced the certificates for the suite with CA trusted certificates.

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 /opt/<Agent_installation_directory>/OPB/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 /opt<Agent_installation_directory>/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 line interface and navigate to the /opt/<Agent_installation_directory>/OPB/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 line interface and navigate to the /opt/<Agent_installation_directory>/OPB/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 > /opt/<Agent_installation_directory>/OPB/contents.txt

The default password for the keystore is “changeit”. Once executed, a file named /opt/<Agent_installation_directory>/OPB/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.sh 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:

-endpoint <ENDPOINT TYPE> Endpoint type name (optional)

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:

-endpoint <ENDPOINT TYPE> Endpoint type name (optional)

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:

-endpoint <ENDPOINT TYPE> Endpoint type name (optional)

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:

-endpoint <ENDPOINT TYPE> Endpoint type name (optional)

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

credentials_mng_console create -user <USER_VALUE> -pass <PASSWORD> -endpoint indexing-domain-12.5 -name <NAME_VALUE> -param sample.url.property <PARAMETER_VALUE> -param sample.secret.property <PARAMETER_VALUE>

Parameters:

`-file <FILE>`	Read parameters from the property file (optional). Parameters will be overwritten if they are specified in the console.
`-user <USER>`	User name
`-pass <PASSWORD>`	Password
`-endpoint <ENDPOINT TYPE>`	Endpoint type name (optional)
`-name <CREDENTIALS NAME>`	Credentials name
`-param <KEY> <VALUE>`	Custom parameters (optional)

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:

`-file <FILE>`	Read parameters from the property file (optional). Parameters will be overwritten if they are specified in the console.
`-user <USER>`	User name
`-pass <PASSWORD>`	Password
`-endpoint <ENDPOINT TYPE>`	Endpoint type name
`-param <KEY> <VALUE>`	Custom parameters (optional)
`-replace`	Replace all existing parameters with input parameters (optional).

delete

Deletes a credential.

Note You cannot delete a single parameter from a credential. You can delete an entire credential.

Usage:

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

Parameters:

`-endpoint <ENDPOINT TYPE>`	Endpoint type name
`-credentialId <CREDENTIALS ID>`	The credentials ID

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

`-user <USER NAME>`	The user name for connecting to the Service Management service.
`-pass <PASSWORD>`	The password for connecting to the Service Management service.

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.

To run the tool for proxy configuration:

Run the proxyConfiguration.sh 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:

`-host <PROXY HOST>`	The address of the proxy server host.
`-port <PROXY PORT>`	The port number of the proxy server.

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:

`-user <USER NAME>`	The user name for connecting to the proxy server.
`-pass <PASSWORD>`	The password for connecting to the proxy server.

removeAuth

Deletes the credentials for connecting to a proxy server.

Usage:

ProxyConfiguration removeAuth