UNMS - Migration Tool


Readers will learn how to easily migrate UNMS to another server using the built-in migration tool.

  • This article focuses on a complete migration of all UNMS settings and devices that are connected to the UNMS server.
  • It is also possible to migrate individual devices using the Migrate option.
  • It is recommended to use the latest version of UNMS and make sure that both servers are running the same version.
  • More information on the Ubiquiti Network Management System can be found on the UNMS website.

Table of Contents

  1. About the Migration Tool
  2. How to Backup and Migrate the UNMS Server
  3. Notes and Recommendations
  4. Migrating Individual Devices
  5. Related Articles

About the Migration Tool

Back to Top

UNMS includes a built-in migration tool that can be used to easily move connected devices to a different server.


Migrating the UNMS settings and connected devices from UNMS-1 ( to UNMS-2 (

The UNMS migration tool can be found in the  settings.png  Settings > Devices > Migration Settings section.

  • When you turn on the Migration Mode, you will be asked to insert the Hostname/IP and Port of the new UNMS server.
  • Once applied, the UNMS key will be automatically replaced on connected Ubiquiti devices.
  • All devices to lose connectivity with the old UNMS server and will show up in the new instance.
  • After the migration, devices that connect to the old UNMS server will be automatically redirected to the new server.
  • It is important to create a backup of the old UNMS server in the  settings.png  Settings > Backup section before starting the migration process. 
  • Restore the backup on the new UNMS server and verify the Hostname/IP prior to initiating the migration.
  • UNMS will check if the new address is accessible from all devices prior to starting the migration.  If it is not, then the migration process is terminated unless you enable the Force Mode option.
NOTE:Use the Force Mode option at your own risk as it will create serious complications and possibly a lot of manual work if the new UNMS server is not reachable by the devices.

How to Backup and Migrate the UNMS Server

Back to Top

Before starting the migration, please take a moment to carefully read the The UNMS Key and the Device Registration Process article to learn how the generic UNMS key works. In the steps below, the original/old UNMS instance will be called UNMS-1 and the new instance will be UNMS-2

GUI: Access the UNMS-1 andUNMS-2 Controller Web Portal. 

1. Verify that both servers are using the same UNMS release version.

2. Verify that UNMS-2 is using the correct IP address or hostname in the  settings.png  Settings > UNMS > Server Settings section.

3. Create a new backup on UNMS-1 in the  settings.png  Settings > Backups section.

4. Upload the backup on UNMS-2 in the same section by selecting the Restore from File option.

NOTE:The step below (step 5) can be skipped for UNMS Cloud.

5. The uploaded backup also overrides the IP address or hostname value in the  settings.png  Settings > UNMS > Server Settings section on UNMS-2. Make sure to correct this after the restore.

6. Start the migration on UNMS-1 by navigating to the  settings.png  Settings > Devices > Migration Settings section.

Migration Mode: On
Force Mode: Off (optional)
Hostname: IP address or hostname of UNMS-2
WS Port: 443 (default)

7. Apply the changes and wait for the migration to complete.

8. Verify if the devices have migrated successfully in the  devices.png  Devices tab on UNMS-2.

NOTE:See the How to Back Up UNMS article for more information on backing up and restoring a UNMS instance.

Notes and Recommendations

Back to Top

  • Any Ubiquiti device (with an enabled UNMS connection), that tries to connect to the old UNMS instance after the migration will be automatically redirected to the new instance. The device will appear there as unauthorized.
  • Devices transferred during the first stage of migration will be attached to their appropriate Sites or Client Sites using the information contained in the created backup.
  • After restoring the backup, make sure to verify the IP address or hostname value on the new UNMS server prior to starting the migration.
  • It is recommended to use an FQDN instead of an IP address to allow for an easier migration.
  • If you are migrating a self-hosted UNMS instance to a new server that uses the same hostname, then make sure to update the A record on the DNS server.
  • If you are experiencing any issues during or after the migration, then please create a new thread on the Ubiquiti Community with the UNMS tag and provide the details of your old and new instance.

Migrating Individual Devices

Back to Top

Individual Ubiquiti devices can also be migrated to a different server using the steps below.

GUI: Access the UNMSController Web Portal. 

1. Navigate to the  devices.png  Devices tab. and select the Ubiquiti device that needs to be migrated.

2. Expand the menu and select the Migrate option.

3. Select whether to migrate the device to an empty or restored (from backup) UNMS instance and fill in the information.

4. Verify if the devices have migrated successfully in the  devices.png  Devices tab on the other instance.

Related Articles

Back to Top

UNMS - The UNMS Key and the Device Registration Process

UNMS - How to Back Up UNMS

UNMS - Installation Guide

Was this article helpful?
10 out of 11 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community