Agent Configuration

This section is a reference for the NetXMS agent (nxagentd) configuration file syntax, security settings, and core parameters.

For agent installation steps, see the installation guide for Linux or Windows. For extending the agent with custom metrics, actions, and data providers, see External Metrics, Actions, and Data Providers.

Configuration File

The agent configuration file is nxagentd.conf. The file uses a simple Key = Value format. Lines starting with # are comments. The agent reads the configuration file at startup; changes require an agent restart unless applied via policy (see Agent Policies).

Configuration File Search Order

If no configuration file is specified on the command line (-c option), the agent searches for nxagentd.conf in the following order:

UNIX/Linux/macOS:

  1. $NETXMS_HOME/etc/nxagentd.conf (if NETXMS_HOME environment variable is set)

  2. SYSCONFDIR/nxagentd.conf (compile-time prefix, typically /usr/local/etc or /usr/etc)

  3. /etc/nxagentd.conf (fallback)

Windows:

  1. Path from the ConfigFile value under registry key HKEY_LOCAL_MACHINE\SOFTWARE\NetXMS\Agent, if set

  2. <InstallDir>\etc\nxagentd.conf (installation directory from the same registry key)

  3. C:\nxagentd.conf (fallback)

In addition to the main configuration file, the agent loads all files from the configuration include directory (see Configuration Include Directory).

INI Syntax

# This is a comment
MasterServers = 10.0.0.1
LogFile = /var/log/nxagentd.log
SubAgent = linux.nsm

Boolean parameters accept yes/no, true/false, or 1/0. Parameters that accept multiple values (like SubAgent or ServerConnection) can be specified multiple times.

XML Syntax

The agent configuration can also be written in XML format. XML configuration is useful for programmatic generation and when using configuration management tools:

<config>
  <CORE>
    <MasterServers>10.0.0.1</MasterServers>
    <LogFile>/var/log/nxagentd.log</LogFile>
    <SubAgent>linux.nsm</SubAgent>
    <SubAgent>logwatch.nsm</SubAgent>
    <ServerConnection>server.example.com</ServerConnection>
  </CORE>
  <DBQUERY>
    <Database>id=mydb;driver=pgsql;server=db.example.com;dbname=appdb</Database>
    <Query>AppUsers:mydb:SELECT count(*) FROM active_users</Query>
  </DBQUERY>
</config>

In XML format, INI section names become XML elements under the root <config> element; core agent parameters (those outside any INI section) go into the <CORE> element. Parameters keep their flat string values — for example, ServerConnection is a single string value, repeated as multiple <ServerConnection> elements for multiple servers. Configuration files in JSON format are also supported.

Server Access Control

Four parameters control which servers can communicate with the agent, each providing a different access level:

Parameter Description

MasterServers

Full control: can read data, execute actions, upload files, change agent configuration, restart the agent, upgrade the agent, and install software packages. Typically only the primary NetXMS server.

ControlServers

Intermediate access: can read data and execute predefined actions, including agent restart via the built-in Agent.Restart action. Cannot change the agent configuration.

Servers

Read-only access: can read metrics and agent metadata, browse and download files, and use enabled proxy functions. Cannot execute actions.

UpgradeServers

Servers allowed to perform remote agent upgrades and install software packages without full master access.

Each parameter accepts a comma-separated list of IP addresses, hostnames, or CIDR subnets:

MasterServers = 10.0.0.1, 10.0.0.2
ControlServers = 10.0.1.0/24
Servers = 192.168.0.0/16
A connecting server is granted the access level of the list it matches (the highest level, if it matches several). A server not listed in any of MasterServers, ControlServers, Servers, or UpgradeServers cannot connect to the agent.

Access Level Matrix

The following table shows the full set of operations available at each access level:

Operation Master Control Servers

Read metrics, lists, and table metrics

X

X

X

Web service proxy

X

X

X

Modbus proxy

X

X

X

SNMP trap proxy

X

X

X

Syslog proxy

X

X

X

TFTP proxy

X

X

X

File manager read operations (browse, download, folder size)

X

X

X

