Migrate UniFi Network (Controller)

This How To Migrate UniFi Network (former called UniFi Controller) helps to migrate from one device to another. If you know how, it’s actually quite easy. Just follow this guide.


Migrate UniFi Network (Controller)

Migrate UniFi Network (Controller)


Index of Migrate UniFi Network (Controller)


I have migrated a couple of months ago my UniFi Network (former called UniFi Controller) instance from a Raspberry Pi 3 installation to a Raspberry Pi 4 Model B instance. Over the time I saw that the Raspberry Pi 4 is having boring times since its resources are not really leveraged by UniFi Network.

Meanwhile I found another cool project that is RetroPi and I decided to migrate back my UniFi Network instance to the Raspberry Pi Model 3 whilst leveraging on the Raspberry Pi Model 4 for the RetroPi project.

This little guide explains how I migrated UniFi Network from Raspberry Pi 4 Model B to Raspberry Pi 3 Model B. A classical hardware downgrade 🙂

How To Migrate UniFi Network (Controller)

To get the migration done, I share with you a couple of steps that should not only work for Raspberry Pi, but also for other Linux based systems.

First phase: Setup Raspberry Pi Model 3 Properly 

  1. Download the latest Raspberry Pi Imager
    Raspberry Pi Imager v1.7.3

    Raspberry Pi Imager v1.7.3


  2. Install the Raspberry Pi Imager or update your existing Raspberry Pi Imager by the in step 1 downloaded Raspberry Pi Imager
  3. Start the newly installed Raspberry Pi Imager / the updated Raspberry Pi Imager
  4. Choose the OS. In the case of this How To I have selected 
    – Raspberry Pi OS (other)
    – Raspberry Pi OS Lite (32-bit) – A port of Debian Bullseye with no desktop environment
  5. Select the storage device you like to install the Raspberry Pi OS image. Typically a SD Card.
  6. Consider to configure headless SSH before you write the Image. If you do this, you will be able to access the Raspberry Pi without a screen, but securely by SSH. For an easy How To check out this How To Setup Raspberry 3B For Headless SSH
  7. If you run Raspberry (like I do) without a monitor and manage it only remotely by SSH, then you can give Raspberry some additional Memory that is reserved for the GPU. This basically means, we now reduce the 64 MB RAM allocated for the GPU (needed for the graphical user interface) and make it available to the rest of the Raspberry. Run the below command:
    sudo raspi-config

    – Select “4. Performance Options”
    – Select “P2 GPU Memory”
    – Change the “64” to “16”
    – Enter, Finish and Restart
  8. After the Restart, login to your Raspberry leveraging on SSH because we need it for the following second phase. 

Second Phase: Install UniFi Network

These easy steps will help you to get UniFi Network (former UniFi Controller) installed on a Raspberry Pi 3B. 

  1. Update your Raspberry by running the below four commands:
    sudo apt update 
    sudo apt full-upgrade -y 
    sudo apt autoremove -y 
    sudo apt-get autoclean -y
  2. Once updated, lets install (or Update) to Java 8 that is needed for UniFi Network. Run:
    sudo apt-get install openjdk-8-jre-headless -y
  3. Add the UniFi Network (former UniFi Controller) repository. To do so, run these two commands:
    echo 'deb http://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list
    sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ubnt.com/unifi/unifi-repo.gpg
  4. Let’s install UniFi Network. Run:
    sudo apt-get update; sudo apt-get install unifi -y

    In case you see an error message that is about mongodb-server, then check out the following additional step: Error message: Mongodb. Once done, run the same command again:
    sudo apt-get update; sudo apt-get install unifi -y
  5. UniFi Network (UniFi Controller) has installed in step 4 MongoDB. This comes with a default database. This default database is not needed and should therefore for security and resources reasons be removed. This we do by the execution of the below two commands:
    sudo systemctl stop mongodb 
    sudo systemctl disable mongodb
  6. Once steps 1-5 were done successfully, we reboot the system. This also allows to check whether after a reboot everything is working properly.
    sudo reboot

Third Phase: Migration Of The Existing UniFi Network Setting and Installation


Once you successfully completed Phase One and Phase Two, you now should be ready to migrate from the old installation to the new one. To get this done we consider the following:

  • The existing installation, on which UniFi Network currently is working is called “OLD”
  • The target installation, means the new UniFi Network installation to which you would like to migrate is called “NEW”

