Develop > Command-Line Interfaces > ConfigExchange Command-Line Interface

ConfigExchange Command-Line Interface

You can use the ConfigExchange command-line interface (CLI) for the following tasks:

  • Migrating policies from the OM to Monitoring Automation. These tasks make use of operations referred to in this section as <omOperation>.

  • Development and management of instrumentation packages:

    • Creating a compatible file structure for instrumentation development.

    • Uploading and downloading instrumentation packages or elements thereof. An element of an instrumentation package can be the base package, a patch or a hotfix.

    These tasks make use of operations referred to in this section as <instrumOperation>.

Location

<OMi_HOME>/opr/bin/ConfigExchange

Synopsis

ConfigExchange [<CONNECTION_INFO>] {<toolInfo> | <omOperation> | <instrumOperation>}

Options

ClosedSyntax for <CONNECTION_INFO>

-rc_file <file> &| -username <login name> [ -password <password> | -smartcard | -winCrypto | -jks <keystore path> -jksPassword <keystore password> ] [[-port <port>] [-server <gatewayserver>] [-ssl] | [-u <URL>]]

Note If <CONNECTION_INFO> is omitted, the command is executed on the server to which you are logged on.

Option Description
{-rc_file | -rcf }<file> Location of your credential store. Values for your username, password, java keystore location, and java keystore password can be defined here, enabling you to run commands without having to specify the values individually each time. Use the options -list_rc, -set_rc, and -delete_rc to work with the file. The default file is <OMi_HOME>/.opr-cli-rc. If this option is not specified, then commands automatically check the default file location for credentials. You must specify this option if your credential store file is in a non-default location. If this file does not exist or does not contain the correct settings, you must manually specify the credentials using the other command options.
{-list_rc| -lrc} [-rc_file <file>] Display the content of the file from which credentials are read. The file contains fields for java keystore, keystore password, username and password, and is encrypted by a hardcoded key.
{-set_rc | -src} <key>=<value> [-rc_file <file>] Configure one setting in the file from which credentials are read. Specify the setting and the new value by using a key=value pair. For example, -set_rc password=<password string>.
{-delete_rc | -drc} <setting> [-rc_file <file> } Delete setting from file from which credentials are read. Possible settings are username, password, jks, and jksPassword.
{-username|-user} <login name>

Sets the login name of the user required to execute CLI operations on the target gateway server.
{-password|-pw} <password>

Sets the password for the specified user. If using SSH on Cygwin, either enter the password in free text or use other communication methods, for example Java keystore, Windows keystore, or smart card authentication.

Default value: empty string
{-smartcard|-sc}

Use certificate stored on smart card or security token for authentication. When OMi is configured to use CAC authentication, the CLI tools under <OMi_HOME>/opr/bin/ do not directly prompt users to enter the password for the smartcard connected to the system. Instead, users must specify that a smartcard authentication is to be run, using the option -sc or -smartcard. Users attempting to run a tool without the -smartcard option automatically receive an error message.

For more information, see Using command-line tools when client certificate enforcement is used.
{-winCrypto|-wc}

If OMi is configured for TLS mutual authentication, this option specifies to use the Windows certificate store for authentication. The certificate store must hold exactly one client certificate, which OMi will use to authenticate the user. This option is only available on Windows systems.

For details, see Configure Client Certificate or Smart Card Authentication.
{-jks|-j} <keystore path>

If OMi is configured for TLS mutual authentication, this option can be used to specify the Java keystore to be used for authentication. The keystore must hold exactly one client certificate, which OMi will use to authenticate the user.

Note It is not necessary that the client certificate contains the flag "Smart Card Logon (1.3.6.1.4.1.311.20.2.2)" in the "Enhanced Key Usage" field.

For details, see Configure Client Certificate or Smart Card Authentication.
{-jksPassword|-jp} <keystore password>

Password for accessing the Java keystore.
{-port|-p} <port>

Uses port <port> to connect to the target gateway server.

Default:
80 (HTTP)
443 (HTTPS)
-server <GatewayServer>

