Installing the UniFi Controller on the Raspberry Pi

With this tutorial, we will be showing you the process of installing the UniFi Controller on a Raspberry Pi

Raspberry Pi UniFi Controller


UniFi is a range of network devices created by Ubiquiti. These devices range from Wi-Fi access points to security gateways and switches.

Setting up the UniFi software on a Raspberry Pi is a fairly straightforward process as it just relies on the multi-platform Java runtime to run.

Using the UniFi network controller, you can manage all the UniFi devices that are a part of your network. You will also be able to use this dashboard to see the statistics of your UniFi network.

Please note that before proceeding you will need to be running a 32-bit version of Raspberry Pi OS for this tutorial to work. At this time, 64-bit is not supported.

Equipment List

Below is a list of the equipment that you will need to set up the Unifi Network Controller software on your Raspberry Pi

Recommended

Optional

This tutorial on setting up the UniFi Network Controller was tested on a Raspberry Pi 4 running the latest version of Raspberry Pi OS Bullseye 32-bit.

Preparing your Raspberry Pi for the UniFi Controller

In this section, we will be preparing the operating system so it can run the UniFi software.

1. The first thing you should do is ensure that your Raspberry Pi is running up to date packages.

To update all packages, you will be required to run the following command.

sudo apt update
sudo apt upgrade

2. To improve the startup speed of the UniFi controller software on our Raspberry Pi, we need to install rng-tools.

We will utilize this package to ensure the Raspberry Pi has enough entropy for the random number generation that the UniFi software uses.

sudo apt install rng-tools

3. We now need to make a slight change to the rng-tools configuration.

Begin editing the config file by running the following command.

sudo nano /etc/default/rng-tools-debian

4. Within this file, find and uncomment the following line.

Find

#HRNGDEVICE=/dev/hwrng

Replace With

HRNGDEVICE=/dev/hwrng

By uncommenting this line, we are adding to the amount of entropy (The amount of randomness) that the system has available.

The Raspberry Pi features an integrated random number generator that we can utilize to increase the entropy pool.

5. Once you have made the change, save the file by pressing CTRL + X, then Y, followed by ENTER.

6. Finally, restart the rng-tools service by running the command below.

sudo systemctl restart rng-tools

Once the service has finished restarting, it should now be safe to proceed to the next section of this guide.

Enforcing 32-Bit Kernel

Recent releases of Raspberry Pi OS have been shipping with a 64-bit kernel even if you are running a 32-bit release of the operating system.

To work around this, we can add an option to the boot configuration file to switch the kernel back to running as 32-bit.

If we don’t do this, we won’t be able to use the UniFi controller on our Raspberry Pi as the version of MongoDB we are using does not support ARM 64-bit.

1. To tell the Raspberry Pi that it should boot using the 32-bit version of the kernel run the following command.

This command adds the line “arm_64bit=0” to the bottom of the “/boot/config.txt” file.

echo "arm_64bit=0" | sudo tee -a /boot/config.txt

2. After making this change to the boot configuration you will need to restart your Raspberry Pi.

You can restart your device by using the command below.

sudo reboot

Extra Steps for Raspberry Pi OS Bullseye

When trying to install the UniFi controller on Raspberry Pi OS Bullseye, you will run into issues with the mongodb package not being available.

To work around this issue we can add the old stretch repository as a source and pin it so that none of its packages will take preference.

Ideally, mongodb will be made available from the official repository, but for now, we will have to work around it

1. Let us start by creating a preferences file for the apt package manager. This file will allow us to modify the priority of the repository that we are about to add.

You can start writing this preferences file by using the following command.

sudo nano /etc/apt/preferences.d/99stretch-mongodb.pref

2. Within this file, you will need to type in the following lines.

#Never Prefer packages from Stretch
Package: *
Pin: release n=stretch
Pin-Priority: 1

These lines tell the apt package manager a few different things. First, we use the wildcard for our package name. The wildcard means our following rules will apply to all packages available.

The following two lines are what we use to set a priority for packages from our new repository. By setting the “pin-priority” to 1, we ensure that apt will prefer other packages over ones from the Stretch repository.

3. Once you have made these changes to the file, you can save and quit by pressing CTRL + X, then Y, followed by the ENTER key.

4. Now that we have created our new preferences file, we can now add our repository that contains mongodb.

Before we can add this repository, we will first need to download the GPG key for the Raspbian repository. This key helps authenticate the packages belong to that specific repository.

