1. Working with Oracle Management Cloud
  2. omcli Command Options

A omcli Command Options

omcli commands let you work with Oracle Management Cloud agents and entities.

Accessing omcli

omcli comes bundled with a deployment of Oracle Management Cloud. You can access omcli from the <AGENT_BASE_DIR>/agent_inst/bin folder.

omcli Commands

Command Usage

start

omcli start agent

Starts the Oracle Management Cloud agents on the host.

stop

omcli stop agent

Stops the Oracle Management Cloud agents running on the host.

status

omcli status agent

Retrieves the status of the Oracle Management Cloud agents running on the host.

setproperty

omcli setproperty agent [-allow_new] -name PROPERTY_NAME -value PROPERTY_VALUE

Sets the specified property name and value in the agent configuration file.

-allow_new is an optional parameter that inserts a new property in the agent configuration file if the property doesn’t exist. -allow_new must be the first option to be provided to the command.

getproperty

omcli getproperty agent -name NAME_1 [... NAME_N] | -category NAME_1

Gets the specified properties or a category of properties from the agent configuration files.

-name accepts a list of property names separated by spaces. However, you can’t have spaces in the property names.

dumpstate

omcli dumpstate agent [-dump_full_state] [COMPONENTNAME ...]

Dumps the internal state of the specified list of components.

clear_property

omcli clear_property agent -name PROPERTY_NAME

Clears the value for the specified property in the agent configuration file.

status

omcli status agent [TIMEOUT]

Returns the status of the agent.

TIMEOUT is the timeout value in seconds.

reload

omcli reload agent

Reloads the configuration properties of the agent.

upgrade

omcli upgrade agent

Requests an upgrade of the agent to the latest available version. The request will be accepted only if the agent is eligible for an upgrade.

Once the request is accepted, the agent will be upgraded as soon as possible.

getversion

omcli getversion agent

Prints the version of the agent.

status agent scheduler

omcli status agent scheduler [-summary]

Displays the status of the agent scheduler.

The status agent scheduler command lists the tasks that are periodically scheduled by the agent. It includes collection items and internal tasks.

status agent connectivity

omcli status agent connectivity [-verbose]

Displays current connectivity issues the agent is suffering.

Also, it indicates whether the agent is running or not. If the agent is not running, it displays connectivity issues experienced at the time of the shutdown.

config agent getTZ

omcli config agent getTZ

Gets the system time zone from the environment.

config agent listtargets

omcli config agent listtargets

 Lists the entities that were registered with the agent.

add_entity

omcli add_entity agent FILENAME [-credential_file CREDENTIAL_FILE [-encryption_method_gpg]] [-tag_all] [-no_check] [-force]

Adds the defined entity to Oracle Management Cloud.

  • FILENAME is the name of the file that contains the entity definition to be added. This file cannot contain any credentials.

  • CREDENTIAL_FILE is an optional parameter and is required only if you need to add entities with credentials.

    A credential file follows this format:

    {"credentials": [
               {"id":"id1", "name":"credName1", "credType":"type1",
                    "properties":[{"name":"prop1", "value":"CLEAR[value1]"},
                                  {"name":"prop2", "value":"FILE[/tmp/filename]"}]
               }
              ]
}
    This sample format includes:

    • A credential with an ID (id1). This credential must match the credential reference in the entity definition and must be unique.

    • A name (CredName1) that you specify to distinguish your credentials.

    • A credential type, from a predefined set of known types (for example, DBCreds for databases).

    • A property name (prop1) whose value (value1) is specified in clear text.

    • A property (prop2) whose value is the contents of the file /tmp/filename.

  •  -encryption_method_gpg is an optional parameter. If specified, this option indicates that the file is encrypted using gpg symmetric encryption.

  • -tag_all is an optional parameter. If specified, the tags in the definition are applied to all the sub-entities as well. The default behavior is that the tags only apply to the entity.

  • -no_check is an optional parameter. If specified, the credential password is not checked before updating. The default behavior is that the credential password is checked.

  • -force is an optional parameter. If specified, all validation errors are ignored.

update_entity

omcli update_entity agent FILENAME [-credential_file CREDENTIAL_FILE [-encryption_method_gpg]] [-tag_all] [-no_check] [-force]

Updates an existing entity.

  • FILENAME is the name of the file that contains the entity definition to be updated. This file cannot contain any credentials.

  • CREDENTIAL_FILE is an optional parameter and is required only if you need to add entities with credentials.

    A credentials file follows this format:

    {"credentials": [
               {"id":"id1", "name":"credName1", "credType":"type1",
                                  "properties":[{"name":"prop1", "value":"CLEAR[value1]"},
                                                {"name":"prop2", "value":"FILE[/tmp/filename]"}]
              }
             ]
}
    This sample format includes:

    • A credential with an ID (id1). This credential must match the credential reference in the entity definition and must be unique.

    • A name (CredName1) that you specify to distinguish your credentials.

    • A credential type, from a predefined set of known types (for example, DBCreds for databases).

    • A property, (prop1), whose value, (value1), is specified in clear text.

    • A property, (prop2), whose value is the contents of the file /tmp/filename.

  • -encryption_method_gpg is an optional parameter. If specified, this option indicates that the file is encrypted using gpg symmetric encryption.

  • -tag_all is an optional parameter. If specified, the tags in the definition are applied to all the sub-entities as well. The default behavior is that the tags only apply to the entity.

  • -no_check is an optional parameter. If specified, the credential password is not checked before updating. The default behavior is that the credential password is checked.

  • -force is an optional parameter. If specified, all validation errors are ignored.

delete_entity

omcli delete_entity agent FILENAME

Deletes an existing entity.

FILENAME is the name of the file that contains the entity definition to be deleted.

