Upgrading the Ubiquiti UniFi Controller Software on Centos

Update: 11/11/19 – Brandon contributed a super handy function you can add to your .bashrc file to automate the entire process below.

I recently completed a deployment of several Ubiquiti UniFi UAP-AC-PRO access points and so far I’ve been very impressed with their performance.

One of the best things about Ubuqiti is that the UniFi controller software is completely free.

Ubiquiti UniFi

Ubiquiti provides a Linux package for Debian /Ubuntu but in order to install UniFi on Centos or any other non Debian based distro you must use their Linux DIY package.

The DIY version of the software isn’t very well documented and has a couple of caveats.

  1. The auto update feature of the UniFi controller software does not work.  
  2. The configuration backup and restore feature does not work.

Since Ubiquiti bundles new versions of the access point firmware with the UniFi controller software it is necessary to upgrade UniFi in order to deploy new AP firmware versions.

This creates a slightly annoying issue since the UniFi software can’t be automatically upgraded.

Furthering frustrations the Linux DIY package doesn’t really provide any useful instructions on the proper way to perform this upgrade.

I decided to share the procedure I’ve been using to upgrade the software to help out the other Centos Linux users out there.

These steps have been tested on Centos 7.0 but they should work for most other distros too.  If you have UniFi installed somewhere besides /opt then you will need to change the paths in the commands below.

 Step 1: Stop the UniFi service

The UniFi service must be stopped before you can proceed with the upgrade.

service unifi stop

Step 2: Backup the current configuration

tar -C /opt/UniFi -zcpvf /root/backup.tar.gz data

You may see a message that one of the journal files changed while being read, this is normal and can be ignored.

Step 3: Download the new UniFi package

The current release version of the UniFi DIY package is 5.4.11.

Ubiquiti recently dropped support of the DIY packages.  They have stopped posting the download links but the files are still present.  To find the links to the new versions of the DIY packages you need to register for access to the beta forums.  The new release posts contain the download links for the DIY packages.

wget https://www.ubnt.com/downloads/unifi/5.4.11-6cbeae59e7/UniFi.unix.zip /root/UniFi.unix.zip

Take a look at the Ubiquiti forums for more information about the lack of support for DIY packages.  Also, please vote for the feature request to provide officially supported RPM packages for the UniFi software.

Step 4: Unzip the new version and fix the ownership

unzip -qo /root/UniFi.unix.zip -d /opt
chown -R ubnt:ubnt /opt/UniFi

Step 5: Restore the configuration backup

tar -C /opt/UniFi -xzpvf backup.tar.gz

Step 6: Start the UniFi service

service unifi start

Verifying the Upgrade

To verify the new version was properly installed log into the UniFi web interface and go to the Settings \ Maintenance menu.  The version is indicated under the server information section of the maintenance page.

UniFi Controller Settings Maintenance Menu

Sam Kear

Sam graduated from the University of Missouri - Kansas City with a bachelors degree in Information Technology. Currently he works as a network analyst for an algorithmic trading firm. Sam enjoys the challenge of troubleshooting complex problems and is constantly experimenting with new technologies.

8 thoughts to “Upgrading the Ubiquiti UniFi Controller Software on Centos”

  1. Nize. Was just looking for something like this to update my cloud controller.
    Now I just need to find a way to setup Remote user VPN authentication on that same cloud controller to have a single point of managing user access. Any thoughts?

  2. Hi Sam. I just used your instructions to upgrade to UniFi Controller version 5.0.6 on a Centos 7 box. It worked flawlessly. Thanks.

  3. Hi Sam,

    Great instructions. Did not work the first time. There already was a UniFi.unix.zip file so the new downloaded had a different name. After that, all good…

  4. Thanks. I have been looking for more documentation on upgrading my centos7 unifi controller. I found the documentation to standing it underwhelming. So it is nice to find this simple upgrading KB.

  5. This was a super helpful step-by-step. However, I found some inefficiencies I’d like to offer a suggestion to improve. After going through these steps, you’ll end up with the backup restored to “/opt/UniFi/data/opt/UniFi/data” instead of “/opt/UniFi/data”. This makes each subsequent backup even larger because each time you untar it, it will nest the restore inside of “/opt/UniFi/data” in a folder called “opt/UniFi/data”…and the process gets to be pretty slow. In order to speed it up, the initial tar to backup the configuration could be modified to look like this:

    tar -C /opt/UniFi -zcpvf /root/backup.tar.gz data

    This will change the directory to “/opt/UniFi” and then tar up the data directory. The addition of the “p” simply preserves the permissions. Then, when it comes time to restore the backup, use this slightly modified untar command (again the “p” preserves the permissions, this time from within the tar as they were when the backup was taken):

    tar -C /opt/UniFi -xzpvf backup.tar.gz

    To make this process even easier for others, I wrote a small function you can place in your “/root/.bashrc” file (copy from the line just below the “—–” until the “—–” at the bottom):
    ——————————————
    # Upgrade Unifi Controller (requires version)
    upgradeUnifi () {
    if [ $# -eq 0 ]; then
    echo “Must specify upgrade version number. Ex: 5.10.20″
    return
    fi
    datestamp=$(date +”%Y%m%d_%H%M%S”)
    echo -n “Downloading UniFi $1…”
    wget -O /root/UniFi_$1.unix.zip http://dl.ubnt.com/unifi/$1/UniFi.unix.zip
    echo “done”
    echo -n “Stopping UniFi service…”
    systemctl stop unifi
    echo “done”
    echo “Backing up /opt/UniFi/data to /root/unifi_backup_$datestamp.tar.gz…”
    tar -C /opt/UniFi -zcpvf /root/unifi_backup_$datestamp.tar.gz data
    echo “…done”
    echo -n “Unzipping UniFi $1…”
    unzip -qo /root/UniFi_$1.unix.zip -d /opt
    echo “done”
    echo -n “Removing new data directory…”
    rm -rf /opt/UniFi/data
    echo “done”
    echo -n “Fixing permissions…”
    chown -R ubnt:ubnt /opt/UniFi
    echo “done”
    echo “Restoring data directory from backup…”
    tar -xzvpf /root/unifi_backup_$datestamp.tar.gz -C /opt/UniFi/
    echo “…done”
    echo -n “Starting UniFi service…”
    systemctl start unifi
    echo “done”
    echo -n “Removing /root/UniFi_$1.unix.zip…”
    rm -rf /root/UniFi_$1.unix.zip
    echo “done”
    }
    ——————————————

    After saving the changes to “/root/.bashrc”, reload the profile by running this:

    source /root/.bashrc

    …then type “upgradeUnifi “. This requires you to know which version you want to upgrade to. When you log into the controller’s web interface, if a new version is available, it will pop up and tell you which new version is available. Something like “5.11.36”. So, to upgrade to that version, simply type:

    upgradeUnifi 5.11.36

    The process will download the 5.11.36 version to “/root/UniFi_5.11.36.unix.zip”, stop the UniFi service, backup the “/opt/UniFi/data” directory as a tarball in “/root/unifi_backup_.tar.gz”, unzip the new version, set the permissions on the new version, restore the data directory to “/opt/UniFi”, start the new UniFi service and remove the downloaded “UniFi_5.11.36.unix.zip” upgrade file.

    Hope this helps make it much faster to upgrade!

    @Sam Kear: Not trying to be presumptions, but feel free to post any of this up higher on your page so others can see it. You have my full permission to do so (since it’s on your blog post anyway 😉 ). Just trying to help.

Leave a Reply

Your email address will not be published. Required fields are marked *