Check whether the new installation is working

First, we login to the NEW installation in order to check whether everything is working as expected. To do so, we open an internet browser and type: https://IP_ADDRESS_OF_NEW_INSTALLATION:8443. For example: If the installation was successful, a screen like the below should show up (depending on your browser you maybe need to confirm first, that you are OK to continue with a by the browser not considered secure connection):

First Logon Screed of UniFi Network Installation

First Logon Screed of UniFi Network Installation


If you get the above window, then GREAT! Follow the next steps!

Backup the OLD UniFi Network (Controller)

Login to your OLD UniFi Network (Controller). In your OLD UniFi Network (Controller) execute the following steps:

  1. Klick on “Settings”
  2. Klick on “System”
  3. Scroll down and to “Backup” and click “Download Backup”. Select the option of “No Limit” or if you like to limit, select which ever limit you prefer.
    How To Backup UniFi Controller

    How To Backup UniFi Controller


  4. Depending on your installation, the download maybe needs a bit of time. Once downloaded successfully, you have the migration file which you need for the next steps. Typically it’s stored (depending on your browser) in the Downloads folder and it’s called something like “network_backup_XX.YY.2023_17-37_v7.3.76.unf”.

Restore the OLD UniFi Network (Controller) to the NEW UniFi Network (Controller)

  1. Switch back now to the NEW installation. On this screen you click “Or restore setup from backup”. 
  2. In the next step you will be asked to select the backup file which you like to restore. Of course you select the one that you just before downloaded from your OLD installation. 
  3. After a while you will receive a message asking you whether you like to Restore the backup. You need to hit the red Restore button. Following this you will find a message like this “Backup restoration is in progress. Your Network application will reboot during this process.”. This can take a while… …. whilst you are training your patience (this can take seconds to dozents minutes) you can watch the computer working by firing the below command into the terminal of the NEW installation:

    This will output something like this:
    top - 19:51:07 up  3:25,  1 user,  load average: 1.19, 0.85, 0.37
    Tasks: 117 total,   1 running, 116 sleeping,   0 stopped,   0 zombie
    %Cpu(s): 22.6 us,  3.5 sy,  0.0 ni, 73.0 id,  0.0 wa,  0.0 hi,  0.9 si,  0.0 st
    MiB Mem :    971.7 total,     86.3 free,    550.8 used,    334.5 buff/cache
    MiB Swap:    100.0 total,     98.7 free,      1.2 used.    368.5 avail Mem 
      PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND                                                                           
      530 unifi     20   0 1353880 497924  16592 S  82.2  50.0  10:56.61 java                                                                              
      914 unifi     20   0  511256 202104 170084 S  23.4  20.3   2:01.56 mongod                                                                            
      359 avahi     20   0    7180   3312   2704 S   1.3   0.3   0:28.29 avahi-daemon                                                                      
     1778 pi        20   0   14388   3876   3004 S   0.7   0.4   0:00.08 sshd                                                                              
     1833 pi        20   0   11248   2980   2516 R   0.7   0.3   0:00.25 top                                                                               
     1801 root      20   0       0      0      0 I   0.3   0.0   0:00.43 kworker/0:0-events                                                                
        1 root      20   0   33776   8836   7072 S   0.0   0.9   0:04.41 systemd                                                                           
        2 root      20   0       0      0      0 S   0.0   0.0   0:00.04 kthreadd                                                                          
        3 root       0 -20       0      0      0 I   0.0   0.0   0:00.00 rcu_gp                                                                            
        4 root       0 -20       0      0      0 I   0.0   0.0   0:00.00 rcu_par_gp                                                                        
        5 root       0 -20       0      0      0 I   0.0   0.0   0:00.00 slub_flushwq                                                                      
        6 root       0 -20       0      0      0 I   0.0   0.0   0:00.00 netns                                                                             
       10 root       0 -20       0      0      0 I   0.0   0.0   0:00.00 mm_percpu_wq                                                                      
       11 root      20   0       0      0      0 S   0.0   0.0   0:00.00 rcu_tasks_rude_                                                                   
       12 root      20   0       0      0      0 S   0.0   0.0   0:00.00 rcu_tasks_trace                                                                   
       13 root      20   0       0      0      0 S   0.0   0.0   0:00.59 ksoftirqd/0                                                                       
       14 root      20   0       0      0      0 I   0.0   0.0   0:04.68 rcu_sched                                                                         
       15 root      rt   0       0      0      0 S   0.0   0.0   0:00.00 migration/0                                                                       
       16 root      20   0       0      0      0 S   0.0   0.0   0:00.00 cpuhp/0                                                                           
       17 root      20   0       0      0      0 S   0.0   0.0   0:00.00 cpuhp/1                                                                           
       18 root      rt   0       0      0      0 S   0.0   0.0   0:00.00 migration/1                                                                       
       19 root      20   0       0      0      0 S   0.0   0.0   0:00.10 ksoftirqd/1

    Anytime you can close this by simply press the “q” for quit on your keyboard. Once the backup is finished, you will see once the login screen appears. This should look like this:

    Migrate UniFi Controller (Raspberry)

    Migrate UniFi Controller (Raspberry)

    Test whether everything is working by login. NOTE: You will not yet find your devices! For migrating your devices being online. You will rather find them offline. This because your devices still believe they belong to your OLD controller. For this reason, we need to tell them that they belong to a NEW UniFi Network (Controller). To do so, follow the next chapter. 

