Deploying the UniFi Controller on Ubuntu

Deploying the UniFi Controller on Ubuntu

Note: The companion webinar for this blog article can be found here.

Step 1: Install Ubuntu

You will need to install Ubuntu. This guide will not cover the installation process for Ubuntu, as:
a) server management is outside the scope of this article,
b) there is plenty of content available online to help you with this (such as Ubuntu’s Server Install Tutorial),
c) most cloud hosting providers will automate the OS installation process for you.

When setting up your new hardware or VM, please bear in mind the minimum recommended requirements for the UniFi Controller.

Minimum recommended requirements

  • Ubuntu 16.04 LTS
  • 1 CPU (x86-64)
  • 2GB RAM
  • 20GB storage
[icon name=”info-circle” class=”” unprefixed_class=””] Please note: these are the minimum recommended requirements. Your server may require more resources depending on the number of devices being managed, the number of clients, your data retention settings and any backup settings you configure in your controller.

For the rest of this guide it is assumed you have already setup your server and linux OS with both sudo and wget installed (both are included in a standard Ubuntu install).

Part 2: Mongo DB

The UniFi Controller requires MongoDB version 2.6 or later, but is not compatible with versions 3.6 and later. If you are using Ubuntu 16.04 LTS it is possible to skip this step as MongoDB v2.6.10 is included in the standard repositories, however it is recommend to update to version 3.4 to take advantage of stability and performance improvements added to MongoDB.

[icon name=”info-circle” class=”” unprefixed_class=””] These commands are specific to Ubuntu 16.04. Tested and also working with Ubuntu 18.04.
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.4.list
sudo apt update
sudo apt-get install mongodb-org -y

To check what version of MongoDB is currently installed, run mongod --version.

Part 3: Java

The current version of the UniFi Controller (5.9.29) requires Java 8 and is not compatible with Java 9. If you don’t explicitly install Java 8, Ubuntu will automatically install Java 9 to fulfil the UniFi controller package’s dependencies resulting in the UniFi Controller failing to load.

It is recommend to install the open-source Java 8 (openjdk-8-jre-headless) package.

You can do this on Ubuntu/Debian by running the following command:

sudo apt install openjdk-8-jre-headless -y

To confirm which version of Java is currently installed/active, run java -version.

Part 4: UniFi Controller

Now it is time to install the UniFi Controller. The current stable release is 5.9.x at the time of writing. There are 2 ways you can to install the controller:

Method 1: Add the repository & use package manager

This method we will add Ubiquiti’s UniFi repository to the APT package manager. This means the controller can be installed by running sudo apt install unifi and the will be updated whenever the Ubuntu installation is updated by running sudo apt update && sudo apt upgrade. If you do NOT want the controller to update with the OS, or you wish to install a beta version of the controller, please install using Method 2 below.

To install the UniFi Controller using the repository, you will need to:

  • add the key for the repository
  • add the repository to the /etc/apt/sources.list.d/ directory in the file 100-ubnt-unifi.list
  • update package repositories
  • install the unifi package

You can do this on Ubuntu/Debian by running the following commands:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 06E85760C0A52C50
echo 'deb http://www.ubnt.com/downloads/unifi/debian unifi-5.9 ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list
sudo apt update
sudo apt install unifi -y

If you have completed this you can proceed to Part 5.

Method 2: Manually download & install package

For this method we will simply grab the UniFi controller package and install it manually. This means this process will need to be repeated in order to upgrade to a new version as the controller will not be automatically updated when we update the system. You will need to use this method if you wish to install a beta version of the controller.

To install the UniFi Controller manually, you will need to:

  • download the UniFi controller package to the current directory
  • install the unifi package

You can do this on Ubuntu/Debian by running the following commands:

[icon name=”info-circle” class=”” unprefixed_class=””] The commands below are based on v5.9.29 which was current at the time of writing. If a newer version has been released or you wish to install a beta version, the URL for the package in line 1 can be updated to use a newer version if available.
wget https://dl.ubnt.com/unifi/5.9.29/unifi_sysvinit_all.deb
sudo dpkg -i unifi_sysvinit_all.deb

