This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

Hypervisor Monitoring

NetXMS can monitor virtualization platforms including VMware vSphere, KVM/libvirt, and Xen through the Virtual Machine Manager subagent (vmgr). VMware vCenter and ESXi can also be monitored through the vcenter agent extension, which does not use libvirt (see VMware vCenter Agent Extension). This enables monitoring of hypervisor hosts, virtual machines, and virtualization resource usage.

Overview

Hypervisor monitoring provides:

  • Hypervisor host information (CPU architecture, model, and frequency; memory utilization)

  • Virtual machine inventory and status

  • Per-VM resource allocation and consumption

Virtual Machine Manager Subagent

Loading the Subagent

SubAgent = vmgr

Connection Configuration

Configuration uses a main [VMGR] section listing host names, with per-host sections providing connection details:

[VMGR]
Host = esx1
Host = kvm1

[VMGR:esx1]
Url = esx://esx1.example.com/
Username = monitor
Password = your_password

[VMGR:kvm1]
Url = qemu+ssh://[email protected]/system
Username = root
Password = your_password

Per-host section parameters:

Parameter Description

Url

Libvirt connection URI (platform-specific, see examples below)

Username

Authentication user

Password

Authentication password

The subagent connects through libvirt, so the hypervisor must be reachable through a libvirt driver:

  • KVM/QEMU (qemu://, qemu+ssh://, qemu+tcp://) and Xen (xen://, xen+ssh://) URLs connect to the libvirt service on the hypervisor host: the monolithic libvirtd daemon, or the modular virtqemud (QEMU) or virtxend (Xen) daemon. The service must be available there, started or socket-activated, with its local socket (for qemu:///system) or remote transport (for the +ssh and +tcp forms) accessible.

  • VMware URLs (esx://, vpx://) connect to the ESXi or vCenter API directly and need no libvirt daemon.

The list of libvirt drivers describes what libvirt can talk to, not what runs on a given host: a KVM-based platform without libvirt cannot be monitored this way (see Unsupported Platforms).

The subagent connects to every configured host once, when the agent starts. A host that cannot be connected is skipped with the warning Unable to add host connection "<name>" with URL "<url>" in the agent log and is not retried until the agent restarts; if libvirt could not open the connection, its error is logged before this warning. The subagent also does not reopen a connection that closes later. If no host can be connected, the subagent does not load and the agent log shows No connections defined, VMGR subagent will not start.

VMware vSphere Monitoring

Connection

The esx:// libvirt driver connects to a standalone ESXi host. For an ESXi host managed by vCenter, use the vpx:// driver with the full inventory path to the host (vpx://vcenter/datacenter/cluster/esxhost):

[VMGR]
Host = esx1
Host = esx2

[VMGR:esx1]
Url = esx://esx1.example.com/
Username = root
Password = your_password

[VMGR:esx2]
Url = vpx://vcenter.example.com/DC1/Cluster1/esx2.example.com
Username = [email protected]
Password = your_password
Use a dedicated read-only monitoring account.

Host Metrics

Parameter Description

VMGR.Host.CPU.Arch(host)

Host CPU architecture

VMGR.Host.CPU.Count(host)

Number of active CPUs on the host

VMGR.Host.CPU.MaxCount(host)

Maximum number of virtual CPUs libvirt allows per guest

VMGR.Host.CPU.Model(host)

Host CPU model

VMGR.Host.CPU.Frequency(host)

Host CPU frequency

VMGR.Host.MemorySize(host)

Total host memory

VMGR.Host.FreeMemory(host)

Free host memory

VMGR.Host.ConnectionType(host)

Libvirt connection type

VMGR.Host.LibraryVersion(host)

Libvirt library version

VMGR.Host.ConnectionVersion(host)

Libvirt connection version

Virtual Machine Metrics

Per-VM metrics require both the host name and VM/domain name as arguments:

Parameter Description

VMGR.VM.Memory.Used(host,vmName)

Memory currently used by VM in bytes

VMGR.VM.Memory.UsedPrec(host,vmName)

VM memory usage as a percentage

VMGR.VM.Memory.Max(host,vmName)

Maximum memory available to VM in bytes

VMGR.VM.CPU.Count(host,vmName)

Number of virtual CPUs assigned to the VM

VMGR.VM.CPU.Time(host,vmName)

VM CPU time in nanoseconds

Tables

VMGR.VM(host)

Virtual machine list with properties. Key column: NAME.

Column Type Description

ID

UINT

VM numeric ID

NAME

STRING

VM name (key)

UUID

STRING

VM UUID

STATE

STRING

State: no state, Running, blocked on resource, paused by user, shut down, shut off, crashed, suspended by guest power management, or Unknown if the state cannot be determined

OS

STRING

OS type/architecture (e.g. hvm/x86_64)

AUTOSTART

STRING

Autostart scheduled: Yes, No, or Unknown

MEMORY

UINT64

Current memory in bytes

MAX_MEMORY

UINT64

Maximum memory in bytes

MEMORY_PREC

UINT64

Memory usage percentage

VIRTUAL_CPU_COUNT

UINT

Number of vCPUs

VIRTUAL_CPU_TIME

UINT64

CPU time in nanoseconds

CONTROL_STATE

STRING

VM control state: Ready to accept commands, Background job is running, Occupied by a running command, Unusable

STATE_DETAILS

STRING

Control state details

CONTROL_STATE_DURATION

UINT

Time in ms since entering current control state

TIME

UINT

Current VM wall clock time (seconds)

IS_PERSISTENT

STRING

Whether VM config is persistent: Yes, No, or Unknown

Other Tables

Table Description

VMGR.InterfaceList(host)

Host network interface list (column: NAME)

VMGR.VMDisks(host,vmName)

VM disks with source path, type, device type, device name, controller type, address

VMGR.VMController(host,vmName)

VM disk controllers with type, index, model

VMGR.VMInterface(host,vmName)

VM network interfaces with MAC address, type, source bridge, NIC model

VMGR.VMVideo(host,vmName)

VM video adapters with type and VRAM

VMGR.Networks(host)

Virtual networks with name, UUID, interfaces, port groups

VMGR.Storages(host)

Storage pools with name, state, capacity, allocation, available bytes

Lists

List Description

VMGR.VMHost

Configured hypervisor host names

VMGR.VMList(host)

Virtual machine names on a specific host

The VMGR.VM(host) table supports instance discovery for automatic per-VM DCI creation.

VMware vCenter Agent Extension

The vcenter agent extension monitors a VMware vCenter server or a standalone ESXi host through the VMware API, without libvirt. It is a Python script that the agent starts and supervises, and it reports CPU and memory utilization of virtual machines and hosts, datastore usage, and the inventory of virtual machines, datastores, and hosts.

The extension polls the server at startup and then VC_POLL_INTERVAL seconds after each poll, and keeps the results of the last successful poll in memory; the agent answers all metric requests from that cache, so DCI polling does not reach vCenter.

Requirements

  • Python 3 with the pyvmomi package on the agent host (pip install pyvmomi)

  • The script nxagent-vcenter.py, which the Linux agent packages install in /usr/share/netxms/extensions/vcenter/ (for a source installation, share/netxms/extensions/vcenter/ under the installation prefix). The Windows agent installer does not include it: copy it from src/agent/extensions/vcenter/ in the source archive of the same version, and give Command the full paths of the Python interpreter and the script, in double quotes if they contain spaces.

  • A vCenter or ESXi account with read access, preferably a dedicated monitoring account

Configuration

Add the extension to the agent configuration file (nxagentd.conf):

*extensions/vcenter
Mode = spawn
Command = /usr/bin/python3 /usr/share/netxms/extensions/vcenter/nxagent-vcenter.py
Environment = VC_HOST=vc.example.com
Environment = [email protected]
Environment = VC_PASSWORD=secret
DebugTag = extension.vcenter

For the other keys of an extension section, see Agent Extensions.

The script reads its settings from the environment variables set with Environment:

Variable Default Description

VC_HOST

 — 

vCenter or ESXi host name (required)

VC_USER

 — 

User name, for example [email protected] (required)

VC_PASSWORD

 — 

Password (VC_PASS is also accepted)

VC_PORT

443

API port

VC_POLL_INTERVAL

60

Poll interval in seconds

VC_VERIFY_TLS

no

Set to yes to verify the server certificate and host name against the CA certificates that Python trusts

Messages from the extension go to the agent log under the debug tag set with DebugTag (extension.vcenter if omitted), and appear only at a sufficient debug level for that tag: level 1 shows failed polls (vcenter poll failed: followed by the error), level 5 adds the script’s own output, including startup errors such as a missing pyvmomi package or a missing VC_HOST or VC_USER, and level 6 adds the messages of successful polls.

Metrics, Lists, and Tables

Virtual machines, datastores, and hosts are identified by their managed object ID (MOID), which does not change when the object is renamed; each metric takes the MOID as its argument.

Metric Description

VMware.VM.Name(*)

Virtual machine name

VMware.VM.CPUUsage(*)

CPU usage, % of the VM’s maximum CPU capacity

VMware.VM.CPUUsageMHz(*)

CPU usage (MHz)

VMware.VM.MemoryUsage(*)

Active guest memory, % of configured memory

VMware.VM.MemoryUsageBytes(*)

Active guest memory (bytes)

VMware.VM.PowerState(*)

Power state: poweredOn, poweredOff, or suspended; CPU and memory usage and uptime are 0 unless the VM is powered on

VMware.VM.UptimeSeconds(*)

Uptime in seconds

VMware.VM.StorageCommittedBytes(*)

Committed storage (bytes)

VMware.Datastore.Name(*)

Datastore name

VMware.Datastore.UsagePerc(*)

Datastore usage (%)

VMware.Datastore.FreeBytes(*)

Free space (bytes)

VMware.Datastore.CapacityBytes(*)

Capacity (bytes)

VMware.Host.Name(*)

Host name

VMware.Host.CPUUsage(*)

CPU usage, % of total host CPU capacity

VMware.Host.CPUUsageMHz(*)

CPU usage (MHz)

VMware.Host.MemoryUsage(*)

Memory usage, % of host memory

VMware.Host.MemoryUsageBytes(*)

Memory usage (bytes)

VMware.Host.NumVMs(*)

Number of virtual machines on the host, including powered-off ones

VMware.Host.ConnectionState(*)

Host connection state, for example connected, disconnected, or notResponding

The lists VMware.VMList, VMware.DatastoreList, and VMware.HostList return the MOIDs for instance discovery, and the tables VMware.VMs, VMware.Datastores, and VMware.Hosts provide inventories with selected utilization and state columns.

Template

The server includes the template VMware vCenter / ESXi Monitoring (file vmware_vcenter_esxi.json in the server’s share/templates directory, for example /usr/share/netxms/templates). The server imports it on startup as controlled by the server configuration variable Server.ImportConfigurationOnStartup; if that variable is set to Never, import the file manually with Configuration  Import configuration. After import, the template is in the template group VMware.

The template is not applied automatically: apply it to the node whose agent runs the extension. It creates DCIs for each virtual machine, datastore, and host through instance discovery on the three lists, with an instance filter that shows the object name in DCI descriptions while keeping the MOID as the instance. Its thresholds generate the VMW_* events (for example VMW_VM_CPU_HIGH and VMW_DATASTORE_FULL_CRITICAL), and the configuration file adds EPP rules that create an alarm when a threshold is reached and terminate it when the value returns to normal.

KVM/libvirt Monitoring

Connection

Connect to KVM hosts via libvirt:

[VMGR]
Host = kvm1
Host = local

[VMGR:kvm1]
Url = qemu+ssh://[email protected]/system
Username = root

[VMGR:local]
Url = qemu:///system

Connection URL formats:

  • qemu:///system — local connection

  • qemu+ssh://user@host/system — SSH-tunneled connection

  • qemu+tcp://host/system — TCP connection

Available Metrics

KVM/libvirt monitoring provides the same VMGR.Host.* and VMGR.VM.* metrics as listed above.

Xen Monitoring

Xen can be monitored in two ways: via libvirt (using the vmgr subagent) or directly using the Xen-specific subagent (xen).

Via libvirt (vmgr)

The libvirt xen:// driver connects to the libxl stack on a Xen dom0 host. It does not work with Citrix XenServer / Citrix Hypervisor.

[VMGR]
Host = xen1

[VMGR:xen1]
Url = xen+ssh://[email protected]/system
Username = root
Password = your_password

This provides the same VMGR.* metrics as for KVM and VMware.

Direct Xen Subagent

The xen subagent connects directly to the local Xen hypervisor via libxl. It must run on the Xen dom0. No configuration is required beyond loading the subagent.

SubAgent = xen

Host Metrics

Parameter Description

XEN.Host.Version

Xen hypervisor version string

XEN.Host.CPU.Cores

Number of CPU cores

XEN.Host.CPU.LogicalCount

Number of logical CPUs

XEN.Host.CPU.PhysicalCount

Number of physical CPUs

XEN.Host.CPU.Online

Currently online CPUs

XEN.Host.CPU.Frequency

CPU frequency in KHz

XEN.Host.CPU.CurrentUsage

Host CPU utilization, current snapshot (%)

XEN.Host.CPU.Usage

Host CPU utilization, 1-minute average (%)

XEN.Host.CPU.Usage5

Host CPU utilization, 5-minute average (%)

XEN.Host.CPU.Usage15

Host CPU utilization, 15-minute average (%)

XEN.Host.Memory.Total

Total host memory in bytes

XEN.Host.Memory.Free

Free host memory in bytes

XEN.Host.Memory.FreePerc

Free memory percentage

XEN.Host.Memory.Used

Used host memory in bytes

XEN.Host.Memory.UsedPerc

Used memory percentage

XEN.Host.Memory.Outstanding

Outstanding claimed memory in bytes

XEN.Host.Memory.OutstandingPerc

Outstanding claimed memory percentage

XEN.Host.Memory.Scrub

Memory being scrubbed, in bytes

XEN.Host.Memory.ScrubPerc

Memory being scrubbed, percentage

Domain (VM) Metrics

All domain metrics accept the domain name or numeric ID as the argument.

Parameter Description

XEN.Domain.CPU.CurrentUsage(dom)

Domain current CPU utilization (%)

XEN.Domain.CPU.Usage(dom)

Domain 1-minute average CPU utilization (%)

XEN.Domain.CPU.Usage5(dom)

Domain 5-minute average CPU utilization (%)

XEN.Domain.CPU.Usage15(dom)

Domain 15-minute average CPU utilization (%)

XEN.Domain.IsExist(dom)

1 if domain exists, 0 otherwise

XEN.Domain.IsOperational(dom)

1 if domain is running or blocked

XEN.Domain.IsPaused(dom)

1 if domain is paused

XEN.Domain.State(dom)

Domain state: RUNNING, BLOCKED, PAUSED, SHUTDOWN, DYING, MISSING, UNKNOWN

XEN.Domain.Net.RxBytes(dom)

Total bytes received across all domain vifs

XEN.Domain.Net.TxBytes(dom)

Total bytes transmitted

XEN.Domain.Net.RxPackets(dom)

Total packets received

XEN.Domain.Net.TxPackets(dom)

Total packets transmitted

Xen Tables

XEN.Domains — domain table with ID, name, state (single string column), memory (current/shared/paged/outstanding/max), vCPU count, CPU time, CPU usage (current and 1-minute average), and network I/O.

XEN.Net.DomainInterfaces — all domain network interfaces with vif name, domain ID/name, network ID, bridge, MAC address, IP, NIC model, and per-interface byte/packet counters.

Xen Lists

List Description

XEN.Domains

All domain names (including dom0)

Unsupported Platforms

Proxmox VE manages its virtual machines with QEMU directly, not through libvirt, so the vmgr subagent cannot monitor them. On a standard Proxmox VE installation, a qemu:///system connection fails with an error such as Failed to connect socket to '/var/run/libvirt/libvirt-sock': No such file or directory. The host itself can be monitored with the agent like any Linux server, and agents installed in the guests report normally; only the host-level virtual machine inventory and per-VM metrics of the vmgr subagent are not available.

Guest Agent Integration

For in-depth guest OS monitoring, install the NetXMS agent inside virtual machines. This provides:

  • Full OS-level metrics (same as OS monitoring)

  • Application-level monitoring

  • Log monitoring

  • File system monitoring

The VM subagent metrics complement guest agent monitoring by providing the hypervisor-level view (allocated resources, host-side performance).

For nodes that run as virtual machines, the server detects the hypervisor type and hypervisor information during the configuration poll and shows them in the node properties. Virtual machines are not automatically linked to their hypervisor hosts in the object tree.

Troubleshooting

vCenter Agent Extension Issues

The extension is not connected (Agent.Extension.IsConnected(vcenter) returns 0)

The script exits at startup. Set the debug level of the extension’s tag to 5 and check the agent log for the reason, for example a missing pyvmomi package or a missing VC_HOST or VC_USER.

The extension is connected, but the lists are empty or the values do not change

The connection to the agent says nothing about the connection to vCenter. A failed poll is logged at debug level 1 as vcenter poll failed: with the error, for example a TLS, authentication, or network error. The extension tries again at the next poll interval and keeps serving the data of the last successful poll, without a time limit, so the values can be stale; before the first successful poll the lists and tables are empty.

VMware Connection Issues (libvirt)

  1. Verify the vCenter/ESXi URL and credentials

  2. Check that the monitoring account has read-only permissions

  3. Verify network access from the agent host to the vCenter/ESXi management interface

  4. Check agent log for libvirt errors, logged under the vmgr debug tag

KVM/libvirt Connection Issues

  1. Verify SSH key authentication is configured (for SSH-tunneled connections)

  2. Check libvirt is running on the KVM host

  3. Verify the monitoring user has permissions to query libvirt

  4. Test connection with virsh -c <url> list

  5. Restart the agent after fixing the connection: a host that failed to connect at startup is not retried