How to Migrate a UniFi Network Application to UniFi OS Server
Moving from the old UniFi Network Application to UniFi OS Server is four jobs: get a server, install UniFi OS Server, restore your backup, and get your devices talking to the new address. The fourth one is where migrations go wrong. Based on migrations we run regularly.
What actually happens to your devices
Every UniFi device holds an inform URL: the address it reports to. Restoring a backup onto a new system does not change what is stored on the devices. They keep calling the old address until something tells them otherwise.
This is why a migration can look finished, with all your settings present in the new interface, while the device list sits there showing everything offline or disconnected. The configuration moved. The devices did not get the memo.
You have three ways to deal with it, and the right one depends on how your network is set up.
Keep the old address pointing at the new system. If your devices inform to a hostname rather than a bare IP address, repoint that hostname at the new server. The devices never notice, because the name they already hold now resolves somewhere new. This is the least disruptive route, and it is how a hosted migration should be done.
Set the inform address from the controller. Once devices are adopted, the controller can push a new inform address. This works, but only for devices that are currently reachable and connected.
Set it on each device. SSH to the device and run set-inform http://newaddress:8080/inform. Reliable, works when nothing else does, tedious across a large site. There is also DHCP option 43 and a DNS record named unifi, which are worth setting up before a migration rather than during one.
Do not "force provision" old devices to fix this
When a device is stuck, the instinct is to force a provision from the controller. On devices running older firmware, that pushes a full configuration and can leave the device unusable rather than merely offline. Use the inform address methods above, and update firmware before migrating, not after something breaks.
The migration, step by step
1. Check what you are moving. Note your Network application version, your device count, and whether your administrator accounts are local or linked to Ubiquiti accounts. Old versions may need an intermediate upgrade before their backup will restore onto current software.
2. Take a backup you trust. Download a .unf backup and keep it somewhere that is not the server you are about to replace. Take it while everything is still running normally.
3. Install UniFi OS Server, or have it provisioned. It runs on ordinary Linux or Windows servers. Give it more disk than you think you need; controller databases grow with device counts and retention.
4. Restore, before you finish the setup wizard. On a fresh system, choose to restore from a backup rather than setting up a new site. If you complete the wizard first and restore afterwards, you can end up with a stray extra site and an owner account you did not intend.
5. Re-point the devices, using one of the three methods above.
6. Verify against a number, not a feeling. Count the devices that were online before, and confirm the same count is online after, an hour later. Devices that were already offline before the migration will stay offline afterwards, and it is better to know that up front.
Two things that catch people out
The owner account. UniFi OS has an owner, and which account becomes the owner matters. If the account you choose is local-only, with no Ubiquiti account linked to it, you will be able to log in locally but you will not be able to use Ubiquiti single sign-on or remote access with it. That is recoverable, but it is much easier to choose a Ubiquiti-linked account at the start.
The old system, kept alive too long. If the old controller stays running and reachable, some devices may continue to inform to it, and you can end up with a device adopted in two places and settings applied from the wrong one. Once you have verified the new system, retire the old one deliberately.
Doing it with us
If you host with us, the migration is a request rather than a project. What we do:
- Provision the new system and restore your backup into it.
- Keep your existing hostname working, so devices re-point without you touching them.
- Migrate your administrator accounts, including their passwords, so people log in with the credentials they already have.
- Watch the device count before and after, and tell you if it does not match.
Typical elapsed time is under an hour for a normal site, most of it waiting for devices to check in. Your devices reconnect on their own schedule, which is usually minutes but can be longer for devices on poor links.
If you are migrating a controller you host yourself and you want it hosted afterwards, that is the same job with the same considerations. Send us a backup and the details of how your devices inform, and we will tell you honestly whether it is straightforward or fiddly before you commit.
Should you migrate at all?
If your Network application is stable, self-hosted, and serving one site that you can walk to, there is no urgency. UniFi OS Server is where Ubiquiti is putting its effort, so you will move eventually, but "eventually" can be on your schedule.
Migrate sooner if you want remote access through Ubiquiti's account system rather than an exposed port, if you are tired of managing Java and certificates, or if you are already planning to move the controller anyway. Doing a migration and a hosting change as one move is less disruptive than doing them separately.
Related:
UniFi and UniFi OS are trademarks of Ubiquiti Inc. Cloud UniFi is an independent hosting provider and is not affiliated with, authorised by or endorsed by Ubiquiti Inc.