UniFi - Changing the Firmware of a UniFi Device


 Overview


This article describes how to change the firmware on UniFi devices, including instructions on 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. 

NOTES & REQUIREMENTS:
If you are planning on using a different firmware version than what comes bundled with the controller version, make sure you disable Automatic Upgrades in the controller first. 

Table of Contents


  1. Simple Upgrade to Newest Firmware Version
  2. How to Change the Firmware Via the Controller Web UI
    1. How to Disable Automatic Upgrades
  3. How to Change the Firmware Using Local Upgrade Via SSH
    1. UniFi AP and UniFi Switch
    2. USG and USG Pro
  4. Related Articles

Simple Upgrade to Newest Firmware Version


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.

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.

The rest of this article describes how to change the firmware when a simple device upgrade is not what the user is looking for. You 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 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

For unadopted APs and Switches, you will see an 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.

NOTE: 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

When you enable the option to "Automatically upgrade AP firmware" all access points will upgrade the moment you upgrade the Controller's software version. If you are changing the firmware of one of the 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 the Controller version. 

Screen_Shot_2017-10-17_at_8.38.27_AM.png


How to Change the Firmware Using Local Upgrade Via SSH


Back to Top

Applicable for: UniFi AP / UniFi Switch


IMPORTANT: To perform a local firmware update, the firmware.bin file's name needs to be changed to fwupdate.bin.

Mac/Linux Users:

1. Download the firmware.bin file from our Downloads page.

2. Issue the following command to change the file name from firmware.bin to fwupdate.bin, and to place it in the UniFi device filesystem. Remember to make appropriate substitutions in the command below:

scp /foldername/firmwarefile.bin user@IP-of-UAP-or-Switch:/tmp/fwupdate.bin

3. If you have downloaded the firmware file from our Downloads page, the path must change to the saved location of the file. The command above will copy the firmware file to the required directory and rename it.

3. 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.

4. Then connect via SSH and issue the following command to initiate a local upgrade.

syswrapper.sh upgrade2 &

Windows Users:

1. Download the program WinSCP. This will allow a SCP session over SSH with a folder structure GUI. Use the SSH credentials to login into the UniFi Device. 

2. Download the bin file from our Downloads page.

3. Move the .bin file to the device's /tmp/ folder by dragging and dropping the file, rename file to fwupdate.bin.

4. 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 it is recommended 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

The last part of the commands mentioned above would change in the following way then: 

scp /foldername/firmware.bin user@IP-of-UAP-or-Switch:/tmp/fwupdate.bin

to

scp /foldername/upgrade.tar user@IP-of-USG:/home/username/upgrade.tar 

You also 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 Tip: 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 in the Controller).