Sets the target gateway server, using <GatewayServer> as the hostname or IP address to locate it.

Default: FQDN of the OMi gateway server
-ssl

When this option is specified, the HTTPS protocol is used to connect to the target gateway server. If omitted, the HTTP protocol is used.

Cannot be used in conjunction with the -url option.
{-url|-u} <url>

Sets the target gateway server, using <url> as the URL to locate it.

Default:
https://<OMi gateway FQDN>:80/opr‑config‑server
ClosedSyntax for <toolInfo>

{‑examples | ‑help | ‑version}

Option Description
{‑examples|-ex} Displays a number of examples of how to use the tool.
{‑help|‑h} Displays a summary of the command options.
‑version Displays version information for the tool.
ClosedSyntax for <omOperation>

{‑check | ‑uploadOM} <arguments>

Option Description

{‑check|‑c} {‑policyfile|‑pf} <fileOrDir> {‑logfile|‑lf} <logFile>

Checks the policy contained in the policy file or directory <fileOrDir> for incompatibilities, and logs the results to <logFile>. Typically, policy files or directories are obtained through exports from HPOM.

For more information on checking and migrating policies from HPOM to Monitoring Automation, see Import configuration data from Operations Manager.
{‑uploadOM|‑uom}̮
{‑input|‑i} <inputDir>

Note <authentication> is required.

Uploads the HPOM policies, policy groups, and instrumentation exported from HPOM for Windows or HPOM for UNIX or Linux to the Monitoring Automation database, using directory <inputDir> as the input directory.
ClosedSyntax for <instrumOperation>

{‑createinstrumdir | ‑download | ‑list | ‑merge | ‑remove | ‑upload} <arguments>

Option Description

{‑createinstrumdir|‑cin} {‑output|‑o} <outputDir>

Creates an empty directory layout for an instrumentation package in the file system in directory <outputDir>.

  • If a directory structure already exists at the specified location, the directory structure is merged in the existing one.
  • If the specified directory does not exist, it is created, including any higher-level directories.

When developing instrumentation, it is recommended to use this structure to ensure you apply the correct layout required by HPOM.

{‑download|‑dl} {‑output|‑o} <outputDir> {‑instrumname|‑inn} <instrum> [‑patch <patchNr>]  [{‑hotfix|‑hf} <hotfixName>   {‑forpatch|‑fp} <patchNr>]

Note <authentication> is required.

Extracts the content of a specific configuration folder, a specific element of an instrumentation package or a policy from the database and downloads it to the file system in directory <outputDir>.

  • Use ‑download ‑output <outputDir> ‑instrumname <instrum> to download the base package labeled <instrum>.

  • Use ‑download ‑output <outputDir> ‑instrumname <instrum> ‑patch <patchNr> to download patch <patchNr> for instrumentation <instrum>.

  • Use ‑download ‑output <outputDir> ‑instrumname <instrum> ‑hotfix <hotfixName> ‑forpatch <patchNr> to download hotfix <hotfixName> for patch <patchNr> for instrumentation <instrum>.

Note To download an entire package, including all its patches and hotfixes, use the ‑merge operation.

{‑list|‑l} {{‑instrumname|‑inn}  <instrum>|ALL}

Note <authentication> is required.

Lists all patches and hotfixes for instrumentation package <instrum>, or use ALL to list all instrumentation packages in the database (Note: ALL is case-sensitive).

‑merge {‑output|‑o} <downloadDir> {‑instrumname|‑inn} <instrum>

Note <authentication> is required.

Downloads the instrumentation package with the label <instrum> and all its patches and hotfixes to the file system and places it in directory <downloadDir>. Data is merged in the following order:

The base package and any patches and hotfixes are downloaded in the order they are applied to an agent:

  1. The base package is downloaded first.
  2. Next, the highest patch is downloaded and applied to the base package.
  3. Then the hotfixes for this patch are downloaded and applied in alphabetical order.
  4. The previous steps are repeated for the next highest patch until all patches have been downloaded.

Note To download a specific element of a package, use the ‑download operation.

