Readers will learn how to easily migrate UISP to another server using the built-in migration tool.
- This article focuses on a complete migration of all UISP settings and devices that are connected to the UISP server.
- It is also possible to migrate individual devices using the Migrate option.
- It is recommended to use the latest version of UISP.
- It is essential to make sure that both servers are running the same version.
Table of Contents
- About the Migration Tool
- How to Backup and Migrate the UISP Server
- Notes and Recommendations
- Migrating Individual Devices
- Related Articles
About the Migration Tool
UISP includes a built-in migration tool that can be used to easily move connected devices to a different server.
Migrating the UISP settings and connected devices from UISP-1 (203.0.113.1) to UISP-2 (203.0.113.2).
The UISP 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 UISP server.
- Once applied, the UISP key will be automatically replaced on connected Ubiquiti devices.
- All devices lose connectivity with the old UISP server and will show up in the new instance.
- After the migration, devices that connect to the old UISP server will be automatically redirected to the new server.
- It is important to create a backup of the old UISP server in the Settings > Backup section before starting the migration process.
- Restore the backup on the new UISP server and verify the Hostname/IP prior to initiating the migration.
- UISP 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.
How to Backup and Migrate the UISP Server
Before starting the migration, please take a moment to carefully read the UISP Key and the Device Registration Process article to learn how the generic UISP key works. In the steps below, the original/old UISP instance will be called UISP-1 and the new instance will be UISP-2.
1. Verify that both servers are using the same UISP release version.
2. Verify that UISP-2 is using the correct IP address or hostname in the Settings > UISP > Server Settings section.
3. Create a new backup on UISP-1 in the Settings > Backups section.
4. Upload the backup on UISP-2 in the same section by selecting the Restore from File option.
5. The uploaded backup also overrides the IP address or hostname value in the Settings > UISP > Server Settings section on UISP-2. Make sure to correct this after the restoration.
6. Start the migration on UISP-1 by navigating to the Settings > Devices > Migration Settings section.
Migration Mode: On
Force Mode: Off (optional)
Hostname: IP address or hostname of UISP-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 UISP-2.
Notes and Recommendations
- Any Ubiquiti device (with an enabled UISP connection), that tries to connect to the old UISP 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 Subscribers 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 UISP server prior to starting the migration.
- It is recommended to use an FQDN instead of an IP address to allow for easier migration.
- If you are migrating a self-hosted UISP 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 Zendesk ticket, and provide the details of your old and new instances.
Migrating Individual Devices
Individual Ubiquiti devices can also be migrated to a different server using the steps below.
1. Navigate to the Devices tab. and select the Ubiquiti devices that need 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) UISP instance and fill in the information.
4. Verify if the devices have migrated successfully in the Devices tab on the other instance.