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 script reads the inputs from the response file and completes the installation.

About Response Files

When you download and extract the agent binary ZIP file, you get a sample response file (.rsp file) along with the installation script. It’s recommended that you create a copy of the original, and then edit the copy for specifying the values of the installation parameters.

Following are some facts about a response file:

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

  • A response file is a single file that you can use for installing all types of agents. However, you have to provide different values for different agent-specific parameters.

  • 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 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.

    If the response file and the AgentInstall script are not co-located, then you must pass the AGENT_RSP_FILE=<absolute path to the agent.rsp file> parameter in the command line when you run the Agentinstall script.

    If the AGENT_RSP_FILE parameter is not passed in the command line, then during agent installation, the default response file is picked up from the location where you’ve extracted your agent binary ZIP file.

  • It lists all the supported parameters (mandatory and optional) for all agent types.

  • All the parameters listed in the response file are the only parameters that the agent installation process supports. If you try to pass any other user-defined parameters, then the installation fails.

  • You must fill the file only once for all agents if your environment details remain the same.

  • During installation, only those parameters specific to an agent type can be present in the response file or as command line parameters. If GATEWAY_HOST, which is not a valid parameter for gateway install is present in the response file at the time of installing a gateway, the installation will fail.

    The installer script determines the agent type based on the binaries you use and picks up the relevant agent parameter values from the response file. For example, if you use the gateway binaries, then the script picks up the gateway parameter values from the response file and completes the installation.

  • If you’re using a cloud agent or a data collector binary (which is basically the same binary) and 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.

  • During the installation, you can specify a combination of command line parameters and the response file for passing parameters to the AgentInstall script. So, you can pass the value of AGENT_BASE_DIRECTORY in the command line along with the rest of the parameters in the response file.

    You can:

    • Specify parameters only through the response file.

    • Specify parameters only through the command line.

    • Specify parameters both through the command line and the response file.

      In this case, the parameter value specified in the command line gets priority over the same value specified in the response file.

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 Specified in a Response File

A response file contains multiple sections for specifying different agent installation parameters.

You must edit the response file by specifying relevant values pertaining to an agent type.

Mandatory Common Parameters for Installing Any Agent

This section lists all the mandatory parameters that are common to any agent installation. Ensure that your response file has the correct values for the following parameters for any type of agent installation.

Parameter Description Notes

TENANT_ID

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

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

Example: inst1–dummytenantid

UPLOAD_ROOT

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

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

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

Optional Common Parameters for Installing Any Agent

This section lists the parameters that you can optionally specify in your response file for any agent installation. However, you need to ensure that your response file contains for values for the common mandatory parameters.

Parameter Description Notes

AGENT_RSP_FILE

The absolute path of the response file including the file name. You must specify this parameter in the command line when running the AgentInstall script if you have saved your response file at a location other than the location where you’ve extracted your agent binary Zip file.

Pass this parameter in the command line along with the Agentinstall.sh script, and not inside response file. If you specify this parameter inside the response file and don't pass this parameter in the command line, then Agentinstall.sh uses the response file from the location where you’ve extracted your agent binary ZIP file and ignores this parameter inside the response file.

Example: /net/abc.us.com/shared/omc/agent.rsp

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_DATA_COLLECTOR_VALIDATIONS

A flag to disable all data collector validations.

  • Example: true

  • Valid values: true or false

  • Default value: false

    To ignore data collector validations, change the value to true, IGNORE_DATA_COLLECTOR_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.

AGENT_IMAGE_LOCATION

Directory of the unzipped agent software bundle on the shared drive.

The directory should have read permission for the agent installation user and should be accessible from the host where the agent is being installed.

EXTRACTION_LOCATION

Directory on the host where the agent is being installed, used for initial unzip of the software bits.

The directory should have write and execute permissions for the agent installation user.

Parameters for Installing Any Agent Over a Proxy Server

If you’re installing an agent over a proxy server, then apart from specifying the common mandatory parameters, ensure that you specify the correct values for the following parameters in your response file for any type of agent installation.

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

Mandatory Parameters Specific to Installing a Data Collector

When you’re installing a data collector, then apart from specifying the common mandatory parameters, ensure that you specify the correct values for the following parameters in your response file.

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.

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 write permissions to OMR_STAGE_DIR.

Example: /stage/test

Optional Parameters for Installing a Data Collector

When you’re installing a data collector, apart from specifying the common mandatory parameters and the mandatory parameters specific to installing a data collector, you must specify the correct values for the following parameters in your response file on an as-needed basis.

Parameter Description Notes

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.

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

Parameters for Installing a Data Collector or a Cloud Agent Over a Gateway

When you’re installing a data collector or a cloud agent that will communicate with Oracle Management Cloud through a gateway, apart from specifying the common mandatory parameters and the mandatory parameters specific to installing a data collector, ensure that you specify the correct values for the following gateway-related parameters in your response file.

Parameter Description Notes

GATEWAY_HOST

Fully Qualified Domain Name (FQDN) of the gateway if the data collector and/or the cloud agents is/are communicating with Oracle Management Cloud through a gateway.

When you install the data collector or the cloud agent, ensure that you provide the gateway host name that was used to install the gateway. For example, if you had specified ORACLE_HOSTNAME=abc.xyz.com when you installed a gateway, then ensure that while installing the cloud agent or data collector, you shouldn’t specify GATEWAY_HOST=abc, because this would result in agent registration failures.

Example: testgateway.test.acme.com

GATEWAY_PORT

Port of the gateway if the data collector and/or the cloud agents is/are communicating with Oracle Management Cloud through a gateway. You can get the port number by running the command on the gateway host:

<AGENT_BASE_DIRECTORY>/agent_inst/bin/omcli status agent

Example: 4459

ADDITIONAL_GATEWAYS

Additional gateways to use for communicating to Oracle Management Cloud for high availability. Specify the Gateway URLs. You can get the URLs by running the following command on the respective gateway hosts.

<AGENT_BASE_DIRECTORY>/agent_inst/bin/omcli status agent

This parameter should only be used when installing a cloud agent or a data collector.

Example: https://abc.us.com:1872, https://xyz.us.com:3782