{‑remove|‑rm} {‑instrumname|‑inn} <instrum> [{‑patch|‑p} <patchNr>] [{‑hotfix|‑hf} <hotfixName> {‑forpatch|‑fp} <patchNr>]

Note <authentication> is required.

Removes an instrumentation package or an element thereof from the database:

  • Use ‑remove ‑instrumname <instrum> to completely remove the instrumentation package labeled <instrum> (including patches and hotfixes).

  • Use ‑remove ‑instrumname <instrum> ‑patch <patchNr> to remove all patches with a patch number ≤<patchNr> (including hotfixes) from instrumentation package <instrum>.

  • Use ‑remove ‑instrumname <instrum> ‑hotfix <hotfixName> ‑forpatch <patchNr> to remove hotfix <hotfixName> for patch <patchNr> from instrumentation package <instrum>.

    Use ‑remove ‑instrumname <instrum> ‑hotfix <hotfixName> ‑forpatch 0 to remove hotfix <hotfixName> from the base package of instrumentation package <instrum>.

{‑upload|‑ul} {‑input|‑i} <inputDir> {‑instrumname|‑inn} <instrum> [‑label <label>] [{‑description|‑de} <descr>] [{‑patch|‑p} <patchNr>] [{‑hotfix|‑hf} <hotfixName> {‑forpatch|‑fp} {<patchNr>|0}][{‑force|‑f}]

Note <authentication> is required.

Uploads instrumentation data from directory <inputDir> to the database as an instrumentation package with object name <instrum>.

An upload error occurs if a configuration object with the name <instrum> already exists in the database. In this case, you can use the option ‑force to work around the upload error and upload the package using the existing name.

Caution Using ‑force overwrites the existing package with the uploaded package, meaning the existing data is lost.

When the instrumentation is uploaded to the database, a label and a description are attached to the package, which are used as the name and description of the package in the Operations Management user interface.

  • Specify option ‑label <label> to name the instrumentation <label>. If ‑label omitted, <instrum> is used as label.
  • Specify option ‑description <descr> to set the text to go into the description to <descr>. If ‑description is omitted, the description is left blank.

