Skip to main content
Version: NG-2.16

Beat Agents

Beats-based agents are lightweight telemetry shippers used to collect and forward host and log data to the vuSmartMaps platform. They are packaged as self-contained binaries with a small configuration footprint, designed for low resource overhead and high reliability. In production, they are typically installed as OS-managed services (systemd/Windows Service) for auto-start on reboot and centralized lifecycle management. They can also run in user-mode where admin access is restricted, but in that case boot persistence must be configured separately.

Healthbeat​

Overview​

Healthbeat is a lightweight metrics agent that runs on Linux and Windows.Healthbeat collects system and service-level metrics such as CPU, memory, disk, and network usage. It also provides prebuilt modules for common applications like Apache, Nginx, MySQL, Kafka, and more, enabling standardized metrics collection with minimal configuration.

Prerequisites​

Allow outbound connectivity from the target host to vuSmartMaps data collection endpoints on:

  • 9092/TCP – non-SSL (Till 2.16 Build)
  • 9094/TCP – SSL (Till 2.16 Build)

User / Permissions​

  • Linux: Non-root user is sufficient; the execution user must have read access to all monitored log paths. --setupinit systemctl requires sudo for service registration and management.
  • Windows: Installation and service management must be done from an elevated Command Prompt (Run as Administrator).
    • Non-admin install on Windows is currently not supported. If required, we must implement Scheduled Tasks (Task Scheduler) as an enhancement.

Installation and Management​

Linux​

Root/Admin installation steps​
  1. Extract the downloaded Healthbeat package.
  2. Change into the extracted directory.
  3. Run:
