Install Management Agents

Follow these instructions to install management agents.

Download the Agent Software

Perform the following steps to download the agent software:

  1. On the Management Agents home page, click the Downloads and Keys from the left menu to view the Agent Software Download pane.

    The Agent Software Download pane is displayed at the top of the page.

  2. On the Agent Software Download pane, select the operating system that the Management Agent will be installed on from the Download column.

  3. Click the link specific to your operating system to download the agent software file.

    For example, click on Agent for LINUX for Linux.

Downloads and Keys page that shows the Agent Software Download at the top with a link to download the agent software file.

The agent software file is now saved on your host.

To verify the file integrity, check if the value of the SHA-256 Checksum column matches the output of the following command: sha256sum <download_file.rpm>

Download the Agent Software Using a URL

You can also download the agent software using a URL. This alternative download method is useful if you want to avoid using the Management Agent user interface to download the agent software file.

Click one of the following platform-specific links of your choice:

Create an Agent Install Key

You need to create an agent install key before performing the Management Agent installation.

An agent install key is issued against your identity domain and validates the authenticity of the installation. Ensure you have it created before starting the Management Agent installation process.

To create a key:

  1. On the Management Agents home page, click Download and Keys from the left menu to view the Agent Install Keys pane.

    The Agent Install Keys pane is displayed at the bottom of the page.

  2. On the Agent Install Keys pane, click Create Key to create a key.

    Downloads and Keys page that shows the Agent Install Keys at the bottom with the Create Key button.

  3. Enter the required details in the Create Key window.

    1. In the Key Name field, specify a name to identify the key.

    2. In the Compartment field, select the compartment from the drop-down list. This is the compartment where the agent resource will be created.

    3. In the Maximum Installs field, specify a number that indicates the maximum number of installs that can be associated with the key. Default value is 1000.

    4. In the Valid for field, specify a number that indicates the period the key is valid for. Default value is 1 Week.

    5. Click Create.

    Create Key dialog box.

    A new key is created.

The Agent Install Keys pane offers different options available to manage the keys. During a later step, the Download Key to File option is useful to download a file that can be used as a response file template as described in Configure a Response File .

For more information about managing the agent install keys, see Manage Agent Install Keys.

Configure a Response File

The Management Agent installation script uses a response file to read the agent parameters specific to your environment.

Review Agents Parameters

A response file containing the agent parameters is required when executing the agent setup script.

The following section describes the parameters supported in the response file:

Table 3-1 Response File Parameters

Parameter Name Parameter Type Description
ManagementAgentInstallKey Mandatory Agent install key required to validate the identity of the domain and the authenticity of the installation.
CredentialWalletPassword Mandatory Password of the agent wallet when the user provides a custom password for the wallet to store sensitive information. Password minimum length is 8 characters and must contain alphabetic characters combined with numbers or special characters.
ProxyHost Optional Proxy server host name or address. If provided, ProxyPort also must be provided.
ProxyPort Optional Proxy server port number. If provided, ProxyHost also must be provided.
ProxyUser Optional User name if the proxy server requires authentication. If provided, ProxyPassword also must be provided.
ProxyPassword Optional User name password if the proxy server requires authentication. If provided, ProxyUser also must be provided.
ProxyRealm Optional The authentication realm for proxy server.
AgentDisplayName Optional The display name for your agent. If it's left empty, the default value will be set as "Agent (host-name)".
Service.plugin.<plugin_name>.download=true Optional The name of the plug-in that you want to deploy during the agent installation. <plugin_name> is a plug-in supported by Management Agents service.

For example, if you want to deploy DataSafe plug-in during the agent installation, it will be: Service.plugin.datasafe.download=true

FreeFormTags = [{"<key1>":"<value1>"}, {"<key2>":"<value2>"}] Optional The tag metadata association if using tags in OCI.

It consists of a key and a value. Key is any name you use to refer to the tag. Value is the value that the user applying the tag adds to the tag key.

DefinedTags = [{"namespace1":{"<key1>":"<value1>"}}, {"namespace2":{"<key2>":"<value2>"}}] Optional The tag metadata association if using tags in OCI. The tag administrator creates and manages all the tags that the users apply to resources. The users should have defined tag policies.

Tag namespace is a container for your tag keys. The tag key is a key within your namespace, you must create tag keys for defined tags in a namespace.

For defined tags, the tag value has a type which it can be either a string or a list of strings. While defining the tag value type, if the type defined was a string then any value can be entered. Whereas, if it was a list of strings, this value has to be one of the strings from that list.

Create a Response File

Before proceeding, ensure you have reviewed and understood the information provided in Review Agents Parameters.

To install and configure agents, you need to create a response file and execute a script using the response file created which will point the agent to the correct OCI region and allow a resource to be created for the agent.

To create a response file, use one of the following options:

