UniFi 5 controller on FreeBSD

Joel Bodenmann
Date : August 24, 2020
Categories : Software
Tags : Free bsd ,Networking

Update: New version of this guide for UniFi6 controller: here.

Configuring, monitoring & maintaining of Ubiquiti’s UniFi products (such as access points, switches, gateways, …) requires the use of their UniFi network controller software. Customers can either purchase one of their cloud keys to use a cloud backed instance of this software or host it themselves.

This post discusses the installation and configuration of a UniFi network controller instance on a FreeBSD machine. I’m using FreeBSD 12.1 but this should be very similar to other FreeBSD versions.

Installation

It’s good practice to take advantage of FreeBSD jailing feature to isolate the UniFi controller from the rest of the system. Setting up a jail is outside of the scope of this post but everything shown will also work outside of a jail as well.

Installation of the UniFi controller is very easy as there’s a port. Unless there’s the desire (or need) to build the package manually it can be installed through pkg:

pkg install unifi5

Depending on the environment installing the LTS version instead might be worth consideration:

pkg install unifi-lts

Everything else is handled automatically by pkg (user creation, …). The only thing left to do is having the UniFi controller start on boot by modifying /etc/rc.conf accordingly if desired so:

unifi_enable="YES"

Firewall

The UniFi controller uses a set of UDP & TCP ports to communicate with the devices and to provide the web interface. The corresponding documentation can be found here.

A minimalistic PF configuration would look like this:

if_lan0="igb0"
if_loc="lo0"

# Jail [unifi]
jail_unifi_addr="192.168.1.20"
jail_unifi_ingress_tcp="{ 5514 8080 8443 6789 27117 }"
jail_unifi_ingress_udp="{ 3478 5656:5699 10001 1900 }"

# Normalize all packages
scrub in all

# Don't filter on localhost
set skip on $if_loc

# Rules
block in log all
pass out all

## Jail [unifi]
pass in on $if_lan0 proto tcp from any to $jail_unifi_addr port $jail_unifi_ingress_tcp
pass in on $if_lan0 proto udp from any to $jail_unifi_addr port $jail_unifi_ingress_udp

Adjustment of the network interfaces & IP is likely to be necessary.

Configuration

Once the package has been installed, the unifi controller can be started:

service unifi start

Further configuration takes place by the means of a well designed interface which should now be reachable through a regular web browser:

https://192.168.1.20:8443