Configuration File Reference

DBDriver

(none)

Database driver module (pgsql.ddr, mysql.ddr, mariadb.ddr, mssql.ddr, oracle.ddr, odbc.ddr, sqlite.ddr)

DBServer

127.0.0.1

Database server address (hostname or IP). For ODBC driver, this is the ODBC data source name.

DBName

netxms_db

Database name (not used by ODBC driver)

DBLogin

netxms

Database login name

DBPassword

(empty)

Database password, plain text or obfuscated with nxencpasswd (obfuscated values are detected and decoded automatically). Enclose in double quotes if it contains #.

DBEncryptedPassword

(none)

Deprecated alias for DBPassword; accepts the same plain text or obfuscated values. Use DBPassword instead.

DBPasswordCommand

(empty)

External command to retrieve the database password. The command is executed at startup with a 30-second timeout; its stdout (trimmed) is used as the password.

DBSchema

(default)

Database schema name (PostgreSQL and Oracle only)

DBDriverOptions

(empty)

Additional driver-specific parameters

DBDrvParams

(empty)

Deprecated. Use DBDriverOptions instead.

DBSessionSetupSQLScript

(empty)

Path to a plain text file containing SQL commands executed on every new database connection, including the initial connection on server startup.

DBCacheConfigurationTables

yes

Cache configuration tables to in-memory SQLite database to speed up server startup

StartupSQLScript

(empty)

Path to a plain text file containing SQL commands executed once on server startup

ListenAddress

*

IP address to listen on for client and agent connections. Use 0.0.0.0 or * for all interfaces.

ManagementAgentAddress

(empty)

Alternate address for connecting to the agent on the local management node. Useful when running server and agent in Docker containers where the internal container IP differs from the accessible address.

MaxClientSessions

256

Maximum number of concurrent client sessions

MaxClientMessageSize

4M

Maximum client message size. Supports K, M, G, T suffixes. Advanced — contact support before changing.

PeerNode

(none)

Comma-separated list of peer node addresses or hostnames in high availability setup. The server will verify no other instance is running on these addresses before removing a stale database lock.

ServerCertificate

(empty)

Path to server TLS certificate file (PEM format)

ServerCertificateKey

(empty)

Path to server TLS private key file. Can be omitted if key is included in the certificate file.

ServerCertificatePassword

(empty)

Password for encrypted server private key. Can be omitted if key is not encrypted.

TunnelCertificate

(empty)

Path to server certificate file used specifically for agent tunnel connections

TunnelCertificateKey

(empty)

Private key for the tunnel certificate. Can be omitted if key is included in the certificate file.

TunnelCertificatePassword

(empty)

Password for encrypted tunnel certificate private key

InternalCACertificate

(empty)

Path to server CA certificate used to issue agent certificates. This certificate is also automatically trusted when verifying agent certificate validity.

InternalCACertificateKey

(empty)

Private key for the internal CA certificate. Can be omitted if key is included in the certificate file.

InternalCACertificatePassword

(empty)

Password for the internal CA certificate key

TrustedCertificate

(empty)

Path to a trusted CA certificate or self-signed certificate. If the certificate chain is longer than one level, add all upper-level certificates using multiple TrustedCertificate entries.

CRL

(none)

Certificate Revocation List — path to a local file or HTTP/HTTPS URL. Supports and autodetects PEM and DER formats. Multiple CRL entries can be present.

AuditLogKey

(empty)

HMAC key used for signing audit log entries

ServerCACertificate

(empty)

Deprecated. Use TrustedCertificate instead.

LogFile

(platform-dependent)

Path to log file. Default is /var/log/netxmsd.log on Linux or C:\netxmsd.log on Windows. Use {syslog} (alias {EventLog}) for syslog (Linux) or Windows Event Log, {systemd} for systemd journal, or {stdout} for standard output.

LogRotationMode

2

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

MaxLogSize

16M

Maximum log file size before rotation (mode 2 only). Supports K, M, G, T suffixes.

LogHistorySize

4

Number of rotated log files to keep; older files are discarded

DailyLogFileSuffix

(empty)

Suffix appended to daily log file names (mode 1). Supports strftime(3) format macros. When empty, %Y%m%d is used.

WriteLogAsJson

no

Write server log entries in JSON format

BackgroundLogWriter

no

Use a separate background thread to write log entries in batches, improving performance under heavy logging

DebugLevel

0

Global debug verbosity (0-9). Value 0 disables debug logging, 9 enables very detailed logging. Can also be set with command-line option -D.

DebugTags

(empty)

Comma-separated list of debug tags with levels (e.g., agent.tunnel.:4,db.query:5). Supports wildcard in tag names. Multiple DebugTags entries are allowed.

DataDirectory

(platform-dependent)