Execute actions

X

X

Restart agent (built-in Agent.Restart action)

X

X

Take screenshots

X

X

Edit agent main configuration file

X

Remote agent upgrade (also servers in UpgradeServers)

X

Install software packages (also servers in UpgradeServers)

X

Deploy and undeploy agent policies

X

File manager write operations (upload, delete, rename, move)

X

File manager follow (tail) mode

X

Send notifications via user support application

X

Run commands in backticks for File.* metrics

X

Use File.Content() metric

X

SNMP.ScanAddressRange() and TCP.ScanAddressRange()

X

Agent, SNMP, TCP proxy operation

X

Authentication and Encryption

Shared Secret

To authenticate server-agent communication, configure a shared secret on both sides:

SharedSecret = MySecretPassphrase
RequireAuthentication = yes

The same shared secret must be configured on the NetXMS server — in node properties, or under Configuration > Network Credentials in the management client.

When RequireAuthentication is set to yes, connections without valid authentication are rejected. Use nxencpasswd -a to generate an obfuscated shared secret for use in configuration files.

Encryption

Direct agent-server communication is protected by NXCP session encryption (the native agent protocol encryption). By default, encryption is required (RequireEncryption = yes).

The agent and server negotiate the strongest mutually supported cipher.

TLS is used for agent tunnel connections in both directions — agent-initiated tunnels and server-initiated TLS connections to the agent’s listener port (see Agent Tunnels). Setting RequireTLS = yes makes the agent reject legacy protocol connections, forcing servers to connect over TLS; do not enable it on agents reachable only through an agent proxy.

The server-side encryption policy for agent connections is controlled by the Agent.DefaultEncryptionPolicy configuration variable:

Value Policy Description

0

Disabled

Encryption is not used. Connections fail if the agent has RequireEncryption = yes.

1

Allow encryption

Communication is unencrypted unless the agent requires encryption (RequireEncryption = yes) or the node property "Force encryption" is set. This is the default.

2

Prefer encryption

Uses encryption if the agent supports it, falls back to unencrypted otherwise.

3

Require encryption

Always encrypted. Connections to agents without encryption support are rejected.

This policy can be overridden per node in node properties.

Certificate Verification

For environments requiring mutual TLS authentication, the agent can verify server certificates:

VerifyServerCertificate = yes
TrustedRootCertificate = /etc/nxagentd/ca-cert.pem

The TrustedRootCertificate parameter can be specified multiple times to trust multiple CA certificates. Certificate Revocation Lists (CRLs) can also be configured:

CRL = /etc/nxagentd/crl.pem
CRLReloadInterval = 7200

Startup and Logging

Parameter Default Description

LogFile

(platform-dependent)

Path to log file (/var/log/nxagentd on Linux, C:\nxagentd.log on Windows), or a special value: {syslog} (syslog), {eventlog} (Windows Event Log), {systemd} (systemd journal), {stdout} (standard output)

LogHistorySize

4

Number of rotated log files to keep

LogRotationMode

2

0=no rotation, 1=daily, 2=by size

MaxLogSize

16777216

Maximum log file size in bytes (when rotation mode=2)

DebugLevel

0

Debug verbosity (0-9)

DebugTags

(none)

Tag-specific debug levels (e.g., tunnel:7,poll:5)

WriteLogAsJson

No

Write log entries in JSON format

BackgroundLogWriter

No

Use background thread for log writing

FileStore

/tmp

Directory used for file transfer operations

DataDirectory

(platform-dependent)

Directory for agent persistent data (agent ID, certificates)

StartupDelay

0

Delay in seconds before agent starts accepting connections after launch

WaitForProcess

(none)

Process name to wait for before starting agent operation

Debug Tags

Debug tags allow fine-grained control over debug output. Instead of increasing the global debug level (which produces excessive output), you can enable verbose logging for specific subsystems:

DebugLevel = 3
DebugTags = tunnel:7,poll.status:5,snmp.proxy:6

The format is tag:level where tag is a subsystem name and level is 0-9.

Subagent Loading

Load subagent modules to extend agent capabilities:

