Readers will learn how to change the firmware on their UniFi device. 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.
For APs there is now the option of a rolling upgrade: 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.
However, 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.
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.
|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
How to Change the Firmware via the Controller Web UI
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.
How to Change the Firmware using the Standard SSH Method
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.binIP 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>/…
|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).
|BZ2||UAP, UAP-LR, UAP-OD, UAP-OD5|
|U7E||UAP-AC, UAP-AC v2, UAP-AC-OD|
|US24P250||US (all current models, with the exception of the US-16-XG)|
|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.|
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 22.214.171.12415. Following the instructions above, User X would use this command:
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:
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
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
/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
User Notes & Tips
These notes have been added thanks to user collaboration. Have anything to contribute? Click on the Give Feedback button below!
- Getting an "Invalid Firmware" error when upgrading via SSH: might be caused by installing an incorrect version first. Correct this by going to the tmp folder and deleting fwupdate.bin first and then trying the upgrade command once more (making sure it was in the correct folder on the controller).