Quick Start

This guide takes you from a fresh installation to a working monitoring setup with data collection, thresholds, and notifications.

Installation

If you already have a running NetXMS installation, skip to Initial Credentials.

The fastest way to get a complete stack — server, agent, web management console, and PostgreSQL database — is Docker Compose:

git clone https://github.com/netxms/docker.git
cd docker/deployment-example
cp .env.example .env
docker compose up -d
docker compose logs init

The first start initializes the database automatically and generates a random password for the admin user. The last command prints the log of the init container, which contains that password (see Initial Credentials). Once the containers are up, open the web management console at https://localhost:8443 (it uses a self-signed certificate, so the browser will show a warning).

This setup is meant as the quickest path to a working system for evaluation. For anything longer-lived, pin a specific version and change the database password in .env — see Docker Compose Deployment for details. For native installation, see Linux, Windows, or macOS.

Initial Credentials

During database initialization, nxdbmgr init generates a random password for the admin user and prints it to the terminal:

IMPORTANT: Generated admin password
   Login:    admin
   Password: <generated password>

Please save this password - it will not be shown again.
You will be required to change it on first login.

The password is shown only once — save it before closing the terminal. On first login you will be asked to change it.

With the Docker Compose setup, database initialization runs inside the init container. Retrieve the generated password from its logs:

docker compose logs init

To set a specific password instead of a generated one, pass -p <password> to nxdbmgr init.

Agent Configuration

The NetXMS agent requires minimal configuration: the server address and log file path.

Windows

The Windows installer automatically generates the configuration file at C:\NetXMS\etc\nxagentd.conf. If the correct server address was specified during installation, no further action is needed.

Sample Windows agent configuration
MasterServers = 127.0.0.1
LogFile = {syslog}

The special value {syslog} sends agent log messages to the Windows Event Log; replace it with a file path (e.g. C:\NetXMS\log\nxagentd.log) to log to a file instead.

Linux

On Linux systems, create or edit /etc/nxagentd.conf:

Sample Linux agent configuration
MasterServers = 127.0.0.1
LogFile = /var/log/nxagentd

Replace 127.0.0.1 with your NetXMS server IP address.

MasterServers acts as a whitelist — the agent only accepts connections from the listed addresses and drops all others.

Server Configuration

NetXMS server has two configuration sources:

  • Configuration file (netxmsd.conf) — static settings that require a server restart to change. Used primarily for database connection credentials and extension module loading.

  • Server configuration variables — stored in the database and changeable at runtime through the management client. Most operational settings (polling intervals, thresholds, retention policies, etc.) live here.

For the full reference, see Server Configuration.

Configuration File

The configuration file must specify at minimum the database driver, connection parameters, and log file.

Supported database drivers:

Driver Description

pgsql

PostgreSQL (including TimescaleDB)

mysql

MySQL

mariadb

MariaDB

mssql

Microsoft SQL Server

oracle

Oracle Database

odbc

ODBC (connects to any supported database via ODBC)

sqlite

Embedded SQLite (evaluation only)

Windows: The installer populates C:\NetXMS\etc\netxmsd.conf.

Linux: Create or edit /etc/netxmsd.conf:

Sample server configuration for PostgreSQL
DBDriver = pgsql
DBServer = localhost
DBName = netxms_db
DBLogin = netxms
DBPassword = password
LogFile = /var/log/netxmsd

Set Up Notifications

Configure a Notification Channel

Notification channels define how NetXMS sends alerts — via email, messengers, SMS, etc.

Configure channels in Configuration  Notification Channels. Example SMTP email configuration:

Server=smtp.example.com
[email protected]
FromName=NetXMS Server
IsHTML=no
TLSMode=TLS
Login=smtp-username
Password=password

Create an Action

Create a notification action in Configuration  Actions:

  1. Set the action type to your notification channel

  2. Specify recipient addresses (separate multiple recipients with ;)

  3. Configure subject and message using macros:

    • %n — node name

    • %m — event message

Action configuration

Configure Event Processing Policy

