Upgrading

This page covers the procedure for upgrading NetXMS to a newer version within the same major release (e.g., 6.0.1 to 6.0.5) or to a new major release (e.g., 5.2 to 6.0).

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:

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

The package manager automatically runs nxdbmgr upgrade to apply any required database schema migrations and restarts the 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 41.07, but server is compiled for version 41.18

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.

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. After installation, upgrade the database schema:

    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.war file matching the server version

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

  3. Restart Tomcat

The web console and desktop client must match the server’s MAJOR.MINOR version. Patch-level differences (e.g., 6.0.1 vs 6.0.3) 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.