OCI Linux

This section describes the steps to run the downloaded script on an OCI instance running on Linux platform.

Note

You can directly add OCI instances to your fleet using the JMS console or JMS APIs. This is the recommended approach for onboarding OCI instances to your fleet.

However, if you are using the install script for onboarding OCI instances, follow the instructions mentioned in this topic.

If the host is present in the same tenancy and region as that of the fleet, the script will configure Oracle Cloud Agent. However, if the host is not present in the same tenancy and region, or if you prefer to install Oracle Management Agent instead of Oracle Cloud Agent, run the script with the install-mgmt-agent parameter.

Note

In the case of OCI instance pools, you need to individually set up the agent on each instance part of the OCI instance pool.

Prerequisites:

Run the installation script with sudo or administrative access.

Make sure the following policy is added before you run the installation script on OCI Linux instances.

 ALLOW dynamic-group JMS_DYNAMIC_GROUP TO MANAGE instances IN
    COMPARTMENT <instance_compartment_ocid>

See Set up OCI Linux instance for JMS for instructions.

Note

By default, the installation script will:

Generate usage tracker with additional functionality to collect the user.name property for better identification of applications running on Application Servers like WebLogic and Tomcat. If you do not want to enable this feature, update the parameter --enable-user-name=false in the installation script. You can modify the Java Usage Tracker properties file in the future to add or remove user.name from the additionalProperties section.
Disable Federal Information Processing Standards (FIPS) mode for plug-ins. To enable FIPS mode in USGov relams, update the parameter --enable-fips-mode=true in the installation script.
Install the agent with MACS default telemetry frequency.

Run the --help command to view the description of options such as enabling or disabling user name, proxy settings, FIPS, and so on.

The following are the optional parameters along with the description:


-c, --cleanup         Uninstall plug-ins, delete configuration files or restore originals from backups and exit.
-f, --force           Uninstall plug-ins, delete configuration files or restore originals from backups and continue installation.
-h, --help            Print usage message end exit.
--diagnostic          Determine if prerequisite conditions are met on the host machine to allow successful 
                      agent installation and plug-in deployment.
--enable-user-name    Generate usage tracker with additional functionality to collect the 'user.name' property for better identification 
                      of applications running on Application Servers like WebLogic and Tomcat servers. 
                      Default value is 'true'. 
--enable-fips-mode    Enable FIPS mode for plug-ins in USGov realms.
                      Format is --enable-fips-mode=true|false (for example, --enable-fips-mode=false).
                      Modify /etc/environment and create a line with ENV_AGENT_PLUGIN_FIPS_APPROVED=true or false.
                      Default value is false.
--install-mgmt-agent  Force Management Agent installation on instance. Use this parameter to monitor an OCI instance belonging to a different tenancy or region.  
--proxy-host          Add proxy host to curl commands, add or replace line 'ProxyHost = VALUE' in install key before Management Agent setup.
                      Format is --proxy-host="VALUE" (for example, --proxy-host="100.0.0.10").
                      Default is no proxy.
--proxy-port          Add proxy port to curl commands, add or replace line 'ProxyPort = VALUE' in install key before Management Agent setup.
                      Format is --proxy-port="VALUE" (for example, --proxy-port="8050").
--proxy-user          Add proxy user to curl commands, add or replace line 'ProxyUser = VALUE' in install key before Management Agent setup.
                      Format is --proxy-user="VALUE" (for example, --proxy-user="opc").
--proxy-password      Add proxy password to curl commands, add or replace line 'ProxyPassword = VALUE' in install key before Management Agent setup.
                      Format is --proxy-password="VALUE" (for example, --proxy-password="example").
--proxy-realm         Add or replace line 'ProxyRealm = VALUE' in install key before Management  Agent setup.
                      Format is --proxy-realm="VALUE" (for example, --proxy-realm="OC1").
--use-agent-installer-path  Path to management agent installation file if it isn't in the same folder as the install script.
--use-java-path      Specify the Oracle Java 8 installation path for agent installation; 
                     if the path is not specified, the script will attempt to find a suitable Oracle Java 8 installation path from the file system. 
                     Format is --use-java-path={CUSTOM_PATH}(for example, --use-java-path=/usr/java/jdk1.8.0_361)).

