Downloading and Running the OHI Agent

This section of the document explains how to obtain the OHI Agent java archive file (or jar file) and how to run it. A Java runtime is needed to run the OHI Agent jar, no other software needs to be installed.

Downloading the OHI Agent

The OHI Agent runnable jar file must be downloaded from OHI Gateway by executing a GET request to its "/agent" HTTP API resource. Accessing the resource is subject to the usual authentication and authorization procedures.

For example, assuming user "agent_downloader" is provisioned in the OHI Gateway and is authorized to access the "/agent" resource, the following curl request will download the OHI Agent jar (it will prompt for the password):

curl -su agent_downloader -o ohi-agent.jar http://gateway_machine/api/agent

For the remainder of this guide it is assumed that the OHI Agent runnable jar file is placed in a directory that is referred to as AGENT_HOME.

Setting up a Properties File

In the AGENT_HOME (or in AGENT_HOME/config) create a file called "application.properties". In the file, add at least valid values for the following system properties (note that all property name=value pairs need to be specified on one line without line breaks; the property names in the table below are formatted for readability):

Property	Required?	Description
agent.gateway.uri	Yes	OHI Gateway URI, including the context root for the HTTP API. Must be a secure connection.
agent.gateway.authentication	Yes	Either OAuth or BasicAuthentication. Defaults to OAuth.
agent.keystore.url	Only if a keystore is used as secrets store	URL to the KeyStore file
agent.keystore.password	Only if a keystore is used as secrets store	The password for accessing the KeyStore. For security reasons this may be listed as environment variable before starting the OHI Agent.
agent.vault.uri	Only if Vault is used as secrets store	Vault URI that the OHI Agent uses to retrieve secrets. Must be a secure connection.
agent.vault.pemFilePath	Only if Vault is used as secrets store	Client certificate in PEM format for accessing the Vault.
agent.vault.token	Only if Vault is used as secrets store	OHI Agent specific token for accessing the Vault.
agent.oauth2.uri	Only if OAuth is used	OAuth2 Authorization Server URI that the OHI Agent uses to retrieve OAuth2 access tokens that are needed to access the OHI Gateway. Must be a secure connection.
agent.oauth2.serverScope	Only if OAuth is used	Optional scope for retrieving OAuth2 access tokens.
ohi.rest.client.agent.gateway.authentication.trust.store.file	Yes	The location of the SSL trust store file
ohi.rest.client.agent.gateway.authentication.trust.store.password	Yes	The password for the SSL trust store file

Running the OHI Agent

Please note that the OHI Agent requires Java 11 to run.

Run the OHI Agent by executing the following command:

java -jar ohi-agent.jar

Checking if the OHI Agent version matches the OHI Gateway version

Upon startup the OHI Agent connects to the OHI Gateway in order to retrieve its configuration. When doing so, it will check if its own version matches that of the OHI Gateway. If that is the case it will log the following informational message:

Agent version a.b.c matches version of Agent that is bundled with Gateway

Otherwise it will log the following warning:

Agent version a.b.c does not match the version of Agent that is bundled with Gateway, please download Agent from Gateway

In the latter case, download the matching version of the OHI Agent from the OHI Gateway and use that.

Checking the health of the OHI Agent

From an operational perspective it is useful to have a mechanism to easily check whether the Agent is up and running. For this purpose, the Agent exposes a specific endpoint. This endpoint can be accessed through

https://<host>:<port>/actuator/health

The below example shows how this is accessed through curl. If the Agent is up it will report back on the status:

curl http://myhost:8890/actuator/health
{"status":"UP"}

The port shown above, is something that is determined by the system. In case you need this port to have a fixed value, include the following startup parameter:

<tt>--server.port=<portnumber></tt>. Where <portnumber> is the port number that you want to system to use.

Display the version of the OHI Agent binary

In order to display the version of the OHI Agent binary that is currently present/installed on-premises, without effectively running the agent the following command can be run from the command line:

java -jar ohi-agent.jar --version

This will print version information, which looks like:

agent (IAT)
Version: 4.0.0

Configuring OHI Agent logging

By default the OHI Agent will log output to the console, and to a logs directory relative to the location where the OHI Agent is started. OHI Agent logging can be configured in various ways. In this section we list the most important configuration options. As is the case for OHI Agent properties, logging configuration is done through adding the appropriate OHI Agent program argument on the command line.

Changing the location where logs are written to

In case you want to have the log files for the OHI Agent written to another directory, you can do so by adding this program argument:

--logging.file.path=/external/as2805_a/logs

Activating a particular component namespace for additional log information

Sometimes it is useful to have the OHI Agent generate additional logging information. This for instance can be used to resolve a service request raised for a problem with the OHI Agent. A support engineer will typically ask that a particular component namespace be put in a state that it starts generated more detailed log information. An example where the root component namespace is put into debug mode, looks like this:

--logging.level.com.oracle.healthinsurance=DEBUG

Externalizing OHI Agent logging configuration in its entirety

There might be reasons where the whole configuration for the logging subsystem needs to be externalized from the application. The externalized log configuration file follow the logback format (check http://logback.qos.ch/manual/configuration.html - "Configuration File Syntax" for details). This can be done using the following:

--logging.config=file:/external/config/logback-spring.xml

or in order to externalize the logging configuration to a web server:

--logging.config=http://somehost:8080/config/logback-spring.xml