Linux Installation

This page covers installation of all NetXMS components on Linux.

Before proceeding, ensure your system meets the system requirements and that you have prepared the database for the server.

Server

Package Repository (Debian/Ubuntu)

Add the official NetXMS repository and install the server package:

curl -sSL https://packages.netxms.org/netxms-release-latest.deb -o /tmp/netxms-release.deb
sudo dpkg -i /tmp/netxms-release.deb
sudo apt update
sudo apt install netxms-server netxms-dbdrv-pgsql

Replace netxms-dbdrv-pgsql with the appropriate driver package for your database:

Package Database

netxms-dbdrv-pgsql

PostgreSQL (recommended)

netxms-dbdrv-mysql

MySQL

netxms-dbdrv-mariadb

MariaDB

netxms-dbdrv-odbc

ODBC (MS SQL Server and others)

netxms-dbdrv-oracle

Oracle Database

netxms-dbdrv-sqlite3

SQLite (evaluation only)

Package Repository (RHEL/CentOS/AlmaLinux)

sudo rpm -i https://packages.netxms.org/netxms-release-latest.rpm
sudo dnf install netxms-server netxms-dbdrv-pgsql
You may need to install the EPEL repository first. See https://docs.fedoraproject.org/en-US/epel/ for details.

Package Repository (Fedora)

sudo dnf config-manager --add-repo https://packages.netxms.org/fedora/netxms.repo
sudo dnf install netxms-server netxms-dbdrv-pgsql

Building from Source

Packages are the recommended installation method. Build from source only when packages are not available for your platform.

Download the release source archive, then configure, build, and install:

curl -O https://www.netxms.org/download/releases/6.1/netxms-6.1.0.tar.gz
tar xzf netxms-6.1.0.tar.gz
cd netxms-6.1.0
./configure --enable-release-build --with-server --with-pgsql --with-agent
make
sudo make install

Commonly used ./configure options (see ./configure --help for the full list):

Option Description

--enable-release-build

Build with release optimizations; always use when building a release archive

--prefix=/opt/netxms

Installation prefix (default: /usr/local)

--with-server

Build server components; requires at least one database driver option

--with-agent

Build the agent (recommended on the server host as well)

--with-pgsql

Build PostgreSQL database driver

--with-mysql

Build MySQL database driver

--with-mariadb

Build MariaDB database driver

--with-odbc

Build ODBC database driver (for MS SQL Server via unixODBC)

--with-sqlite

Build SQLite database driver

A source-installed server looks for netxmsd.conf in <prefix>/etc first, then /etc (full search order in the Configuration File Reference). The source tree provides a sample configuration file (contrib/netxmsd.conf-dist).

Create a systemd Unit

A source install does not register a systemd service. Create /etc/systemd/system/netxms-server.service, replacing /usr/local with your installation prefix:

[Unit]
Description=NetXMS core server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
ExecStart=/usr/local/bin/netxmsd -S
LimitNOFILE=65535
LimitCORE=infinity
Restart=on-failure
RestartSec=30
TimeoutSec=900
UMask=0077

[Install]
WantedBy=multi-user.target
Alias=netxmsd.service
sudo systemctl daemon-reload
sudo systemctl enable netxms-server

Configure the Server

Create or edit /etc/netxmsd.conf with your database connection parameters:

DBDriver = pgsql.ddr
DBServer = localhost
DBName = netxms_db
DBLogin = netxms
DBPassword = password
LogFile = /var/log/netxmsd

See Database Setup for details on each parameter. For the full list of server configuration file parameters, see Configuration File Reference.

Initialize the Database

After configuring the server, initialize the database schema:

nxdbmgr init

The nxdbmgr command reads database connection parameters from /etc/netxmsd.conf and automatically detects the location of SQL initialization scripts based on the configuration and installation prefix.

nxdbmgr init generates a random password for the admin user and prints it to the terminal — save it, it is shown only once. To set a specific password instead, pass -p <password>.

The database type is normally deduced from the driver name; it can also be given explicitly as nxdbmgr init <type> (valid types: mssql, mysql, oracle, pgsql, sqlite, tsdb). In particular, use nxdbmgr init tsdb to initialize a TimescaleDB schema on PostgreSQL. With the -C <dba_login>/<dba_password> option, nxdbmgr can also create the database and user for you before initialization using DBA credentials.