Download this key to your Raspberry Pi by using the following command in the terminal.

curl -L https://archive.raspbian.org/raspbian.public.key | gpg --dearmor | sudo tee /usr/share/keyrings/raspbian-archive-keyring.gpg >/dev/null

5. With the GPG we can finally add the older Raspbian repository to our sources list.

To add this repository we will be creating a new file called “stretch_mongodb.list” in the “/etc/apt/sources.list.d/” directory.

Using this simple one liner, we can echo the repository string and add it straight into this new file without having to use a text editor like nano.

echo "deb [signed-by=/usr/share/keyrings/raspbian-archive-keyring.gpg] http://archive.raspbian.org/raspbian stretch main" | sudo tee /etc/apt/sources.list.d/stretch_mongodb.list

6. As we have made changes to the package sources, we need to update the package list.

You can update the package list by using the following command on your Raspberry Pi.

sudo apt update

Installing the UniFi Controller to the Raspberry Pi

1. Our first task is to add the UniFi repository to our sources list.

We can achieve this by running the command below.

echo 'deb [signed-by=/usr/share/keyrings/ubiquiti-archive-keyring.gpg] https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

2. We now need to add the repositories GPG key by using the following command.

curl https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg >/dev/null

The GPG key is what helps tell the package manager it is downloading the correct package.

3. As we made changes to the repositories, we need to now update the package list by running the command below.

sudo apt update

4. Now finally, we can install version 8 of the OpenJDK runtime as well as the Unifi Controller software itself to our Raspberry Pi by running the following command.

sudo apt install openjdk-8-jre-headless unifi

Installing UniFi through this method will automatically set up a service. This service will automatically start the UniFi software at boot.

Additionally, we are installing version 8 of the Java runtime environment as it is currently the only version supported by the UniFi controller.

First Boot of the UniFi Controller on your Raspberry Pi

In this section, we are going to walk you through the initial configuration steps of the UniFi software.

1. First, retrieve the local IP address for your Raspberry Pi.

If you have terminal access to your Pi, you can use the following command.

hostname -I

2. With your Raspberry Pi’s IP address handy, go to the following web address in your favorite web browser.

https://[IPADDRESS]:8443

If you run into a certificate error, it is safe to ignore it as we know what device we are connecting to.

3. The first step requires you to give a name for your Raspberry Pi powered UniFi controller (1.).

You are also required to agree to the end-user license agreement and terms of service from UniFi, once you have read through them, click the checkbox (2.).

Once all done, click the “Next” button (3.) to proceed.

Set Name of UniFi Network

4. Next, you will need to sign in to your Ubiquiti account (1.).

If you don’t already have an account, you can register at the Ubiquiti website.

Once you have entered your login details, proceed by clicking the “Next” button.

Sign in to Ubitquiti Account

5. Tweak the settings on this page that best suits your needs.

Once configured, click the “Next” button.

UniFi Network Setup

6. Use this screen to connect your Pi UniFi Network controller to the devices on your network.

To proceed, click the “Next” button.

Connect Raspberry Pi to UniFi Devices

7. Now give your new Wi-Fi network a name and a password.

Once you have configured your WiFi details (1.), click the “Next” button to proceed (2.).

Setup UniFi WiFi Details

8. This final screen will get you to review all your settings.

You will also be able to use this screen to set both the country and timezone (1.). Make sure you set these before continuing.

Once you have verified everything is correct, you can now click the “Finish” button (2.) to finish the setup process.

Review Raspberry Pi UniFi Configuration Settings

7. At this point, you should now have successfully set up the UniFi network controller on your Raspberry Pi.

Raspberry Pi UniFi Dashboard

If you have run into any issues with setting up the UniFi software, feel free to drop a comment below.