SubAgent = linux.nsm
SubAgent = dbquery.nsm
SubAgent = logwatch.nsm

The EnableSubagentAutoload parameter (default: yes) automatically loads platform-appropriate subagents (e.g., linux.nsm on Linux, winnt.nsm on Windows).

See Subagents for available subagent modules.

External Subagents

External subagents are standalone processes that communicate with the agent through a named pipe or local socket. They are used when a monitoring plugin needs to run as a separate process (e.g., for isolation or different runtime requirements):

ExternalSubagent = MYSUBAGENT:*

The value format is name:user, where name is the external subagent connection name and user is the operating system account allowed to connect to the communication channel (* allows any user).

Configuration Include Directory

In addition to the main configuration file, the agent loads all files found in the configuration include directory. By default the agent searches for a nxagentd.conf.d directory in the same locations as the main configuration file (typically ending up next to nxagentd.conf).

The location can be overridden with the NXAGENTD_CONFIG_D environment variable (UNIX/Linux) or the ConfigIncludeDir value under registry key HKEY_LOCAL_MACHINE\SOFTWARE\NetXMS\Agent (Windows).

This is useful for separating custom parameters from the base configuration, especially when using configuration management tools.

Proxy Configuration

The agent can act as a proxy for various protocols, forwarding requests to devices not directly reachable from the server. See Agent Proxies for detailed proxy setup.

# Enable specific proxy functions as needed
EnableProxy = yes
EnableSNMPProxy = yes
EnableSNMPTrapProxy = yes
EnableSyslogProxy = yes
EnableModbusProxy = yes
EnableTCPProxy = yes
EnableWebServiceProxy = yes

# SNMP trap proxy settings
SNMPTrapListenAddress = *
SNMPTrapPort = 162

# Syslog proxy settings
SyslogListenPort = 514

Zone Configuration

In multi-zone deployments where agents in different network segments may have overlapping IP addresses, assign each agent to a zone:

ZoneUIN = 5

Zone 0 is the default zone. Each zone operates as an independent IP address space within NetXMS.

Agent Registration

The agent generates a unique ID on first startup, stored in the agent’s local database (with a backup copy in the nxagentd.id file in the data directory). This ID is used for agent tunnel binding and identification.

Self-Registration

An agent can register itself with the server automatically using the -r flag:

nxagentd -r <server_address>

This connects to the server’s client port (4701) and sends a registration request. The server must have Agent.EnableRegistration set to 1 (default) for this to work. The server passes the registered address through the network discovery pipeline (bypassing the discovery filter), which creates a node object for the agent.

Agent Config Files on Server

The agent can download its configuration from the server on startup using the -M flag:

nxagentd -M <server_address>

This causes the agent to connect to the specified server and request a matching configuration file. The server evaluates filter scripts on each stored configuration to determine which one to send.

To manage agent config files on the server, navigate to Configuration > Agent Configurations in the management client. Each configuration entry has:

  • Name — identifier for the configuration

  • Filter script — NXSL script that determines whether this configuration matches the requesting agent

  • Configuration file content — the nxagentd.conf content to send

The filter script receives the following arguments:

Variable Description

$1

IP address of the requesting agent

$2

Platform name (e.g., Linux-x86_64, windows-x64)

$3

Major version number

$4

Minor version number

$5

Release number

The script must return true to indicate a match. Configurations are evaluated in order; the first matching configuration is sent to the agent.

Example filter script that matches all Linux agents (platform names are case-sensitive, e.g. Linux-x86_64):

return ($2 ~= "^Linux");

Example filter script matching agents in a specific subnet:

return (InetAddress($1).inSubnet("10.0.5.0", 24));

When the agent receives a configuration, it overwrites its local nxagentd.conf file. If no matching configuration is found on the server, the agent uses its existing local configuration. If no local configuration exists either, the agent logs a warning and starts with built-in default settings.

The -M feature requires a direct connection to the server and does not work with agent tunnel connections.

Identity Reset

The agent ID is stored in the agent’s local database, with a backup copy in the nxagentd.id file in the data directory (/var/lib/netxms on Linux). To reset the agent identity (e.g., after cloning a VM), stop the agent and run:

nxagentd -T

The -T (--reset-identity) option resets the stored agent ID and removes the contents of the agent certificate directory, discarding certificates issued for the old identity. A new agent ID is generated on the next agent start.

Complete Parameter Reference

Server Access Control

Parameter Default Description

MasterServers

(none)

Comma-separated list of server addresses (IP, hostname, or CIDR) with full control: read data, execute actions, modify config, restart agent, upgrade agent, install packages, upload files.

ControlServers

(none)

Servers with intermediate access: read data and execute predefined actions (including agent restart via the Agent.Restart action). Cannot change the agent configuration.

Servers

(none)

Servers with read-only access: query metrics and agent metadata, browse and download files, use enabled proxy functions. Cannot execute actions.

UpgradeServers

(none)

Servers allowed to perform remote agent upgrades and install software packages without full master access.

SharedSecret

admin

Shared secret for server-agent authentication. Must match the secret configured on the server for this node.

RequireAuthentication

No

Require shared secret authentication for all server connections. When disabled, any server in the access list can connect without authentication.

RequireEncryption

Yes

Require encryption for incoming server connections (NXCP session encryption). When enabled, unencrypted connections are rejected.

RequireTLS

No

Accept only TLS-protected incoming server connections. Non-TLS connections are rejected when enabled.

Certificate and TLS

Parameter Default Description

TrustedRootCertificate

(none)

Path to trusted CA certificate file(s) for verifying server identity. Can be specified multiple times to add multiple trusted CAs.

VerifyServerCertificate

No

Verify server TLS certificate against trusted root certificates. When enabled, connections from servers with untrusted certificates are rejected.

CACertificates

(none)

Path to a CA certificate bundle file for TLS verification.

CRL

(none)

Path to Certificate Revocation List file(s). Can be specified multiple times. Used for certificate-based authentication.

CRLReloadInterval

14400

Interval in seconds to reload CRL files. Default is 4 hours.

EnableCertificateRevocationChecks

No

Enable certificate revocation checks when verifying digital signatures of executable files (User Support Application executable, software packages). Windows only.

EnableSSLTrace

No

Enable detailed SSL/TLS protocol tracing in agent log. Useful for debugging TLS connection issues.

TrustedPackagePublishers

(unset)

Semicolon-separated list of trusted Authenticode publisher names for validating software packages deployed through the agent. When unset, packages signed with the Raden Solutions release signing certificate are trusted. Windows only.

Tunnel Configuration

Parameter Default Description

ServerConnection

(none)

Server address for establishing a tunnel connection, in the format address[:port][,certificate[%password]]. One server per directive; repeat the directive for multiple servers. The agent initiates an outbound TLS connection to each configured server. See Agent Tunnels for details.

TunnelKeepaliveInterval

30

Interval in seconds between tunnel keepalive messages. Helps detect broken connections through firewalls.

Logging

Parameter Default Description

LogFile

(platform-dependent)

Path to agent log file. Default is /var/log/nxagentd on Linux/UNIX or C:\nxagentd.log on Windows. Special values: {syslog} to log to syslog, {eventlog} to log to the Windows Event Log, {systemd} to log via the systemd journal, {stdout} to log to standard output.

LogHistorySize

4

Number of rotated log files to keep when using file-based logging.

LogRotationMode

2

Log rotation mode: 0 = no rotation, 1 = daily rotation, 2 = rotation by size (when file exceeds MaxLogSize).

MaxLogSize

16777216

Maximum log file size in bytes before rotation (only applies when LogRotationMode = 2). Default is 16 MB.

DailyLogFileSuffix

(empty)

Suffix appended to daily log file name when using daily rotation mode. Supports strftime format specifiers. When empty, %Y%m%d is used.

DebugLevel

0

Global debug verbosity level (0-9). Level 0 disables debug output. Higher values produce more verbose output.

DebugTags

(none)

Comma-separated list of debug tags with specific levels, allowing fine-grained debug control. Format: tag1:level,tag2:level (e.g., tunnel:7,poll:5,db:3).