./install --quick --installpath <path> [--cpulimit <#cores>] [--memlimit <MB>] --setupinit systemctl [--enablessl]

Arguments

  • --quick – non-interactive quick installation.
  • --installpath <path> – base directory for installation (default: $HOME); agent home becomes <path>/healthbeat.
  • --cpulimit <#cores> – CPU core limit (default: 1). Used to set max_procs and CPU quota.
  • --memlimit <MB> – memory limit in MB (default: 512, minimum 128).
  • --setupinit systemctl – systemd system service (requires sudo).
  • --enablessl – enables SSL and switches Kafka port to 9094.
Root/Admin agent management steps​
sudo systemctl <start|stop|status> healthbeat.service
Non-root installation steps​
  1. Extract the downloaded Healthbeat package.
  2. Change into the extracted directory.
  3. Run:
./install --quick --installpath <path> [--cpulimit <#cores>] [--memlimit <MB>] [--setupinit <lingering|legacy>] [--enablessl]

Arguments

  • --quick – non-interactive quick installation.

  • --installpath <path> – base directory for installation (default: $HOME); agent home becomes <path>/healthbeat.

  • --cpulimit <#cores> – CPU core limit (default: 1). Used to set max_procs and CPU quota.

  • --memlimit <MB> – memory limit in MB (default: 512, minimum 128).

  • --setupinit <mode> – startup mode:

    • legacy – user-mode process; no auto-start after reboot.
    • lingering – systemd user service with loginctl enable-linger.
      note

      A normal (non-sudo) user can enable lingering for their own account only if the distro ships systemd’s org.freedesktop.login1.set-self-linger polkit action with defaults set to allow it. This was added/fixed in systemd around v230. If a distro is on systemd < 230, there is no “self-linger without root” path; you’ll need root (or an admin/polkit override).
      Refer here before proceeding with lingering.

  • --enablessl – enables SSL and switches Kafka port to 9094.

Non-root agent management steps​

The exact commands depend on --setupinit:

Legacy mode (legacy) – user process:

<AGENT_HOME>/healthbeat <start|stop|status>

User service (lingering) – systemd user service:

systemctl --user <start|stop|status> healthbeat.service
note

Auto-start behavior (Linux non-root installs)

If the agent is not installed as a system service, it will not auto-start after reboot by default. Use one of these mechanisms:

  • Recommended: lingering user service (systemd user unit) + loginctl enable-linger
  • Alternative: a periodic cron “ensure-running” job (starts agent if not running)
  • Least reliable: start on user login via shell profile

Windows​

Root/Admin installation steps​
  1. Extract the Healthbeat package.
  2. Open Command Prompt as Administrator.
  3. Run:
.\healthbeat-installer.exe [--enablessl] /SILENT /NOCANCEL /DIR="<path>\healthbeat" /MEMLIMIT "<MB>" /CPULIMIT "<#cores>"

Arguments

  • /DIR – optional custom install directory (default: C:\vunet\healthbeat).
  • /MEMLIMIT <MB> – memory cap (default 512).
  • /CPULIMIT <#cores> – CPU cores cap (default 1).
  • --enablessl – optional, enables SSL.
Root/Admin agent management steps​

In an elevated Command Prompt:

sc <start|stop|query> healthbeat
Non-root/Non-Admin installation steps​

Currently, we do not support installing the agent as a non-administrator user on Windows. If a customer specifically requires a non-admin deployment, we must implement Windows Task Scheduler–based startup (Scheduled Tasks) as an enhancement.

Uninstallation​

Linux​

cd <AGENT_HOME>
./uninstall
Windows​
cd C:\vunet\healthbeat   # or your custom path
.\unins000.exe

Update resource limits​

Linux​

From AGENT_HOME:
cd $AGENT_HOME

./update --resource_cap --cpulimit <cores> --memlimit <MB>
Windows​

Edit supervisor.ini in AGENT_HOME:

[limits]
memory_mb = {MEMLIMIT}
cpu_limit = {CPULIMIT}

Supported Operating Systems​

  • Linux (Ubuntu, RHEL, CentOS, etc.)
  • Windows Server / Windows desktop (11)

Logbeat​

Overview​

Logbeat is a lightweight log shipper that tails files and directories, supports multiline events, backpressure handling, at-least-once delivery, and forwards logs to vuSmartMaps.

Prerequisites​

Network​

Allow outbound connectivity from the target host to vuSmartMaps data collection endpoints on:

  • 9092/TCP – non-SSL (Till 2.16 Build)
  • 9094/TCP – SSL (Till 2.16 Build)

User / Permissions​

  • Linux: Non-root user is sufficient; the execution user must have read access to all monitored log paths. --setupinit systemctl requires sudo for service registration and management.
  • Windows: Installation and service management must be done from an elevated Command Prompt (Run as Administrator).
    • Non-admin install on Windows is currently not supported. If required, we must implement Scheduled Tasks (Task Scheduler) as an enhancement.

Installation and Management​

Linux​

Root/Admin installation steps​
  1. Extract the downloaded Logbeat package.
  2. Change into the extracted directory.
  3. Run:
./install --quick --installpath <path> [--cpulimit <#cores>] [--memlimit <MB>] --setupinit systemctl [--enablessl]

Arguments

  • --quick – non-interactive quick installation.
  • --installpath <path> – base directory for installation (default: $HOME); agent home becomes <path>/logbeat.
  • --cpulimit <#cores> – CPU core limit (default: 1). Used to set max_procs and CPU quota.
  • --memlimit <MB> – memory limit in MB (default: 512, minimum 128).
  • --setupinit systemctl – systemd system service (requires sudo).
  • --enablessl – enables SSL and switches Kafka port to 9094.
Root/Admin agent management steps​
sudo systemctl <start|stop|status> logbeat.service
Non-root installation steps​
  1. Extract the downloaded Logbeat package.
  2. Change into the extracted directory.
  3. Run:
./install --quick --installpath <path> [--cpulimit <#cores>] [--memlimit <MB>] [--setupinit <lingering|legacy>] [--enablessl]

Arguments

  • --quick – non-interactive quick installation.

  • --installpath <path> – base directory for installation (default: $HOME); agent home becomes <path>/logbeat.

  • --cpulimit <#cores> – CPU core limit (default: 1). Used to set max_procs and CPU quota.

  • --memlimit <MB> – memory limit in MB (default: 512, minimum 128).

  • --setupinit <mode> – startup mode:

    • legacy – user-mode process; no auto-start after reboot.
    • lingering – systemd user service with loginctl enable-linger.
      note

      A normal (non-sudo) user can enable lingering for their own account only if the distro ships systemd’s org.freedesktop.login1.set-self-linger polkit action with defaults set to allow it. This was added/fixed in systemd around v230. If a distro is on systemd < 230, there is no “self-linger without root” path; you’ll need root (or an admin/polkit override).
      Refer here before proceeding with lingering.

  • --enablessl – enables SSL and switches Kafka port to 9094.

Non-root agent management steps​

The exact commands depend on --setupinit:

Legacy mode (legacy) – user process:

<AGENT_HOME>/logbeat <start|stop|status>

User service (lingering) – systemd user service:

systemctl --user <start|stop|status> logbeat.service
note

Auto-start behavior (Linux non-root installs)

If the agent is not installed as a system service, it will not auto-start after reboot by default. Use one of these mechanisms:

  • Recommended: lingering user service (systemd user unit) + loginctl enable-linger
  • Alternative: a periodic cron “ensure-running” job (starts agent if not running)
  • Least reliable: start on user login via shell profile

Windows​

Root/Admin installation steps​
  1. Extract the Logbeat package.
  2. Open Command Prompt as Administrator.
  3. Run:
.\logbeat-installer.exe [--enablessl] /SILENT /NOCANCEL /DIR="<path>\logbeat" /MEMLIMIT "<MB>" /CPULIMIT "<#cores>"

Arguments

  • /DIR – optional custom install directory (default: C:\vunet\logbeat).
  • /MEMLIMIT <MB> – memory cap (default 512).
  • /CPULIMIT <#cores> – CPU cores cap (default 1).
  • --enablessl – optional, enables SSL.
Root/Admin agent management steps​

In an elevated Command Prompt:

sc <start|stop|query> logbeat
Non-root/Non-Admin installation steps​

Currently, we do not support installing the agent as a non-administrator user on Windows. If a customer specifically requires a non-admin deployment, we must implement Windows Task Scheduler–based startup (Scheduled Tasks) as an enhancement.

Uninstallation​

Linux​

cd <AGENT_HOME>
./uninstall

Windows​

cd C:\vunet\logbeat   # or your custom path
.\unins000.exe

Update resource limits​

Linux​

From AGENT_HOME:
cd $AGENT_HOME

./update --resource_cap --cpulimit <cores> --memlimit <MB>
Windows​

Edit supervisor.ini in AGENT_HOME:

[limits]
memory_mb = {MEMLIMIT}
cpu_limit = {CPULIMIT}

Supported Operating Systems​

  • Linux (Ubuntu, RHEL, CentOS, etc.)
  • Windows Server / Windows desktop (11)

Eventlogbeat​

Overview​

Eventlogbeat is a lightweight Windows agent that reads Windows Event Logs (Application, System, Security, Hardware, etc.), tracks its read offsets, and forwards events reliably to vuSmartMaps. It runs as a Windows service for continuous collection.

Prerequisites​

Network​

Allow outbound connectivity from the target host to vuSmartMaps data collection endpoints on:

  • 9092/TCP – non-SSL (Till 2.16 Build)
  • 9094/TCP – SSL (Till 2.16 Build)

Permissions​

Installation and service management must be done from an elevated Command Prompt (Run as Administrator).

  • Non-admin install on Windows is currently not supported. If required, we must implement Scheduled Tasks as an enhancement.

Installation and Management​

Windows (only)​

Root/Admin installation steps​
  1. Extract the Eventlogbeat package.
  2. Open Command Prompt as Administrator.
  3. Run:
.\eventlogbeat-installer.exe [--enablessl] /SILENT /NOCANCEL /DIR="<path>\eventlogbeat" /MEMLIMIT "<MB>" /CPULIMIT "<#cores>"

Arguments

  • /DIR – optional; default is C:\vunet\eventlogbeat.
  • /MEMLIMIT <MB> – memory cap (default 512).
  • /CPULIMIT <#cores> – CPU cores cap (default 1).
  • --enablessl – enables SSL communication to vuSmartMaps.
Root/Admin agent management steps​

In an elevated Command Prompt:

sc <start|stop|query> eventlogbeat

Uninstall / Update​

Uninstall​

cd C:\vunet\eventlogbeat   # or your custom path
.\unins000.exe

Update resource limits​

If the agent uses supervisor.ini, update:

[limits]
memory_mb = {MEMLIMIT}
cpu_limit = {CPULIMIT}

Supported Operating Systems​

  • Windows Server / Windows desktop version 11(Eventlogbeat is not available for Linux/Unix.)