Steps

(Optional diagnostic check) Navigate to the folder where you saved the installation script and management agent software. Run the script using the following command:

$ sudo bash ./JMS_YourFleetName_linux.sh --diagnostic

Depending on the operating system and agent type, the results will be similar to:

Diagnostic failed:

======================================================================================================
Diagnostic Summary
======================================================================================================
Shell is supported? : Yes
User has sudo/root privileges? : Yes
Certified OS? : Yes
Meets minimum disk requirements? : Yes
Meets minimum memory requirements? : Yes
Able to reach OCI endpoint? : No
	Check your internet connection and proxy setting.
Is clock sync with OCI platform? : Unknown
	The clock sync check was skipped. Can't read headers as provided OCI endpoint is not reachable.
Certificate verification has been passed? : Unknown
	The certificate check was skipped. Can't read certificate as provided OCI endpoint is not reachable.
Prerequisites for Oracle Cloud Agent were installed? : No
	OCI Metadata and Instance Config are not available but are required for installation.
	Try to manually install 'oci-metadata' and run the JMS_YourFleetName_linux_updated.sh script again.
	Or force Management Agent installation on the instance using the '--install-mgmt-agent' argument.
Meets Java requirement? : No
	Management Agent requires a minimum Oracle JDK 1.8 (1.8.0_281). The recommended version is 1.8.0_361 or later.
	Try to install Java manually and run the JMS_YourFleetName_linux_updated.sh script again.
Valid Management Agent installer? : No
	Found 0 files with the 'oracle.mgmt_agent*.rpm' pattern in the /home/opc folder.
	Run the JMS_YourFleetName_linux_updated.sh script again with the '--use-agent-installer-path' parameter.
Existing Management Agent has been detected? : No
=================================================================================================================================================================================
Diagnostics have failed. Please resolve all issues and run script JMS_YourFleetName_linux_updated.sh again.
Please refer troubleshooting guide https://docs.oracle.com/en-us/iaas/jms/doc/troubleshooting.html for more details.

A copy of this installation log can be found at /var/log/oracle/JMSInstallScript/JMSInstallScriptLogs-05Jul2024-075822-9591.log

Diagnostic completed successfully:

======================================================================================================
Diagnostic Summary
======================================================================================================
Shell is supported? : Yes
User has sudo/root privileges? : Yes
Certified OS? : Yes
Meets minimum disk requirements? : Yes
Meets minimum memory requirements? : Yes
Able to reach OCI endpoint? : Yes
Certificate verification has been passed? : Yes
Is clock sync with OCI platform? : Yes
Meets Java requirement? : Yes
Certified OS for Oracle Cloud Agent? : Yes
Oracle Cloud Agent has been detected? : Yes
=======================================================================================================================================================
Diagnostics have finished running and no error occurred.

A copy of this installation log can be found at /var/log/oracle/JMSInstallScript/JMSInstallScriptLogs-05Jul2024-055555-128898.log

See Running Agent Installation Diagnostics for the complete list of question with solutions or recommendations.

Navigate to the folder where you saved the installation script and management agent software. Run the script using the following command:

$ sudo bash ./JMS_YourFleetName_linux.sh

If installation is successful, you'll see a message similar to the following:

...
Management Agent installation has been completed.
Management Agent plugin 'Java Management Service' installation has been completed.
Management Agent plugin 'Java Usage Tracking' installation has been completed.
Management Agent was successfully registered using key YourFleetName (ocid1.managementagentinstallkey.oc1.iad.<ocid hash>).Assigned JMS Fleet is YourFleetName (ocid1.jmsfleet.oc1.iad.<ocid hash>).

(Optional) To verify if the management agent is running, run the following script on your Linux machine:
```
curl -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/
```
where 169.254.169.254 is the IP address of the OCI Compute Instance Metadata Service.
If installation is successful, you'll see a message similar to the following:
```
{    
 "desiredState": "ENABLED",
 "name": "Management Agent"
},
{
 "desiredState": "ENABLED",
 "name": "Oracle Java Management Service"
}
```

The log files are located in the /var/log/oracle-cloud-agent/plugins/oci-jms/ directory.

Oracle Cloud Infrastructure Documentation