vuSmartMaps Agents

Introduction

vuSmartMaps delivers end-to-end visibility into business journeys, applications, and IT infrastructure across the enterprise. To achieve this, the platform connects to a wide variety of systems and collects metrics and logs in real time using a set of lightweight, purpose-built agents.

These agents run close to the data source (on servers, middleware, applications, and OS platforms) and securely stream telemetry back to vuSmartMaps for analytics, alerting, and visualization.

This document focuses on:

• Which agents to use – by platform, use case, and data type (metrics vs. logs).
• How to deploy and operate agents – installation paths, run-as user model (root vs non-root), service registration, and restart behaviour.
• How to keep agents safe and predictable in production – resource caps, log rotation, antivirus exclusions, SSL/JMX connectivity, and Kubernetes considerations.

In subsequent sections, each agent will be described in two deployment modes:

1. Agents deployed as root – typically used where system-level service registration or privileged operations are required.
2. Agents deployed as non-root – preferred wherever possible to align with least-privilege and customer security policies.

This ensures that, for every customer implementation, the deployment pattern, restart behaviour on server reboot, and operational guardrails are clearly defined and do not rely on implicit assumptions.

Agent Portfolio Overview

The vuSmartMaps agent portfolio can be grouped into two broad categories:

• Metrics collection agents – collect system, application, and service performance metrics.
• Log collection agents – collect and forward application, system, and event logs.

The table below summarizes each agent, its primary purpose, and its supported operating systems.

Agent	Category	Primary Functionality	Supported OS / Platforms*	Key Notes / Dependencies
Healthbeat	Metrics	Lightweight metrics collector for OS (CPU, memory, disk, etc.) and common services (Apache, Nginx, MySQL, PostgreSQL, MongoDB, HAProxy, Zookeeper, vSphere, Oracle, etc.).	Linux, Windows, macOS, Kubernetes, Red Hat OpenShift	Go-based agent; supports heartbeat & exec modules.
vuHealthAgent	Metrics	Java-based metrics and availability agent for platforms where Go agents are not supported; collects system metrics, service/device availability, and custom command output.	AIX, HP-UX, Solaris, and other Java-capable UNIX platforms where Go is not available (e.g. SPARC systems).	Requires Java ≥ 1.8
vuAppAgent	Metrics	Application-level monitoring for Java ecosystems: WebSphere, WebLogic, JBoss, Apache Tomcat, IIB, WebSphere MQ, OHS, AppDynamics, local/remote JVMs, etc.	Linux/Unix (incl. AIX, HP-UX, Solaris), Windows	Requires Java ≥ 1.7
Logbeat	Logs	Lightweight log shipper to collect and forward file-based logs to vuSmartMaps with multiline handling, backpressure awareness, and at-least-once delivery guarantees.	Linux, Windows, Kubernetes, Red Hat OpenShift	Go-based; monitors files/directories via “harvesters”.
vuLogAgent	Logs	Java-based log forwarding agent for platforms where Logbeat is not supported (e.g. AIX, Solaris).	AIX, HP-UX, Solaris, and similar UNIX platforms with Java ≥ 1.5	Requires Java; suitable for SPARC and older NIX platforms.
Eventlogbeat	Logs	Windows Event Log collector for Application, System, Security, Hardware, and other Windows event channels.	Windows	Runs as a Windows service; uses Windows Event Log APIs.

Agent Installation and Management [Native / VM / Bare-metal]

Install as Root/Admin (System Service)

What requires root/admin

Root/Admin privileges are required for OS-enforced actions such as:

• Registering the agent as a system-managed service (Linux systemd/SysV, Solaris rc/SMF, AIX inittab/SRC, HP-UX init/rc, Windows SCM)
• Writing service definitions / boot hooks into protected locations (/etc, /sbin, Windows service registry, etc.)
• Enabling/starting/stopping system services using OS service tooling
• Setting secure permissions on protected directories and service artifacts created during installation

note

In most enterprise setups, the execution user is customer-controlled.

• Our installer generally does not create OS users by default.
• If a dedicated service account is required, it should be pre-created by customer admin, and the service should be configured to run under that account.

Why root/admin is required

Operating systems restrict service registration and boot integration to privileged administrators. This is an OS policy boundary—not agent functionality. Registering as a system service enables:

• Auto-start after reboot (boot-time integration)
• Consistent service lifecycle management (start/stop/status)
• Auditable operational control (standard OS tooling)
• Optional crash recovery policies (where the OS service manager supports and is configured for it)

Refer this document for more information.

Root/Admin installation workflow (common)

1. Download the agent package from the approved location (customer repository / share / installer bundle).
2. Copy package to target host and extract it.
3. Run the installer using privileged execution:
   • Unix: sudo -i or sudo <installer>
   • Windows: run PowerShell/CMD as Administrator
4. Choose / enable service mode (system service registration).
5. Start + enable service and validate telemetry.

Install as Non-Root (User Mode)

When to use non-root installation

Use non-root installation when:

• Customer security policy restricts root/admin access
• Customer accepts that boot auto-start needs additional configuration

Key limitation: Without root/admin you cannot register a system service in most OS. Therefore, auto-start after reboot is not guaranteed unless you configure an explicit user-mode boot mechanism.

Non-root installation workflow (common)

1. Choose a dedicated non-privileged account (recommended) vunetagent (or customer standard).
2. Ensure the user has:
   • Read permissions to monitored logs/paths
   • Network egress to broker/collector endpoint
   • Sufficient ulimit (open files/processes) if needed
3. Extract package under user-owned install path:
   • /home/vunetagent/vunet/ or /data/vunet/agents/
4. Run installer without service registration options:
   • <INSTALLER> --installpath <USER_OWNED_PATH> --setupinit legacy (or omit setupinit)
5. Start agent manually to validate telemetry:
   • <AGENT_HOME>/agent start (or equivalent)
6. Configure non-root auto-start after reboot.