UniFi - Changing the Firmware of a UniFi Device


 Overview


This article describes how to change the firmware on UniFi devices (access points, switches, gateways), 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. Please see our Related Articles below if you are searching for information on how to update the UniFi Network Controller software, or how to change the Cloud Key's firmware version.

NOTES & REQUIREMENTS:
If you are planning on using a different firmware version than what is offered by the UniFi Network Controller, make sure you disable Automatic Upgrades in the Controller first. Scheduled upgrades will revert the firmware back to the version offered by the Content Delivery Network (CDN), as long as the Controller has internet access.

Table of Contents


  1. Simple Upgrade to Newest Firmware Version
  2. How to Change the Firmware Via the Controller Web UI
    1. Devices with Internet Access
    2. Devices without Internet Access (cache)
  3. How to Change the Firmware Using Local Upgrade Via SSH
    1. UniFi AP and UniFi Switch
    2. USG and USG Pro
  4. How to Disable Automatic Upgrades
  5. 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. When there is an update available, an Upgrade option will appear when you hover over each device along with the Locate and Restart options (if in list view). If using the grid view a small upgrade icon will appear to the upper right of each device as applicable.

There is also the option of a rolling upgrade for wireless devices. To use this feature, go to the Devices tab and click on Wireless. A button will appear on the upper, right-hand of the screen, offering the option to Start Rolling Upgrade if there are any wireless devices 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 you're looking for. You might be in need of an older version or a non-released version. This can be handy to help with adoption issues, for troubleshooting, or simply upgrading to the latest available firmware under development. It is possible to run a different version of firmware on any UniFi device. Typically, you would run the same version on each type of device, 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). 


How to Change the Firmware Via the Controller Web UI


Back to Top

Devices with Internet Access

For unadopted devices, you will see an upgrade option in the Devices tab of the Controller when hovering over that device on the list. You will be able to perform the upgrade action before adopting the device, which is especially useful if you are experiencing adoption issues.

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 the device to expand the Properties panel. Select the Config tab > Manage Device > Custom Upgrade.

In this section, you can enter a link that points to the new firmware version. Firmware .bin (or .tar for USGs) links can be found on our official Downloads page under the Firmware section, or within the Releases section in our Community. If using the Downloads page:

1. Use the menu to the left to select your device.

2. Click on the newest firmware available (shown under the Firmware header, as opposed to the Software or Documentation headers). This will expand the firmware information. You can also click the Download icon and skip this step.

3. Click Download and read and accept the terms presented.

4. The next pop-up window will provide the firmware name (now is a good moment to verify this is a firmware .bin file if upgrading a UAP or USW, or a .tar file if upgrading a USG)—but definitely not a software file (.exe, .pkg, .deb), a Download button, and a Direct URL. This is the link you must copy for this method as well as the ones described in the following sections of this article. 

ATTENTION: When upgrading from firmware version 3.7.56 or older use http:// instead of https:// in the URL. It is also recommended to test using http:// if the https upgrades are failing.
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.

Devices without Internet Access (Cache)

If the devices do not have internet access, but the UniFi Network Controller does, then a good option is to cache the firmware, which basically allows the UniFi Network Controller to provide the firmware link directly for upgrade. Caching the firmware can also be used as a tool when other upgrading methods are failing, by keeping it all within the controller. 

1. Cache firmware by going to Settings > Maintenance > Firmware and selecting the All tab.

2. You can select to view All UniFi Devices, only the Known Devices, or only the Site Devices.

3. Select the applicable firmware(s) and click Cache in the actions column to add that firmware to the Cached tab. 

4. Once you verify the firmware is now in the Cached tab, go to the Devices section and hover over the device in question. An "Upgrade" option should now appear along with the usual Locate and Restart.


How to Change the Firmware Using Local Upgrade Via SSH


Back to Top

Applicable for: UniFi AP / UniFi Switch


Internet Upgrade

If the UAP/USW has Internet connectivity, it’s easiest to let it download the update file, then install it. SSH to the device, then run the following command replacing the URL with one found in the Downloads page. Please verify you are using the firmware .bin file specific to your device (UAP, USW, USG, etc) and not the UniFi Network Controller software.

upgrade https://dl.ui.com/path/to/upgrade-vX.Y.Z.bin

It will download the specified file, upgrade it, and reboot into the new version.

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. Please verify you are downloading the firmware .bin file specific to your device (UAP, USW, USG, etc) and not the UniFi Network Controller software.

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 .bin 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 an 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. Please verify you are downloading the firmware .bin file specific to your device (UAP, USW, USG, etc) and not the UniFi Network Controller software.

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

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

syswrapper.sh upgrade2 &

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

Applicable for: UniFi Security Gateway / UniFi Security Gateway Pro


All models of USG allow local upgrade, though they use a .tar file rather than the .bin used by the APs and switches. There are two options for a local upgrade, one downloading via HTTP or HTTPS (HTTPS highly recommended) from USG itself, and one method of doing an offline upgrade.

Internet Upgrade

If the USG has Internet connectivity, it’s easiest to let it download the update file, then install it. Via SSH to USG, run the following, replacing the URL with one found in the Downloads page. Please verify you are downloading the firmware .tar file specific to your device and not the UniFi Network Controller software.

upgrade https://dl.ui.com/path/to/upgrade-vX.Y.Z.tar

It will download the specified file, upgrade it, and reboot into the new version.

Offline Upgrade

Where the USG is not yet connected to the Internet, you can download the upgrade.tar file to your local system, then use SCP to copy it to USG.

scp /foldername/upgrade-vX.Y.Z.tar user@<IP-of-USG>:~/upgrade.tar

Then SSH to the USG, and run the following to perform the upgrade using that file.

sudo syswrapper.sh upgrade upgrade.tar


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 > Services section.

2. Make sure the checkbox for Automatic Upgrades (Automatically upgrade AP firmware) is left unchecked. The wording might be slightly different depending on the Controller version. 

We're sorry to hear that!