Option 1: Download a response file template to create a response file

You can download a template file containing the agent parameters which can be saved and used as a response file during the agent installation.

To download a response file template, use the Download Key to File menu option from the Agent Install Keys list.
  • Click Download and Keys from the left menu to open the Agent Install Keys pane. From the list of agent install keys, select the key that you want to download.

  • On the right side of the selected key, click the action menu Action Menu and select Download Key to File.

    A file is downloaded. For more information, see Download Agent Install Key.

When downloading the agent install key to a file, the downloaded file contains the agent parameters, including the value of the specific agent install key.

After downloading the file, you need to customize it according to your environment: edit the mandatory agent parameters using a text editor, and comment out or remove the parameters that aren't required for your agent configuration. Finally, save it as input.rsp response file.

Option 2: Create a response file using a text editor

You can create a response file manually using a text editor. For example, you can create a file using your preferred text editor, add the agent parameters required for your agent configuration to the file and save it as input.rsp response file.

Sample of input.rsp response file:
managementAgentInstallKey = MS4wLHVzLWFzaGJ1cm4tMSxvY2lkMS50ZW5hbmN5
CredentialWalletPassword = abcdefgh1#

After creating the response file using any of the above options, check the file permissions and ensure it has read permissions for all users.

Install Management Agent

You must install the management agent to collect data from sources that you want to manage and monitor from Oracle Cloud Infrastructure.

Install Management Agent on Linux

To install the management agent software on Linux, perform the following steps:
  1. Login as a user with sudo privileges.

  2. Install the management agent software.

    Navigate to the directory where you have downloaded the management agent software RPM file and run the following command to install the RPM file:
    sudo rpm -ivh <rpm_file_name.rpm>
    The output will look similar to the following:
    $sudo rpm -ivh oracle.mgmt_agent-<VERSION>.rpm
    Preparing... ################################# [100%]
    Checking pre-requisites
    
          Checking if any previous agent service exists
          Checking if OS has systemd or initd
          Checking available disk space for agent install
          Checking if /opt/oracle/mgmt_agent directory exists
          Checking if 'mgmt_agent' user exists
          'mgmt_agent' user already exists, the agent will proceed installation without creating a new one.
          Checking Java version
          JAVA_HOME is not set. Trying default path
          Java version: 1.8.0_231 found at /usr/bin/java
    
    Updating / installing...
          1:oracle.mgmt_agent-<VERSION>202################################# [100%]
    Executing install
          Unpacking software zip
          Copying files to destination dir (/opt/oracle/mgmt_agent)
          Initializing software from template
          Creating 'mgmt_agent' daemon
          Agent Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer-log-0
          Setup agent using input response file (run as any user with 'sudo' privileges)
          Usage:sudo
          /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=[RESPONSE_FILE]
    Agent install successful
    
    The agent installation process does the following:
    • A new user called mgmt_agent is created. This will be the management agent user. If mgmt_agent user already exists, the agent installation process will use it to install the agent software.
    • When mgmt_agent daemon is created, the hard and soft nofile ulimit are set to 5000.
    • All agent files are copied and installed by mgmt_agent user. The agent install base directory is the directory where the agent is installed. The directory is created as part of the agent installation process under /opt/oracle/mgmt_agent directory.
    Log files from the agent installation are located under /opt/oracle/mgmt_agent/installer-logs directory. To view the log files or any other agent installation files, login as mgmt_agent user running the following:
    sudo -u mgmt_agent sh
  3. Configure the management agent by running the setup.sh script using a response file.
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=<full_path_of_response_file>
    The output will look similar to the following:
    sudo /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=<user_home_directory>/input.rsp
    Executing configure
          Generating communication wallet
          Parsing input response file
          Validating install key
          Generating security artifacts
          Registering management agent
          Configuration Logs: /opt/oracle/mgmt_agent/configure-logs
    
    Agent configuration successful
    
    Starting agent...
    Agent started successfully
    In future agent can be started by directly running: sudo systemctl start mgmt_agent
    Please make sure that you delete input.rsp or store it in a secure location.

For more information about creating response files, see Create a Response File.

Install Management Agent on Windows

