nguvu

Ubiquiti Unifi setup

Last revised 21 November 2017.

NOTE: This guide is now deprecated, please see the preferred Ruckus Unleashed guide here.

Contents

Introduction

A number of people reached out asking how to configure the Unifi software and access points to work with my pfSense guide so here it is. The Unifi controller does not need to be running continuously for basic Unifi access point configuration, you can run it when needed on a Mac, Linux or Windows based desktop although to make use of some of the advanced logging and telemetry functionality it does need to be running constantly and collecting data from associated access points. I’ve run the Unifi software in a Debian virtual machine on ESXi successfully for a couple of years now. The VM doesnt require a lot of resources, mine is configured as follows:

To support full functionality of the Unifi software, make sure that you can access the root account via SSH, the hostname is set and DNS, DHCP and NTP all function.

Connect hardware

Connect the unifi access points to your Vl10_MANAGEMENT network, either directly to a PoE switch or making use of one of the included PoE injectors. Make sure to use good quality Cat5e cable, preferably solid core copper if using PoE to ensure adequate current carrying capacity and robust operation. Watch out for stranded and CCA (Copper Clad Aluminum) which are lesser quality.

Install Unifi Software

Install prerequisites

ssh into your Debian VM and log into the root account to perform the following installation steps.

apt-get update
apt-get install dirmngr sudo

Add Ubiquiti Unifi repository

Pick one of the following repositories:

Further details on versions are available on the Unifi community forums. This guide will use the testing branch which at the time of writing this guide covers v5.6.19, the last verison of the 5.6 branch.

echo "deb http://www.ubnt.com/downloads/unifi/debian testing ubiquiti" | tee /etc/apt/sources.list.d/100-ubnt.list

Fetch GPG key

apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50

# apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50
Executing: /tmp/apt-key-gpghome.FkeAPmqMG9/gpg.1.sh --keyserver keyserver.ubuntu.com --recv C0A52C50
gpg: key 06E85760C0A52C50: public key "UniFi Developers <unifi-dev@ubnt.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

Install Unifi package

apt-get update
apt-get install unifi -y

This will download and install a number of required packages, verify this completes successfully before proceeding.

start Unifi

Enable unifi to start automatically at boot

systemctl enable unifi
systemctl start unifi

and verify the service started correctly by entering systemctl status unifi

