UISP Cloud Hosting - Migration scenarios
Note: UPG (Ubiquiti Payment Gateway) is not available on UISP Console or Local instance
Note: In case of a migration from unmsapp.com, the new domain will be uisp.com. This change has no impact, as both domains are configured in the DNS settings of the UISP Console proxy. Therefore, hostname.unmsapp.com will function the same as hostname.uisp.com.
Migration from UISP Cloud Hosting to UISP Console using the same hostname
-
Prepare the backup of the UISP Cloud Hosting
- Go to the UISP Portal and check if the UISP Cloud Hosting you are migrating is present there. If not, sign in with the correct UI Account.
- If your UISP Cloud application is already disabled, click on the Download Backup link to download the backup file. Then, skip to Part 2: Set up a new UISP Console, below.
- If your UISP Cloud is enabled, then check the backup settings in the CRM module: Go to System > Tools > Backup and enable all entities you want to include in the migration backup.
- Create the backup of the UISP Cloud Hosting.
- Go to UISP Application > Settings > Backup and click Create Backup.
- Wait for the backup to be created and download it to your PC.
- Go back to the UISP Portal and remove your UISP Cloud application. Only the owner has permission to do this.
-
Set up a new UISP Console
- Turn on the new UISP Console and ensure that port 9 or 10 is connected to the internet.
- If there is an SD card in the UISP Console's slot, temporarily remove it.
- Open the UISP Mobile app and make sure it is updated to the latest version.
- Sign in to the UISP Mobile app using the same SSO account associated with the UISP Cloud Hosting you are migrating from.
- iOS: Tap More > Log in
- Android: Tap the user icon in the top left bar, tap Login to ui.com, then add your account.
- Wait for the adoption modal to appear for the UISP Console and follow the Setup Wizard.
- If the mobile app displays an error about a missing internet connection, please contact support.
- When prompted to create a UISP application instance, select New Instance.
- When asked for the hostname of the new UISP application, choose the same hostname as the old UISP Cloud.
- If you receive an error indicating that the hostname is already in use, verify that the old UISP Cloud instance has been deleted and that the UISP Mobile app is linked to the UI account of the cloud's owner.
- Confirm that the new UISP application is running before reinserting the SD card.
- Update the UISP application to the latest version via Settings > Maintenance.
-
Restore backup on UISP Console
-
- Log in to the UISP Application running on the UISP Console.
- Restore the backup in the UISP Application: Go to Settings > Backup and click Restore from File.
- Wait for the restoring process to finish.
- After restoring, you will need to wait a bit to be able to log in with an SSO account.
You might see this message for some time: “Authentication failed. The UI Account you are currently using is not bound to the SSO used for this UISP Console.“ - Assign the pending UISP Console device to the site after the restore; it’s the Console UISP is running on. Due to the backup restore from another instance, the Console is in a pending adoption state.
- The vault key will be transferred from the UISP Cloud Hosting.
- Check mail server settings in UISP Network: Settings > General > Mail Server on UISP Console.
-
Migration from UISP Cloud Hosting to UISP Console using a different hostname
-
Prepare the backup of the UISP Cloud Hosting
- Go to the UISP Portal and check if the UISP Cloud Hosting you are migrating is present there. If not, sign in with the correct UI Account.
- If your UISP Cloud application is already disabled, click on the Download Backup link to download the backup file. Then skip to part 2 (Set up a new UISP Console).
- If your UISP Cloud is enabled, then stop automatic billing and payment processing in the CRM module: System > Billing > Invoicing.
- Disable the Automatic billing enabled option.
- Disable the Online payment processing option.
- Disable Client zone in the CRM module: System > Settings > Client Zone and disable Enable client zone.
- Check the backup settings in the CRM module: System > Tools > Backup and enable all entities you want to include in the migration backup.
- Create the backup of the UISP Cloud Hosting.
- Go to UISP Application > Settings > Backup and click Create Backup.
- Wait for the backup to be created and download it to your PC.
-
Set up a new UISP Console
- Turn on the new UISP Console and ensure that port 9 or 10 is connected to the internet.
- If there is an SD card in the UISP Console's slot, temporarily remove it.
- Open the UISP Mobile app and make sure it is updated to the latest version.
- Sign in to the UISP Mobile app using the same SSO account associated with the UISP Cloud Hosting you are migrating from.
- iOS: Tap More > Log in
- Android: Tap the user icon in the top left bar, tap Login to ui.com, then add your account.
- Wait for the adoption modal to appear for the UISP Console and follow the Setup Wizard.
- If the mobile app displays an error about a missing internet connection, please contact support.
- When prompted to create a UISP application instance, select New Instance.
- Confirm that the new UISP application is running before reinserting the SD card.
- Update the UISP application to the latest version via Settings > Maintenance.
-
Restore backup on UISP Console
- Log in to the UISP Application running on the UISP Console.
- Restore the backup in the UISP Application: Go to Settings > Backup and click Restore from File.
- Wait for the restoring process to finish.
- After the restore, you will need to wait a bit to be able to log in with the SSO account.
You might see this message for some time: “Authentication failed. The UI Account you are currently using is not bound to the SSO used for this UISP Console.“ - Assign the pending UISP Console device to the site after the restore; it’s the Console UISP is running on. Due to the backup restore from another instance, the Console is in a pending adoption state.
- The vault key will be transferred from the UISP Cloud Hosting.
- Check mail server settings in UISP Network: Settings > General > Mail Server on UISP Console.
- Set the proper hostname in UISP Network: Settings > General > UISP Hostname.
- Enable previously disabled options in the CRM module: Automatic billing, Online payment processing, and Client zone on UISP Console.
-
Migrate devices to UISP Console
- Go to the UISP Cloud Hosting you are migrating from and enable migration mode in Settings > Devices > Migration.
- Enable the option Migration Mode.
- Enable the option With Backup.
- Enter the new hostname in the Hostname field.
- Optional: if you are using a custom port, you can set the Port option. The default value is 443.
- Apply changes.
- All devices should connect to the new UISP application.
- Go to the UISP Cloud Hosting you are migrating from and enable migration mode in Settings > Devices > Migration.
-
Configure new UISP instance running on UISP Console
- Check mail server settings in Settings > General > Mail Server.
- Set the proper hostname in Settings > General > UISP Hostname.
- Enable previously disabled options in the CRM module: Automatic billing, Online payment processing, and Client zone on UISP Console.
Tips
- Don’t forget to inform your clients that the URL of the client section has changed to the new domain.
- Check your 3rd party integrations and update the URL to the new one.
Migration from UISP Cloud Hosting to Local instance/custom server
-
Prepare the backup of the UISP Cloud Hosting
- Go to the UISP Portal and check if the UISP Cloud Hosting you are migrating is present there. If not, sign in with the correct UI Account.
- If your UISP Cloud application is already disabled, click on the Download Backup link to download the backup file. Then skip to part 2 (Set up a new UISP Console).
- If your UISP Cloud is enabled, then stop automatic billing and payment processing in the CRM module: System > Billing > Invoicing.
- Disable the Automatic billing enabled option.
- Disable the Online payment processing option.
- Disable Client zone in the CRM module: System > Settings > Client zone and disable Enable client zone.
- Check the backup settings in the CRM module: System > Tools > Backup and enable all entities you want to include in the migration backup.
- Create the backup of the UISP Cloud Hosting.
- Go to UISP Application > Settings > Backup and click Create Backup.
- Wait for the backup to be created and download it to your PC.
-
Set Up new UISP Application on your server
- Set up a new UISP instance on your local server. Click Upload Backup during the setup process.
- Wait for the Setup Wizard to finish, and ensure you can access the UISP Application.
- Wait for the restoring process to be finished.
- Set password for at least one user using UISP CLI:
- SSH to your local server.
- Print list of users: /home/unms/app/unms-cli set-password.
- Set password for selected user: /home/unms/app/unms-cli set-password --username <USERNAME>.
- Login to UISP using the new set password.
-
Migrate devices to a new instance
- Go to your UISP Cloud Hosting you are migrating from and enable migration mode in Settings > Devices > Migration.
- Enable the option Migration Mode.
- Enable the option With Backup.
- Enter the new hostname in the Hostname field.
- Optional: if you are using a custom port, you can set the Port option. The default value is 443.
- Apply changes.
- All devices should connect to the new UISP application.
- Go to your UISP Cloud Hosting you are migrating from and enable migration mode in Settings > Devices > Migration.
-
Configure a new UISP instance running on the local server
- Check mail server settings in Settings > General > Mail Server.
- Set proper hostname in Settings > General > UISP Hostname.
- Enable previously disabled options in the CRM module: Automatic billing, Online payment processing, and Client zone on the UISP Console.
- Download the Vault key from UISP Cloud Hosting: go to UISP Portal, click the three dots and select Download Vault.
- Upload the vault key in the UISP Application running on your local server: go to Settings > Credentials Vault and upload the key.
Tips
- Don’t forget to inform your clients that the URL of the client section has changed to the new domain.
- Check your 3rd party integrations and update the URL to the new one.
Troubleshooting
Getting the "Hostname has already been used" error
When the UISP Console/Cloud hostname is deleted, it has a 24-hour protection window. In this window only the UI Account that deleted the hostname can use it again. After the protection window ends, any UI Account can claim that hostname. Make sure to use the correct UI Account when creating a new UISP console/cloud application to avoid getting this error.