UISP - Migrate UISP Instances Using Built-In Migration Tool
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 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.
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 UISP server is not reachable by the devices.
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 the target server is using the same or higher version of the UISP application. It is not possible to apply UISP backup from a higher version to a lower one.
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.
NOTE: The step below (step 5) can be skipped for UISP Cloud.
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 view on UISP-2.
NOTE: See the How to Back Up UISP article for more information on backing up and restoring a UISP instance.
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, please make sure to verify the IP address or hostname value on the new UISP server before 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 support 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 view. and click on the Ubiquiti device that needs to be migrated.
2. In the side panel select the Manage tab and expand the Advanced section. Click on the link Migrate to different UISP application.
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 view on the other instance.