Part 5: Setup the UniFi Controller

The UniFi Controller should now be installed and the service should be started. You can confirm the status of the controller by using the sudo systemctl status unifi command.

Navigate to https://ip.of.your.server:8443/manage in your browser (Google Chrome or Firefox) to start configuring your controller.

While configuring your controller, there are a few things you may wish to consider, such as:

DNS records

You can create an A record to point unifi.yourdomain.com.au at the IP address for your controller to allow use of FQDN instead of the IP for adoption and management.

SSL certificate

By default the controller will use a self-signed certificate, resulting in security warnings in the browser when accessing the management console. This can be fixed by installing a certificate issued by a certificate authority (such as implementing letsencrypt using a cron script).

SMTP settings in UniFi Controller

If you wish to take advantage of e-mail notifications don’t forget to set and test SMTP details in the UniFi Controller settings.

Part 6: Secure your server and data

It is important you lock down access to your server from the internet and make sure you backup your data. While server management is outside the scope of this article, some essential steps and recommendations are summarised below.

Firewall rules

The following is a list of the only ports that are required for Layer 3 management of devices (assuming all ports are left as default).

Port Protocol Description
3478 UDP Port used for STUN.
8080 TCP Port used for device and controller communication.
8443 TCP Port used for controller GUI/API as seen in a web browser
8880 TCP Port used for HTTP portal redirection.
8843 TCP Port used for HTTPS portal redirection.
6789 TCP Port used for UniFi mobile speed test.

Management Access

Management access to your server should be locked down. Most cloud hosting providers will allow you to gain terminal access to your server via their web management console. If you wish to open SSH to the internet to manage your server, it is imperative that you setup certificate authentication and disable passwords, implement firewall ACL where possible and setup fail2banor similar to prevent brute-force attacks.

Backups

Many cloud hosting providers will offer backup options for purchase. You can also setup automatic backups in the UniFi Controller and use rsyncor similar to sync the autobackup directory to another location.

Updates

It is recommended you access your server regularly to install updates and check backups etc. It may be worthwhile setting up unattended-upgradesto automatically install important security and OS updates as they are released.

Useful Commands

Here are some useful commands you may need when troubleshooting issues.

UniFi Controller

To check the status of the UniFi Controller service: sudo systemctl status unifi.

To start the UniFi Controller service: sudo systemctl start unifi.

To stop the UniFi Controller service: sudo systemctl stop unifi.

To restart the UniFi Controller service: sudo systemctl restart unifi.

To view the entire UniFi log: sudo cat /usr/lib/unifi/logs/server.log.

To show and follow the newest line of the UniFi log: sudo tail -f /usr/lib/unifi/logs/server.log.

MongoDB

To check the current version of MongoDB: mongod --version.

To check the status of the MongoDB service: sudo systemctl status mongod.

To view the entire UniFi database log: sudo cat /usr/lib/unifi/logs/mongod.log.

To show and follow the newest line of the UniFi database log: sudo tail -f /usr/lib/unifi/logs/mongod.log.

Java

To check the current version of Java: java -version.

To set OpenJDK 8 as default, run sudo update-java-alternatives --set java-1.8.0-openjdk-amd64.

To uninstall OpenJDK 9 (if installed automatically by Ubuntu), run sudo apt remove openjdk-9-jre-headless

UniFi Devices

To check the current adoption status of a device: info.

To set the inform URL for a device: set-inform <inform url>.

To manually upgrade a device: upgrade <firmware url>.

To reset a device to defaults: set-default.

Additional Reading

UniFi – Getting Started

UniFi – Device Adoption Methods for Remote UniFi Controllers

UniFi – Ports Used

UniFi – How to Install and Update via APT on Debian or Ubuntu

UniFi Installation Scripts | UniFi Easy Update Scripts | Ubuntu 18.04 and 16.04 | Debian 8 and 9