Using Response Files for Installing Oracle Management Cloud Agents

To reduce the complexity and increase the accuracy of Oracle Management Cloud Agent installation, especially for installation of multiple agents, you use a response file. At the time of installation, the AgentInstall.sh script reads the inputs from the response file and performs the installation.

About Response Files

When you download and extract the agent ZIP file, depending on the type of agent, you get a sample response file (.rsp file) along with the installation script. It’s recommended that you create a copy of the original response file, and then edit the copy for specifying the values of the installation parameters. If you perform a cloud agent or data collector download, a response file named agent.rsp is downloaded. If you perform a gateway download, a response file named gateway.rsp is downloaded.

Following are some facts about a response file:

  • The response file should always be a plain text (UTF-8) character set file, so that the AgentInstall.sh script can parse it.

  • A response file is not platform-specific or release-specific. You can create or update the response file and keep using it for any platform and for any future installations unless a new parameter is added to the file.

  • You can save the response file in the same location where you’ve saved your AgentInstall.sh script, or you can save the response file in a shared or mounted location, which can be accessible from multiple hosts. This way you can have the response file in a single location and use the same response file for agent installation on multiple hosts. See Notes in Installing Agents Using a Shared Software Bundle for more information.

  • The response file lists all the supported parameters (mandatory and optional).

  • All the parameters listed in the response file are the only parameters that the agent installation process supports.

  • If your environment details remain the same, you can use the same parameter values without editing the response file again.

  • The cloud agent and data collector are installed using the same ZIP file. If the response file has data collector parameter values specified, the installer starts the data collector installation; otherwise the installer starts the cloud agent installation.

Note:

Because the passwords that you specify in the response file are in plain text, you need to adequately protect the response file or delete the it as soon as the installation process completes.

Parameters for Installing a Cloud Agent

This section describes the parameters that are required for installing a cloud agent.

You must edit the response file (agent.rsp) and provide values for the parameters that are required to install a cloud agent.

To install a cloud agent, see Installing a Cloud Agent.

The following are list of parameters that are specified in the response file:

Registration Parameters

This section lists the registration parameters that are required to install a cloud agent. Ensure that your response file has the correct values for the following parameters.

Parameter Description Notes

TENANT_NAME

or

TENANT_ID (supported in older versions and it remains backwards compatible)

Name of the tenant where Oracle Management Cloud is running. You can get the TENANT_NAME value for an agent by navigating to Administration > Agents > Download, and selecting an agent type from the Agent Type drop-down list. The TENANT_NAME value is displayed at the bottom of the page.

Example: inst1–dummytenantid

AGENT_REGISTRATION_KEY

Key to validate the identity of the tenant and the authenticity of the installation. You can get the registration key from Oracle Management Cloud Dashboard, by navigating to Administration > Agents > Registration Keys.

Example: R5bokWss0EC9R1pJlf2SqiAJ9p

AGENT_BASE_DIRECTORY

Empty directory where the agent must be installed on the host machine. If the given directory is not present, then a directory is created during installation.

Note: For Windows, the length of the directory path including the drive letter should be less than 24 characters.

Example:

Linux: /omc_agent/dc

Windows: D:\omc_agent\dc

Communication Parameters

This section lists the communication parameters that are required to install a cloud agent.

Parameter Description Notes

OMC_URL

or

UPLOAD_ROOT (supported in older versions and it remains backwards compatible)

The absolute URL including the protocol that is required to connect to Oracle Management Cloud for uploading data for the specific TENANT_NAME. To get this value, navigate to Administration > Agents > Download, and select an agent type from the Agent Type drop-down list. The OMC_URL value is displayed at the bottom of the page.

Example: https:/dummytenantid.itom.<datacenter>.oraclecloud.com

GATEWAY_HOST

If cloud agent or data collector is communicating to OMC using the gateway, then provide the Fully Qualified Domain Name (FQDN) of the gateway. When you install the cloud agent, make sure you provide the same gateway host name that was used to install the gateway.

For example, when deploying the gateway, if you specify ORACLE_HOSTANME=abc.xyz.com and when installing the cloud agent, you specify GATEWAY_HOST=abc, it will result in cloud agent registration failures. A gateway agent must be installed on the host and should be up and running.

Example: GATEWAY_HOST=testgateway.test.oracle.com

GATEWAY_PORT

If cloud agent or data collector is communicating to OMC using a gateway, the gateway port must be specified.