Start the Server

sudo systemctl start netxms-server

Verify the server is running:

sudo systemctl status netxms-server

Check the log file for any startup errors:

tail -50 /var/log/netxmsd

systemd Ordering for Local Database

If the database engine runs on the same host as the NetXMS server, add an ordering dependency so the database shuts down only after the server process has completed. This prevents data corruption during system shutdown or restart.

For PostgreSQL:

sudo systemctl edit netxms-server

Add the following lines in the editor:

[Unit]
After=network.target postgresql.service

Then reload the systemd configuration:

sudo systemctl daemon-reload

Replace postgresql.service with the appropriate unit name for your database engine (e.g., mysql.service, mariadb.service).

Post-Installation Steps

After the server is running:

  1. Connect with the management client as admin, using the password generated during database initialization (see Initial Credentials)

  2. You will be asked to change the password on first login

  3. Proceed to the Quick Start guide for initial configuration

Kernel Tuning

On large systems that send many ICMP pings or handle high volumes of SNMP traffic, the default Linux network buffer sizes may be insufficient. Increase the following kernel parameters:

sudo sysctl -w net.core.rmem_default=1703936
sudo sysctl -w net.core.wmem_default=1703936
sudo sysctl -w net.core.rmem_max=1703936
sudo sysctl -w net.core.wmem_max=1703936

To make these changes persistent across reboots, add them to /etc/sysctl.conf or create a file in /etc/sysctl.d/:

cat <<EOF | sudo tee /etc/sysctl.d/99-netxms.conf
net.core.rmem_default = 1703936
net.core.wmem_default = 1703936
net.core.rmem_max = 1703936
net.core.wmem_max = 1703936
EOF
sudo sysctl --system
Increasing these values increases kernel memory usage and may affect other applications on the same host. Adjust the values based on your environment — the values above have been tested on systems monitoring several thousand nodes.

Firewall Configuration

Ensure the following ports are open on the server host:

Port Protocol Purpose

4701

TCP

Management client connections (desktop client and web management console)

4700

TCP

Agent connections (if agents connect to server)

4703

TCP

Agent tunnel connections

162

UDP

SNMP trap reception

514

UDP

Syslog reception (if enabled)

8000 / 8443

TCP

WebAPI HTTP / HTTPS listeners (only if the WebAPI is enabled and exposed beyond the local host)
firewalld
sudo firewall-cmd --permanent --add-port=4701/tcp
sudo firewall-cmd --permanent --add-port=4700/tcp
sudo firewall-cmd --permanent --add-port=4703/tcp
sudo firewall-cmd --permanent --add-port=162/udp
sudo firewall-cmd --reload
ufw
sudo ufw allow 4701/tcp
sudo ufw allow 4700/tcp
sudo ufw allow 4703/tcp
sudo ufw allow 162/udp

Agent

The NetXMS agent collects monitoring data from managed hosts and delivers it to the central server.

Package Repository (Debian/Ubuntu)

curl -sSL https://packages.netxms.org/netxms-release-latest.deb -o /tmp/netxms-release.deb
sudo dpkg -i /tmp/netxms-release.deb
sudo apt update
sudo apt install netxms-agent

Package Repository (RHEL/CentOS/AlmaLinux)

sudo rpm -i https://packages.netxms.org/netxms-release-latest.rpm
sudo dnf install netxms-agent

Package Repository (Fedora)

sudo dnf config-manager --add-repo https://packages.netxms.org/fedora/netxms.repo
sudo dnf install netxms-agent

Static Binary

For systems without package manager support, download a precompiled static binary:

curl -sSL https://www.netxms.org/download/releases/6.1/nxagent-6.1.0-linux-x86_64-static.tar.gz | \
  sudo tar xz -C /usr/local

Building from Source

Packages are the recommended installation method. Build from source only when packages are not available for your platform.

Download the release source archive, then configure, build, and install:

curl -O https://www.netxms.org/download/releases/6.1/netxms-6.1.0.tar.gz
tar xzf netxms-6.1.0.tar.gz
cd netxms-6.1.0
./configure --enable-release-build --with-agent
make
sudo make install

The agent looks for nxagentd.conf in <prefix>/etc first, then /etc.

Create a systemd Unit

