Ubiquiti Unifi on Ubuntu or Debian

Ubiquiti Unifi controller server runs even on a Raspberry Pi Zero. However, Raspberry Pi Zero or Raspberry Pi 1 requires additional configuration, since the CPU is only ARMv6. ARMv7 and newer CPU from Raspberry Pi 2 and newer work out of the box.

This example assumes the Unifi server is at 192.168.1.2, and that the WiFi APs are on 192.168.10.*.

Unifi 5.6 is the last Unifi version to support Unifi AP-AC v2 hardware. Since November 6, 2018, AP-ACv2 do not officially receive security updates. Decommission AP-ACv2 hardware as soon as practicable.

Prereqs

Backup existing Unifi configuration by navigating to either:

  • Avahi: https://unifi.local:8443
  • https://192.168.1.2:8443

and clicking Settings → Maintenance → Backup and save to your laptop.

Install Java 8 and other prereqs

apt install oracle-java8-jdk dirmngr

Be sure Java defaults to version 8

java -version

If not, see switching Java version

Java 9 is not yet supported at least through Ubiquiti 5.9. Java 8 is recommended for Unifi 5.6, and required for Unifi 5.7.

Install

Add to /etc/apt/sources.list.d/ubnt.list

deb http://www.ubnt.com/downloads/unifi/debian stable ubiquiti

If you have deprecated hardware requiring Unifi 5.6, use the LTS channel instead

deb http://www.ubnt.com/downloads/unifi/debian unifi-5.6 ubiquiti

Execute

apt-key adv --keyserver keyserver.ubuntu.com --recv 06E85760C0A52C50
apt update
apt install unifi

after about 10 seconds browse https://192.168.1.2:8443. If you have a very slow CPU (slower than Raspberry Pi 2) you may need to wait a little longer.

Assuming the Unifi server is using UFW firewall:

ufw enable

ufw allow proto tcp from 192.168.1.0/24 to any port 8443
ufw allow proto tcp from 192.168.10.0/24 to any port 8080
ufw allow proto udp from 192.168.10.0/24 to any port 3478
Portusage
8080Ubiquiti WiFi APs → Unifi server
8443HTTPS admin control panel
3478STUN AP control

Unifi updates often include AP firmware updates. Upon AP update, Wifi may go down for a few minutes while the APs say “provisioning”.

Be sure the firewall allows UDP on port 3478 to the Unifi server, or you’ll get error:

STUN Communication Failed This device is not able to connect to the internal STUN server. Please check if the device is able to reach the STUN server on port 3478

Upgrade

On upgrading from older Unifi versions to Unifi 5.10, you may get errors like:

cat /usr/lib/unifi/logs/server.log

ERROR system - [exec] error, rc=141, cmdline=[/usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre/bin/java, -Dfile.encoding=UTF-8, -Djava.awt.headless=true, -Dapple.awt.UIElement=true, -Xmx1024M, -XX:+ExitOnOutOfMemoryError, -XX:+CrashOnOutOfMemoryError, -XX:ErrorFile=/usr/lib/unifi/logs/hs_err_pid%p.log, -jar, /usr/lib/unifi/lib/ace.jar, start]

I fixed this by:

apt remove oracle-java8-jdk

apt install openjdk-8-jre-headless

Features

Neighboring Access Points

“Neighboring access points” shows you any other AP (including hidden SSID listed by BSSID). It’s fascinating to see how much better (more sensitive, longer range) the AP is than typical mobile devices. You may see distant SSIDs that you’ve never seen from a mobile or laptop in the same office.

Changelog

  • 5.6.22 Fix for KRACK vulnerability via firmware update. Check in the Unifi management screen that your APs have updated to the appropriate firmware version listed.
  • 5.6.18 5.6 brings RADIUS server to Unifi, and many more options to the GUI instead of config files. Lots of bugfixes in general over 5.5.
  • 5.5.24 enabled 802.11r finally. Full changelog included.
  • Unifi 5.3 added features:

    • allow individual permanent on/off of AP LED
    • complete mobile-friendly UI refresh
    • added DFS (enabled with 2016 or newer hardware)
    • better RF scanning
    • ability to log for up to one year

Notes