Running Ubiquiti UniFi Controller on a Raspberry Pi

Running Ubiquiti UniFi Controller on a Raspberry Pi

UPDATE: 25th Sept 2017

As per my previous article, I’ve now deployed a Ubiquiti UniFi network at home and its working wonderfully, the speeds are good and already wireless roaming work pretty well.

I decided however that ‘pretty well’ just isn’t good enough and that I also want to be able to gather statistics on the network so I can see whats happening.

This requires an always running controller but I don’t want to leave my laptop switch on all the time, not do I want to buy a server just to run Linux to run the Ubiquiti UniFi controller software.

Enter the Pi

And so it is I turned to a Raspberry Pi 3 to be my budget Linux server.

Its cheap enough to be used for something as simple as this project but powerful enough to handle the load, below is an idiots guide to installing the Ubiquiti UniFi Controller on a Raspberry Pi, from setting up the Raspberry Pi right through to running the controller.

Installing and Running the Ubiquiti UniFi Controller on a Raspberry PI

Pre-Requisites

You are going to need the following items for this project:

Step 1: Start the Raspbian Download

Downloading the Rasbian linux distribution can take a while so lets set that going in the background:

  1. Go the Raspberry Pi Downloads page at http://www.raspberrypi.org/downloads/
  2. Select the download you want (either with or without PIXEL, it doesn’t matter for this project)

Step 2: Install Software Utilities

You may have some or all of these free utilities already but I’ve listed them for completeness:

2.1 SDFormatter Utility

Download the free SD card formatter from here and install it (it’s safe and is even recommended by the Raspberry Pi Foundation).

Why use an SD Card Formatter instead of the standard Windows format tool?

We’ll I’ll be honest I’m not sure by the SD Association website explains:  It is strongly recommended to use the SD Card Formatter instead of formatting utilities provided with operating systems that format various types of storage media. Using generic formatting utilities may result in less than optimal performance for your memory cards.
The SD/SDHC/SDXC memory cards have a “Protected Area” on the card for the SD standard’s

2.2 An Unzip Utility

I recommend 7Zip, its the best free zipping utility I’ve found out there and has great integration with Windows, definitely worth keeping after this project!

You can download it from: http://www.7-zip.org/

Once installed, right click on the file to extract it to your computer.

2.3 Etcher Utility

Ethcher is a simple utility for deploying an ISO image to an SD card or other media, there are lots out there but this is super simple.

It can be downloaded from: http://etcher.io/

Once downloaded, install it – you can probably uninstall this once you’re done as it has limited usefulness outside of formatting SD cards.

Step 3: Formatting the SD card

Now pop the Micro SD card in to the SD Card adapter (if you haven’t already) and do the following:

  1. Insert the SD card in to your card reader
  2. Run the SDFormatter utility
  3. Make sure your memory card is select in the drive dropdown menu
  4. Leave the default options in place and click Format

Step 4: Unzip the Raspian file

Once your Rasbian file has finished downloading, you need to unzip it – with 7Zip installed this is as easy as right clicking the downloaded file and selecting Extract here.

Note where the resulting ISO file is, it should be named something like 2017-01-11-raspbian-jessie.img

