UniFi - Changing the Firmware of a UniFi Device

thumbs_up_i_25x25.png  Was this useful? Help us identify your favorite articles by clicking on the thumbs up at the bottom of the page. And if you think this article is not useful, please let us know why by clicking on the feedback link below!

 Overview

Readers will learn how to change the firmware on their UniFi device. This article describes the more common upgrade to the most recent release via the GUI, as well as manually changing the firmware version, be it to an unreleased version or reverting to an older firmware version. 

There are three methods described in this article: via the controller Web UI, or via SSH either with the "standard" method or by a local upgrade. For more information on how to connect to a device using SSH refer to the Related Articles at the bottom of this article.

info_i_25x25.png Note: If you are going to use a different version than what comes with the controller, make sure you disable Automatic Upgrades in the controller first. 

Table of Contents


 

Simple Upgrade to New Firmware Version Release


Back to Top

A simple device upgrade to the most recent release can be done within the controller, in the Devices section. An upgrade option will appear under the Actions column of each device when there is an available upgrade.

Screen_Shot_2017-04-11_at_12.57.28_PM.png

There is also the option of a rolling upgrade for APs: once inside the Devices tab, click on APS. A button will appear on the upper, right-hand of the screen, offering the option to Start Rolling Upgrade if there are UAPs with pending upgrades on the list.

Screen_Shot_2017-04-11_at_12.56.51_PM.png

The rest of this article describes how to change the firmware when a simple device upgrade is not what the user is looking for. They might be in need of an older or a non-released version. This can be handy to help with adoption issues, for troubleshooting, or simply upgrading to the latest available firmware if a new controller isn't yet available. It is possible to run a different version of firmware on any UniFi device. Usually you would run the same version on APs, or your switches, but in some cases you may only want to test a new firmware in a certain location before rolling it out site wide (or to multiple sites). As of Controller version 5.4.2 we allow batch firmware upgrading via the controller UI.


How to Change the Firmware via the Controller Web UI


Back to Top

Applicable for: UniFi AP/UniFi Switch/UniFi Security Gateway/UniFi Security Gateway Pro

We've made it much easier to change device firmware via the controller web UI. For any unadopted device, you will have the upgrade option which can be performed before you adopt the device. This may help if you experience issues adopting a device.

For any adopted UniFi device you can easily upgrade or change the device firmware from the device properties window. This is found under either under Configuration>Custom Upgrade or Configuration>Manage Device>Custom Upgrade. 

We've made it much easier to change device firmware via the controller web UI. For any unadopted AP and Switch, you will have the upgrade button in the Devices tab of the controller. You will be able to use this option even before adopting the device, this will be specially useful if you are experiencing issues adopting a device. Note: the upgrade button does not work for USG and USG-PRO-4.

For any adopted UniFi device you can easily upgrade or change the device firmware from the device Properties window. In the Devices tab click on Name/MAC address of the AP to expand the Properties panel. Select the Configuration tab > Manage Device > Custom Upgrade.

In this section you can enter a link that points to the new firmware version. Firmware links can be found on our official download page, HERE, and also within the release notes or firmware blog posts HERE.

info_i_25x25.png Notes:
  • Currently UniFi access points and switches will not work with a HTTPS link, so please make sure it is a HTTP link.
  • When using a link to a firmware binary on our CDN, the UniFi device will need to be able to properly resolve the host via DNS/access the WAN. The custom upgrade would also work for a locally hosted FTP or HTTP server. 

How to Disable Automatic Upgrades


Back to Top

If you are changing the firmware of one of your devices to one other than the released version, you will want to disable the automatic upgrades to avoid it rolling back to that public release. 

1. To do so, go to Settings > Site

2. Make sure the checkbox for Automatically upgrade firmware is left unchecked. Wording might be slightly different depending on your Controller version. 

Screen_Shot_2017-10-17_at_8.38.27_AM.png


How to Change the Firmware using the Standard SSH Method


Back to Top

Applicable for: UniFi AP/ UniFi Switch

SSH into the AP/Switch. For more information on how to connect to a device using SSH please refer to this article: How to Establish a Connection Using SSH. Issue the following command, making the necessary substitutions described below:

upgrade http://IP of Controller:8080/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin
IP of Controller: is the IP address of the Cloud Key or computer where the controller software is installed.
8080: is the inform port for the devices to communicate with the controller. You should use 8080 unless you changed it manually when setting up the controller.
Binary folder: represents the model name of the AP or Switch. Check the table below.
Firmware version for AP or Switch: is the firmware version number. To find this navigate to <unifi base folder>/dl/firmware/<binary folder>/… 
info_i_25x25.png Note: The location <unifi_base> will vary depending on your operating system. See this article for more information.