Request your devices to migrate

In this final step we are going to tell the UniFi devices to migrate to the NEW UniFi Network (Controller). To do so, follow these steps:

  1. Login to the OLD UniFi Network (Controller)
  2. Click “Settings”
  3. Click “System”
  4. Within “Site Management” click on “Export Site”. 
  5. Read carefully the guidance and click “Download the Site Export File”
  6. Once downloaded click on “Continue”
  7. Now the menu will tell you to go to the NEW UniFi Network (Controller). This however we have not to do, since we already restored the full backup before. We continue by clicking “Continue”.
  8. A new window pop’s up. It’s basically asking you the IP of the NEW UniFi Network (Controller). Of course you enter the IP Address and the port of the NEW UniFi Network (Controller). Furthermore, you select the devices to be migrated. In my case, all of them. Click “Migrate Devices”
  9. You will see the summary and you need to click “Device_Actions_Forget_Label_Plural”. This looks like the menu was not made properly. However, I click it.
  10. Another message looking like this: “DEVICE_ACTIONS_FORGET_CONFIRM_MESSAGE_PLURAL” will be shown. This looks like strange, but click the “Forget” button
  11. Finally you see a message telling you devices were removed.
  12. Move to the NEW UniFi Network (Controller) and check whether the devices become online. NOTE: This can take seconds, up to dozens of minutes. The devices will disappear in the OLD controller. 
  13. You are done. Enjoy managing your network with the new controller.

Additional Information of How To Migrate UniFi Network (Controller)

Error Message: Mongodb

There is a likelihood that you receive an error message like the below one. This chapter helps you to fix it.

Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:

The following packages have unmet dependencies:
 unifi : Depends: mongodb-server (>= 2.4.10) but it is not installable or
                  mongodb-10gen (>= 2.4.14) but it is not installable or
                  mongodb-org-server (>= 2.6.0) but it is not installable
         Depends: mongodb-server (< 1:4.0.0) but it is not installable or
                  mongodb-10gen (< 4.0.0) but it is not installable or
                  mongodb-org-server (< 4.0.0) but it is not installable
E: Unable to correct problems, you have held broken packages.

The error message is most likely caused because UniFi does not support the latest version of MongoDB. For this reason wee need to allow installing an older version. To fix this situation run:

echo 'deb http://archive.raspbian.org/raspbian stretch main contrib non-free rpi' | sudo tee /etc/apt/sources.list.d/raspbian_stretch_for_mongodb.list

Follow me

It would be amazing if you follow myHowTo.blog. To follow leverage on

  • Click to follow me on Twitter
  • Bookmark this page and comeback from time to time

Help and Comments

I am really looking forward for you to contact me if for example you found a better option or other idea then in this how to. Also, please touch base if you found an error or anything not working or if you have something that you would love to be added to this how to. Simply click this link to touch base with me.

Linking and Recommending the HowTo or the myhowto.blog

I would love to see you are recommending this how to or link it to your website. Also, I would love if you link or recommend the whole myhowto.blog. Please feel free to do so! In case you like to touch base regarding this topic with me, then simply click this link. I look forward!