78 Comments

  1. Avatar for Chris
    Chris on

    Emmet. Thank you much for the update. I’m currently running into an issue with pihole unbound service failed. Would you mind helping?

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Chris,

      Sorry to hear that you are having issue. Did this happen to occur after installing the UniFi controller? If so, could you please show any errors that are occurring?

      Cheers,
      Emmet Young

  2. Avatar for Chris
    Chris on

    I’d followed the step. However, the current version of the Unifi controller does not support it. Thank you!

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Chris,

      A recent change to Raspberry Pi OS may of broken the original steps. I have updated the guide with additional steps that should work around the latest issue.

      Cheers,
      Emmet

  3. Avatar for piman
    piman on

    Heads up, there appears to be an issue with a recent update of the Pi and operating with the 64 bit kernel. Stopped working for me recently. Solution is below.

    https://community.ui.com/questions/Unifi-on-Raspberry-Pi-stopped-working-after-update/bc6604ce-ad18-4b7e-9622-f7172f424e03?page=0

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Piman,

      Thank you for the heads up about this issue. I have updated the guide to implement the workaround.

      Cheers,
      Emmet

  4. Avatar for Dan
    Dan on

    Many hours saved, thank you.

  5. Avatar for Opcom
    Opcom on

    Great, thank You

  6. Avatar for Marco
    Marco on

    You are the greatest!!!
    Thanks a lot Emmet, worked for me: Updated Pi to the buster Version and the Unifi Controller from Version 6.4.54 to 7.2.95
    And now I try to get the L3 adoption fixed…

  7. Avatar for lovepi
    lovepi on

    Thanks — ran from start to finish on a 3B and working great. 32bit dietpi base install.

  8. Avatar for Tim
    Tim on

    Thanks for the updated tutorial.
    Unfortunately still not there. something to do with 32 vs 64 bit Raspbian OS. I am using 64 bit.
    First error occurs in step 6 under the “Extra Steps for Raspberry Pi OS Bullseye” section:

    $ sudo apt update
    [[SNIPPED]
    N: Skipping acquire of configured file 'main/binary-arm64/Packages' as repository 'http://archive.raspbian.org/raspbian stretch InRelease' doesn't support architecture 'arm64'

    Second error on step 3 of the “Installing the UniFi Controller to the Raspberry Pi” section:

    $ sudo apt update
    . . .
    All packages are up to date.
    N: Skipping acquire of configured file 'main/binary-arm64/Packages' as repository 'http://archive.raspbian.org/raspbian stretch InRelease' doesn't support architecture 'arm64'
    N: Skipping acquire of configured file 'ubiquiti/binary-arm64/Packages' as repository 'https://www.ui.com/downloads/unifi/debian stable InRelease' doesn't support architecture 'arm64'

    So step 4 does not work:

    $ sudo apt install openjdk-8-jre-headless unifi
    . . .
    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.

    So that's as far as I can get for now.

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Tim,

      At this stage this tutorial will only work with a 32-bit release of Raspberry Pi OS.

      Cheers,
      Emmet

  9. Avatar for Tim
    Tim on

    When to apply this excellent looking post to my new RPi 4B and ran into two problems right off the bat.
    #1 openjdk-8-jre-headless is not available in the Buster repo’s any more. I installed openjdk-11-jre-headless just to see how far I could get.
    #2 When I added the stretch repo and did the sudo apt update I get this:

    Get:6 http://archive.raspbian.org/raspbian stretch InRelease [15.0 kB]
    Err:6 http://archive.raspbian.org/raspbian stretch InRelease
      The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 9165938D90FDDD2E
    Reading package lists... Done
    W: GPG error: http://archive.raspbian.org/raspbian stretch InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 9165938D90FDDD2E
    E: The repository 'http://archive.raspbian.org/raspbian stretch InRelease' is not signed.
    N: Updating from such a repository can't be done securely, and is therefore disabled by default.
    N: See apt-secure(8) manpage for repository creation and user configuration details.

    So it looks like there needs to be an update to this post or an update the unifi and PI OS to get unifi working on the Pi.

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Tim,

      Thank you for the heads up about this issue.

      I have re-adjusted the tutorial so that the Raspbian repository will not work correctly and you should now be able to proceed with the install. It looks like in a recent release the GPG key belonging to that repository stopped being shipped with the operating system.

      I have also re-adjusted the install order so that OpenJDK 8 will now be installed from the older stretch repository alongside mongodb. Since OpenJDK 8 is EOL im not hugely surprised it has been removed from the repository, but sadly in this case it is required for UniFi to function.

      Cheers,
      Emmet

  10. Avatar for mike
    mike on

    openjdk-8-jre-headless is no longer available.
    sudo apt install openjdk-8-jre-headless
    E: Unable to locate package openjdk-8-jre-headless

    1. Avatar for Emmet
      Emmet on
      Editor

      Hi Mike,

      Please try re-running through the tutorial. The guide has been updated to work around this issue.

      Cheers,
      Emmet

  11. Avatar for swansinflight
    swansinflight on

    Life saver. Had to update my Pi2 from Buster to Bullseye for PiHole reasons, and this part was my sticking point – much appreciated!!!!

Leave a Reply

Your email address will not be published. Required fields are marked *