Open Configuration  Event Processing Policy to set up alarm and notification rules:

  1. Find the built-in rules "Generate alarm on threshold violation" and "Terminate threshold violation alarms" (they match SYS_THRESHOLD_REACHED and SYS_THRESHOLD_REARMED events)

  2. Add your notification action to these rules

  3. The first rule creates an alarm with a key combining the source object ID, DCI ID, and instance

  4. The second rule automatically terminates the matching alarm using the same key

  5. Save the policy

Event Processing Policy

Configure SNMP Defaults

If your network has SNMP devices with common credentials, configure defaults in Configuration  Network credentials.

During configuration polls, NetXMS tries the configured community strings, USM credentials, and ports sequentially until finding a working combination.

Enable Network Discovery

Passive Discovery

Passive discovery finds new devices by querying ARP and routing tables from known nodes, without sending probe traffic.

  1. Open Configuration  Network Discovery

  2. In the General section, select Passive only

  3. Optionally enable SNMP trap source address as a discovery source

  4. Save the configuration

For large networks, initial discovery may take several hours. Let NetXMS run overnight to gather complete network information.

Requirements for successful discovery:

  • NetXMS server must have SNMP access to switches and routers

  • Device credentials must be added to the default credential list in Configuration  Network credentials

Add Nodes Manually

If discovery does not find all devices, add nodes manually:

  1. Right-click on Infrastructure Services in the object tree

  2. Select Create node

  3. Enter the node’s IP address or hostname

Create Node dialog

Node creation may take a moment while NetXMS performs initial polling. The node is automatically placed under the appropriate subnet.

Create Data Collection Items

Data Collection Items (DCIs) define what metrics to collect, how often, and what thresholds to check.

CPU Usage (Agent)

  1. Select a node and open the Data Collection tab

  2. Click the + button to add a new DCI

  3. Set origin to NetXMS Agent

  4. Click Select to browse available metrics

  5. Search for CPU and select System.CPU.Usage

  6. Go to the Threshold tab and click Add

  7. Configure: if last polled value > 85, generate SYS_THRESHOLD_REACHED; when back to normal, generate SYS_THRESHOLD_REARMED

  8. Click OK

CPU DCI properties
Threshold configuration

The DCI will now collect CPU usage every 60 seconds, store data for 30 days, and generate an alarm when usage exceeds 85%.

Interface Traffic

To quickly set up traffic monitoring on network interfaces:

  1. Expand a node in the object tree and select one or more interfaces

  2. Right-click and select Create data collection items

  3. Check the metrics you need (bytes in/out, packets, errors, etc.)

  4. DCIs are created automatically

Create interface traffic DCIs

Interface Traffic Templates

Creating DCIs interface by interface does not scale beyond a handful of nodes. NetXMS ships three built-in templates for this purpose — "Interface Traffic Agent 32-bit counters", "Interface Traffic Agent 64-bit counters", and "Interface Traffic SNMP". Each collects inbound and outbound traffic per interface using instance discovery, and each has an auto-apply rule, so you do not need to apply them manually. The templates are imported automatically at server startup (see Server.ImportConfigurationOnStartup in Server Configuration Variables) and are located in the Templates perspective, group Interface Traffic.

To enable traffic collection on a node:

  1. Open the node’s Properties, go to Custom Attributes, and add the attribute Template.InterfaceTraffic with the value yes.

  2. Wait for the next automatic binding poll, or select Poll  Configuration in the node’s context menu. The template matching the node’s capabilities — agent with 32-bit counters, agent with 64-bit counters, or SNMP — is applied automatically.

  3. Wait for the next instance discovery poll, or select Poll  Instance discovery in the node’s context menu. Traffic DCIs are created for Ethernet and point-to-point interfaces whose Expected state is Up. Loopback interfaces are skipped.

To enable traffic collection on many nodes at once, add Template.InterfaceTraffic to a container and mark it Inheritable, so that all nodes in the container get the attribute (see Inheritable Attributes).

To exclude an interface, set the custom attribute Template.InterfaceTraffic to no on the interface itself, or add the custom attribute Template.InterfaceTraffic.Exclude to the node with a comma-separated list of interface names.

Removing Template.InterfaceTraffic from a node later does not remove the template. See Auto-Apply Rules for details on how auto-apply rules are evaluated.

Next Steps

With basic monitoring configured, explore these topics: