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:

• 1 x Raspberry PI 3
• 1 x Micro SD Card (16GB or more recommended)
• 1 x Micro SD Card adapter
• 1 x Micro USB Cable
• 1 x HDMI Cable
• 1 x Case (Optional but recommended)
• A power source for your PI such as a high power charger or USB port socket
• A computer with with an SD card reader and internet connection
• A wifi network or network cable
• A USB keyboard & mouse

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.