Step 5: Deploy the Image to the SD Card

  1. Run Etcher
  2. Click Select Image and browse to the ISO file you unzipped
  3. Click Select Drive (if there is no option, it may have selected your drive for you, ensure its the correct one
  4. If all is well, click Flash to begin the process
  5. The process will take a few minutes depending on the speed of your PC and SD card

Step 6: Make Pi

Now its time to make Pi:

  1. Get the SD card and insert it in to the Raspberry Pi
  2. Plugin the screen, keyboard and then power (in that order)
  3. After a couple of moments, you should see a black screen with lots of white text scrolling up (this is what Linux looks like booting up).
  4. You’ll know when the Raspberry Pi will finish booting because you’ll see a prompt saying:
    raspberrypi login:
  5. Enter a username of pi   <press enter>
  6. Enter a password of raspberry   <press enter>

Step 7: Connecting a Raspberry Pi to Wifi

Now we need to connect your Raspberry Pi to your wireless network (you can skip this step if you are using a network card):

At the comment prompt type:

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

This launches the nano text editor, scroll down and add the following snippet to the bottom, replacing yourSSID and yourWifiPassword with the appropriate values:

network={
 ssid="yourSSID"
 psk="yourWifiPassword"
}

Save the file by pressing Ctrl+X and press Y when asked if you want to proceed, then enter to confirm.

Restart your Raspberry Pi by typing

sudo shutdown –h

Your Raspberry Pi should now be connected to your wifi, you can test this by pinging a website (assuming its connected to the internet) or pinging your router.  To ping a web server, type

ping google.com

You should see a response like this:

64 bytes from lhr25s12-in-f14.1e100.net (216.58.204.46): icmp_seq=123 ttl=54 time=16.8 ms

Step 8: Enable SSH the Raspberry Pi

Now we’re not going to want to leave a keyboard and screen plugged in to our Raspberry Pi so lets enable SSH so we can remotely administrate it:

At the command prompt type:

sudo raspi-config

On the configuration screen that appears, select Advanced Options

Scroll down to SSH   <press enter>

When prompted as to whether or not you would like SSH enabled, obviously click Yes.

Step 9: Update your Raspberry Pi

If you haven’t already, update your Raspberry Pi firmware by running the following command:

sudo apt-get install rpi-update && echo Y | sudo rpi-update

The Raspberry Pi will then begin updating its firmware, this may take a little while so be patient and do not restart or unplug the Raspberry Pi!

At the command prompt type:

sudo apt-get update && sudo apt-get upgrade -y

The Raspberry Pi will then begin updating its operating system, this may take a little while so be patient and do not restart or unplug the Raspberry Pi!

Step 10: Install the Ubiquiti UniFi Controller Software

Out of the box the Raspberry Pi isn’t setup to simply install the Ubiquiti UniFi Controller from the Raspbian repository and so we have to manually add the location of the install package to the sources list on our Raspberry Pi:

echo 'deb http://www.ubnt.com/downloads/unifi/debian unifi5 ubiquiti' | sudo tee -a /etc/apt/sources.list.d/ubnt.list > /dev/null

Install the dirmngr service to facilitate the key install in the next step:

sudo apt install dirmngr

Next we add the key to our Raspberry Pi that is used to authenticate that the software we are downloading is the legitimate Ubiquiti software:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50

Ok great, we’ve added the Ubiquiti software to our known list and provided our Raspberry Pi with the means to check its authenticity, now lets trigger a download of it:

sudo apt-get update

Now we need to tell the Raspberry Pi to install the Ubiquiti Unfi Controller Software:

sudo apt-get install unifi -y

Restart the Raspberry Pi to complete the installation

sudo reboot

Step 11: Give your Raspberry Pi a Static IP Address

Now that we’ve got everything installed, we need to have a static IP address set up on the Pi so it doesn’t change (changes to the Ubiquiti Controller IP address can cause Access Points to become orphaned), to do this enter the following:

sudo nano /etc/dhcpcd.conf

Once the nano editor appears, scroll to the bottom of the page using your keyboard arrow keys and paste a configuration based on the following options:

static ip_address – this the IP address you want your Raspberry Pi to use
static routers – this is the IP address of your router (probably your modem/firewall for home installs)
static domain_name_servers – this is your DNS server, you can most likely use your routers IP address

For a network cable (ethernet) connection, enter the following:

interface eth0
 static ip_address=192.168.1.250/24
 static routers=192.168.1.254
 static domain_name_servers=192.168.1.254

For a wireless (wifi) connection, enter the following:

interface wlan0
 static ip_address=192.168.1.251/24
 static routers=192.168.1.254
 static domain_name_servers=192.168.1.254

Remember that you cannot use the same IP address twice so you should ideally use an IP address outside of the ‘DHCP’ scope of your router or network server, if you really don’t know how to do this, set it as the highest unused IP address until you can find out how!

Important: Do not use the wifi network you are controlling as the primary connection for the Ubiquiti UniFi Controller software for obvious reasons!

Now simply reboot the unit to have it take on the new IP address:

sudo reboot

Step 12: Launch the Ubiquiti UniFi Controller!

After all that hardware, you can now reap the rewards:

Open up a web browser

Type in the IP address you gave the Raspberry Pi, preceded by https:// and followed by :8443

For example mine is: https://192.168.1.251:8443/

You may see a browser warning about privacy, you can safely ignore this as its simply because the SSL certificate used by the controller isn’t verified by anyone.

Bob McKay

About Bob McKay

Bob is a Founder of Seguro Ltd, a full time father and husband, part-time tinkerer-with-wires, coder, Muay Thai practitioner, builder and cook. Big fan of equality, tolerance and co-existence.

Disclosure Policy

22 comments on «Running Ubiquiti UniFi Controller on a Raspberry Pi»

  1. David says:

    Thanks for the tutorial!

    Unfortunately, when I run the first command of Step 10 I get the following error:

    “`
    [1] 876
    -bash: gt: command not found
    -bash: /dev/null: Permission denied
    “`

    After a little digging, I realized the correction is to replace `&gt` with the ‘greater than’ symbol: `>`. Just wanted to leave a heads-up for anyone else that may be having this problem.

    1. Bob McKay says:

      Hey David,

      Thanks for the heads up! It looks like wordpress converted the > symbol to its HTML special character! Updated now

      1. Andre Somers says:

        I think the same happened in step 9 with the & character, which now reads & instead.

        1. Andre Somers says:

          That should read &_amp;_ . The forum software changes that to read & again.

          1. Bob McKay says:

            Hey Andre,
            Thanks for the comment and for taking the time to point this out, much appreciated! So frustrating – every time I save this page, I have to remember to change all of these before the ‘last save’! Hope you’re having fun with the Raspberry Pi!
            All the best

  2. Bryan Casteel says:

    Hello Bob,

    Your tutorial was wonderfully helpful! I now have my Unifi Controller (v.5.5.20.0) running on a Raspberry Pi (Raspian Stretch Kernel Version 4.9) and no longer on my laptop! I thought I would let you know of a couple changes I noticed with the new version of Raspbian code-named Stretch:
    1. In Step 8 above – turning on SSH is no longer that easy. I had to add a blank file called ssh.txt to my root directory which automatically turned on SSH. I now have the option to turn it on and off in the Advanced settings under the “Interfaces” sub-menu.
    2. In Step 10 above – dirmngr is now an optional component in Stretch and has to be first installed (sudo apt install dirmngr). Also, Ubiquiti has updated the GPG Keys for the source code as well as the repository branch request name as detailed here: https://help.ubnt.com/hc/en-us/articles/220066768-UniFi-How-to-Install-Update-via-APT-on-Debian-or-Ubuntu.
    3. Finally, for anyone migrating from a Unifi controller on a controller over to one on a Raspberry Pi that doesn’t want to mess up all of their configurations that they have already set up – I found this video by Ubiquity to be very helpful: https://www.youtube.com/watch?v=aLusMBh9EP8.

    Thanks again for your help and the time you spend putting this information out there for all of us!

    1. Bob McKay says:

      Hi Bryan,

      That’s incredible timing! When you wrote your comment I was right in the middle of re-installing my Raspberry PI UniFi Controller because updating the UniFi software killed it (no response on the web interface). Unfortunately, after spending all evening reinstalling it, I got the same problem at the end! Interesting about the SSH – I didn’t have to put a blank file anywhere, I just had to go to ‘Interfaces’ and the option was there (I wish they’d enable it by default!). I got caught by the dirmngr gotcha too (already updated the blog entry)!
      Great tip on the configuration information and the signing keys, many thanks!
      I’m planning on trying the Snappy Ubuntu Core tonight to see how that goes (I’m hoping for improved performance) and if it works, will update the tutorial to use this.
      Thanks again for the info!
      All the best
      Bob

      1. Stephen says:

        I’m glad they didn’t enable it by default. Having a open ssh server with the default password is a huge security risk

  3. Dave says:

    Hi Bob,

    Thank you for this article. Great stuff.
    Small remark for step 12. It’s not HTTP but it’s HTTPS. At least in my case.

    With regards,
    Dave

  4. Oxcize says:

    When enter the static ip adresses, and i reboot the stuff. It keeps getting an ip from DHCP. it doesnt get static.

    I used 10.0.0.240 for Eth0 and 10.0.0.220 for Wlan. 10.0.0.138 is the gateway.

    But it keeps getting an ip from dhcp (10.0.0.164)

  5. Sascha says:

    Hello,
    this tutorial works perfect.
    Now just one question: when there is a new version of the controller software, how is it possible to update ?
    thanks for all

  6. Gerard Zwart says:

    Hi all,

    Install on Pi went perfectly.
    But now from my browser entering https://IP-address:8443/ and then get: ERR_CONNECTION_REFUSED
    Anyone any idea what could go wrong.

    I am able to ping the IP-address, so pretty sure that is ok.

    PLease help, thanks a lot
    Gerard

    1. Bob McKay says:

      Hi Gerard,

      No idea I’m afraid, what happens if you telnet in to it on that port? Is there a firewall between you and the device?

      Bob

  7. Alex says:

    Hello Bob,

    I followed everything, but because of a small sdcard, I installed the light version. Nevertheless, the whole procedure works.
    But: the last step is not working. I get the ssl warning after entering the address, but then nothing happens. I don’t get the logon page of the controller dashboard.
    Some specs:
    Raspberry Pi 3 Model B Rev 1.2
    Linux raspberrypi 4.14.22-v7+ #1096
    Debian 9.3

    What can I check?

    Thanks,
    Alex

    1. Bob McKay says:

      Hi Alex,
      What are you doing to get past the SSL warning and what browser are you using? I’d recommend chrome.

      1. Alex says:

        Hello Bob,
        The problem was, I think, Java. Installing Java was not possible. Too less space.
        I bought a 16GB card and now it’s working.
        Even very easy migrated from the current controller to the raspberry controller.
        Just use a dns name and change the IP or CNAME.
        I used ‘Override inform host with controller hostname/IP’

        Thanks!

  8. Michel says:

    Very good tutorial Bob; congratulations !

    I have carefully followed all the steps, but when I try to connect with https://192.168.xxx.xxx:8443, I’m getting the same error as Gerard : ERR_CONNECTION_REFUSED.

    I’m new with Debian and Raspberry Pi; this error might be due to a basic parameter not set properly, but I have no idea where to look for.

    Any help would be appreciated.

    1. Bob McKay says:

      Hi Michel,

      Do you have an option to force Chrome to continue? If you telnet on to port 443, what response do you get?

      I would also try updating the Raspian too via sudo apt-get update && sudo apt-get upgrade –y

  9. Kees says:

    Hi,
    Nice report on the Ubiquity Unifi controller software on the RPI. I\’m thinking on placing it on my RPI3 which I use as server for several app\’s. Could you tell me what the processor load is and the storage usage?
    Regards Kees

    1. Bob McKay says:

      Thanks! I honestly don’t know because I upgraded to the Cloud Key a year or so ago but – given that you don’t need a controller unless your making changes or running logs, I suspect its very low if you turn off or minimize the logging requirements (traffic doesn’t actually run through it after all). I suspect that the most CPU intensive bit are the rendering of the web pages when you are using them (which will be rare).

  10. Will says:

    Hi Bob,
    Thanks for taking the time to post this instructions. Very helpful.

    One additional package I had to install to get it working on my Pi3 B+ was ‘openjdk-8-jre’.

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.