UNMS v1 - Migration Tool


This article describes how to use the built-in Migration tool to easily move the UNMS server to a different machine.

NOTE: This guide is focused on a complete migration of all devices. It is also possible to migrate individual ones with the button 'Migrate' in the device list. It is recommended to use UNMS version 0.14.0+, or 1.0.0-beta.3+.

Table of Contents

  1. About the Migration Tool
  2. How to Migrate UNMS
  3. Notes
  4. Related Articles

About the Migration Tool

Back to Top

Find the Migration tool in the UNMS interface under Settings > Devices > Migration Settings.


There are two different stages in the migration process. The first stage happens immediately when the Migration tool is enabled. In this stage, UNMS first checks if the new address is accessible from all devices. If it is not, then the migration process is terminated at this point.

NOTE: It is possible to disable this verification but if the devices cannot connect to the new hostname it will create serious complications and possibly a lot of manual work.

If the verification completes successfully then the domain part of the device-specific UNMS key is automatically rewritten for all connected devices with the provided value. This will cause all devices to lose connectivity with the current UNMS instance.

In the second stage, UNMS waits for any new devices and when they connect, UNMS will do the same change to it automatically. 

How to Migrate UNMS

Back to Top

First of all, it is necessary to understand how the generic UNMS key works. Please carefully read this article. In the following steps, the original UNMS instance will be called UNMS A and the new instance where the migration should move all devices will be UNMS B.

  1. Make sure UNMS B is running on the new address.
  2. Create a backup of the current UNMS A instance.
  3. Apply that backup on UNMS B by going to (in UNMS B) Settings -> Backups -> Restore & Download -> Restore and click the 'Choose File' button.
  4. (Skip this for UNMS Cloud) When the backup is applied, go to Settings -> UNMS -> UNMS Hostname/IP and make sure there is the correct hostname (the backup inserted the hostname of UNMS A here).
  5. Now UNMS B is prepared and it is possible to start the migration from UNMS A.
  6. In UNMS A go to Settings -> Devices -> Migration Settings.
  7. Turn the Migration mode ON and insert the hostname and port of the UNMS B instance. Use standard port 443 for the UNMS Cloud instance.
  8. Click "Apply Changes".
  9. Open UNMS B and check if all devices have migrated correctly.


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 because of the information contained in the created backup.
  • When the backup of old UNMS is applied to the new one the old Hostname rewrites the new one. For that reason, it is vital to check the hostname in step three.
NOTE: It is strongly recommended to have the FQDN as a Hostname if possible. Moving UNMS server to a different address is more convenient that way. The migration tool is specifically created to allow easy transfer even when the IP address is used.

Related Articles

Back to Top 

UNMS - The UNMS Key and the Device Registration Process
UNMS - How to Back Up UNMS

We're sorry to hear that!