WriteLogAsJson

No

Write log entries in JSON format. Useful for integration with log aggregation tools like Elasticsearch or Splunk.

BackgroundLogWriter

No

Use a background thread for writing log entries to reduce I/O impact on agent performance.

Network

Parameter Default Description

ListenAddress

*

IP address to listen on for incoming server connections. Use * to listen on all interfaces, or specify a specific IP address.

ListenPort

4700

TCP port to listen on for incoming server connections.

MaxSessions

0

Maximum number of concurrent server sessions. 0 means auto-detect (32, or 1024 when proxy mode is enabled).

SessionIdleTimeout

120

Idle session timeout in seconds. Sessions with no activity for this duration are automatically closed.

DisableIPv4

No

Disable IPv4 protocol support. Agent will only use IPv6.

DisableIPv6

No

Disable IPv6 protocol support. Agent will only use IPv4.

File and Directory Paths

Parameter Default Description

FileStore

/tmp

Directory used for file transfer operations between server and agent. On Windows, default is C:\.

DataDirectory

(platform-dependent)

Directory for agent persistent data (agent ID, certificates, local database). Resolved at runtime based on installation prefix.

DumpDirectory

(DataDirectory)

Directory for writing crash dump files. Windows only.

DumpDirectorySizeLimit

8G

Limit on the total size of the crash dump directory. Accepts size suffixes (e.g., 512M, 8G). Windows only.

ConfigIncludeDir

(auto)

Directory from which additional configuration files are loaded. By default the agent searches for nxagentd.conf.d in the standard configuration file locations. Can also be set via the NXAGENTD_CONFIG_D environment variable (UNIX/Linux) or the ConfigIncludeDir registry value under HKEY_LOCAL_MACHINE\SOFTWARE\NetXMS\Agent (Windows).

FileModeCreationMask

(none)

File creation mode mask (umask) for files created by the agent. UNIX only. Specified as octal value (e.g., 022).

Agent Behavior

Parameter Default Description

StartupDelay

0

Delay in seconds before the agent starts accepting connections after launch. Useful to wait for dependent services.

WaitForProcess

(none)

Process name to wait for before starting. Agent will not begin operation until this process is detected running.

EnableSubagentAutoload

Yes

Automatically load platform-appropriate subagents (e.g., linux.nsm on Linux, winnt.nsm on Windows).

EnableActions

Yes

Allow execution of actions defined in the agent configuration. Set to no to disable all action execution for security.

EnableArbitraryCommandExecution

No

Allow arbitrary command execution through the agent. When disabled, only pre-configured actions can be executed. Enable with caution as it allows the server to run any command on the agent host.

AutoStartUserAgent

No

Automatically start a user-mode session agent on Windows. Used for monitoring user sessions and desktop-level metrics. Windows only.

ForceReportUserAgent

No

Report the User Support Application as installed even if its installation is not detected. Windows only.

UserAgentExecutable

nxuseragent.exe

Name of the User Support Application executable started and monitored by the agent. Windows only.

UserAgentWatchdog

No

Enable watchdog that restarts the User Support Application in active user sessions if it is not running. Windows only.

EnablePushConnector

Yes

Enable the local push connector (named pipe or local socket) used by nxapush and local applications to push DCI values through the agent.

EnableWatchdog

No

Enable the watchdog process that automatically restarts the agent if it crashes.

ExternalSubagentStartupTimeout

120

Time in seconds given to a freshly started external subagent to connect to the master agent before the watchdog considers it hung and restarts it. Values below 30 are raised to 30. Windows only.

ExternalSubagentWatchdog

No

Enable watchdog that restarts external subagent processes that terminate or fail to connect to the master agent. Windows only.

SyncTimeWithServer

No

Synchronize agent system time with the NetXMS server. Only applies if the agent runs with sufficient privileges for time adjustment.

CreateCrashDumps

Yes (Windows), No (other platforms)

Create crash dump files when the agent process crashes. Useful for debugging.

FullCrashDumps

Yes (Windows)

