Upgrading

This page covers the procedure for upgrading NetXMS to a newer version within the same release line (e.g., 6.2.5 to 6.2.6) or to a new release line (e.g., 6.1 to 6.2).

For migrating the database between different database engines, see Database Migration.

Before You Begin

Always back up the database before upgrading. Upgrades are one-way, and downgrading requires restoring from backup. For a complete pre-upgrade backup (including configuration files and server data directory), see Pre-Upgrade Backup.

Pre-Upgrade Checklist

  1. Review the release notes and the Breaking Changes Between Releases for any changes that may require manual intervention

  2. Schedule a maintenance window — upgrades require restarting the server, which temporarily interrupts monitoring

  3. Back up the database using your database engine’s native backup tool (pg_dump, mysqldump, etc.)

  4. Check the database for errors — stop the server and run:

    nxdbmgr check

    Proceed only if the database checker does not report any errors.

Linux Upgrade

Package Upgrade

If you installed via the package repository, upgrading is straightforward. NetXMS 6.2 packages are published in the repositories at https://packages.netxms.org/ (see Linux Installation); version 7 and later use separate 7.x/ repositories, so a configured 6.x repository never offers them.

Upgrade the packages:

Debian/Ubuntu
sudo apt update
sudo apt upgrade netxms-server netxms-agent
RHEL/CentOS/AlmaLinux
sudo dnf upgrade netxms-server netxms-agent

Database Schema Upgrade

On Debian and Ubuntu, the netxms-server package runs nxdbmgr upgrade to apply any required database schema migrations and restarts the server. The RHEL-compatible and Fedora packages neither upgrade the database schema nor restart the server; after dnf upgrade, stop the server, upgrade the schema, and start it again:

sudo systemctl stop netxms-server
nxdbmgr upgrade
sudo systemctl start netxms-server

In some cases (for example, if the database engine packages were also upgraded simultaneously), the automatic database upgrade may not succeed. If this happens, the server will not start and the log file will show a message similar to:

Your database has format version 61.36, but server is compiled for version 62.44

To resolve this, manually run the database upgrade and start the server:

nxdbmgr upgrade
sudo systemctl start netxms-server
It is always safe to run nxdbmgr upgrade manually after a package upgrade, even if the automatic upgrade already succeeded. The tool detects that the database is up to date and exits without making changes.

On TimescaleDB, nxdbmgr upgrade and nxdbmgr check abort if the TimescaleDB extension version registered in the database does not match the installed TimescaleDB library — typically after the TimescaleDB package was upgraded. In that case, run ALTER EXTENSION timescaledb UPDATE; as the first statement of a psql -X session in every database that uses the extension, then run nxdbmgr upgrade again.

Source Upgrade

When you build a new version from source into a prefix that already contains an installed NetXMS (for example, /usr/local), run make -j$(nproc) install instead of make followed by make install. A bare make can link new binaries against the previously installed NetXMS libraries and fail with undefined symbols; the install target installs each library before the binaries that depend on it are linked. Alternatively, build into an empty directory (./configure --prefix=/path/to/empty/dir) and copy the result to the target system. After installation, run nxdbmgr upgrade before starting the server.

Windows Upgrade

  1. Stop the NetXMS services (Core and Agent) via the Services console or:

    net stop NetXMSCore
net stop NetXMSAgentdW32

  2. Run the new version installer. It detects the existing installation and performs an in-place upgrade.

  3. The installer’s Upgrade database schema if needed task (selected by default) runs nxdbmgr upgrade. If you deselected it, upgrade the database schema manually after installation:

    nxdbmgr upgrade

  4. Start the services:

    net start NetXMSCore
net start NetXMSAgentdW32

Agent Upgrades

Agents can be upgraded independently of the server. The server is backward-compatible with older agent versions, so agents can be upgraded gradually.

Manual Agent Upgrade

Upgrade agents using the same method as initial installation (package manager, installer, or source build).

Centralized Agent Upgrade

NetXMS can push agent upgrades from the server:

  1. Upload the new agent package to the server’s package manager (Configuration  Packages)

  2. Select target nodes and deploy the upgrade package

  3. The server pushes the package to each agent, which performs a self-upgrade and restart

Centralized agent upgrade applies only to agents installed from standalone installers (primarily Windows). Agents installed via package managers (apt, dnf) should be upgraded through the package manager to maintain proper package state.
For large environments with many package-managed agents, consider using external orchestration tools such as Ansible or Salt to coordinate agent upgrades across multiple hosts.

Post-Upgrade Verification

After upgrading:

  1. Check the server log for any errors:

    tail -100 /var/log/netxmsd

  2. Verify the server version in the management client (Help  About)

  3. Check that all agents are connected (monitor the SYS_AGENT_UNREACHABLE events)

  4. Verify data collection is working (check recent DCI values on a few nodes)

Web Console Upgrade

After upgrading the server, also upgrade the web management console:

  1. Download the new nxmc-6.2.6.war file matching the server version

  2. Replace the old WAR file in Tomcat’s webapps directory

  3. Restart Tomcat

Desktop Client Upgrade

On Windows, close the desktop client and run the new netxms-client-6.2.6-x64.exe installer. It upgrades the existing installation in place and keeps the previously selected components. The client files are replaced, and so are the bundled Java runtime and the command line tools if those components are installed.

The Flatpak build is upgraded with flatpak update com.netxms.NetXMSClient.

The web console and desktop client must match the server’s MAJOR.MINOR version. Patch-level differences (e.g., 6.2.5 vs 6.2.6) are compatible, but MAJOR.MINOR mismatches may cause unexpected behavior or connection failures.

Rollback

If the upgrade causes problems:

  1. Stop the server

  2. Restore the database from the pre-upgrade backup

  3. Reinstall the previous server version (using packages or source)

  4. Start the server

Do not attempt to downgrade the database schema. Database schema changes are forward-only. Always restore from backup if you need to roll back.