You can obtain the port number by executing the following command:

$Gateway_Agent_Home/agent_inst/bin/omcli status agent

Example: GATEWAY_PORT=4472

ADDITIONAL_GATEWAYS

For gateway high availability, additional gateway hosts (comma separated list of gateway URLs) can be specified. You can obtain the URL by running the following command on respective gateway hosts:

$Gateway_Agent_Home/agent_inst/bin/omcli status agent

Note: This parameter should only be used while deploying a cloud agent or a data collector.

Example: ADDITIONAL_GATEWAYS=https://abc.us.com:1872,https://xyz.us.com:4475

Proxy Parameters (Optional)

If you’re installing the cloud agent over a proxy server, then apart from specifying the Registration Parameters and Communication Parameters, ensure that you specify the correct values for the following parameters in your response file.

Parameter Description Notes

OMC_PROXYHOST

Address of your proxy server to be used for connection. Ensure that you don't pass the https:// value with the proxy host details

Required only if you’re deploying the agent over a proxy server

Example: www-proxy.company.com

OMC_PROXYPORT

Port of your proxy server

Required only if you’re deploying the agent over a proxy server

Example: 80

OMC_PROXYUSER

User name required to access your proxy server

Required only if you are using a proxy server to communicate with Oracle Management Cloud. It requires a username and password.

Example: johndoe

OMC_PROXYPWD

Password required to access your proxy server

Required only if you’re deploying the agent over a proxy server

OMC_PROXYREALM

Authentication realm (if any) to be used to access your proxy server

Required only if you’re deploying the agent over a proxy server

Example: MyServer

Other Optional Parameters

This section lists the parameters that you can optionally specify in your response file for installing a cloud agent. However, you need to ensure that your response file contains values for the Registration Parameters and Communication Parameters.

Parameter Description Notes

AGENT_PORT

The port number to which the agent process will be bound. The AgentInstall script stops the installation process if this port is occupied at the time of installation.

If you don’t specify any value, the default port (4459) or an available port in the range 4460-4479 is used.

This applies to new installations only. If you have older agents already running on other port numbers, you can continue to run them as such.

Example: 4461

ORACLE_HOSTNAME

The host name where the agent will be installed. If specified, the value is validated to check if it resembles the agent host name and that it is neither an IP address nor a junk value (such as foobar, test, and so on). It must match the fully qualified domain name (FQDN) specified in the /etc/hosts (in UNIX) and C:\Windows\System32\drivers\etc\hosts (in Windows) file and must map to the correct FQDN and IP address of the host.

Note: Use this parameter when you want to provide a network-resolvable hostname instead of installer-computed hostname.

Note: Ensure the parameter is a fully qualified domain name as most of the services in Oracle Management Cloud require the host to be an FQDN. It must resolve to a valid IP address.

Example: example.tst.acme.com

If you don’t specify any value, the AgentInstall script evaluates the host name using the INetAddress Java class methods.

IGNORE_VALIDATIONS

A flag to disable all validations and prerequisite checks.

  • Example: true

  • Valid values: true or false

  • Default value: false

    To ignore validations, change the value to true, IGNORE_VALIDATIONS=true.

IGNORE_ULIMIT_CHECK

A flag to disable ulimit checks (only on non-windows platforms).

  • Example: true

  • Valid values: true or false

  • Default value: false

    To ignore ulimit checks, change the value to true, IGNORE_ULIMIT_CHECK=true.

DISPLAY_NAME

A display name for the tenant management agent as given by the user.

The default value is <agent host>: <agent port>. For example, host:4459.

AGENT_HOST_DISPLAY_NAME

A display name for the tenant management agent host as given by the user.

The default value is <agent host>: <agent port>. For example, host:4459.

Parameters for Installing Data Collector

This section describes the parameters that are required for installing a data collector.

To install a data collector, see Installing a Data Collector.

To install a data collector, edit the response file (agent.rsp) and specify values for the agent (see, Parameters for Installing a Cloud Agent).

In addition to the cloud agent parameters, you must also specify the data collector specific values that are listed in the following sections.

Data Collector Parameters

The following are data collector specific parameters that are required to install a data collector.

Parameter Description Notes

DATA_COLLECTOR_USERNAME

User that’s created for the data collector in the Oracle Management Repository and is used to collect Oracle Enterprise Manager Cloud Control data. The user name must be a minimum of 5 characters and a maximum of 26 characters in length and must start with a string (a-z or A-Z).

