Skip to main content
Version: NG-3.1

Troubleshooting and Maintenance

Troubleshooting OmniAgent Issues​

This section outlines common issues encountered during OmniAgent installation and startup, along with recommended checks to help identify and resolve them.

note

In the ADI-based installation flow, most configuration parameters are automatically handled by the platform. Troubleshooting should focus on installation execution, service status, connectivity, and logs rather than manual configuration files.

Linux-Specific Issues​

Installation Failing​

If the OmniAgent installation fails on Linux systems, perform the following checks:

    • Verify that the target location has correct ownership and permissions. Avoid using user home directories as the OmniAgent working directory. Use a dedicated system directory such as /opt/vunet/omniagent.
  • Ensure the installation command is executed with appropriate privileges (for example, sudo)
  • Confirm that there are no permission-related errors during installation

Common Issues (All Platforms)​

Installation Failing​

If installation fails across any platform:

  • Ensure the installation command generated from the platform is used without modification
  • Verify that the command is executed with appropriate privileges
  • Check for any errors displayed during execution
OmniAgent Failing to Start​

If OmniAgent fails to start:

  • Check the OmniAgent log file located in the OmniAgent working directory:

logs/omniagent.log

  • The logs directory is created after OmniAgent starts successfully.
  • Review error messages, startup failures, or connectivity-related issues recorded in the log file.

If OmniAgent fails even before creating the omniagent.log file, use the following platform-specific commands to check the system logs for OmniAgent:

Linux

sudo journalctl -u omniagent

AIX

sudo errpt -a -N omniagent

Solaris

sudo tail -f $(svcs -L omniagent)

Advanced Debugging​

For advanced troubleshooting:

  • Review the OmniAgent logs for detailed error messages
  • Enable debug-level logging if required and restart OmniAgent to capture more detailed output

After resolving the issue, revert logging configuration to its original level.

OmniAgent Not Appearing in Host Landscape​

If OmniAgent does not appear in the Host Landscape:

  • Ensure OmniAgent is installed and running
  • Verify that the service has started successfully
  • Check logs for connectivity or authentication errors
  • Confirm that the host appears in: Host Landscape → Hosts tab
Authentication Issues (API Key)​

If OmniAgent is unable to authenticate with the platform, logs may show a 401 Unauthorized error.

To resolve this issue:

  • Check the OmniAgent log file for authentication-related errors
  • Verify that the installation command includes a valid API key
  • If required, regenerate the API key from the OmniAgent API Keys dashboard
  • Re-run the installation command with the correct API key
  • Restart OmniAgent
Platform Connectivity Issue (Base URL)​

If OmniAgent is unable to connect to the platform:

  • Check the OmniAgent logs for connectivity-related errors
  • Verify that the platform URL used during installation is correct
  • Ensure the host can reach the platform over the network
  • If required, regenerate the installation command and reinstall OmniAgent
TLS Configuration Issue (Certificates)​

If TLS-related errors occur:

  • Check the OmniAgent logs for TLS connection errors
  • Verify that certificate paths and files are correctly configured during deployment or via TLS settings
  • Ensure certificates are valid and trusted
  • Restart OmniAgent after making corrections
Lock Acquisition Issues​

If OmniAgent fails due to lock-related errors:

  • Verify that no other OmniAgent process is currently running on the system
  • Ensure only one instance of OmniAgent is active per host

Maintenance​

Uninstallation​

To uninstall OmniAgent, run the following command:

sudo ./omniagent uninstall

Platform-Specific Notes

  • Linux, AIX, Solaris: Run the command with sudo privileges
  • Windows: Run the command from Command Prompt or PowerShell with administrator privileges

What Happens During Uninstallation

  • The OmniAgent service is stopped
  • All probe processes managed by OmniAgent are stopped
  • OmniAgent is removed from the system service registry
  • Configuration files, logs, and related data in the location are retained for troubleshooting or reuse during reinstallation

Upgrade OmniAgent​

Upgrading OmniAgent in the ADI framework is performed by reinstalling the agent using the latest package generated from the platform. This ensures that the upgraded version is correctly associated with the configured environment, host group, and authentication settings.

Steps to Upgrade OmniAgent​

1. Download the Latest OmniAgent Package

  • Navigate to Data Studio > Host Landscape
  • Click Download OmniAgent
  • Select:
    • Platform
    • Environment
    • Host Group
  • Copy the generated installation command or download the package

2. Stop OmniAgent (Recommended)

Before upgrading, stop the existing OmniAgent service:

sudo ./omniagent stop

3. Uninstall the Existing Version

Run the uninstall command:

sudo ./omniagent uninstall

Platform-specific notes:

  • Linux, AIX, Solaris: Use sudo
  • Windows: Run as Administrator

What happens during uninstall

  • OmniAgent service is stopped
  • All probe processes are terminated
  • Existing logs and data are retained

4. Install the New Version

Run the installation command generated from the platform. This command:

  • Installs the latest version
  • Applies:
    • API key
    • Environment
    • Host Group
  • Ensures correct platform registration

5. Start OmniAgent

After installation, start the service:

sudo ./omniagent start

6. Verify Upgrade

After restarting:

  • Check that OmniAgent is running:
sudo ./omniagent status

Ensure:

  • Host is reporting
  • Probe health is visible
  • Monitoring resumes successfully