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.nsm
SubAgent = filemgr.nsm
SubAgent = dbquery.nsm

The .nsm extension is the standard subagent module extension (NetXMS Subagent Module). 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

Subagent	Platform	Description
`linux.nsm`	Linux	CPU, memory, disk, network, process metrics for Linux systems
`winnt.nsm`	Windows	System metrics for Windows
`freebsd.nsm`	FreeBSD	System metrics for FreeBSD
`netbsd.nsm`	NetBSD	System metrics for NetBSD
`openbsd.nsm`	OpenBSD	System metrics for OpenBSD
`sunos.nsm`	Solaris	System metrics for Solaris/SunOS
`aix.nsm`	AIX	System metrics for IBM AIX
`darwin.nsm`	macOS	System metrics for macOS

linux.nsm

Linux

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

winnt.nsm

Windows

System metrics for Windows

freebsd.nsm

FreeBSD

System metrics for FreeBSD

netbsd.nsm

NetBSD

System metrics for NetBSD

openbsd.nsm

OpenBSD

System metrics for OpenBSD

sunos.nsm

Solaris

System metrics for Solaris/SunOS

aix.nsm

AIX

System metrics for IBM AIX

darwin.nsm

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.nsm), and on Windows it loads winnt.nsm (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

Subagent	Description
`aifileops.nsm`	AI file operations — provides file search and content analysis tools for the AI assistant. See AI Assistant.
`asterisk.nsm`	Asterisk PBX monitoring — collects call statistics, channel data, and SIP registration status. See Asterisk Monitoring.
`bind9.nsm`	BIND 9 DNS — collects BIND 9 DNS server statistics.
`dbquery.nsm`	Database query — executes SQL queries against databases and returns results as metrics. See Database Monitoring.
`devemu.nsm`	Device emulator — emulates devices for testing purposes.
`ds18x20.nsm`	DS18x20 temperature sensors — reads temperature from 1-Wire DS18x20 sensors. See Hardware Monitoring.
`ecs.nsm`	Deprecated — legacy alias for `netsvc.nsm`. Automatically redirected. See Service Monitoring.
`entsoe.nsm`	ENTSO-E — collects European electricity market and grid data from the ENTSO-E Transparency Platform.
`fbdev.nsm`	Framebuffer screenshots — captures screenshots from the Linux framebuffer device.
`filemgr.nsm`	Remote file management — browse, view, download, and upload files on the agent host. See Remote File Management.
`gps.nsm`	GPS receiver — reads location data from GPS devices connected via serial port.
`informix.nsm`	IBM Informix monitoring — collects database metrics. See Database Monitoring.
`java.nsm`	Java subagent — loads Java-based monitoring plugins (Docker, JMX, OPC UA, Ubiquiti LiteWave). See Java Subagent below.
`lldpd.nsm`	lldpd integration — provides LLDP topology information collected by the `lldpd` daemon.
`lmsensors.nsm`	lm-sensors — reads hardware sensor data via Linux lm-sensors. See Hardware Monitoring.
`logwatch.nsm`	Log file monitoring — watches log files for patterns and generates events. See Log Monitoring.
`mongodb.nsm`	MongoDB — monitors MongoDB instances. See Database Monitoring.
`mqtt.nsm`	MQTT client — subscribes to MQTT topics and collects data from IoT brokers.
`mssql.nsm`	Microsoft SQL Server monitoring — collects SQL Server database metrics. See Database Monitoring.
`mysql.nsm`	MySQL monitoring — collects MySQL/MariaDB database metrics. See Database Monitoring.
`netconf.nsm`	NETCONF — communicates with network devices using the NETCONF protocol.
`netsvc.nsm`	Network service checks — HTTP, SMTP, POP3, SSH, and custom TCP service monitoring. See Service Monitoring.
`openmeteo.nsm`	Open-Meteo — collects weather data from the Open-Meteo service.
`oracle.nsm`	Oracle Database monitoring — collects Oracle database metrics. See Database Monitoring.
`pgsql.nsm`	PostgreSQL monitoring — collects PostgreSQL database metrics. See Database Monitoring.
`ping.nsm`	ICMP ping from the agent — allows the agent to perform ping checks to specified targets. See ICMP Monitoring.
`portcheck.nsm`	Deprecated — legacy alias for `netsvc.nsm`. Automatically redirected. See Service Monitoring.
`prometheus.nsm`	Prometheus exporter — scrapes Prometheus-format metrics endpoints.
`redis.nsm`	Redis monitoring — collects Redis server metrics.
`rpi.nsm`	Raspberry Pi — reads GPIO, temperature, and voltage metrics from Raspberry Pi. See Hardware Monitoring.
`sms.nsm`	SMS sending — sends SMS messages through a serial GSM modem.
`ssh.nsm`	SSH monitoring — executes commands on remote hosts via SSH. See SSH Monitoring.
`tuxedo.nsm`	Oracle Tuxedo — monitors Oracle Tuxedo middleware.
`ups.nsm`	UPS monitoring — collects data from UPS devices via USB or serial connections. See UPS Monitoring.
`vmgr.nsm`	Virtual Machine Manager — monitors hypervisors (VMware, Xen, KVM). See Hypervisor Monitoring.
`wineventsync.nsm`	Windows Event Log synchronization — forwards Windows Event Log entries to the server (Windows only). See Windows Event Log.
`winperf.nsm`	Windows performance counters — provides access to all Windows performance counter objects (Windows only).
`wmi.nsm`	WMI queries — executes WMI queries on Windows systems (Windows only).
`xen.nsm`	Xen hypervisor — monitors Xen virtualization hosts.

aifileops.nsm

AI file operations — provides file search and content analysis tools for the AI assistant. See AI Assistant.

asterisk.nsm

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

bind9.nsm

BIND 9 DNS — collects BIND 9 DNS server statistics.

dbquery.nsm

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

devemu.nsm

Device emulator — emulates devices for testing purposes.

ds18x20.nsm

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

ecs.nsm

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

entsoe.nsm

ENTSO-E — collects European electricity market and grid data from the ENTSO-E Transparency Platform.

fbdev.nsm

Framebuffer screenshots — captures screenshots from the Linux framebuffer device.

filemgr.nsm

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

gps.nsm

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

informix.nsm

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

java.nsm

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

lldpd.nsm

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

lmsensors.nsm

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

logwatch.nsm

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

mongodb.nsm

MongoDB — monitors MongoDB instances. See Database Monitoring.

mqtt.nsm

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

mssql.nsm

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

mysql.nsm

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

netconf.nsm

NETCONF — communicates with network devices using the NETCONF protocol.

netsvc.nsm

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

openmeteo.nsm

Open-Meteo — collects weather data from the Open-Meteo service.

oracle.nsm

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

pgsql.nsm

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

ping.nsm

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

portcheck.nsm

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

prometheus.nsm

Prometheus exporter — scrapes Prometheus-format metrics endpoints.

redis.nsm

Redis monitoring — collects Redis server metrics.

rpi.nsm

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

sms.nsm

SMS sending — sends SMS messages through a serial GSM modem.

ssh.nsm

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

tuxedo.nsm

Oracle Tuxedo — monitors Oracle Tuxedo middleware.

ups.nsm

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

vmgr.nsm

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

wineventsync.nsm

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

winperf.nsm

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

wmi.nsm

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

xen.nsm

Xen hypervisor — monitors Xen virtualization hosts.

Java Subagent

The Java subagent (java.nsm) 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.nsm

[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

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.

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

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.

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 either as *SECTION or [SECTION]:

SubAgent = dbquery.nsm

[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 all metrics, lists, and tables registered by the agent core and all loaded subagents.

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:

Clone the NetXMS source repository
Study the existing subagent implementations under src/agent/subagents/ for patterns and best practices
Use the subagent header files in include/ for the API definitions
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

Verify the subagent is loaded: query remotely with nxget -I <agent_address> to check if expected metrics are available
Check if the subagent requires a configuration section (e.g., [DBQUERY])
Restart the agent after configuration changes
Check agent log for subagent initialization errors