Example: testdcjlr

DATA_COLLECTOR_USER_PASSWORD

Password to be set for DATA_COLLECTOR_USERNAME (must be 5-8 alphanumeric characters and must start with a letter). The password rules of the data collector are the same as that of the Oracle Management Repository database password rules, because the data collector creates a schema in the Oracle Management Repository database. However, data collector passwords can’t have a special character or numeric as the first character.

Example: jDC5878

OMR_USERNAME

Privileged database user name to sign in to the Oracle Management Repository; must have the SYS role. The user should have access to create DATA_COLLECTOR_USERNAME user in the OMR to collect data from it.

Example: sys

OMR_USER_PASSWORD

Password used to sign in to the Oracle Management Repository in your data center.

Example: password_4u

OMR_HOST_USERNAME

User name (of the install user of Oracle Management Repository) for the host where Oracle Management Repository is running in your data center.

Example: johndoe

OMR_STAGE_DIR

Directory where the data collector stores the harvested data in an archived form. OMR_STAGE_DIR should be present in OMR_HOSTNAME and the user deploying the data collector must have read or write permissions to OMR_STAGE_DIR. This directory must have at least 2048 MB free space available. The directory name can be up to 4000 characters.

Example: /stage/test

OMR_HOST_USER_PASSWORD

Password for the host where the Oracle Management Repository is running in your data center.

Example: AUPA0fgQ1

Leave this parameter blank if OMR_HOST_USER_SSH_KEY is provided.

OMR_HOST_USER_SSH_KEY

Path to the private SSH key to be used to connect to your Oracle Management Repository.

Example: $HOME/.ssh/id_rsa

Leave this parameter blank if OMR_HOST_USER_PASSWORD is provided.

OMR_CONNECT_STRING

Connection string to be used to connect to Oracle Management Repository.

The OMR_CONNECT_STRING, or a combination of OMR_HOSTNAME, OMR_PORT, and either OMR_SID or OMR_SERVICE_NAME is required to connect to the Oracle Management Repository.

Example: mytestconnectstring

Leave this parameter blank if a combination of OMR_HOSTNAME, OMR_PORT, and either OMR_SID or OMR_SERVICE_NAME is provided.

OMR_HOSTNAME

Fully qualified name of the host where the Oracle Management Repository is running.

Example: example.test.acme.com

Leave this parameter blank if OMR_CONNECT_STRING is provided.

OMR_PORT

Listen port of the Oracle Management Repository in your data center.

Example: 1845

Leave this parameter blank if OMR_CONNECT_STRING is provided.

OMR_SID

SID of the Oracle Management Repository (mutually exclusive with OMR_SERVICE_NAME).

Example: orcl

Leave this parameter blank if OMR_CONNECT_STRING or OMR_SERVICE_NAME is provided.

OMR_SERVICE_NAME

Service name of the Oracle Management Repository (mutually exclusive with OMR_SID).

Example: orcl.acme.com

Leave this parameter blank if OMR_CONNECT_STRING or OMR_SID is provided.

Optional Data Collector Parameters

The following are optional parameters required to install a data collector.

Parameter Description Notes

OMR_USER_ROLE

User role to connect to the Oracle Management Repository, such as sysdba.

Example: sysdba

OMR_HOST_SSH_PORT

Optional

SSH port (default=22) on which the Oracle Management Repository is configured to listen.

Example: 22

NAMESPACE

Namespace (default host:port) used to identify the data collector.

Example: dcagent.test.acme.com:1845

IGNORE_DATA_COLLECTOR_VALIDATIONS

 Flag to disable all data collector validations.

Valid values: true or false

Parameters for Installing a Gateway

This section describes the parameters that are required for installing a gateway.

You must edit the response file (gateway.rsp) and provide values for the parameters that are required to install a gateway.

To install a gateway, see Installing a Gateway.

The following are list of parameters specified in the response file:

Registration Parameters

This section lists all the registration parameters that are required to install a gateway. Ensure that your response file has the correct values for the these parameters.

The following table lists the Registration Parameters required for gateway installation.

Parameter Description Notes

TENANT_NAME

or

TENANT_ID (supported in older releases)

Name of the tenant where Oracle Management Cloud is running. You can get the TENANT_NAME value for an agent by navigating to Administration > Agents > Download, and selecting an agent type from the Agent Type drop-down list. The TENANT_NAME value is displayed at the bottom of the page.

