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


Overview


This article provides the steps to update the UniFi Controller on a Debian or Ubuntu system via APT (Advanced Package Tool). 

NOTES & REQUIREMENTS:
Before upgrading the UniFi Controller, make sure that you have backed up the UniFi Controller Database. You will need to make sure that the user has sudo permissions. For more information about adding a user to sudo list, see this link.

Table of Contents


  1. Introduction
  2. UniFi Controller APT Steps
  3. Log Files Location
  4. User Notes & Tips
  5. Related Articles

Introduction


Back to Top

In order to update the UniFi controller via APT, you will need to create source files or edit lines in an existing sources.list file with Linux text editors: vi or nano. That is the most common method for package updates and installs for these operating systems. The repo structure should be permanent, but if there are any changes they will be pointed out in the release posts, found in the Community.

Follow the instructions below to stay with the current stable release, regardless of changes in versions. When there is a new stable release, typically there will be a post on the Community announcing it.


UniFi Controller APT Steps


Back to Top

1. 

Use the following command to add a new source list:

 

echo 'deb http://www.ubnt.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list
NOTE: Using http://www.ubnt.com/downloads/unifi/debian on a browser will result in a 403 Forbidden page. This is because we do not allow direct listing/access to this link. The URL is only meant to be used when using the CLI commands as in the one shown above.

2. Add the GPG Keys. To add the GPG Keys use one of the two methods described below, Method A is recommended. When using the commands below, it is assumed you have sudo and wget installed, more information about sudo can be found here, and wget here.

User Tip: For Ubuntu 18.04, run the following commands before installing UniFi in step 4.
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6
echo "deb http://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
See an example of what scripts the Community is using to install the UniFi Controller on Ubuntu 16.04 and 18.04 in this Community post.

(Method A) Download and install the following trusted key into /etc/apt/trusted.gpg.d

sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ubnt.com/unifi/unifi-repo.gpg 

(Method B) Using apt-key.

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 06E85760C0A52C50 

3. Update. Retrieve the latest package information. Note: If this results in an error, please check the User Tip below.

sudo apt update 

4. Install and upgrade the UniFi controller.

sudo apt install unifi

5.  This step may not be required, depending on the Linux distro you have. If your distro does not come with MongoDB, and it's not available in their repo, then please see the MongoDB installation guide. You can find the latest installation guide for Ubuntu here, and Debian here. We recommend at least MongoDB 2.6.10. Some users have changed the backend to use MongoDB 3 successfully too. The UniFi Controller should now be accessible at the computer's configured local or public IP address.

warning_25x25.png  We strongly recommend staying with the stable release, but for those users who wish to do otherwise, click here to expand and see possible suite names, as well as code names in the table within.
"Testing" refers to the next generation release, it's not released to the general public yet. "Stable" refers to the current stable release, that is the one supported by UBNT and described in this article. "Old Stable" is the previous stable release, once it has been displaced by the new, current stable release.

 

Suite Name Code Name   Archived Code Names
oldstable unifi-5.7     The code names below have been archived and are no longer supported, these should only be used in very specific, rare scenarios.
stable unifi-5.9
testing *

unifi3

unifi4

unifi-5.3

unifi-5.4

unifi-5.5

unifi-5.6

 

*testing is empty at the moment 


Log Files Location


Back to Top

Log files will be essential for any troubleshooting you might perform. Find them here:

  • /usr/lib/unifi/logs/server.log
  • /usr/lib/unifi/logs/mongod.log
NOTE: If your controller is running on a Unix/Linux based system, then you will require superuser (sudo) privileges to access these log files.

User Notes & Tips


Back to Top

These notes have been added thanks to user collaboration. Have anything to contribute? Click on the Give Feedback button below!

  • If you are installing in a VM or a headless server, you may encounter entropy issues. This could be anything from slow service start/restart to complete service failure. The fix is to install haveged. This is an external link for a tutorial on the subject.
  • Since UniFi controller version 5.6.x the UniFi service does not run as root. This means that you cannot bind to privileged ports (<1024). The controller will fail to start if you try to use these ports. 
  • The following affects APT versions 1.5 onward (Ubuntu 17.10 and Debian Sid or newer). A recent version of the apt-secure man page stated: "Since version 1.5 changes in the information contained in the Release file about the repository need to be confirmed before APT continues to apply updates from this repository", meaning that when performing an update from a major version to the next (for example 5.5.x to 5.6.x) the apt update will result in an error.
    • To fix this run the command the following way: apt update --allow-releaseinfo-change
    • If you receive an error stating the command is not understood in combination with the other options, users have reported that issuing the following two commands has fixed it: issue apt clean and hit enter, followed by apt update and enter.
  • The UniFi Controller when installed on Debian and Ubuntu will not have a GUI since it's being run as a Service. Please use the service command for starting, stopping and restarting the UniFi Controller.
  • If you see the following error on your DNS server, a user reports solving this by forcing the system to use 8.8.8.8 as DNS server, not his ISP.
  • At the moment Ubiquiti does not support arm64, hence it is not available via the repo. A download and manual installation will be necessary for this.
  • In the Add the GPG Keys, method B: Source: External Link. For users behind restrictive firewalls the following command will allow them to import the GPG key:

    apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 06E85760C0A52C50

  • Because of the Java 8 dependency, when using UniFi controller 5.7.X some additional steps might be needed. See this Community post for details.
  • The command apt is apt-get in Ubuntu older than 14.04.
  • This Community post shares some scripts for UniFi Controller software installation on Ubuntu 18.04 and 16.04 and Debian 8/9.

Related Articles


Back to Top

UniFi - Recommended Minimum System Requirements

UniFi - Change Default Ports for Controller and UAPs


We're sorry to hear that!