To install the management agent software on Windows, perform the following steps:
  1. Extract the management agent software.

    Navigate to the directory where you have downloaded the management agent software ZIP file and unzip it to any preferred location.

  2. Login as an Administrator user and open a Command Prompt window.

  3. Install and configure the management agent by running the install.bat script using a response file.
    installer.bat <full_path_of_response_file>
    The output will look similar to the following:
    C:\Users\test_agent>installer.bat C:\Users\input.rsp
    Checking pre-requisites
    
            Checking if previous agent service exists
            Checking if C:\Oracle\mgmt_agent\agent_inst directory exists
            Checking if C:\Oracle\mgmt_agent\200820.0751 directory exists
            Checking available disk space for agent install
            Checking Java version
                    Java version: 1.8.0_261 found at C:\Program Files\Java\jdk1.8.0_261
     
    Executing install
            Unpacking software zip
            Copying files to destination dir (C:\Oracle\mgmt_agent)
            Initializing software from template
            Creating mgmt_agent service 
    
    Agent install successful 
    
    Executing configure
    
            Parsing input response file
            Generating communication wallet
            Validating install key
            Generating security artifacts
            Registering Management Agent
    
    The mgmt_agent service is starting....
    The mgmt_agent service was started successfully.
    
    
    Agent setup completed and the agent is running
    In the future agent can be started by directly running: NET START mgmt_agent
    Please make sure that you delete C:\Users\input.rsp or store it in secure location.
    

For more information about creating response files, see Create a Response File.

The agent installation process does the following:
  • A new directory is created as part of the agent installation process: C:\Oracle\mgmt_agent.
  • The agent install base directory is the directory where the agent will be installed. By default, the agent is installed under C:\Oracle directory. This default directory can be changed by setting the AGENT_INSTALL_BASEDIR environment variable before running the install.bat script.
  • Log files from the agent installation are located under C:\Oracle\mgmt_agent\installer-logs directory.

Verify the Management Agent Installation

Verify the Agent Installation Using User Interface

To verify the agent installation using the user interface, perform the following steps:

  1. On the main Management Agents page, click Agents from the left menu.

    The Agents page is displayed with a list of all agents installed.

    Agents list page that shows all the management agents installed.

  2. From the Agents list, look for the agent that was recently installed using the Created column which displays the date of the agent installation or the Host column which displays the host name where the agent was installed.

Verify the Agent Installation Using Command Line Interface on Linux

  1. Login to the host using a user with sudo privileges.

  2. Run the following command:

    For Oracle Linux 6: sudo /sbin/initctl status mgmt_agent

    For Oracle Linux 7: sudo systemctl status mgmt_agent

    For more details, check log file: /opt/oracle/mgmt_agent/agent_inst/log/mgmt_agent.log.

Verify the Agent Installation Using Command Line Interface on Windows

  1. Login to the host using an Administrator’s command shell.

  2. Run the following command:
    sc query mgmt_agent

    For more details, check the log file: C:\Oracle\mgmt_agent\agent_inst\log\mgmt_agent.log.

Troubleshoot Management Agent Installation Issues

Users may encounter various errors during Oracle Management Agent installation process. Causes and recommended actions for such errors are listed below.

Please uninstall the agent and remove the service file before installing the new agent!

Cause: There's an agent already installed on your host. A previous deinstall process did not remove the agent service file successfully.

Action:
  • Run rpm -e oracle.mgmt_agent to uninstall the agent. If command succeeds, try installing the new agent. If command doesn't work, try the next recommended action.
  • Execute ls /opt/oracle/mgmt_agent to check if you have residuals of the previous agent installation. If you find it, delete it by running: rm -rf /opt/oracle/mgmt_agent.
  • Check if you already have agent service file at the following location depending on your Linux version:
    • For OL7 (if you are using systemd): /etc/systemd/system/mgmt_agent.service
    • For OL6 (if you are using init): /etc/init/mgmt_agent.conf.

      If you find that you have this service file, remove it by running: rm -rf /etc/init/mgmt_agent.conf and then retry installing the new agent.

Java is not a 64-bit JVM! Please set path of a 64-bit JVM in the environment variable JAVA_HOME or Java not found please set your preferred path in JAVA_HOME.

Cause: The JAVA_HOME environment variable is not set or it's not pointing to a 64 bit JDK location.

Action: Set JAVA_HOME environment variable to the right JDK version and retry installing the agent. Currently, only 64 bit JDK is supported.

Agent installation failed, please check log file.

Cause: The installation script cannot add a user and group during the management agent installation process because the available group ids on your Linux system are already in used.

Executing install
    Unpacking software zip
    Copying files to destination dir (/opt/oracle/mgmt_agent) 
useradd: Can't get unique GID (no more available GIDs) 
useradd: can't create group 
Agent installation failed, please check log file

Action: Consult with the system administrator before proceeding with the following:

  1. Edit the /etc/login.defs file. You require sudo privileges to edit the file.

    Look for the following entries:
    SYS_GID_MIN               nnnn
    SYS_GID_MAX               mmmm
    SYS_UID_MIN               pppp
    SYS_UID_MAX               qqqq
    Where nnnn and pppp are the minimum value and mmmm and qqqq are the maximum value.

    If the above entries don't exist in the file, add them.

  2. Update the value of SYS_GID_MAX entry based on the system administrator's recommendation, and save the file.

  3. Remove the failed agent installation by running: sudo rpm -e oracle.mgmt_agent.

  4. Retry the agent installation.