Oracle Cloud Infrastructure Documentation

Running Agent Installation Diagnostics

The diagnostic command helps in troubleshooting issues during the installation process. It displays error messages, warning messages, and debug information. The command is included in the OMA software installer and the install script, which provides valuable feedback and identifies any potential installation problems. It helps to determine if prerequisite conditions are met on the host machine to allow successful agent installation and plug-in deployment.

Enabling Diagnostic

To enable diagnostic in the installer and installation script, run the following diagnostic command before you start the installation process:

For Linux and macOS:

$ sudo bash ./JMS_YourFleetName_<linux|macos>.sh --diagnostic

For Windows (using PowerShell):

.\JMS_YourFleetName_windows.ps1 --diagnostic
The diagnostic collects all possible and useful information, and adds the output to the log file. The diagnostic summary is displayed with all the findings. If there are any issues, the diagnostics script generates a list of warnings and recommendations on how to correct the issues.
Note

The log files can be located in the following path:
  • for Linux: /var/log/oracle/JMSInstallScript/
  • for macOS: /Library/Oracle/JMSInstallScript/
  • for Windows: C:\ProgramData\Oracle\JMSInstallScript

Based on the installation environment (Operating System and Operating System architecture) and the agent type (OCA or OMA), a diagnostic summary with criteria checked and its results displayed as Yes/No responses is provided.

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 https://oracle.com endpoint? : Yes
Meets Java requirement? : Yes
Valid Management Agent installer? : No    
   Found 2 files with 'oracle.mgmt_agent*.rpm' pattern in /home/opc folder.    
   Please, run script test_linux.sh again with --use-agent-installer-path parameter.
Management Agent has been detected? : No
======================================================================================================
Diagnostics have failed. Please resolve all issues and run the jms setup installer again.
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 https://oracle.com endpoint? : Yes
Meets Java requirement? : Yes
Valid Management Agent installer? : Yes
Existing Management Agent has been detected? : Yes
Existing Management Agent has JMS plugins? : Yes
Existing Management Agent can be upgraded? : Yes
======================================================================================================
Diagnostics have finished running and no error occurred.

The criteria checked during the diagnostic run may differ according to the installation environment. The following table provides a summarized list of all criteria checked across all supported platforms.

Table A-2 Diagnostic Summary

Criteria Solution/Recommendation
User has sudo/root privileges? Ensure that you have sudo, root, or administrator access.
Shell is supported? Ensure that you are using the latest Shell version.
  • Windows: You must use PowerShell version 5.1 or later.
  • Linux: If you are using unsupported shell, update the shell and run the installation script again.
Certified OS? Ensure that the operating system version is supported. See the JMS System Requirements for supported platforms.
Able to reach OCI endpoint? Check your internet connection and proxy setting.
Meets minimum disk requirements? All platforms requires 300MB of free disk space. Clean up the disk and rerun the script.
Meets minimum memory requirements? Management Agent with JMS plug-ins require 500Mb of free memory. Clean up the memory and rerun the script.
Java found in Users directory? Ensure that you keep Java in a common location that is accessible to all users.
Available Java for agent installation? Ensure that you are using the latest Oracle JDK 8 release to set up the management agent. See Agent Prerequisites.
Management Agent installer available? Ensure that you download the correct agent software installer file specific to your operating system. Save the installer file in the same directory as the install script and check if it is accessible.

If the installer is not in the same directory as the script, specify the path using the --use-agent-installer-path parameter.

Existing Management Agent has been detected? If you already have an existing management agent installation, and if you want to proceed with a reinstallation, you can use the --reinstall parameter.
Existing Management Agent can be upgraded to a newer version? If you have enabled auto upgrade feature, the agents are automatically upgraded when the new version is available. However, if there is an issue:
  • Update the management agent by specifying the installer path using the --use-agent-installer-path parameter.

    OR

  • Reinstall the management agent using --reinstall parameter.
Fleet check passed? If the fleet OCID is found during the check, you can upgrade the agent. If the fleet ID is not found, then reinstall the agent using --reinstall parameter.
Prerequisites for Oracle Cloud Agent were installed? Ensure that the following prerequisites are met before installing Oracle Cloud Agent:
  • Instance is located in a supported $OCI_REALM_KEY realm
  • OCI Metadata and Instance Config are available. If not, install oci-metadata manually or force install the management agent using --install-mgmt-agent argument.
  • Package jq is installed, else install it manually. You can force install the management agent as well, using --install-mgmt-agent argument.
  • OCI CLI is installed, else install it manually and run the script again. You can force install the management agent as well, using --install-mgmt-agent argument.
Meets Java requirement? Ensure that you have installed the following Java versions to run:
  • Management agent - Oracle JDK 1.8 or later
  • OCA JMS plug-in: Oracle JDK 11 or later
Valid Management Agent installer? Ensure that the management agent installer package specific to your OS is accessible. If there are any issues, run the script again with the --use-agent-installer-path parameter.
Management Agent can be unzipped? An error occurs if the script is unable to use jar and unzip utilities for unzipping the management agent. Download the management agent again and run the installation script.
Existing Management Agent has JMS plug-ins? If there are any missing plug-ins in the existing management agent, you can either:
  • Deploy the plug-ins using the Management Agents page in OCI
  • Reinstall the Management Agent with Java Management Service by running the script with the --reinstall parameter
Meets requirements for JMS advanced features? To enable JMS advanced features on the instance, ensure that sudo executable is accessible.
Certified OS for Oracle Cloud Agent? Java Management Service only supports Oracle Cloud Agent on Oracle Linux. To force the Management Agent installation on an instance, use the --install-management-agent argument.
Certificate verification has been passed?
Note

Currently, this option is available only for Linux and macOS platforms.
Ensure that the service is accessible by reviewing your firewall and proxy settings.
Is clock sync with OCI platform?
Note

Currently, this option is available only for Linux and macOS platforms.
Ensure that the host's clock is in sync with the OCI platform. If it is not in sync, synchronize the host clock within 5 minutes of the OCI platform and run the script again.

See Maximum Allowed Client Clock Skew for more information.