Write full memory crash dumps instead of minidumps. Produces larger files but provides more debugging information. Windows only.

FatalExitOnCRTError

No

Terminate agent on C runtime library errors. Windows only.

LogUnresolvedSymbols

No

Log warnings about unresolved symbols in loaded subagent modules. Useful for debugging subagent load issues.

SystemName

(hostname)

Custom system name reported by the agent. If empty, the operating system hostname is used.

ExternalMasterAgent

(none)

Name of the master agent connection used when this agent process runs as an external subagent loader. When set, the agent registers itself with the specified master agent as an external subagent instead of operating standalone.

PlatformSuffix

(none)

Custom suffix appended to the platform name reported by the agent. Used to distinguish custom agent builds or package variants.

ZoneUIN

0

Zone UIN (Unique Identification Number) for this agent. Used in multi-zone deployments where agents in different zones may have overlapping IP addresses. Zone 0 is the default zone.

Proxy Functions

Parameter Default Description

EnableProxy

No

Enable agent proxy mode. Allows this agent to forward NetXMS protocol requests to other agents in isolated network segments.

EnableSNMPProxy

No

Enable SNMP proxy mode. Allows this agent to forward SNMP requests to devices not directly reachable from the server.

EnableSNMPTrapProxy

No

Enable SNMP trap proxy mode. The agent listens for SNMP traps and forwards them to the NetXMS server.

EnableSyslogProxy

No

Enable syslog proxy mode. The agent listens for syslog messages and forwards them to the NetXMS server.

EnableTCPProxy

No

Enable TCP proxy mode. Allows the server to establish TCP connections through this agent to remote hosts.

EnableTFTPProxy

No

Enable TFTP proxy mode. Allows forwarding TFTP requests through this agent.

EnableModbusProxy

No

Enable Modbus TCP proxy mode. Allows the server to query Modbus devices through this agent.

EnableEtherNetIPProxy

No

Enable EtherNet/IP proxy mode. Allows the server to query EtherNet/IP devices through this agent.

EnableWebServiceProxy

No

Enable web service proxy mode. Allows the server to make HTTP/HTTPS requests through this agent to web services not directly reachable.

SNMP Proxy Settings

Parameter Default Description

SNMPTimeout

0

SNMP request timeout in milliseconds for proxied SNMP requests. 0 means use the server-configured timeout.

SNMPTrapListenAddress

*

IP address to listen on for incoming SNMP traps. Only applies when EnableSNMPTrapProxy is enabled.

SNMPTrapPort

162

UDP port to listen on for incoming SNMP traps. Only applies when EnableSNMPTrapProxy is enabled.

SyslogListenPort

514

UDP port to listen on for incoming syslog messages. Only applies when EnableSyslogProxy is enabled.

Connectors

Parameter Default Description

EnableControlConnector

Yes (Windows), No (UNIX)

Enable the control connector for local process communication. On Windows, enables named pipe for service control. On UNIX, enables a local socket.

EnableEventConnector

Yes

Enable the event connector for receiving Windows events or session agent events.

SessionAgentPort

28180

TCP port for user session agent communication. Set to 0 to disable the session agent listener.

Data Collection

Parameter Default Description

DataCollectionMinThreadPoolSize

4

Minimum number of threads in the data collection thread pool.

DataCollectionMaxThreadPoolSize

64

Maximum number of threads in the data collection thread pool.

DataReconciliationBlockSize

1024

Number of data values sent in a single reconciliation batch when reconnecting to the server after an outage.

DataReconciliationTimeout

60000

Timeout in milliseconds for data reconciliation operations.

DataWriterFlushInterval

5000

Interval in milliseconds between flushes of the local data cache to the server.

DataWriterMaxTransactionSize

10000

Maximum number of data values in a single write transaction.

OfflineDataExpirationTime

10

Number of days to keep collected data in the local database when the server is unreachable. Data older than this is discarded.

DisableLocalDatabase

No

Disable the local SQLite database used for offline data caching. When disabled, data collected during server outages is lost.

DisableHeartbeatListener

No

