Taking Control of Your Wi-Fi

Ubiquiti UniFi APs and Controller Software on Linux

Background

For years, I bought Wi-Fi routers and access points from the likes of Linksys, Netgear, D-Link, and Asus. Warranties would immediately be voided as I loaded alternative, Linux-based firmwares onto these devices. I started with DD-WRT before moving on to Tomato-based firmwares and OpenWrt. Tomato by Shibby is my choice for Broadcom chipset devices. OpenWrt supports a wide variety of hardware and has DIY geek appeal.

Gradually, I came to expand my network of Wi-Fi APs to cover the entire house, immediate yard, outbuildings, etc. If you're in an apartment or crowded suburbia, absolutely get yourself a quality device that supports 5GHz, like the higher end models from Asus. It's really crowded out there on 2.4GHz, so only use that as a fallback. Locate your single 5GHz device somewhere central and (hopefully) enjoy the speed and lack of hiccups.

On the other hand, some of us want to expand our coverage to several acres. No dead spots in certain corners of the house. Decent Wi-Fi coverage while out in the garden or mowing the lawn. Minimum lot size in my town is two acres, and it's not unreasonable to want that (or more) covered. This desire for increased coverage and easy management of multiple APs led me to try the UniFi products by Ubiquiti.

Dumb APs, Smart Control

Ubiquiti addresses the management and cost concerns of multiple APs by dumbing down the AP. The UniFi APs are simple, don't directly support web-based management, and don't really have the resources to run (comparatively heavyweight) Linux firmwares. What these APs do support is Java-based management software in the form of the UniFi Controller. The cross-platform nature of Java allows this software to run on Windows PCs, Macs, Linux boxes, and so on. You can fire up the software once to get things configured, and then not really worry about it. Alternatively, you can run the controller 24/7 to provide monitoring and captive portal functionality.

Now that I have a decently low-power yet powerful box on which to run this, in the form of a coreboot Chromebox, it's time to make the UniFi Controller run as a service on Linux. Ubiquiti somewhat supports this, but it still takes effort and research to make it right. For the benefit of myself and others, I'm going to document everything in one place.

Minimum System Requirements

Resource requirements are not especially light, considering you'll be running Java and MongoDB.

• 2GiB RAM
• 10GB storage
• Single 64-bit x86 processor core

In theory, other architectures should work, but don't expect somebody to have created packages or compiled binaries. Given RAM and CPU requirements, I don't recommend planning to deploy on an embedded ARM platform like the Raspberry Pi or BeagleBone Black. If you do manage to get this running on an alternative platform like ARM or MIPS, please let me know!

Selecting a Linux Distro

Ubiquiti appears to support Ubuntu and Debian best, providing repositories from which to obtain packages. The software itself is also available in a ZIP archive, for those who are pledged to another distro and willing to put in some work. I'll be documenting the procedure for Debian 7 (wheezy) here. Debian a good, solid choice for this. If you're able run this all in a virtual machine, I highly recommend it.

Installing and Configuring the Software

We start with a relatively stock Debian 7 install. I accepted most of the defaults, deselecting the desktop and selecting ssh and standard utilities package sets. Configure networking as you'd like it once the install has completed.

We'll add the apt repositories for Ubiquiti and MongoDB.

apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50
echo "deb http://www.ubnt.com/downloads/unifi/distros/deb/wheezy wheezy ubiquiti" >/etc/apt/sources.list.d/ubiquiti.list
apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10
echo "deb http://downloads-distro.mongodb.org/repo/debian-sysvinit dist 10gen" >/etc/apt/sources.list.d/mongodb.list
aptitude update

Let's disable startup of the default MongoDB instance in advance. It's going to want to pre-allocate multiple GB of journal files, so best to avoid that.

echo "ENABLE_MONGODB=no" >>/etc/default/mongodb

Now we'll install all the packages, watching the UniFi controller fail to start. This is due to the unifi init script setting an outdated JAVA_HOME path. We can fix that in the init script or create a symlink. I'm going to recommend the symlink so we can safely upgrade the unmodified package init script in the future.

aptitude install unifi
ln -sf java-6-openjdk-amd64 /usr/lib/jvm/java-6-openjdk

Just to be safe, we can make sure services are stopped and database journal files are removed.

service unifi stop
service mongodb stop
rm -Rf /var/lib/mongodb/journal
rm -Rf /var/lib/unifi/db/journal

Now we'll edit UniFi controller properties to disable DB journaling, then start the service.

echo "unifi.db.nojournal=true" >>/var/lib/unifi/system.properties
service unifi restart

Now point your browser at http://<ip-address>:8080/ and accept the certificate to access the software interface. I hope you found this useful. Please let me know if you have problems or improvements.