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:
- Go the Raspberry Pi Downloads page at http://www.raspberrypi.org/downloads/
- 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:
- Insert the SD card in to your card reader
- Run the SDFormatter utility
- Make sure your memory card is select in the drive dropdown menu
- 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
Run Etcher
- Click Select Image and browse to the ISO file you unzipped
- Click Select Drive (if there is no option, it may have selected your drive for you, ensure its the correct one
- If all is well, click Flash to begin the process
- 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:
- Get the SD card and insert it in to the Raspberry Pi
- Plugin the screen, keyboard and then power (in that order)
- 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).
- You’ll know when the Raspberry Pi will finish booting because you’ll see a prompt saying:
raspberrypi login: - Enter a username of pi <press enter>
- 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:
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.
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 `>` with the ‘greater than’ symbol: `>`. Just wanted to leave a heads-up for anyone else that may be having this problem.
Hey David,
Thanks for the heads up! It looks like wordpress converted the > symbol to its HTML special character! Updated now
I think the same happened in step 9 with the & character, which now reads & instead.
That should read &_amp;_ . The forum software changes that to read & again.
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
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!
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
I’m glad they didn’t enable it by default. Having a open ssh server with the default password is a huge security risk
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
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)
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
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
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
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
Hi Alex,
What are you doing to get past the SSL warning and what browser are you using? I’d recommend chrome.
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!
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.
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
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
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).
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’.