Readers will learn how to easily migrate UNMS to another server using the built-in migration tool.
NOTES & REQUIREMENTS:
Table of Contents
- About the Migration Tool
- How to Backup and Migrate the UNMS Server
- Notes and Recommendations
- Migrating Individual Devices
- Related Articles
About the Migration Tool
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 (203.0.113.1) to UNMS-2 (203.0.113.2).
The UNMS migration tool can be found in the 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 > 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
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 and UNMS-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 > UNMS > Server Settings section.
3. Create a new backup on UNMS-1 in the 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 > 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 > 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 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
- 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
Individual Ubiquiti devices can also be migrated to a different server using the steps below.
GUI: Access the UNMS Controller Web Portal.
1. Navigate to the 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 tab on the other instance.