OmniAgent Administration and Operations

Security Overview

Control security

OmniAgent communicates with the VuSmartMaps management platform using a TLS-encrypted TCP connection by default. This ensures that all control-plane communication—such as agent state reporting and update instructions—is protected against interception and tampering during transmission.

During deployment of the VuSmartMaps platform, a custom certificate file can be provided before OmniAgent installation. This certificate is packaged by default with all OmniAgent and probe packages. When present, the certificate is added to the set of trusted root certificate authorities used by OmniAgent to verify the server’s identity and establish a secure TLS connection.

This approach enables secure communication even in environments that use private certificate authorities or internally managed certificates.

TLS Configuration

TLS behavior is configured through the OmniAgent configuration file using the tls section. This section allows administrators to control how server certificates are validated during secure communication.

# TLS configuration.
tls:
  # Path to certificate file directory. If not provided, system cert pool will
  # be used. Optional.
  certDirectory: "certs"
  # Skip TLS verification on errors.
  # Optional. Default: false
  insecureSkipVerify: false
  # Server name to use in TLS config. Required if certificate is provided.
  # Optional.
  serverName: "vunetsystems.com"

TLS Configuration Details

• Certificate Directory (certDirectory): Specifies the directory containing trusted certificate files. If not provided, OmniAgent uses the system’s default certificate trust store.
• TLS Verification Control (insecureSkipVerify): Determines whether TLS verification errors should be ignored. By default, verification is enforced to ensure secure communication.
• Server Name (serverName): Specifies the expected server name during TLS handshake. This is required when a custom certificate is provided to ensure proper certificate validation.

Security Benefits

• Ensures encrypted communication between OmniAgent and the management server
• Prevents unauthorized servers from impersonating the VuSmartMaps platform
• Supports custom and private CA environments
• Centralizes TLS behavior through configuration, avoiding hard-coded security settings

Resource Control and Isolation

OmniAgent is designed to operate with strict resource boundaries to ensure minimal impact on the host system and to prevent observability probes from consuming excessive resources.

OmniAgent Resource Limits

OmniAgent runs with predefined resource limits to maintain a lightweight footprint on the host.

Hard Limits

• CPU: 1 core
• Memory: 250 MB

Idle State Consumption

• CPU: Less than 0.01 core
• Memory: Less than 30 MB

These limits ensure that OmniAgent remains efficient even when managing multiple probes.

Probe Resource Utilization Management

OmniAgent actively manages the resource usage of individual probes to maintain system stability. Each probe operates within defined limits for:

• CPU usage
• Memory consumption
• Log disk usage

Enforcement Behavior

If a probe exceeds its configured resource limits:

1. OmniAgent stops the probe.
2. The probe is restarted after a waiting period.
3. The waiting period increases exponentially with each subsequent breach, up to a maximum of 10 minutes.
4. If the probe remains within limits for 20 consecutive minutes, the waiting period is reset to its initial value.

This controlled restart mechanism prevents repeated resource exhaustion while allowing probes to recover automatically.

Probe Resource Configuration

• Probes are added with preconfigured resource limits by default.
• Remote updates to probe resource limits will be supported directly from the platform in a future release.
• To request changes to probe resource limits, contact VuSmartMaps Support.

Monitoring Resource Usage

Both resource limits and current utilization of probes can be monitored from the OmniAgent Management Console:

• OmniAgent Console → Hosts → Select Host → Probes
• OmniAgent Console → Probes → Select Probe

These views provide visibility into probe behavior and help identify resource-related issues.

Troubleshooting OmniAgent Issues

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

Linux-Specific Issues

Installation Failing

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

• Verify that the target working directory can be successfully changed (chown) to the intended user.
• During re-installation, ensure that:
  • The existing directory contents (data, logs, probes)
  • And the installation commands are using the same user account. A mismatch in ownership or user context can cause installation failures.

Common Issues (All Platforms)

Installation Failing

If installation fails across any platform:

• Verify that the configuration file is valid and correctly formatted.
• Ensure the --config flag points to the correct configuration file path.

OmniAgent Failing to Start

If OmniAgent fails to start:

• Check the log file located at:

logs/omniagent.log

for error messages or startup failures.

• For advanced debugging:
  • Ensure the OmniAgent service is stopped.
  • Update the configuration file under the logs section:
    • Set outputType to stdout
    • Set logLevel to debug
• From the OmniAgent working directory, run:

./omniagent -w . -c <config-file>

• Review the debug output to identify the issue.
• After resolving the problem, revert the logging configuration to its original values.
• If OmniAgent fails due to lock acquisition errors, verify that no other OmniAgent process is currently running on the system.

OmniAgent Not Appearing in Management UI (Hosts View)

If OmniAgent does not appear in the management UI host view:

• Refer to the “OmniAgent Failing to Start” section and complete all recommended checks.
• Verify that TLS configuration in the configuration file is correct.
• Review the OmniAgent logs located at:

logs/omniagent.log

Authentication Issues (API Key)

If OmniAgent is configured with an invalid or missing API key, it will fail to authenticate with the platform and log a 401 Unauthorized error.

To resolve this issue:

• Check the OmniAgent log file
• If a 401 Unauthorized message is present, verify that the API key configured in the OmniAgent configuration file is correct.
• Retrieve or regenerate the API key from the OmniAgent API Keys Dashboard in the Management UI.
• Update the configuration file with the correct API key and restart OmniAgent.

Platform Connectivity Issue (Base URL)

If the vuSmartMaps base URL configured for OmniAgent is invalid or unreachable, OmniAgent logs will show errors while attempting to ping the platform.

To verify this issue:

• Check the OmniAgent log
• If errors related to pinging or reaching the platform are present, verify that the vuSmartMaps base URL configured for OmniAgent is correct.
• Update the base URL if required and restart OmniAgent.

TLS Configuration Issue (Certificates)

If the certificates folder path is invalid or the configured certificate is invalid, OmniAgent logs will show errors while establishing a TLS connection.

To verify this issue:

• Check the OmniAgent log If TLS-related errors are present, verify that:
  • The certificates folder path configured for OmniAgent is valid.
  • The certificate files configured for OmniAgent are correct.

After correcting the TLS configuration, restart OmniAgent and review the logs.

Maintenance

Uninstallation

To uninstall OmniAgent, run the following command using the OmniAgent executable:

omniagent uninstall

Platform-specific notes

• Linux: If OmniAgent is installed as a system service, run the command with sudo privileges.

• Windows: Run the command from a Command Prompt or PowerShell window 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 other associated data in the working directory are retained. This allows the data to be reused for troubleshooting or for reinstalling OmniAgent at a later time.

Upgrade

To upgrade OmniAgent to a newer version, follow the steps below.

1. Download the new OmniAgent package
   • Obtain the latest OmniAgent executable for your operating system.
2. Uninstall the existing version
   • Run the uninstall command using the currently installed OmniAgent executable:

omniagent uninstall

1. Linux: If OmniAgent is installed as a system service, run the command with sudo.
2. Windows: Run the command from a terminal or command prompt with administrator privileges.

• This step stops the running OmniAgent service and all associated probe processes, while retaining existing configuration files and logs.

3. Install the new version

• Run the installation command using the newly downloaded executable, with the same arguments and configuration file used during the original installation:

omniagent install

• The new executable replaces the previous version in the working directory and is used for all subsequent operations.

4. Start OmniAgent
   • After installation completes, start OmniAgent to resume normal operation:

omniagent start