A source install does not register a systemd service. Create /etc/systemd/system/netxms-agent.service, replacing /usr/local with your installation prefix:

[Unit]
Description=NetXMS agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nxagentd -S
LimitCORE=infinity
Restart=always
UMask=0077

[Install]
WantedBy=multi-user.target
Alias=nxagentd.service
sudo systemctl daemon-reload

Configuration

Create or edit /etc/nxagentd.conf:

MasterServers = 10.0.0.1
LogFile = /var/log/nxagentd

Replace 10.0.0.1 with your NetXMS server IP address or hostname.

Key configuration parameters:

Parameter Default Description

MasterServers

(none)

Comma-separated list of server addresses (IP, hostname, or CIDR) with full control over the agent, including configuration changes and upgrades.

ControlServers

(none)

Servers with intermediate access: read data and execute predefined actions.

Servers

(none)

Servers with read-only access.

SharedSecret

admin

Shared secret for server-agent authentication; must match the secret configured on the server. Used when RequireAuthentication is enabled.

RequireAuthentication

No

Require shared secret authentication for all server connections.

ServerConnection

(none)

Server address for an agent-initiated tunnel connection. See Agent Tunnels.

LogFile

(platform-dependent)

Path to agent log file. Special values: {syslog} (syslog / Windows Event Log), {systemd} (systemd journal), {stdout} (standard output).

DebugLevel

0

Debug verbosity level (0-9); 0 disables debug output.

For the full list of agent configuration parameters, see Agent Configuration.

Start the Agent

sudo systemctl enable netxms-agent
sudo systemctl start netxms-agent

Verify the agent is running:

sudo systemctl status netxms-agent

Agent Tunnels

In environments where agents cannot accept inbound connections (firewalled hosts, NAT, cloud VMs), use agent tunnels. The agent initiates an outbound TLS connection to the server, eliminating the need for inbound port 4700.

Add the following to the agent configuration:

ServerConnection = server.example.com
MasterServers = server.example.com
ServerConnection defines the tunnel endpoint, but MasterServers (or ControlServers/Servers) is also required to authorize the server to communicate with the agent through the tunnel.

The agent connects to the server on port 4703 (TLS) and maintains a persistent tunnel. The server communicates with the agent through this tunnel for all polling and data collection operations.

For detailed tunnel configuration, see Agent Tunnels.

Verifying Agent Connectivity

After installing the agent, verify connectivity from the server using nxget:

nxget 10.0.0.50 System.PlatformName

This should return the agent’s platform information (e.g., Linux-x86_64).

You can also test metric collection using nxget from the server:

nxget <agent_address> "System.Hostname"
nxget opens a direct connection to the agent on port 4700, so it cannot reach agents that connect through an agent tunnel.

Web Management Console

The NetXMS web management console provides browser-based access to the monitoring system. It is a Java web application deployed on a Jakarta EE-compatible servlet container such as Jetty or Apache Tomcat.

Prerequisites

  • Java Runtime Environment (JRE) 17 or later

  • Apache Tomcat 11 or later, Jetty 12 or later, or any servlet container supporting Jakarta Servlet API 6.0

  • Network access to the NetXMS server on port 4701

Deploy on Jetty

Install Java

Debian/Ubuntu
sudo apt install default-jre
RHEL/CentOS/AlmaLinux
sudo dnf install java-17-openjdk

Download and Extract Jetty

Download the latest Jetty 12.x release from https://jetty.org/ and extract it to /opt:

sudo tar -xzf jetty-home-12.x.y.tar.gz -C /opt

Create a Jetty Base Directory

sudo mkdir -p /opt/jetty-base
cd /opt/jetty-base
sudo java -jar /opt/jetty-home-12.x.y/start.jar \
  --add-modules=server,http,ee10-deploy,gzip,http2,https,logging-logback,plus,ssl,work

Configure SSL

Generate a self-signed certificate (replace with a CA-signed certificate for production):

sudo keytool -genkeypair -alias jetty -keyalg RSA -keysize 2048 \
  -keystore /opt/jetty-base/etc/keystore.p12 -storetype PKCS12 \
  -validity 3650 -storepass changeit \
  -dname "CN=your-server, O=Your Org, C=US"

Edit /opt/jetty-base/start.d/ssl-context.ini and set the keystore password:

jetty.sslContext.keyStorePath=etc/keystore.p12
jetty.sslContext.keyStorePassword=changeit
jetty.sslContext.keyManagerPassword=changeit
jetty.sslContext.trustStorePath=etc/keystore.p12
jetty.sslContext.trustStorePassword=changeit

Deploy the Web Console WAR

sudo curl -o /opt/jetty-base/webapps/root.war \
  https://netxms.com/download/releases/6.1/nxmc-6.1.0.war

Verify Startup

java -jar /opt/jetty-home-12.x.y/start.jar --jetty.base=/opt/jetty-base

The console will be accessible at https://your-server:8443/.

Create a systemd Unit

Create /etc/systemd/system/jetty.service:

[Unit]
Description=Jetty Web Server
After=network.target

[Service]
Type=simple
User=jetty
ExecStart=/usr/bin/java -jar /opt/jetty-home-12.x.y/start.jar --jetty.base=/opt/jetty-base
Restart=on-failure

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now jetty

Deploy on Tomcat

Install Java and Tomcat

Debian/Ubuntu
sudo apt install default-jre tomcat11
RHEL/CentOS/AlmaLinux

RHEL-family repositories do not provide Tomcat 11. Install a JRE from the distribution, then download Apache Tomcat 11.x from https://tomcat.apache.org/ and install it manually — or use the Jetty instructions above instead.

sudo dnf install java-17-openjdk

Deploy the Web Console WAR

sudo curl -o /var/lib/tomcat11/webapps/nxmc.war \
  https://netxms.com/download/releases/6.1/nxmc-6.1.0.war

Tomcat automatically extracts and deploys the application.

Restart Tomcat

sudo systemctl restart tomcat11

Access the web console at http://your-server:8080/nxmc.

Configuration

The web console needs to know the NetXMS server address. The quickest method is to set an environment variable before starting the servlet container:

export NXMC_SERVER=10.0.0.1

For systemd-managed services, add Environment=NXMC_SERVER=10.0.0.1 to the service unit’s [Service] section.

Alternatively, create an nxmc.properties file on the servlet container’s classpath:

server=10.0.0.1

For the full list of configuration properties, all supported configuration methods (JNDI, properties file, JVM properties, environment variables), and the server address resolution order, see Web Console Configuration Reference.

Reverse Proxy Configuration

For production deployments, place a reverse proxy (Nginx or Apache) in front of the servlet container to handle TLS termination.

Nginx Example

