Reconfiguring UniFi controller after a move to new host or a server can be a pain. Wouldn't it be awesome if you were able to migrate UniFi controller to a new server without having to configure everything from scratch? Here is how to do it.
Ubiquiti UniFI controller is a web-based management interface for managing several of Ubiquiti's devices. UniFi line of devices are widely gaining popularity as reliable networking gear at both prosumer and enterprise levels. Consumer-grade routers are great for small environments, once I moved to a bigger 3-level house, my reliable ASUS AC68U was not enough to cover the entire house. Actually, routers are powerful enough but most devices do not have powerful enough radios to send data back to the router through all the walls, which is why access points or mesh networks are gaining popularity.
I previously ran UniFi controller on my Docker-based Home Server with Traefik Reverse Proxy. I constantly tinker with my Intel NUC Home Server. This made UniFi controller unavailable at times. So I decided to move UniFi controller to cloud. Currently my controller is hosted on VultrVPS and it has been working great!
I have migrated Ubiquiti UniFi controller several times: Windows to native Linux app to Docker to native Linux app on DigitalOceanVPS to finally now on Docker on Vultr VPS. I made these moves without losing the settings for my home network site. Otherwise, it would have been a lot of work to configure each and every device again. In this UniFi controller migration guide, I am sharing the process I used.
Requirements
There are several basic requirements for successfully following this guide:
Access to current UniFi controller
New controller software installed on new server
Both old and new controller software versions must be the same - not required but can cause problems sometimes
Unifi Controller Version: Settings -> Controller
The environment in which the UniFi controller software resides (Windows, Linux, Mac, Docker, etc.) does not matter.
1. Backup UniFi Controller Settings
On the existing UniFi controller, back up your settings and download it to a known location. You can do this by going to UniFi controller Settings->Auto Backup->Download, as shown in the image below.
Download Unifi Controller Backup
UniFi settings will be downloaded as .unf file.
2. Install UniFi Controller on New Server
If you do not have UniFi controller installed already, I strongly recommend going the Docker way. You may follow my guide to install UniFi controller on Docker with Traefik Reverse Proxy. I followed this procedure to get UniFi controller running on the new VPS.
There are compiled executables for several platforms. Visit, UniFi Controller Download page to download and install yours.
Unifi Controller Download Page
Based on my previous experiences, I strongly discourage using native Windows app as I had a lot of issues with Java and the interface freezing up on me.
3. Restore UniFi Controller Settings
There are at least 3 ways you can migrate UniFi controller settings to a new controller software. The easiest way to restore UniFi configuration is during initial setup using the wizard, as shown below. Click on restore from previous backup and load the .unf backup file downloaded in step 1.
Restore Unifi Controller Configuration
The next option is to go through the initial setup wizard first. You do not need to add any devices (press Next) or create a WiFi network (press Skip). The only two things you will have to do is provide admin user details for the controller and device authentication details as shown below.
Unifi Controller Access Details
You will need the device authentication details to re-adopt your UniFi network devices into the new controller. Confirm and finish the setup wizard. Since we are restoring from previous backup, you may hit Skip for Cloud Login Credentials. Once done, you should be on UniFi controller interface. From here, go to Settings->Maintenance and restore the .unf backup file, as shown below.
Restore Unifi Controller Settings
Hit Confirm and give it a few minutes. Your site and its settings should be restored and the controller will be restarted (it can take a while ~5 to 10 min). Login using your old controller credentials and continue to move UniFi controller.
The third option to restore UniFi backup is very similar to the second one and only applies if you already have a functional site on the new UniFi Controller. In this case, add a new site and then restore the settings as above.
4. Set New UniFi Controller IP/Hostname
The location of your UniFi controller has now changed. Therefore, you will have to go to Settings->Controller and change the Controller Hostname/IP, to reflect the new one.
Change Unifi Controller Hostname Or Ip
Enter your new controller host IP address (local home network or IP of your cloud instance). Alternatively, you may use a FQDN, which is what I do. Then check Override inform host with controller hostname/IP and save the settings. If your UniFi controller is hosted on the cloud (away from your home network) or on a different subnet, you may disable the Make controller discoverable on L2 network option.
5. Re-adopting Devices
We are not done migrating UniFi controller completely yet. After restoring the settings you may notice that you see your devices but none of them are manageable on the controller as shown below.
Unifi Devices Disconnected
This is because your UniFi devices have not yet been adopted/recognized by the UniFi controller software. Your UniFi devices need to start sending data to your new controller. This involves modifying the inform IP on all your devices.
Controller on Same Network (L2 Adoption)
If your UniFi controller move was to a new server within same broadcast space (subnet) then the re-adoption of devices is quite easy. All you have to do is shutdown your old UniFi controller and have the new controller running. UniFi devices should automatically re-associate with the new controller. UniFi devices, by default inform to hostname unifi on port 8080. If there are two controllers with the same hostname, it will cause conflicts and hence shutting down your old controller is important.
However, if you had manually modified the inform IP previously (described below) to point to a specific IP address on your network (or hostname) and the IP address/hostname of your new UniFi controller server is different, then you will have to follow the method below (L3 adoption) to update the inform URL for the devices to be recognized again.
Controller on Different/External Network (L3 Adoption)
When UniFi controller is located on a different subnet or externally/remotely (eg. cloud VPS) then there are multiple ways to update inform IPs on your UniFi gear. Ubiquiti has an article on the various adoption methods. I am going to show you the two ways I followed and think are the easiest.
Method 1: Update Inform URL Using Ubiquiti Device Discovery Tool
Ubiquiti Network offers a Google Chrome app called Device Discovery Tool. You install the app, launch it, and click on UniFi Family as shown below. Any unadopted device should show up on the list.
Ubiquiti Device Discovery Tool
The keyword above is unadopted, which means if a device is already informing a controller it will not show up and you cannot modify the inform IP using this tool. You will have to shut down the controller that the device is informing to and then rescan on the discovery tool. Alternatively, you may use the SSH method described below.
Note that only unadopted UniFi devices show up on the Ubiquiti Device Discovery Tool and not all of your existing devices.
Once any unadopted device shows up, click Action and fill in the details highlighted below.
Set Inform Url For Unifi Devices Using Discovery Tool
You need four pieces of information:
Actions: This will be Set Inform
Inform URL: This will include either the IP address or hostname of your controller. In my case, since the controller is located on the cloud, I am using a subdomain: unifi.example.com. So my inform URL is http://unifi.example.com:8080/inform. You can also replace unifi.example.com with IP address or local hostname.
Username: This is the device authentication username from step 1.
Password: This is the device authentication password from step 1.
As you update the above information and click Execute for each device, it should disappear from the list, indicating that it has been adopted (remember: only unadopted devices show up on the list). Within a few minutes after updating the inform URL, your UniFi controller migration will be complete and the devices should be re-adopted on your new controller.
Method 2: Update Inform URL Using SSH
Using each devices IP address (local) you can SSH into it using the device authentication details from step 1. For SSH, I recommend using PuTTY or one of the PuTTY alternatives. There are also several Android SSH clients that can be used for this purpose. Once you login, you should reach the root terminal on each device (indicated by the # at the end of the prompt).
On UniFi Security Gateway (USG), you will need to issue one additional command first to reach the root terminal (not needed for switches and APs):
mca-cli
Once you are at the root terminal, issue the following command to update the inform URL for each device:
set-inform http://unifi.example.com:8080/inform
Remember to replace unifi.example.com with the IP address or hostname in your situation. The whole process should flow something like what is shown in the image below.
Set Inform Url For Unifi Devices Using Ssh
In addition to the above methods, using your mobile phone app is also convenient. This is described in detail in Ubiquiti's remote adoption methods article.
Verifying UniFi Controller Migration to New Server
Unifi Devices Adopted On Unifi Controller
The last step in moving UniFi controller to a new host is verifying that all the network devices have been adopted successfully and reporting data to your new UniFi controller. If everything went well then your devices on your new controller should all say Connected as shown above.
Like I said before, I have migrated UniFi controllers several times and I learned quite a bit during the process. In this Ubiquiti UniFi migration guide, I tried to share what I learned so a beginner can follow along. If you have any trouble, just shoot me a comment below and I will try to help you out. Otherwise, enjoy moving your UniFi controller to a new server.
Anand is a self-learned computer enthusiast, hopeless tinkerer (if it ain't broke, fix it), a part-time blogger, and a Scientist during the day. He has been blogging since 2010 on Linux, Ubuntu, Home/Media/File Servers, Smart Home Automation, and related HOW-TOs.