The TENANT_NAME must be in the format: <instance_name>-<identity_domain>

Example: inst1–dummytenantid

AGENT_REGISTRATION_KEY

Key to validate the identity of the tenant and the authenticity of the installation. You can get the registration key from Oracle Management Cloud Dashboard, by navigating to Administration > Agents > Registration Keys.

Example: R5bokWss0EC9R1pJlf2SqiAJ9p

AGENT_BASE_DIRECTORY

Empty directory where the agent must be installed on the host machine. If the given directory is not present, then a directory is created during installation.

Note: For Windows, the length of the directory path including the drive letter should be less than 24 characters.

Example:

Linux: /omc_agent/dc

Windows: D:\omc_agent\dc

Communication Parameters

The following table lists the Communication Parameters required for gateway installation.

Parameter Description Notes

OMC_URL

or

UPLOAD_ROOT (supported in older releases)

The absolute URL including the protocol that is required to connect to Oracle Management Cloud for uploading data for the specific TENANT_NAME. To get this value, navigate to Administration > Agents > Download, and select an agent type from the Agent Type drop-down list. The OMC_URL value is displayed at the bottom of the page.

Example: https:/dummytenantid.itom.<datacenter>.oraclecloud.com

Proxy Parameters (Optional)

If you’re installing a gateway over a proxy server, then apart from specifying the Registration Parameters and Communication Parameters, ensure that you specify the correct values for the following parameters in your response file.

Parameter Description Notes

OMC_PROXYHOST

Address of your proxy server to be used for connection. Ensure that you don't pass the https:// value with the proxy host details

Required only if you’re deploying the agent over a proxy server

Example: www-proxy.company.com

OMC_PROXYPORT

Port of your proxy server

Required only if you’re deploying the agent over a proxy server

Example: 80

OMC_PROXYUSER

User name required to access your proxy server

Required only if you are using a proxy server to communicate with Oracle Management Cloud. It requires a username and password.

Example: johndoe

OMC_PROXYPWD

Password required to access your proxy server

Required only if you’re deploying the agent over a proxy server

OMC_PROXYREALM

Authentication realm (if any) to be used to access your proxy server

Required only if you’re deploying the agent over a proxy server

Example: MyServer

Other Optional Parameters

This section lists the parameters that you can optionally specify in your response file for installing a gateway. However, you need to ensure that your response file contains values for the Registration Parameters and Communication Parameters.

Parameter Description Notes

AGENT_PORT

The port number to which the agent process will be bound. The AgentInstall script stops the installation process if this port is occupied at the time of installation.

If you don’t specify any value, the default port (4459) or an available port in the range 4460-4479 is used.

This applies to new installations only. If you have older agents already running on other port numbers, you can continue to run them as such.

Example: 4461

ORACLE_HOSTNAME

The host name where the agent will be installed. If specified, the value is validated to check if it resembles the agent host name and that it is neither an IP address nor a junk value (such as foobar, test, and so on). It must match the fully qualified domain name (FQDN) specified in the /etc/hosts (in UNIX) and C:\Windows\System32\drivers\etc\hosts (in Windows) file and must map to the correct FQDN and IP address of the host.

Note: Use this parameter when you want to provide a network-resolvable hostname instead of installer-computed hostname.

Note: Ensure the parameter is a fully qualified domain name as most of the services in Oracle Management Cloud require the host to be an FQDN. It must resolve to a valid IP address.

Example: example.tst.acme.com

If you don’t specify any value, the AgentInstall script evaluates the host name using the INetAddress Java class methods.

IGNORE_VALIDATIONS

A flag to disable all validations and prerequisite checks.

  • Example: true

  • Valid values: true or false

  • Default value: false

    To ignore validations, change the value to true, IGNORE_VALIDATIONS=true.

IGNORE_ULIMIT_CHECK

A flag to disable ulimit checks (only on non-windows platforms).

  • Example: true

  • Valid values: true or false

  • Default value: false

    To ignore ulimit checks, change the value to true, IGNORE_ULIMIT_CHECK=true.

DISPLAY_NAME

A display name for the tenant management agent as given by the user.

The default value is <agent host>: <agent port>. For example, host:4459.

AGENT_HOST_DISPLAY_NAME

A display name for the tenant management agent host as given by the user.

The default value is <agent host>: <agent port>. For example, host:4459.