● unifi.service - unifi
   Loaded: loaded (/lib/systemd/system/unifi.service; enabled; vendor preset: en
   Active: active (running) since Fri 2017-11-03 12:14:18 PDT; 12s ago
 Main PID: 5035 (jsvc)
   CGroup: /system.slice/unifi.service
           ├─5035 unifi -cwd /usr/lib/unifi -home /usr/lib/jvm/java-8-openjdk-am
           ├─5037 unifi -cwd /usr/lib/unifi -home /usr/lib/jvm/java-8-openjdk-am
           ├─5038 unifi -cwd /usr/lib/unifi -home /usr/lib/jvm/java-8-openjdk-am
           ├─5049 /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java -Xmx1024M -XX:E
           └─5934 bin/mongod --dbpath /usr/lib/unifi/data/db --port 27117 --unix

Nov 03 12:14:17 unifi2 systemd[1]: Starting unifi...
Nov 03 12:14:18 unifi2 unifi.init[4979]: Starting Ubiquiti UniFi Controller: uni
Nov 03 12:14:18 unifi2 systemd[1]: Started unifi.

Disable default Mongodb instance

Unifi will start its own version of MongoDB so we can and should disable the default instance from running at boot

systemctl stop mongodb
systemctl disable mongodb

Configure Unifi Software

Open a browser and head to https://:8443, in my case this is https://unifi2:8443 where you will be presented with the installation wizard.

Unifi setup wizard
Unifi setup wizard

Set your country and timezone as appropriate for your location

Configure devices

Unifi wizard - configure devices
Unifi wizard - configure devices

We will not select any presented devices here as we will configure them in the main application in a moment.

Click Next

Configure WiFi

Unifi wizard - configure wifi
Unifi wizard- configure wifi

We won’t configure the SSIDs here as we will do them in the main application.

Click Skip

Controller Access

We will configure the admin access details on this page.

Unifi wizard - controller access
Unifi wizard - controller access

Device authentication

Click Next

Confirm settings

Unifi wizard - confirm settings
Unifi wizard - confirm settings

Check your settings are as intended and click Finish

Cloud login credentials

Unifi wizard
Unifi wizard

I dont use a cloud controller and prefer to self-host where possible, click Skip

First Login

Unifi login
Unifi login

Enter your username and password as set during the installation wizard setup and click Sign In. You’ll be presented with a dashboard which won’t be populated with any data because we haven’t adopted any access points yet. Before we get to adopt your access points, lets configure the software first. To enter the settings section, click on the cogs icon towards the bottom left corner of the window.

Site

Site Configuration

Services

Device authentication

Click Apply Changes

Configure wireless networks

We will configure the SSIDs and associate them with the correct VLAN using the following table as a refresher for our settings. Feel free to edit the SSID values to something more suitable for your setup.

LAN SSID VLAN ID IP subnet range
VL10_MGMT WIFI-MGMT NONE 192.168.10.0/24
VL20_VPNLAN WIFI-VPN 20 192.168.20.0/24
VL30_CLRNET WIFI-CLRNET 30 192.168.30.0/24
VL40_GUEST WIFI-GUEST 40 192.168.40.0/24

Management network configuration

I was undecided if I should include this, exposing your management network on wifi is an unnecessary risk, however I have personally made use of it before and it may be useful for those configuring the system for the first time due to ease of access. It would be remiss of me to not say that management networks and ease-of-access terms don't belong in the same sentence so please consider the implications of exposing your management network on your wifi network.

Click +New Wireless Network

Open Advanced options and set

802.11 rate and beacon controls = default
Mac filter = default
Radius mac authentication = default

Click Save

VPN network configuration

Click +New Wireless Network

Open Advanced options and set

802.11 rate and beacon controls = default
Mac filter = default
Radius mac authentication = default

Click Save

VPNLAN configuration
VPNLAN configuration

Clearnet configuration

Click +New Wireless Network

Open Advanced options and set

802.11 rate and beacon controls = default
Mac filter = default
Radius mac authentication = default

Click Save

Guest configuration

My guest network is firewalled on the pfSense router and I don’t limit bandwidth for users of the guest network either as I make use of the guest network as a failover network from time to time. Due to these reasons I don’t apply guest policy in the configuration below. Its possible to limit bandwidth and provide access via a portal, I may add these as an addendum to this guide later if theres demand.

Click +New Wireless Network

Open Advanced options and set

802.11 rate and beacon controls = default
Mac filter = default
Radius mac authentication = default

Click Save

After clicking Save, your wireless networks page should look like this

Final network configuration
Final network configuration

Configure Services

Configure NTP

In order for access point firmware updates to take place easily from within the web client, we need to an accurate time set. Navigate to Services > NTP and configure the NTP servers. All my devices sync with my pfSense router hence the 192.168.10.1 address.

NTP configuration
NTP configuration

Controller

Controller settings

Make sure the controller name is set correctly as per your hostname record, in my case of Unifi2

Apply changes

Adopt Access Points

Adopt access point
Adopt access point

Now we’ve configured all the settings needed to create and configure our SSIDs, we can adopt our access points. Navigate to DEVICES where you should see your access points pending adoption. Adoption is initiated by clicking ADOPT next to the respective access point. After displaying PROVISIONING for a little while, the status should change to CONNECTED.

Adopted access point
Adopted access point

Once the access point has been adopted you should be able to join any of the provisioned SSIDs. Validate that you can connect, receive an appropriate DHCP address and that you can access internal devices and internet sites.

Configure Access Points

Click on the access point name and a panel will slide out on the right of the browser window where we can configure access point related settings.

Access point alias

Navigate to General > Alias and set a more meaningful name e.g. Kitchen
Click Save

Band steering

Navigate to General > Band Steering and set Prefer 5G = ON.
This will coerce device promotion from crowded 2.4GHz frequencies into the 5Ghz range.

Airtime fairness

Navigate to General > Airtime fairness and set it to ON.
This will encourage fairer airtime sharing.

Apply the above changes.

Upgrading

Unifi Software

New software is made available through Unifi and the beta program frequently and its worth keeping up to date. Before updating your system, please make sure to make a backup in case you need to roll back to a previous version. To update your installation SSH into Unifi system and enter wget <filename> -O <destination_filename>, e.g for version 5.7.3 you would enter

wget https://dl.ubnt.com/unifi/5.7.3-91ad2e6240/unifi_sysvinit_all.deb -O ~/unifi/downloads/5.7.3-installer.deb

and to install the .deb package,

sudo dpkg -i ~/unifi/downloads/5.7.3-installer.deb

Once applied its usually worth rebooting. It can take a few minutes for a new install to be accessible due to database conversions so don’t panic if it isn’t accessible immediately.

Access Point firmware

To upgrade an access point with new firmware, click on the access point to be upgraded and navigate to Config > Manage Device > Custom Upgrade. Here is where you enter the link to the firmware and then click Upgrade. In case of issues, its worth noting HTTPS transfers require accurate time to be set. If you are having trouble verify your NTP settings are correct.

Tuning Setup

Its impossible to produce a guide for tuning access point radios that would work in anything but a small selection of setups, not only are homes and offices wildy different in terms of area and construction, but radio frequency utilisation and pollution will be different too. I want to share a few concepts and ideas that have worked well for me and are likely to work well for a fair percentage of readers.

Access point positioning

Generally keeping the access points with a clear line of sight to the locations where clients are likely to be used, typically this means ceiling mounting. Using a site survey tool like Netspot equips you with actual reading of your access points signal strength across your space. This info can really help establishing the optimal number and placement of access points.

Netspot
Netspot

Avoid congested frequency bands

Higher channel widths can support a higher data rates, however the downside is that there are fewer non-overlapping channels available which can lead to congestion problems.

Make use of the inbuilt Unifi RF environment scan which can be accessed under each access points tool menu. Pick non overlapping channels for each access point.

Unifi frequency scan
Unifi frequency scan

Adrian Grando’s Wifi Explorer is excellent for wifi network inspection. The recently released pro version also enables the use of Metageek’s Wi-spy DBx for frequency analysis.

Wifi explorer
Wifi explorer

For 2.4Ghz there are only three non-overlapping channel, 1, 6 & 11, stick to 20Mhz channel widths as increasing to 40Mhz reduces the number of non-overlapping channels and makes using multiple access points difficult. You can see in the above image my 3 access points use 2.4Ghz channels 1, 6 & 11 and 5.4Ghz 36, 52 & 100 to prevent congestion.
For 5Ghz there are many more non-overlapping channels and its possible to configure 40Mhz or even 80Mhz channel widths in certain environments without congestion.
If using the DFS frequency ranges, ensure you aren’t being impacted by nearby RADAR installations or other sources of interference that could cause your access point to reallocate to another channels causing congestion. The Unifi software will alter you in the logging section if this is happening.

Tuning for optimal 5Ghz network usage is more challenging than 2.4Ghz, see this FCC document for a more thorough detailed breakdown of the range.

Radio power

Radio communications depend on clear signals both ways between access point and client. Turning up the transmit power on the access point doesn’t magically solve range problems because although the clients can hear the access point more clearly, they don’t usually have the radio power to be able to transmit back as loudly. You are likely better off turning down the broadcast power and enabling devices to migrate to other more optimal access points where a more balanced communication stream can occur.

Click on each access point in turn and under config, set the transmit powers as follows:

Verify your devices, especilally mobile devices, can still access wifi across your area and verify they transfer to hotspots with better SNR sensibly.

Disable unused 802.11 rates

Depending on the devices in use on your network, you may see some benefits in disabling some of the rates associated with older wifi devices. To disable these frequencies navigate to Settings > Wireless Networks. Edit settings and change the 802.11 rate options as follows:

2G Data rate control

5G Data rate control

Save and verify your devices still function correctly.

Disable CCK rates
Disable CCK rates

Block LAN to WLAN Multicast and Broadcast Data

Multicast/Broadcast data is sent at the lowest modulation rate and can negatively affect performance. Unless you absolutely need this feature, it is recommended to block this traffic. If after blocking this traffic you notice difficulty connecting to certain wifi devices, for example printers which may rely on this system for detection, consider adding specfic MAC addresses to the excepted devices before reverting to disabling the block completely. I’ve added an exception for my printer (HP8600), a portable audio speaker (A7) and the subnet gateway (unknown hostname) to support reliable discovery in the image below. See this Ubiquiti document for further information.

Block LAN to WLAN Multicast and Broadcast Data
Block LAN to WLAN Multicast and Broadcast Data

Changelog

21 November 2017
Refined Block LAN to WLAN section

18 November 2017
Added Block LAN to WLAN Multicast and Broadcast Data section