How to install the UniFi Controller on Ubuntu

Ubiquiti UniFi is properly supported on Ubuntu and Debian, breaking away from being Windows only. Being on Linux also reduces a lot of overhead that Windows typically laid on. The installation instructions provided by Ubiquiti aren’t the best so here’s my take on it. I will be using a freshly installed Ubuntu 14.04.1 LTS.

Add the repository and GPG keys

To install the controller you will need to add the Ubiquiti repository to your apt sources list. Add /etc/apt/sources.list.d/100-ubnt.list (or edit /etc/apt/sources.list). The ‘stable’ source is considered a floating version, and still valid. But if you wish to stay with a specific release branch, then you must specify it in the source line (for example, for UniFi v5 you would use the ‘unifi5’ source).

sudo nano /etc/apt/sources.list.d/100-ubnt.list

## Debian/Ubuntu
# stable => unifi4
# deb http://www.ubnt.com/downloads/unifi/debian unifi4 ubiquiti
# deb http://www.ubnt.com/downloads/unifi/debian unifi5 ubiquiti

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

# oldstable => unifi3
# deb http://www.ubnt.com/downloads/unifi/debian unifi3 ubiquiti
# deb http://www.ubnt.com/downloads/unifi/debian oldstable ubiquiti

Next you will need to add the GNU Privacy Guard (GPG) keys for UniFi and MongoDB (used to store your users and WiFi statistics within the UniFi controller). The GPG keys verifies the genuinity of who you will be downloading from during the installation. Here’s another one liner to add both (Ubiquiti first then MongoDB):

# for Ubiquiti
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50
# or over HTTP by using hkp://keyserver.ubuntu.com:80

# for MongoDB
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

Now perform update to ensure Ubuntu recognises the repository:

sudo apt-get update

Install UniFi

Finally the big moment – installing the UniFi controller.

sudo apt-get install unifi -y

It will install a bunch of dependencies with it including Java 6, MongoDB, Tomcat and a Java SSL certificate tool.

As of August, the unifi-beta and unifi-rapid packages are obsolete.
Access the web interface

If everything went smoothly you should be able to access the controller through your web browser:

https://unifi-server-here:8443

Depending on the version installed, you will be taken to the setup wizard. You’re done!

Problems?

Determine the problem

A good start would be to go through the system logs and google the issue:

cat /var/log/unifi/server.log

Restart UniFi

Just like any other service in Ubuntu, UniFi can be stop, started and restarted.

# to stop the controller
sudo service unifi stop

# to start the controller
sudo service unifi start

# to restart the controller
sudo service unifi restart

# to view the controller’s current status
sudo service unifi status

Java Home not found

This issue can be tricky. UniFi cannot access Java to run Tomcat (its web server). To check if you have Java, simply run:

java -version

If nothing appears you do not have Java. The latest version of UniFi supports Java 8. To install Java, follow this guide from Digital Ocean.

If you do have Java (or installed it now), you will have to edit the UniFi startup script to point out the location of Java. Open the startup script:

sudo nano /etc/init.d/unifi

Change the ‘JAVA_HOME’ location to your new Java location:

JAVA_HOME=/opt/jdk/jdk1.8.0_XX

Keystore file missing / java.io.FileNotFoundException

When going through the log file you may find the error:

java.io.FileNotFoundException: /usr/lib/unifi/data/keystore (No such file or directory)

This error means that the ‘keystore’ file is missing, resulting in Tomcat not being able to start up. The keystore file is responsible for encrypting your connection (HTTPS/SSL).

Generate a new keystore file, answering blank to every question including password:

sudo keytool -genkey -keyalg RSA -alias selfsigned -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise -validity 365 -keysize 2048 -destalias unifi

Restart UniFi when successful and try accessing the web interface again.

sudo service unifi restart

Firewall and how to change default ports for Controller and UAPs

If don’t know how to setup your firewall I will send you to my article How To Setup a Firewall with UFW on an Ubuntu and Debian Server

Default Ports

By default, the UniFi Controller will operate on the following ports:

• unifi.http.port=8080 (port for UAP to inform controller)
• unifi.https.port=8443 (port for controller GUI / API, as seen in web browser)
• portal.http.port=8880 (port for HTTP portal redirect)
• portal.https.port=8843 (port for HTTPS portal redirect)
• unifi.db.port=27117 (local-bound port for DB server)

In version 4.5.2 and later, users can also define the port assigned to STUN services, for scenarios where two or more separate UniFi instances are desired on the same controller machine:

• unifi.stun.port=3478 # UDP port used for STUN

Since v3.2.9+ and v4.6.0+, two more ports are being reserved for device redirector. There is no need to open firewall for these ports on controller. However, on controller, avoid to use these ports.

• port 8881 for redirector port for wireless clients
• port 8882 for redirector port for wired clients

Changing the Ports

UniFi gives operators the freedom to change these ports from their default assignments. By using a network utility (netstat, etc.), users can determine which ports are in use/opened/closed. The steps are outlined below:

1. Close any instances of UniFi software running on controller(s)
2. Modify the file system.properties accordingly—the file can be found in the directory <unifi_base>/data/system.properties
3. Make sure all ports needed by UniFi are available
   Restart UniFi

Example (Windows)

1. Run “netstat – ano” command in the command line.
2. Locate the PID for the mentioned port in use.
3. Open task manager and select view and select columns , put a check for PID (process identifiers)
4. Check the process corresponding to the PID located for the port during step 2.
5. End the process if it is possible.
6. If not possible go on the location <unifi_base>/data and open the system file with word or notepad.
7. Modify this file to change the port that was in use. For example if port 8081 was in use you would modify the line “unifi.shutdown.port=8081” to something like “unifi.shutdown.port=8089” assuming port 8089 was not already in use.