Packages can be uploaded as base packages, patches, or hotfixes.

  • Use ‑upload ‑input <inputDir> ‑instrumname <instrum> to upload a base package prepared in <inputDir> and name it <instrum>.
  • Use ‑upload ‑input <inputDir> ‑instrumname <instrum> ‑patch <patchNr> [‑label <label> to upload a patch prepared in <inputDir> as patch <patchNr> for instrumentation package <instrum>.
  • Use ‑upload ‑input <inputDir> ‑instrumname <instrum> ‑hotfix <hotfixName> ‑forpatch <patchNr> to upload a hotfix prepared in <inputDir> as hotfix <hotfixName> for patch <patchNr> for instrumentation package <instrum>.
  • Use ‑upload ‑input <inputDir> ‑instrumname <instrum> ‑hotfix <hotfixName> ‑forpatch 0 to upload a hotfix for the base package of instrumentation package <instrum>.

Exit Status

Exit Status

Description

Output
0

Successful completion of the requested operation

 No output.
1

Failure of the requested operation

 An error message stating why the operation failed, followed by the tool's help text.
300‑399

HTTP Redirection (300-399)

An error message stating the HTTP error number and description.

For more information about HTTP error status values, see publicly available HTTP documentation.
400‑499

HTTP Client Error (400-499)
500‑599

HTTP Internal Server Error (500-599)

Restrictions

Some operations require authorization. The specified user must be an OMi user with permission to create policy templates. If <CONNECTION_INFO> is required, <CONNECTION_INFO> must be specified and valid.

If <CONNECTION_INFO> is omitted when requesting an operation requiring authentication, ConfigExchange does not execute the requested operation, and exits with the following error:

Username may not be null. Operation requires authentication. Please enter the login name and password.

The error can be fixed by inserting an <CONNECTION_INFO>.

Non-admin users also need the following file permissions to operate this command-line tool:

File Windows Permissions Linux Permissions
<OMi_HOME>/conf/TopazInfra.ini read r
<OMi_HOME>/log/opr-clis.log full control rw

<OMi_HOME>/log/opr-pgctl.log

Note: This file is not available on gateway server systems.
full control rw
<OMi_HOME>/conf/encryption.properties read r
<OMi_HOME>/conf/seed.properties read r

Examples

This section shows a number of real-life examples you can use as a starting point for developing your own ConfigExchange commands.

  • Upload Instrumentation, Policies and Policy Groups from HPOM

    A policy was exported from HPOM to the directory /usr/myOMPolicy. Issue the following command to upload the policy:

    ConfigExchange ‑username myU ‑password myPwd ‑uploadOM ‑input /usr/myOMPolicy

  • Upload Instrumentation Packages, Patches, and Hotfixes

    • A new instrumentation package was prepared in the directory /usr/myCustomInstrum. Issue the following command to overwrite existing instrumentation myInstrum with the new package:

      ConfigExchange ‑username myU ‑password myPwd ‑upload ‑input /usr/myCustomInstrum ‑instrumname myInstrum ‑force

    • A new instrumentation package was prepared in the directory /usr/myCustomInstrum. Issue the following command to upload the new package as a patch for instrumentation myInstrum with patch number 3 and label the patch myFix:

      ConfigExchange ‑username myU ‑password myPwd ‑upload ‑input /usr/mydir ‑instrumname myInstrum ‑patch 3 ‑label myFix

    • A new instrumentation package was prepared in the directory /usr/myCustomInstrum. Issue the following command to upload the new package as a hotfix with name hf_CPUfix for patch number 3 of instrumentation myInstrum, and attach the description MyCP hotfix for patch 3; fix CPU issue:

      ConfigExchange ‑username myU ‑password myPwd ‑upload ‑input /usr/myCustomInstrum ‑instrumname myInstrum ‑hotfix hf_CPUfix ‑forpatch 3 ‑force ‑description "hotfix for patch 3; fixes CPU issue"

    • A new instrumentation package was prepared in the directory /usr/myCustomInstrum. Issue the following command to upload the new package as a hotfix with name hf_CPUfix for the base package of instrumentation myInstrum:

      ConfigExchange ‑username myU ‑password myPwd ‑upload ‑input /usr/myCustomInstrum ‑instrumname myInstrum ‑hotfix hf_CPUfix ‑forpatch 0

  • Download an Instrumentation Package from the Database to the Local File System

    Issue the following command to download the entire package for instrumentation package myInstrum from the database, and place it in directory myDownloads:

    ConfigExchange ‑merge ‑output myDownloads ‑instrumname myInstrum

  • Download the Contents of a Configuration Folder from the Database to the Local File System

    Issue the following command to download the configuration objects in configuration folder myInstrum from the database, and place them in directory myDownloads:

    ConfigExchange ‑download ‑output myDownloads ‑startId 7d6468fb‑486d‑b7cd‑8bff‑f6c26b34c305

  • Download Specific Elements of an Instrumentation Package from the Database to the Local File System

    • Issue the following command to download the base package for instrumentation package myInstrum from the database, and place it in directory myDownloads (patches and hotfixes are not downloaded):

      ConfigExchange ‑username myU ‑password myPwd ‑download ‑output myDownloads ‑instrumname myInstrum

    • Issue the following command to download patch number 1 for instrumentation package myInstrum from the database, and place it in directory myDownloads (the base package and any hotfixes for the patch are not downloaded):

      ConfigExchange ‑username myU ‑password myPwd ‑download ‑output myDownloads ‑instrumname myInstrum ‑patch 1

    • Issue the following command to download hotfix hf_CPUFix for patch number 1 for instrumentation package myInstrum from the database, and place it in directory myDownloads (the base package and the patch the hotfix is for are not downloaded):

      ConfigExchange ‑username myU ‑password myPwd ‑download ‑output myDownloads ‑instrumname myInstrum ‑hotfix hf_CPUFix ‑forpatch 1

    • The same command used in the previous example can be shortened using command element abbreviations, in which case it looks as follows:

      ConfigExchange ‑user myU ‑pw myPwd ‑dl ‑o myDownloads ‑inn myInstrum ‑hf hf_CPUFix ‑fp 1

  • Remove Instrumentation Packages or Elements Thereof from the Database

    • Issue the following command to remove instrumentation package MyInstrum, including all associated patches and hotfixes, from the database:

      ConfigExchange ‑user myU ‑pw myPwd ‑remove ‑instrumname myInstrum

    • Issue the following command to roll back hotfix hf_CPUFix for patch number 1 from instrumentation package MyInstrum (the base package and the patch are not removed):

      ConfigExchange ‑user myU ‑pw myPwd ‑remove ‑instrumname myInstrum ‑hotfix hf_CPUFix ‑forpatch 1

    • Issue the following command to roll back patches with a patch number ≤1 and all their hotfixes (the base package and any patches with a patch number >1 are not removed):

      ConfigExchange ‑user myU ‑pw myPwd ‑remove ‑instrumname myInstrum ‑patch 1

  • Create a Directory Structure to be Used as a Template for Preparing an Instrumentation Package from Scratch with the Intention to Upload It

    Issue the following command to create a directory structure for instrumentation MyInstrum in the directory /usr/myCustomInstrum:

    ConfigExchange ‑createinstrumdir ‑output /usr/myCustomInstrum

  • Investigate Which Patches and Hotfixes are Installed for a Certain Instrumentation Package

    Issue the following command to list all patches and hotfixes for instrumentation myInstrum:

    ConfigExchange ‑username myU ‑password myPwd ‑list ‑instrumname myInstrum

Troubleshooting

ClosedGeneral Troubleshooting

Some of the errors reported by ConfigExchange can be classified as warnings and can be ignored. The policy upload process ignores these errors and continues. The following sections describe some of these errors.

ClosedOperation failed. HTTP Status: 400 (Bad Request)

  • Problem: An instrumentation with dirName "<name>" already exists.

    The tool re-attempts uploading an instrumentation after encountering import problems. In this case the error may happen because an instrumentation with the same name, ID, or version already exists in the database, having been created during the first attempt.

    Solution: Can be ignored.

  • Problem:

    Template "<name>" already exists with a different ID (<ID>) in the database.

    The tool attempts to import a policy template that already exists in the database with the same name but a different ID.

    Solution: Policy names must be unique in OMi, also across different policy template types. In OM, rename the policies using unique policy names and then re-import them to OMi.

  • Problem:

    Template version "<name>" <version> (version ID <ID>) is already in the database.

    You may be attempting to upload a policy with the same version number as a policy already uploaded to the database. For example, if an HPOM policy is uploaded to Monitoring Automation, and is then modified in both Monitoring Automation and HPOM, the same policy version numbers are created with different policy content. If you then attempt to re-import the HPOM-modified policy to Monitoring Automation, ConfigExchange generates an error.

    Solution: Delete the policy version in Monitoring Automation and re-import the HPOM policy. A policy should have a dedicated master. Do not modify a policy in both Monitoring Automation and HPOM to avoid version conflicts.

  • Problem: Object [templateVersion] is read-only.

    ConfigExchange attempts to re-import the same policy version. However either the policy was modified without leading to a new version on the Operations Management server or instrumentation was missing during the first upload. For example, ConfigExchange imports a policy although some instrumentation categories are missing. When importing the same policy for a second time, ConfigExchange assumes that new categories were added to the policy.

    Solution: Can be ignored.

ClosedOperation failed. HTTP Status: 404 (Not Found)

  • Problem: No template with id: "<ID>" found.

    A policy group contains a policy that cannot be uploaded to Monitoring Automation, for example because the policy type is not supported in Monitoring Automation.

    Solution: Can be ignored.

  • Problem: No instrumentation with id: "<ID>" found.

    This may occur when importing further versions of same policy name.

    Solution: Can be ignored.

Related Topics Link IconRelated Information

Send Help Center feedback