refresh_entity

omcli refresh_entity agent FILENAME [-preserve]

Refreshes an existing entity, such as a WebLogic Domain, to ensure that Oracle Management Cloud is synchronized with the changes made to the entity. For example, if WebLogic Servers are added to or removed from the WebLogic Domain, then this command ensures that the changes reflect in Oracle Management Cloud as well.

  • FILENAME is the name of the file that contains the entity definition to be refreshed.

  • [-preserve] is an optional parameter. If specified, deleted entities are preserved and continue to exist in Oracle Management Cloud.

status_entity

omcli status_entity agent FILENAME [-long] [-verbose]

Verifies and displays the status of the entity.

  • FILENAME is the name of the file that contains the entity definition whose status must be verified. The format of this file is the same as in the file used for the add or update entity operation.

  • -long is an optional parameter. If specified, the status of the entity is extracted from Oracle Management Cloud as well.

  • -verbose is an optional parameter. If specified, detailed messages for entity operations are extracted.

add_credential_store

omcli add_credential_store agent [ wallet-file ] [ -no_password ]

Configures the agent to use a wallet-based credential store. The wallet can be pre-existing. The wallet can be found in the location identified by wallet-file; if no wallet-file is specified, then the wallet is created in $EMSTATE/sysman/config/creds/. If -no_password is specified, then an SSO wallet (protected only by file permissions) will be created and used. If the -no_password token is omitted, then you are prompted for a password to use in the wallet.

Note: To add a credential store to an agent, stop the agent, add the credential store, then restart the agent.

add_credentials

omcli add_credentials agent -credential_file CREDENTIALS_FILE [ -encryption_method_gpg ] [ -allow_entityless ]

Adds a file full of credentials to the agent. Credentials listed in CREDENTIALS_FILE are of the following form: 

{ "entity":"lama.abc.example.com:1899",     
	"name":"lama.abc.example.com:1899-HostSSHPwdCreds",     
	"type":"HostSSHPwdCreds",     
	"globalName":"AgentUserCredential",     
	"description":"SSH Credential for the agent user",     
	"properties":[ { "name":"USERNAME", "value":"<username>" },                    
							{ "name":"PASSWORD", "value":"<password>" } ] }

If -encryption_method_gpg is specified, then the credentials file is encrypted using symmetric gpg, and a passphrase may be needed. If -allow_entityless is specified, then the agent will not produce an error about credentials that are missing the entity field. However, a global name should be supplied if an entity isn’t.

list_credentials

omcli list_credentials agent [ TARGETNAME:TARGETTYPE | -global ] [ -usage USAGE ]

Lists the non-sensitive credential attributes for specified credentials.

If an entity is specified, then only the credential definitions relative to the entity are listed. If -global is specified, then only the credential definitions with global names are listed. If neither is specified, then all credentials are listed. If -usage is specified, then only the credentials that may be used for that usage are listed. When supplied, USAGE can have one of the following values:

  • ORCHESTRATION

  • MONITORING

  • INTERNAL

disable_credential

omcli disable_credential agent CREDENTIAL_NAME [ TARGETNAME:TARGETTYPE | -global ]

Disables the specified credential.

If -global is provided, then only the credentials with the CREDENTIAL_NAME global name are disabled. If CREDENTIAL_NAME TARGETNAME:TARGETTYPE is specified, then only the credentials with the CREDENTIALS_NAME local name are disabled within the entity's scope.

enable_credential

omcli enable_credential agent CREDENTIAL_NAME [ TARGETNAME:TARGETTYPE | -global ]

Enables the specified credential.

If -global is provided, then only the credentials with the CREDENTIAL_NAME global name are enabled. If CREDENTIAL_NAME TARGETNAME:TARGETTYPE is specified, then only the credentials with the CREDENTIAL_NAME local name are enabled within the entity's scope.

remove_credential

omcli remove_credential agent CREDENTIAL_NAME [ TARGETNAME:TARGETTYPE | -global ]

Removes the specified credential.

If -global is provided, then only the credential with the CREDENTIAL_NAME global name is removed.

If CREDENTIAL_NAME TARGETNAME:TARGETTYPE is specified, then the credential with name CREDENTIAL_NAME on the specified TARGETNAME (entity name) is removed.

set_credential_alias

omcli set_credential_alias agent ALIAS_NAME TARGETNAME:TARGETTYPE CREDENTIAL_NAME [ TARGETNAME:TARGETTYPE | -global ]

Sets the credential alias ALIAS_NAME to refer to credential CREDENTIAL_NAME within the entity.

If -global is provided, then the ALIAS_NAME credential alias will be created referring to the credential with global name CREDENTIAL_NAME.

remove_credential_alias

omcli remove_credential_alias agent ALIAS_NAME TARGETNAME:TARGETTYPE

Removes the specified credential alias within the scope of the entity.

generate_support_bundle

omcli generate_support_bundle agent DIRECTORY

Generates a specific set of logs and configuration information that can be used to diagnose problems with the agent.

DIRECTORY specifies the directory in which the archive bundle will be generated.

secure

omcli secure agent

Secures communication for the agent.

secure add_trust_cert_to_jks

omcli secure add_trust_cert_to_jks [-password <password> -trust_certs_loc <loc> -alias <alias>]

Allows to add/import additional certificates to the agent's monitoring truststore for secure communication between the agent and its monitored entities.

The location of the agent's monitoring truststore is: <AGENT_BASE_DIR>/agent_inst/sysman/config/montrust/AgentTrust.jks

  • If -password is specified, <password> is the password to AgentTrust.jks agent truststore.
  • If -trust_certs_loc is specified, <loc> is the location of the trust certificate file to import into the agent truststore.
  • If -alias is specified, <alias> is the alias for the certificate to import.