server {
    listen 443 ssl;
    server_name monitoring.example.com;

    ssl_certificate     /etc/ssl/certs/monitoring.crt;
    ssl_certificate_key /etc/ssl/private/monitoring.key;

    location / {
        proxy_pass http://127.0.0.1:8080/nxmc/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Apache httpd Example

<VirtualHost *:443>
    ServerName monitoring.example.com

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/monitoring.crt
    SSLCertificateKeyFile /etc/ssl/private/monitoring.key

    ProxyPass / http://127.0.0.1:8080/nxmc/
    ProxyPassReverse / http://127.0.0.1:8080/nxmc/
    RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

Troubleshooting

Web Console Does Not Start

For Tomcat, check log files at /var/log/tomcat11/catalina.out. For Jetty, check the console output or the log file configured in start.d/logging-logback.ini.

Common issues:

  • Java not found — Ensure JAVA_HOME is set correctly

  • Port conflict — The default port 8080 (or 8443 for HTTPS) may be in use by another application

  • Permission denied — Ensure the servlet container has read access to the WAR file

Cannot Connect to Server

  • Verify the server address via one of the configuration methods above

  • Check that port 4701 is accessible from the web server host

  • Verify the NetXMS server is running

WebAPI

The NetXMS WebAPI provides RESTful HTTP access to the monitoring system, enabling integration with third-party tools, custom dashboards, and automation scripts.

The WebAPI is built into the server: REST endpoints are provided by the webapi server module and served by the server’s own HTTP listener. No separate service, package, or Java runtime is required.

The standalone WebAPI service (nxapisrv) used with older NetXMS versions is deprecated and has been removed.

Enabling the WebAPI

Load the module by adding the following line to /etc/netxmsd.conf and restarting the server:

Module = webapi

By default the API listens for plain HTTP requests on 127.0.0.1:8000. Listener settings are controlled by the [WEBAPI] section of netxmsd.conf:

[WEBAPI]
Port = 8000
# Listen address: loopback (default), any, or a specific IP address
Address = loopback
# Optional HTTPS listener
TLSEnable = yes
TLSPort = 8443
TLSCertificate = /etc/ssl/certs/webapi.crt
TLSCertificateKey = /etc/ssl/private/webapi.key

Configuration Parameters

All parameters belong to the [WEBAPI] section of the server configuration file (netxmsd.conf).

Parameter Description

Enable

Enable or disable the WebAPI listener. Default: yes.

Address

HTTP listen address: loopback, any, or a specific IP address. Default: loopback.

Port

HTTP port. Default: 8000.

TLSEnable

Enable the HTTPS listener. Default: no.

TLSAddress

HTTPS listen address. Default: 0.0.0.0 (all interfaces).

TLSPort

HTTPS port. Default: 8443.

TLSCertificate

Path to the TLS certificate file (PEM format). Required when TLSEnable is yes.

TLSCertificateKey

Path to the TLS private key file (PEM format). Required when TLSEnable is yes.

ReproxyPath

Path to the reproxy binary used for TLS termination. Default: /usr/bin/reproxy (reproxy.exe in the server binary directory on Windows).
The HTTPS listener is provided by a reproxy helper process that the server starts and supervises automatically when TLSEnable is set.

API Usage

Authentication

Authenticate by sending a POST request to the login endpoint:

curl -X POST http://localhost:8000/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "<password>"}'

The response includes a bearer token for subsequent requests.

Example: List Objects

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/v1/objects

Example: Read Current DCI Values

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/v1/objects/42/data-collection/current-values

For the complete API reference, see the REST API section.

Security Considerations

  • The plain HTTP listener binds to the loopback interface by default. To expose the API beyond the local host, enable the TLS listener (TLSEnable) or keep the HTTP listener on loopback behind a reverse proxy.

  • Always use TLS in production. Use certificates from a trusted CA or your internal PKI.

  • Restrict network access to the API port using firewall rules.

Desktop Management Client

The NetXMS desktop management client is also available for Linux as an alternative to the web console. It offers the same functionality as the web console and may provide better responsiveness for daily administrative tasks.

Two distribution forms are available: a Flatpak package on Flathub and a standalone JAR. There is no DEB or RPM package for the desktop client — the netxms-client package in the NetXMS repositories contains command-line client tools only (nxalarm, nxevent, nxpush, and similar).

Flatpak (Flathub)

Each release line is published on Flathub as a separate application, listed as NetXMS followed by the version (for example, NetXMS 6.2). Different release lines can be installed side by side.

On distributions with Flathub enabled by default, such as Fedora and Linux Mint, the client appears in the standard software center (GNOME Software, KDE Discover). Search for NetXMS and install the release line that matches your server. Other distributions, including Ubuntu, need Flatpak and the Flathub repository set up first — see the Flathub setup instructions.

To install from the command line instead, use the application ID com.netxms.NetXMSClientXX, where XX is the major and minor version without the dot (for example, com.netxms.NetXMSClient62 for 6.2). The only exception is com.netxms.NetXMSClient without a suffix, which is the 4.5 release line.

flatpak install flathub com.netxms.NetXMSClient<XX>

The Flatpak build runs in a sandbox that blocks Local Command object tools, such as a tool that launches a local terminal or ssh client. When such a tool is blocked, the client shows a dialog with a ready-to-run flatpak override command; run it on the host and restart the client:

flatpak override --user --talk-name=org.freedesktop.Flatpak com.netxms.NetXMSClient<XX>
This override lets the client run arbitrary commands on the host and removes the isolation provided by the sandbox. Enable it only if you actually use Local Command object tools.

Standalone JAR

The standalone JAR runs on any 64-bit Linux system with a Java runtime.

  1. Install a 64-bit Java 17 or later runtime, for example sudo apt install default-jre on Debian or Ubuntu. On Ubuntu 22.04, default-jre installs Java 11 — install openjdk-17-jre instead.

  2. Download nxmc-6.1.0-standalone.jar from the NetXMS download page.

  3. Run it:

    java -jar nxmc-6.1.0-standalone.jar

The client writes its log to ~/.nxmc4/nxmc.log; inspect it if the client fails to start or connect.