Install Management Agents
Download the Agent Software
Perform the following steps to download the agent software:
-
On the Management Agents home page, click the Downloads and Keys from the left menu to view the Software Download pane.
The Software Download pane is displayed.
-
On the Software Download pane, select the operating system that the Management Agent will be installed on from the Download column.
-
Click the link specific to your operating system to download the agent software file.
For example, click Agent for WINDOWS (X86_64) for Windows.
The 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>
The Agent software image download URL is available only via
agent-image list
CLI command or
ListManagamentAgents
API with valid
OCI authentication. For details, see Download the Agent Software Using CLI.
Download the Agent Software Using CLI
- Obtain the
object-url
value using the agent-image list CLI command.oci management-agent agent-image list --compartment-id <tenancyId>
The return
object-url
value is similar to the following:https://objectstorage.<region_identifier>.oraclecloud.com/n/<namespace>/b/<bucketName>/o/Linux-x86_64/latest/oracle.mgmt_agent.rpm
From the above, make a note of the <namespace> and <bucketName> values.
- Download the Management Agent software with
OCI authenticated principal using the
<namespace> and
<bucketName> values from Step 1:
-
For Linux:
oci os object get --namespace <namespace> --bucket-name <bucketName> --name Linux-x86_64/latest/oracle.mgmt_agent.rpm --file oracle.mgmt_agent.rpm
-
For Windows:
oci os object get --namespace <namespace> --bucket-name <bucketName> --name Windows-x86_64/latest/oracle.mgmt_agent.zip --file oracle.mgmt_agent.zip
-
For Solaris:
oci os object get --namespace <namespace> --bucket-name <bucketName> --name Solaris-Sparc64/latest/oracle.mgmt_agent.zip --file oracle.mgmt_agent.zip
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>
-
Oracle Cloud Infrastructure (OCI) Command Line Interface (CLI) is a command line interface tool. For more information, see Command Line Interface (CLI).
To obtain the
object-url
value, you can also use the
Management Agent API ListManagementAgentImages
.
Create Install Key
You need to create an install key before performing the Management Agent installation.
An 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:
-
On the Management Agents home page, click Download and Keys from the left menu to view the Install Keys pane.
The Install Keys pane is displayed at the bottom of the page.
-
On the Install Keys pane, click Create Key to create a key.
-
Enter the required details in the Create Key window.
-
In the Key Name field, specify a name to identify the key.
-
In the Compartment field, select the compartment from the drop-down list. This is the compartment where the agent resource will be created.
-
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.
-
In the Valid for field, specify a number that indicates the period the key is valid for. Default value is 1 Week.
-
The Unlimited checkbox is optional.
If it's selected, the key can be used for an unlimited number of agent and gateway installations and the key never expires.
Risks of using unlimited keys: Oracle recommends to keep the life time of an Install Key to a minimum required time and limited number of agents. Ensure that you keep the downloaded key in a secure location to protect confidentiality. If the unlimited install key is compromised, an attacker can install rogue agents in your tenancy. A regular audit of your tenancy's agents can help to mitigate any potential risks associated with unlimited install keys. When an unlimited install key is not needed anymore, make sure to delete it either using the Management Agents Console or CLI.
A new key is created.
-
The 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 install keys, see Manage Install Keys.
If you are installing a Management Gateway, you can use the same install key to install Management Gateway and Management Agent. For information about Management Gateway, see Management Gateway.
Configure a Response File
The Management Agent installation script uses a response file to read the agent parameters specific to your environment.
Review Agent 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 | Install key required to validate the identity of the domain and the authenticity of the installation. |
CredentialWalletPassword |
Optional | Password of the agent wallet when the user provides a custom password for the
wallet to store sensitive information.
The password minimum
length is 8 characters with the following specifications:
All characters from the password must be from the
characters defined above. For example, if the password has the
|
GatewayServerHost |
Optional | Host name or address of the Management Gateway server or proxy server.
If provided, If the Management Gateway is
configured in high availability mode, you must specify the load
balancer host name as the |
GatewayServerPort |
Optional | Port number of the Management Gateway server or proxy server.
If
provided, If the Management Gateway is
configured in high availability mode, you must specify the load
balancer port number as the |
GatewayServerUser |
Optional | User name, if the Management Gateway server or proxy server requires
authentication.
If provided,
|
GatewayServerPassword |
Optional | Password, if the Management Gateway server or proxy server requires
authentication.
If provided,
|
GatewayServerRealm |
Optional | The authentication realm for the proxy server.
If using Management Gateway, this value is not needed. |
AgentDisplayName |
Optional | The display name for your agent. If it's left empty, the default value will be
set to "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
the Management Agent service.
For example, if you
want to deploy the DataSafe plug-in during the agent
installation, it will be:
|
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. |
GatewayServerRootCACertOcid |
Optional | This parameter is available starting with Agent
version 221019.0021.
When the Agent connects to a Management Gateway of version 221019.0021.1667404647 or above, the connection will be encrypted. This
parameter specifies the |
Create a Response File
Before proceeding, ensure you have reviewed and understood the information provided in Review Agent Parameters.
To install and configure agents, you need to create a response file and execute a script using the newly created response file which will point the agent to the correct OCI region and allow a resource to be created for the agent.
When creating a response file, check the file location and permissions. Ensure the response file has read permissions for
mgmt_agent
OS user.
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.
-
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
and select Download Key to File.
A file is downloaded. For more information, see Download 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.
- Open the file using a text editor, review it and edit the mandatory agent parameters. See Review Agent Parameters.
- Comment out (add the
#
symbol at the start of the line) or remove the agent parameters that you don't require for your specific agent configuration. - Uncomment (remove the
#
symbol from the start of the line) the agent parameters that you require for your specific agent configuration and update the agent parameter value if needed. - Save the updated response file. For example, it can be saved 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 response file and save it. For example, the
response file can be saved as input.rsp
.
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 mgmt_agent
user
(OS user created during the Management Agent installation process).
Install Management Agent
After downloading the agent software and creating an install key, you can proceed with the installation of the management agent to collect data from sources that you want to manage and monitor from Oracle Cloud Infrastructure.
Install Management Agent on Linux (RPM file)
-
Login as a user with
sudo
privileges. -
Install the management agent software.
Navigate to the directory where you have downloaded the management agent softwareRPM
file and run the following command to install theRPM
file:sudo rpm -ivh <rpm_file_name.rpm>
For example:
sudo rpm -ivh oracle.mgmt_agent-<VERSION>.rpm
The output will look similar to the following: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_281 found at /usr/bin/java Updating / installing... 1:oracle.mgmt_agent-<VERSION>################################# [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. Ifmgmt_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. - By default, the
mgmt_agent
service is enabled and started automatically after the agent installation.
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 asmgmt_agent
user running the following:sudo -u mgmt_agent sh
- A new user called
-
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=<response_file_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
Linux (ZIP
file)
ZIP
file,
perform the following steps:
-
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. -
Login as a user with
sudo
privileges. -
Install and set up the management agent by running the
installer.sh
script providing a response file. For information about how to create a response file, see Create a Response File.Navigate to the directory where you unzipped the management agent softwareZIP
file and run the following:sudo ./installer.sh <full_path_of_response_file>
For example:
sudo ./installer.sh /tmp/input.rsp
The output will look similar to the following:sudo ./installer.sh <user_home_directory>/input.rsp 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 Checking Java version JAVA_HOME is not set or not readable to root Trying default path /usr/bin/java Java version: 1.8.0_282 found at /usr/bin/java Checking agent version 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 Agent install successful Executing configure Parsing input response file Validating install key Generating communication wallet Generating security artifacts Registering Management Agent Starting agent... Agent started successfully Agent setup completed and the agent is running. In the future agent can be started by directly running: sudo systemctl start mgmt_agent Please make sure that you delete <user_home_directory>/input.rsp or store it in secure location.
The agent installation process does the following:- A new user called
mgmt_agent
is created. This will be the management agent user. Ifmgmt_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 installation files are owned 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. - By default, the
mgmt_agent
service is enabled and started automatically after the agent installation.
Log files from the agent installation are located under
/opt/oracle/mgmt_agent/installer-logs
directory.Log files from the running agent are located under
/opt/oracle/mgmt_agent/agent_inst/log
.To view the log files or any other agent installation files, login asmgmt_agent
user running the following:sudo -u mgmt_agent sh
- A new user called
Install Management Agent on Windows
-
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. -
Login as an Administrator user and open a Command Prompt window.
-
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:installer.bat C:\<user_home_directory>\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_281 found at C:\Program Files\Java\jdk1.8.0_281 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:\<user_home_directory>\input.rsp or store it in secure location.
For more information about creating response files, see Create a Response File.
- 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 theAGENT_INSTALL_BASEDIR
environment variable before running theinstall.bat
script. -
Log files from the agent installation are located under
C:\Oracle\mgmt_agent\installer-logs
directory.
Install Management Agent on Solaris
-
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.
-
Set
SUDO_PATH
environment variable with the path to sudo. You may usesudo -E
option to retain environment variables while running the command as sudo.Confirm
useradd
andgroupadd
are in yourPATH
environment variable. For example, if it is at location/sbin/useradd
then confirm it's in your path.Confirm
sudo
is in yourPATH
environment variable. For example, if sudo is at location/usr/bin/sudo
then confirm thePATH
environment variable has"/usr/bin"
. -
Login as a user with
sudo
privileges. -
Install and configure the management agent by running the
installer.sh
script using a response file.For information about creating response files, see Create a Response File.
Navigate to the directory where you unzipped the management agent softwareZIP
file and run the following:sudo ./installer.sh <full_path_of_response_file>
The output will look similar to the following:sudo ./installer.sh <user_home_directory>/input.rsp 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 Checking Java version JAVA_HOME is not set or not readable to root Trying default path /usr/bin/java Java version: 1.8.0_282 found at /usr/bin/java Checking agent version 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 Agent install successful Executing configure Parsing input response file Validating install key Generating communication wallet Generating security artifacts Registering Management Agent Starting agent... Agent started successfully Agent setup completed and the agent is running. In the future agent can be started by directly running: sudo systemctl start mgmt_agent Please make sure that you delete <user_home_directory>/input.rsp or store it in secure location.
The agent installation process does the following:- A new user called
mgmt_agent
is created. This will be the management agent user. Ifmgmt_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 installation files are owned 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. - By default, the
mgmt_agent
service is enabled and started automatically after the agent installation.
Log files from the agent installation are located under
/opt/oracle/mgmt_agent/installer-logs
directory.Log files from the running agent are located under
/opt/oracle/mgmt_agent/agent_inst/log
.To view the log files or any other agent installation files, login asmgmt_agent
user running the following:sudo -u mgmt_agent sh
- A new user called
Install Multiple Management Agents
Install multiple management agents feature is currently available only on Linux.
Agent Service Identifiers
Agent service identifiers are used to identify an agent service in presence of other agent instances on a given machine in order to avoid confusion. Each management agent service can be installed with a specific identifier which is used to locate and manage that particular agent instance.
If a management agent installation starts without providing a service identifier, a default installation is assumed.
mgmt_agent-
followed
by a string that consists only of alphanumeric values, hyphen or underscore as the only
allowed characters. For example:
mgmt_agent-oc1_phx-abc123
To install the management agent with a service identifier, perform the following steps:
-
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. -
Login as a user with
sudo
privileges. -
Install and set up the management agent by running the
installer.sh
script using a response file.For information about creating response files, see Create a Response File.
Navigate to the directory where you unzipped the management agent softwareZIP
file and run the following:sudo ./installer.sh <full_path_of_response_file> <service identifier>
For example:sudo ./installer.sh /tmp/input.rsp mgmt_agent-oc1_phx-abc123
The output will look similar to the following:sudo ./installer.sh <user_home_directory>/input.rsp mgmt_agent-oc1_phx-abc123 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-oc1_phx-abc123 directory exists Checking if 'mgmt_agent' user exists Checking Java version JAVA_HOME is not set or not readable to root Trying default path /usr/bin/java Java version: 1.8.0_282 found at /usr/bin/java Checking agent version Executing install Unpacking software zip Copying files to destination dir (/opt/oracle/mgmt_agent-oc1_phx-abc123) Initializing software from template Checking if JavaScript engine is available to use Creating mgmt_agent-oc1_phx-abc123 daemon Agent Install Logs: /opt/oracle/mgmt_agent-oc1_phx-abc123/installer-logs/installer.log.0 Agent install successful Executing configure Parsing input response file Validating install key Generating communication wallet Generating security artifacts Registering Management Agent Starting agent... Agent started successfully Agent setup completed and the agent is running. In the future agent can be started by directly running: sudo systemctl start mgmt_agent-oc1_phx-abc123 Please make sure that you delete <user_home_directory>/input.rsp or store it in secure location.
- A new user called
mgmt_agent
is created. This will be the management agent user. Ifmgmt_agent
user already exists, the agent installation process will use it to install the agent software. - A daemon using the service identifier as the name is created.
- Hard and soft nofile ulimit are set to 5000.
- All agent installation files are owned 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/<service-identifier>
directory. - By default, the
<service-identifier>
daemon service is enabled and started automatically after the agent installation. - All interaction with the agent daemon service, like starting or stopping an agent, can
be done using the
<service-identifier>
. For example:sudo systemctl start <service-identifier> sudo systemctl stop <service-identifier>
Log files from the agent installation are located under
/opt/oracle/<service-identifier>/installer-logs
directory.
Log files from the running agent are located under
/opt/oracle/<service-identifier>/agent_inst/log
.
mgmt_agent
user running the
following:sudo -u mgmt_agent sh
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:
-
On the main Management Agents page, click Agents from the left menu.
The Agents page is displayed with a list of all agents and gateway installed.
To see only the agents, you can use the
Filters
section from the left menu:Go to
Filters
, use theInstall Type
dropdown list and selectAgent
.All the agents are displayed.
-
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
Verify the Agent Installation Using Command Line Interface on Linux
-
Login to the host using a user with
sudo
privileges. -
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
-
Login to the host using an
Administrator
account’s command shell. -
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.
Verify the Agent Installation Using Command Line Interface on Solaris
-
Login as a user that has
sudo
privilege to execute commands as root user. -
Run the following command:
sudo /etc/init.d/mgmt_agent status
For more details, check log file:
/opt/oracle/mgmt_agent/agent_inst/log/mgmt_agent.log.
Troubleshoot Management Agent Installation Issues
-
For Management Agents issues, see Troubleshoot Management Agents Service.
-
For Management Gateway issues, see Troubleshoot Management Gateways.
-
For Management Agents on compute instances issues, see Troubleshoot Management Agents on Compute Instances.