Server Migration

This page covers moving a NetXMS server installation to a new machine — whether for hardware replacement, OS migration, or moving to the cloud.

For migrating between different database engines (e.g., SQLite to PostgreSQL), see Database Migration.

Before You Begin

Always create a full backup before starting any migration. See Backup and Recovery for backup procedures.

Pre-Migration Checklist

  1. Back up the database using your database engine’s native backup tool

  2. Back up the server configuration file (netxmsd.conf)

  3. Back up the server data directory

  4. Note the current NetXMS version (netxmsd -v) — install the same version on the new server

  5. Plan agent reconnection (DNS update or configuration changes)

  6. Schedule a maintenance window

What Needs to Move

Component Location Migration method

Database

External server or local

Native DB tools or nxdbmgr migrate

Configuration file

/etc/netxmsd.conf (Linux), C:\NetXMS\etc\netxmsd.conf (Windows)

File copy

Data directory

/var/lib/netxms/ (Linux), C:\NetXMS\var (Windows)

File copy

Scenario 1: External Database

When the database runs on a separate server (or a managed cloud database), migration is straightforward because the database stays in place.

  1. Install NetXMS on the new server (same version as the source)

  2. Copy the configuration file from the old server:

    scp old-server:/etc/netxmsd.conf /etc/netxmsd.conf

  3. Review netxmsd.conf and update any paths or settings specific to the old server (log file path, data directory, etc.)

  4. Stop the server on the old machine:

    sudo systemctl stop netxms-server

  5. Copy the data directory from the old server:

    rsync -a old-server:/var/lib/netxms/ /var/lib/netxms/

  6. Start the server on the new machine:

    sudo systemctl start netxms-server
No database migration is needed in this scenario. The new server connects to the existing external database using the same credentials.

Scenario 2: Database on the Same Machine

When the database runs on the same machine as the NetXMS server, the database must also be moved.

Same Database Engine on the New Server

If you are keeping the same database engine (e.g., PostgreSQL on both old and new servers), use the engine’s native dump and restore tools. This is faster and more efficient than using nxdbmgr.

PostgreSQL

On the old server:

sudo systemctl stop netxms-server
pg_dump -U netxms -Fc netxms_db > /tmp/netxms-db.dump

On the new server (after installing NetXMS and PostgreSQL):

createdb -U netxms netxms_db
pg_restore -U netxms -d netxms_db /tmp/netxms-db.dump

MySQL / MariaDB

On the old server:

sudo systemctl stop netxms-server
mysqldump -u netxms -p netxms_db > /tmp/netxms-db.sql

On the new server (after installing NetXMS and MySQL):

mysql -u netxms -p netxms_db < /tmp/netxms-db.sql

Microsoft SQL Server

On the old server:

BACKUP DATABASE netxms_db TO DISK = 'C:\temp\netxms-db.bak' WITH COMPRESSION;

Restore on the new server using RESTORE DATABASE or SQL Server Management Studio.

After restoring the database, copy the configuration file and data directory to the new server (see Copying the Data Directory below), then start the server.

Changing Database Engine

If you want to switch to a different database engine as part of the migration (e.g., moving from MySQL to PostgreSQL), use the nxdbmgr migrate command.

See Database Migration for the full procedure.

Copying the Data Directory

The NetXMS server data directory contains files that are not stored in the database and must be copied separately.

Default locations:

  • Linux: /var/lib/netxms/

  • Windows: C:\NetXMS\var

The directory contains:

Subdirectory Contents

mibs/

SNMP MIB files and compiled MIB cache

files/

User-uploaded files

packages/

Agent upgrade packages

images/

Uploaded images

backgrounds/

Dashboard background images

cert/

Server certificates (including the CA used for agent tunnel certificates)

crl/

Certificate Revocation Lists

housekeeper/

Housekeeper working files (transient, can be skipped)

Copy the entire data directory to the new server:

Linux
rsync -a old-server:/var/lib/netxms/ /var/lib/netxms/
Windows
robocopy "\\old-server\c$\NetXMS\var" "C:\NetXMS\var" /E

Ensure the ownership and permissions are correct on the new server:

chown -R netxms:netxms /var/lib/netxms/

Post-Migration Steps

Verify Server Starts

Start the server and check the log for errors:

sudo systemctl start netxms-server
tail -100 /var/log/netxmsd

Check Database Consistency

Run nxdbmgr check to verify database integrity:

nxdbmgr check

Verify Data

  • Check node count matches the original system

  • Verify recent DCI data is present

  • Confirm event log contains historical entries

  • Review server configuration variables

Agent Reconnection

After migration, agents need to connect to the new server address.

DNS-Based Agent Configuration

If agents use a DNS hostname to connect, update the DNS record to point to the new server’s IP address. Agents reconnect automatically on the next connection attempt.

IP-Based Agent Configuration

If agents are configured with the server’s IP address, update agent configuration on each host:

  • Agents using tunnel connections: update the ServerConnection section in nxagentd.conf

  • Agents using direct connections: update MasterServers, ControlServers, and Servers parameters in nxagentd.conf

For large environments, use NetXMS agent policies to push updated configuration to all agents before shutting down the old server.

Decommission the Old Server

After verifying the new server is fully operational:

  1. Confirm all agents have reconnected

  2. Stop the NetXMS server on the old machine

  3. Keep the old server available for a rollback period before decommissioning