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 the required administrative privileges.
• 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 the required administrative 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.lo

• 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, check the OmniAgent logs for authentication-related errors.

• A 401 Unauthorized error indicates that OmniAgent did not provide a valid authentication credential.
• A 403 Forbidden error indicates that the credential was authenticated but does not have the required OmniAgent permission.
• Revoked and expired API keys are rejected by the platform.
• Disabling a Service Account invalidates the API keys associated with that account.
• When the Service Account is enabled again, its associated API keys become valid again, provided that the keys are active, have not expired or been revoked, and the Service Account has the required OmniAgent permission.

To resolve authentication issues:

1. Check the OmniAgent log file:

logs/omniagent.log

2. Verify the API key stored on the host.

For Linux, AIX, and Solaris:

sudo ./omniagent view-api-key

For Windows:

omniagent.exe view-api-key

The command displays only a masked representation of the stored key. It does not display or log the complete secret.

3. For a new or upgraded OmniAgent, confirm that the stored API key begins with vun_.

Note: Existing OmniAgent installations that have not yet been upgraded may continue to use UUID-format legacy API keys.

4. From the API Keys page, verify:

• The API key is not revoked.
• The API key has not expired.
• The owning Service Account is active.
• The key has the expected owner and rotation status.

5. If the platform administrator has provided a replacement vun_ API key, apply it to the host.

For Linux, AIX, and Solaris:

sudo ./omniagent replace-api-key \--api-key \<vun\_api\_key\> sudo ./omniagent restart

For Windows:

omniagent.exe replace-api-key \--api-key \<vun\_api\_key\> omniagent.exe restart 

The replace-api-key command validates the vun_ prefix, requests confirmation, and stores the replacement key in the protected credential store. The running OmniAgent uses the replacement key after the service is restarted.

note

Do not update the API key in the OmniAgent configuration file. The API key is stored separately in the protected credential store on the host.

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 using the required administrative 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
• The securely stored OmniAgent API key and its credential-protection data are removed during an explicit uninstallation.
• Configuration files, logs, and related working-directory data are retained for troubleshooting or reuse. However, reinstalling OmniAgent after an explicit uninstall requires a valid API key supplied through a newly generated installation command or applied using the supported local key-replacement command.

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

• Verify in Host Landscape

Ensure:

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