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.

Subagents

Subagents extend the NetXMS agent with additional monitoring capabilities. Each subagent is a loadable module (shared library) that registers new metrics, lists, tables, and actions with the agent.

For metrics provided by the agent core and subagents, see Agent Metrics Reference. For agent configuration file syntax, see Agent Configuration.

Loading Subagents

Subagents are loaded through the agent configuration file:

SubAgent = logwatch
SubAgent = filemgr
SubAgent = dbquery

In SubAgent, the .nsm extension (NetXMS Subagent Module) is optional; when it is omitted, the agent appends it, so SubAgent = logwatch loads logwatch.nsm. On UNIX-like systems, the agent searches for subagent files in its library directory (typically /usr/lib/netxms on Linux). On Windows, subagent DLLs are installed into the agent’s bin directory and found through the default DLL search path.

Subagents can also be loaded via agent configuration policies (see Agent Policies).

Platform Subagents

Platform subagents provide operating system-specific metrics. They are the primary source for OS monitoring data:

Subagent Platform Description

linux

Linux

CPU, memory, disk, network, process metrics for Linux systems

winnt

Windows

System metrics for Windows, including the Net.Interfaces table; scope and lease information from the Microsoft DHCP Server role (see DHCP Server Monitoring)

freebsd

FreeBSD

System metrics for FreeBSD

netbsd

NetBSD

System metrics for NetBSD

openbsd

OpenBSD

System metrics for OpenBSD

sunos

Solaris

System metrics for Solaris/SunOS

aix

AIX

System metrics for IBM AIX

darwin

macOS

System metrics for macOS

The platform subagent is loaded automatically on all platforms: on UNIX-like systems the agent derives the module name from the operating system name reported by uname (e.g., linux), and on Windows it loads winnt (a separate module, not built into the agent). An explicit SubAgent entry for the platform subagent is unnecessary when automatic loading is enabled.

Feature Subagents

Feature subagents add specific monitoring capabilities:

Subagent Description

aifileops

AI file operations — provides file search and content analysis tools for the AI assistant. Requires at least one RootFolder entry in the [aifileops] section; modifying tools are available to master servers only. See AI Assistant.

asterisk

Asterisk PBX monitoring — collects call statistics, channel data, and SIP registration status. See Asterisk Monitoring.

bind9

BIND 9 DNS server — collects name server statistics (query results, requests, zone transfers, dynamic updates, NOTIFY messages) from the JSON statistics channel of BIND 9. See BIND 9 DNS Server Monitoring.

dbquery

Database query — executes SQL queries against databases and returns results as metrics. See Database Monitoring.

devemu

Device emulator — emulates devices for testing purposes.

dnsmasq

dnsmasq DHCP server — reads DHCP scopes, reservations, and leases from the dnsmasq configuration and lease files (UNIX-like systems). See DHCP Server Monitoring.

ds18x20

DS18x20 temperature sensors — reads temperature from 1-Wire DS18x20 sensors. See Hardware Monitoring.

ecs

Deprecated — legacy alias for netsvc. Automatically redirected. See Service Monitoring.

entsoe

ENTSO-E — collects electricity generation, forecasts, and cross-border flows from the ENTSO-E Transparency Platform and derives carbon intensity. See ENTSO-E Grid Data.

fbdev

Framebuffer screenshots — captures screenshots from Linux framebuffer devices (/dev/fb*) for systems without a desktop session. See Framebuffer Screenshots.

filemgr

Remote file management — browse, view, download, and upload files on the agent host. See Remote File Management.

gps

GPS receiver — reads location data from GPS devices connected via serial port. See GPS Receiver Subagent.

informix

IBM Informix monitoring — collects database metrics. See Database Monitoring.

java

Java subagent — loads Java-based monitoring plugins (Docker, JMX, OPC UA, Ubiquiti LiteWave). See Java Subagent below.

kea

ISC Kea DHCP server — reads DHCPv4 and DHCPv6 scopes, reservations, and leases through the Kea control sockets (UNIX-like systems). See DHCP Server Monitoring.

lldpd

lldpd integration — provides LLDP topology information collected by the lldpd daemon.

lmsensors

lm-sensors — reads hardware sensor data via Linux lm-sensors. See Hardware Monitoring.

logwatch

Log file monitoring — watches log files for patterns and generates events. See Log Monitoring.

mongodb

MongoDB — monitors MongoDB instances. See Database Monitoring.

mqtt

MQTT client — subscribes to MQTT topics and collects data from IoT brokers.

mssql

Microsoft SQL Server monitoring — collects SQL Server database metrics. See Database Monitoring.

mysql

MySQL monitoring — collects MySQL/MariaDB database metrics. See Database Monitoring.

netconf

NETCONF — proxy for NETCONF data collection and device configuration backup. See NETCONF Monitoring.

netsvc

Network service checks — HTTP, SMTP, POP3, SSH, and custom TCP service monitoring. See Service Monitoring.

oracle

Oracle Database monitoring — collects Oracle database metrics. See Database Monitoring.

pgsql

PostgreSQL monitoring — collects PostgreSQL database metrics. See Database Monitoring.

ping

ICMP ping from the agent — allows the agent to perform ping checks to specified targets. See ICMP Monitoring.

portcheck

Deprecated — legacy alias for netsvc. Automatically redirected. See Service Monitoring.

prometheus

Prometheus metrics — scrapes Prometheus and OpenMetrics endpoints and receives Prometheus remote write data. See Prometheus Monitoring.

redis

Redis monitoring — collects Redis server metrics. See Redis Subagent.

rpi