Disable the heartbeat listener used for connection monitoring.

Execution Timeouts

Parameter Default Description

DefaultExecutionTimeout

5000

Default timeout in milliseconds for external process execution (external metrics, actions). If set to 0, defaults to 5000 (5 seconds).

ExternalMetricTimeout

0

Timeout in milliseconds for external metric execution. Overrides DefaultExecutionTimeout for metrics. 0 means use DefaultExecutionTimeout.

ExternalMetricProviderTimeout

30000

Timeout in milliseconds for external metric provider execution. Default is 30 seconds.

ExternalCommandTimeout

0

Timeout in milliseconds for external command (action) execution. 0 means use DefaultExecutionTimeout.

LongRunningQueryThreshold

250

Threshold in milliseconds for logging slow database queries in the agent log.

Web Service

Parameter Default Description

WebServiceCacheExpirationTime

600

Time in seconds before cached web service responses expire. Default is 10 minutes.

WebServiceThreadPoolSize

64

Maximum number of threads in the web service request thread pool.

Subagent and Extension Loading

Directive Description

SubAgent = module.nsm

Load a subagent module. Can be specified multiple times for multiple subagents. Example: SubAgent = linux.nsm

ExternalSubagent = name:user

Accept a connection from an external subagent process via named pipe or local socket. name is the external subagent connection name; user is the OS account allowed to connect ( for any user). Example: ExternalSubagent = MYSUBAGENT:

Extension = name: command

Register a generic agent extension: the agent spawns the specified command as an extension process and communicates with it. Can be specified multiple times.

External Metrics and Actions

Directive Description

ExternalMetric = Name: command

Define a metric collected by running an external command. Arguments from the DCI are substituted as $1, $2, etc.

ExternalMetric = Name(*): command $1

Define a parameterized metric. The (*) indicates it accepts arguments.

ExternalList = Name: command

Define a list metric. Each line of command output becomes a list item.

ExternalTable = Name:options:command

Define a table metric. options is a semicolon-separated list of named options: instanceColumns, description, separator, mergeSeparators, defaultColumnDataType, backgroundPolling, pollingInterval, timeout. Example: ExternalTable = FS:instanceColumns=MountPoint;description=File systems:df -P

ExternalMetricProvider = command:interval

Define a metric provider that runs periodically and caches results for multiple metrics. interval is the polling period in seconds. An optional timeout can be added after a comma: command:interval,timeout.

BackgroundExternalMetric = Name: command

Define an external metric that runs in the background and caches results. Unlike regular external metrics, the cached value is returned immediately without waiting for command execution.

Action = Name: command

Define an action that can be executed remotely by the server. Arguments are substituted as $1, $2, etc.

AcceptedEnvironmentVariables = list

Comma-separated list of environment variable names that can be passed to externally executed commands. By default, the agent sanitizes the environment for security.

Deprecated Parameters

These parameters are supported for backward compatibility but should be replaced with their current equivalents.

Deprecated Parameter Current Equivalent Notes

ExternalParameter

ExternalMetric

Renamed for consistency.

ExternalParameterShellExec

ExternalMetric

Shell execution is now handled automatically based on platform.

ExternalMetricShellExec

ExternalMetric

Shell execution is now handled automatically based on platform.

ActionShellExec

Action

Shell execution is now handled automatically based on platform.

ExternalParameterProvider

ExternalMetricProvider

Renamed for consistency.

ExternalParametersProvider

ExternalMetricProvider

Alternate deprecated name.

ExternalParameterTimeout

ExternalMetricTimeout

Renamed for consistency.

ExternalParameterProviderTimeout

ExternalMetricProviderTimeout

Renamed for consistency.

ExecTimeout

DefaultExecutionTimeout

Renamed for clarity.

DataCollectionThreadPoolSize

DataCollectionMaxThreadPoolSize

Renamed to distinguish from min pool size.

EncryptedSharedSecret

SharedSecret

Obfuscated secrets are now put into SharedSecret directly; generate them with nxencpasswd -a.

ZoneId

ZoneUIN

Renamed to Zone UIN (Unique Identification Number).