The path will change according to the model of the AP or the switch. Please refer the table below to match the binary folder with the device model(s).

Folder Device Model
BZ2 UAP, UAP-LR, UAP-OD, UAP-OD5 
U2HSR UAP-Outdoor+
U2IW UAP-InWall
U2Sv2 UAP-v2, UAP-LR-v2
U7E UAP-AC, UAP-AC v2, UAP-AC-OD
U7P UAP-Pro
U7PG2 UAP-AC-Lite, UAP-AC-LR, UAP-AC-PRO, UAP-AC-EDU, UAP-AC-M, UAP-AC-M-PRO, UAP-AC-IW
U7HD UAP-AC-HD 
U7SHD UAP-AC-SHD
US24P250 US (all current models, with the exception of the ones listed below)
USXG US-16-XG
US24PL2 US-24-L2-POE, US-48-L2-POE

info_i_25x25.png Note: The upgrade alias expects the use of a URL, so it must point to the controller, a locally hosted FTP or HTTP server or to a link from our official download page HERE.

Example

User X has a UniFi Controller software version 5.4.11 installed in a computer with an IP address of 192.168.1.26. He wants to upgrade the firmware of his UAP-AC-PRO which is already adopted in the controller with the bundled firmware 3.7.40.6115. Following the instructions above, User X would use this command:

upgrade http://192.168.1.26:8080/dl/firmware/U7PG2/3.7.40.6115/firmware.bin 

Applicable for: UniFi Security Gateway/ UniFi Security Gateway Pro

Users upgrading a USG or a USG-Pro-4 must begin by going to an elevated console. So in the Command Line Interface you must type: 

sudo su
upgrade link_to_firmware_file

The USG will need internet access if the link used is not from a locally hosted FTP or HTTP server. Firmware files for USG and USG-PRO-4 do not come bundled with the UniFi Controller software due to file size constraints. You can download the required firmware files HERE.


How to Change the Firmware using Local Upgrade via SSH


Back to Top

Applicable for: UniFi AP / UniFi Switch

To perform a local firmware update, the firmware.bin file's name needs to be changed to fwupdate.bin. So, what you need to do is copy the file from the appropriate directory of the controller—or from your computer if downloaded from our downloads page HERE. For the appropriate directory you can reference the binary folder table above.

For Linux you would:

Open Terminal and issue the following command, making the appropriate substitutions:

scp /usr/lib/unifi/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin user@IP-of-UAP-or-Switch:/tmp/fwupdate.bin

Where/usr/lib/unifi/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin is the path to the firmware file in your computer. If you have downloaded the firmware file from our Downloads page, the path must change to the saved location of the file.

For Mac you would:

Open Terminal and issue the following command, making the appropriate substitutions:

scp /Applications/UniFi.app/Contents/Resources/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin user@IP-of-UAP-or-Switch:/tmp/fwupdate.bin

Where /Applications/UniFi.app/Contents/Resources/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin is the path to the firmware file in your computer. If you have downloaded the firmware file from our Downloads page, the path must change to the saved location of the file. The commands above will copy the firmware file to the required directory and rename it. You will now be prompted to enter the password that you use for SSH access. As you type, no characters will appear on screen for security purposes. Carefully enter the correct password, and press Enter. Then connect via SSH and issue the following command to initiate a local upgrade.

syswrapper.sh upgrade2 &

Applicable for: UniFi Security Gateway / UniFi Security Gateway Pro

The USG and USG-Pro do allow local upgrade, but you may want to use upgrade.tar for the file name instead of fwupdate.bin. You will have to place the firmware file in a writable directory, so use the following, substituting the admin-username with the appropriate name: /home/admin-username

So the last part of the commands mentioned above would change. For example, for Linux the command would change from:

/usr/lib/unifi/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin user@IP-of-UAP-or-Switch:/tmp/fwupdate.bin

to

/usr/lib/unifi/dl/firmware/binary folder/firmware version for AP or Switch/firmware.bin user@IP-of-usg:/home/username/upgrade.tar 

You need to run the command elevated. Assuming you're in the home directory, and the file is named upgrade.tar then you would issue the following command:

sudo syswrapper.sh upgrade upgrade.tar