Server data directory for MIB files, encryption keys, and persistent state. Linux default: /var/lib/netxms (packages) or PREFIX/var/lib/netxms (source build). Windows default: <InstallDir>\var.

LibraryDirectory

(platform-dependent)

Directory containing database drivers (.ddr) and network device driver files (.ndd). It is generally recommended not to change this parameter.

DumpDirectory

/var/tmp (UNIX) or C:\ (Windows)

Directory for storing server crash dump files

ProcessAffinityMask

0xFFFFFFFF

CPU affinity bitmask for the server process (Windows only). Each bit represents a logical processor on which server threads are allowed to run.

CodePage

(system default)

Character encoding for non-Unicode text conversion. Has no effect on Windows or if the server was compiled without iconv support.

DefaultThreadStackSize

1M

Default stack size for server threads. Supports K, M, G, T suffixes. Advanced — contact support before changing.

CreateCrashDumps

yes

Enable creation of crash dump files when the server encounters a fatal error (Windows only)

FullCrashDumps

yes

Write full memory dumps instead of minidumps (Windows only). Requires CreateCrashDumps = yes.

Module

(none)

Additional server module to load at startup. Can be specified multiple times to load multiple modules.

PerfDataStorageDriver

(empty)

Fanout driver for sending collected performance data to an additional storage backend (e.g., InfluxDB, ClickHouse). Multiple entries can be specified. See Fanout Drivers for details.

URL

(empty)

Vault server URL (e.g., https://vault.example.com:8200)

AppRoleId

(empty)

Vault AppRole role ID for authentication

AppRoleSecretId

(empty)

Vault AppRole secret ID for authentication

DBCredentialPath

(empty)

Path to database credentials secret in Vault

Timeout

5000

Vault request timeout in milliseconds

TLSVerify

yes

Verify Vault server’s TLS certificate

Enable

yes

Enable the built-in web API listener

Address

loopback

IP address to listen on. Accepts an IP address, loopback/localhost, or any/* (all interfaces).

Port

8000

HTTP listener port

TLSEnable

no

Enable HTTPS listener. Silently disabled if TLSCertificate and TLSCertificateKey are not set.

TLSAddress

0.0.0.0

IP address for the HTTPS listener

TLSPort

8443

HTTPS listener port

TLSCertificate

(empty)

Path to TLS certificate for the HTTPS listener

TLSCertificateKey

(empty)

Path to TLS private key for the HTTPS listener

ReproxyPath

/usr/bin/reproxy (UNIX) or <InstallDir>\bin\reproxy.exe (Windows)

Path to the reproxy executable used to terminate TLS for the HTTPS listener. Used only when TLSEnable is yes.

ClusterMode

no

Enable cluster mode

NodeName

(empty)

This node’s name in the cluster

NodeAddress

(empty)

This node’s client-reachable address, advertised to redirected clients when this node is active (cluster channel addressing uses PeerAddress/ChannelPort)

PeerAddress

(empty)

Peer node address

ChannelPort

4704

TCP port for the cluster communication channel

PeerPort

(ChannelPort)

Peer node’s cluster channel port, if different

EnableDataCollectionFeed

yes

Replicate collected data to the standby node

LeaseValidity

20

Cluster lease validity time (seconds)

LeaseRefreshInterval

5

Cluster lease refresh interval (seconds)

FenceMargin

3

Fencing margin (seconds)

JournalRetentionTime

86400

Cluster journal retention time (seconds)

OnPromoteCommand

(empty)

Command executed when this node is promoted to primary

OnDemoteCommand

(empty)

Command executed when this node is demoted to standby

-c <file>

Use alternate configuration file instead of default search path

-C

Check configuration file for errors and exit

-d

Run as daemon (UNIX) or service (Windows)

-D <level>

Set debug level (0-9). Overrides DebugLevel in configuration file.

-e

Run database consistency check before startup (invokes nxdbmgr check)

-G

Generate sample configuration file and exit

-h

Display help message and exit

-l

Show log file location (from configuration) and exit

-q

Disable interactive debug console

-t <tag>:<level>

Set debug level for a specific log tag (e.g., -t db.query:7)

-T

Enable SQL query tracing (sets db.query tag to level 9)

-v

Display version information and exit

-A <entry>

Add a configuration file entry at startup (e.g., -A "DebugLevel=7")

-p <file>

Path to PID file (default: /var/run/netxmsd.pid)

-S

Run as systemd daemon (use Type=notify in systemd unit file)

-I

Install as Windows service

-R

Remove Windows service

-s

Start Windows service

-S

Stop Windows service

-L <user>

Login name for service account (use with -I)

-P <password>

Password for service account (use with -I)

-M

Create service with manual start type (use with -I)

-m

Ignore service start command if service is configured for manual start

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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 = 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.

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.

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).