Raspberry Pi — reads GPIO, temperature, and voltage metrics from Raspberry Pi. See Hardware Monitoring.

sms

SMS sending — sends SMS messages through a serial GSM modem. See NXAgent notification driver.

ssh

SSH monitoring — executes commands on remote hosts via SSH. See SSH Monitoring.

tuxedo

Oracle Tuxedo and Enduro/X — reads domain, machine, client, queue, server, service, and service group information through the .TMIB service; built from source for either product (UNIX-like systems). See Oracle Tuxedo and Enduro/X Monitoring.

ups

UPS monitoring — collects data from UPS devices via USB or serial connections. See UPS Monitoring.

vmgr

Virtual Machine Manager — monitors hypervisors (VMware, Xen, KVM). See Hypervisor Monitoring.

weather

Weather data — collects current conditions and forecasts from Open-Meteo, MET Norway, or Bright Sky as a data source for correlation and trend prediction. See Weather Data.

wineventsync

Windows Event Log synchronization — forwards Windows Event Log entries to the server (Windows only). See Windows Event Log.

winperf

Windows performance counters — provides access to all Windows performance counter objects (Windows only).

wmi

WMI queries — executes WMI queries on Windows systems (Windows only).

xen

Xen hypervisor — monitors Xen virtualization hosts.

Java Subagent

The Java subagent (java) provides a framework for loading Java-based monitoring plugins within the agent process. It starts a JVM inside the agent and loads plugin JAR files.

Java Subagent Configuration

SubAgent = java

[JAVA]
JVM = /usr/lib/jvm/java-17/lib/server/libjvm.so
JVMOptions = -Xmx256m
ClassPath = /opt/netxms/java/plugins/*
Plugin = jmx.jar
Plugin = docker.jar
Parameter Default Description

JVM

libjvm.so / jvm.dll

Full path to the JVM shared library. The default is the bare library name (libjvm.so on UNIX-like systems, jvm.dll on Windows), resolved through the loader’s standard library search path.

JVMOptions

(none)

JVM command-line options (e.g., -Xmx512m, -XX:+UseG1GC). Can be specified multiple times.

ClassPath

(none)

Additional entries for the Java classpath. Can be specified multiple times. Supports wildcards.

Plugin

(none)

Java plugin JAR file to load. Can be specified multiple times. Plugin entries are read from the [JAVA] section by the Java side of the subagent.

Available Java Plugins

Plugin Description

docker.jar

Docker container monitoring — collects container metrics and status.

jmx.jar

JMX monitoring — connects to Java applications via JMX and collects MBean attributes. See JVM Monitoring.

opcua.jar

OPC UA client — reads data from OPC UA servers (industrial automation).

ubntlw.jar

Ubiquiti LiteWave — monitors Ubiquiti LiteWave devices.

The ExternalSubagent configuration parameter is not related to Java plugins. It registers a standalone external subagent connection by name, optionally restricted to an OS user: ExternalSubagent = name[:allowed OS user].

Subagent Configuration

Some subagents require additional configuration sections in the agent configuration file. A section header is written as [SECTION] (the older *SECTION form is still accepted):

SubAgent = dbquery

[DBQUERY]
Database = id=mydb;driver=pgsql;server=db.example.com;dbname=appdb;login=monitor;password=secret
Query = AppUsers:mydb:SELECT count(*) FROM active_users

Each subagent documents its configuration options. Refer to the specific monitoring module documentation for configuration details.

Listing Available Metrics

To see all metrics provided by loaded subagents, query the agent remotely using nxget:

nxget -I <agent_address>

This lists the scalar metrics registered by the agent core and all loaded subagents. To enumerate lists and tables, query nxget -l <agent_address> Agent.SupportedLists and nxget -l <agent_address> Agent.SupportedTables.

From the management client, available metrics can also be browsed in the metric selection dialog when creating or editing a DCI — the list shows all metrics reported by the agent, including those from subagents.

Writing Custom Subagents

Custom subagents can be written in C/C++ using the NetXMS subagent SDK. A subagent implements the standard subagent interface and registers its metrics with the agent framework.

The subagent API provides functions for:

  • Registering metrics (single value metrics)

  • Registering lists (multi-value metrics)

  • Registering tables (tabular data)

  • Registering actions (executable commands)

  • Accessing agent configuration

  • Sending events to the server

For external scripts and tools, consider using external metrics and actions in the agent configuration instead of writing a native subagent. See Agent Configuration for details on external metrics.

Development Resources

The NetXMS source code includes example subagents and the full SDK headers. The recommended approach for developing custom subagents:

  1. Clone the NetXMS source repository

  2. Study the existing subagent implementations under src/agent/subagents/ for patterns and best practices

  3. Use the subagent header files in include/ for the API definitions

  4. Build using the NetXMS build system

For most monitoring extensions, external metrics (ExternalMetric, ExternalList, ExternalTable) or NXSL scripts provide a simpler alternative to writing native subagents.

Troubleshooting Subagents

Subagent Fails to Load

Check the agent log for error messages:

[ERROR] Cannot load subagent "mysubagent.nsm": libmylib.so: cannot open shared object file

Common causes:

  • Missing shared library dependencies — install required libraries

  • Wrong architecture — the subagent must match the agent’s architecture (32-bit vs 64-bit)

  • Incorrect file path — verify the module exists in the agent’s library directory

Subagent Metrics Not Available

  1. Verify the subagent is loaded: query remotely with nxget -I <agent_address> to check if expected metrics are available

  2. Check if the subagent requires a configuration section (e.g., [DBQUERY])

  3. Restart the agent after configuration changes

  4. Check agent log for subagent initialization errors