This article describes advanced options for firmware updates when there are issues with standard upgrades. These methods are not recommended for most users.
- Custom device firmware update
- Cached device firmware update
- Firmware update via SSH
- UniFi Network application update via SSH
- Troubleshooting
Custom firmware update
For most users, we recommend using the Network application’s automatic upgrade capabilities. If you need to update a device’s firmware to a specific version, you can use the custom upgrade option. To use this method, your device must have access to the internet. You will also need a link to the firmware version you are looking to use, which can be found at the bottom of the Release post for your specific device. This method works to upgrade or downgrade firmware. Downgrading is not generally recommended and may cause other issues.
1. Within the firmware Release post, scroll to the bottom and expand the Download links. Find your device model, right-click, and Copy Link Address.
2. In the Network application, click on your device to reveal its properties panel, and navigate to Device > Manage > Custom Upgrade.
3. Paste in the firmware link copied in step 1 and click Apply Custom Upgrade.
Cached firmware update
If the device does not have internet access, but the UniFi Network application does, then you can cache the firmware and update. For this method to work, you must have previously cached a firmware version and saved it to the Network application. This method works to upgrade or downgrade firmware.
To cache firmware, go to Settings > System Settings > Maintenance > Device Firmware Cache. Under the Available Firmware tab, hover over the Cache column of the device and select Cache.
The device will now appear with an update available in the UniFi Devices section. Click Update available and confirm your changes.
Firmware Update via SSH
Updating a UniFi Network device (UAP, USW, USG)
To SSH into your UniFi Network devices, you must enable Device SSH Authentication and create a user and password to use during your SSH session. See instructions on how to do so here.
1. Copy the link of your device’s firmware download link from the Release post. See the Custom Upgrade section for more details on where to find the download link.
2. SSH into the device and run the upgrade command followed by the download link.
For example:
upgrade https://dl.ui.com/unifi/firmware/UAL6/5.60.1.12923/BZ.mt7621_5.60.1+12923.210416.1641.bin
1. Download the firmware to your computer by opening the Release post and clicking on your device’s Firmware Download link. See the Custom Upgrade section for more details on where to find the firmware link.
2. Use the scp command on a terminal such as the Terminal application in macOS and Linux, or PuTTY on Windows to transfer the firmware file to the device. For a UniFi Security Gateway, rename the file to upgrade.tar and then transfer the file to the /home/<username>/ folder on the USG. If the USG is in factory default state, the username is ubnt. If the USG has already been adopted, then use the SSH username.
scp </folder path/firmwarefile.bin> <user>@<IP of device>:/tmp/fwupdate.bin
Example for UniFi Access Point or UniFi Switch:
scp /Users/alexpro/Desktop/BZ.mt7621_5.60.1+12923.210416.1641.bin Alex@192.168.1.219:/tmp/fwupdate.bin
Example for UniFi Security Gateway:
scp upgrade.tar ubnt@192.168.1.1:/home/ubnt/upgrade.tar
3. When prompted for a password, use the same one used for SSH, set in the Device SSH Authentication section.
4. SSH into the device and issue the following command to initiate a local upgrade:
If updating a UniFi Access Point or UniFi Switch use:
syswrapper.sh upgrade2 &
If updating a UniFi Security Gateway modify the command and use:
sudo syswrapper.sh upgrade upgrade.tar
Updating a UniFi OS Console
To SSH into your UniFi OS Console, you must enable it within the UniFi OS Settings. See instructions on how to do so here.
1. Copy the link of your UniFi OS Console’s firmware download link from the Release post. See the Custom Upgrade section for more details on where to find the firmware link.
2. Connect to the console via SSH and input the upgrade command followed by the firmware download link specific to your console found in the Release post.
If updating a Dream Machine (UDM, UDM Pro) use:
ubnt-upgrade <download link>
For example:
ubnt-upgrade https://fw-download.ubnt.com/data/udm/0974-udmpro-1.8.0-f7d38e82e05c4febb5da3c0dbdb487d4.bin
If updating a Cloud Key (UCK Gen2, UCK Gen2 Plus) use:
ubnt-systool fwupdate <download link>
1. Download the firmware to your computer by opening the Release post and clicking on your device’s Firmware Download link. See the Custom Upgrade section for more details on where to find the firmware link.
2. Using a terminal such as the Terminal application in macOS or Linux, or PuTTY on Windows, issue the scp command to transfer the firmware file to the device. User and password will be the same as the ones used to SSH into the console.
If updating a Dream Machine (UDM, UDM Pro) use:
scp </foldername/firmwarefile.bin> <user>@<IP-of-console>:/mnt/data/fw.bin
For example:
scp /Users/alexpro/Desktop/c374-udmpro-1.10.0-13-7c563cf205df48f1bd66530982a50141.bin root@192.168.1.1:/mnt/data/fw.bin
If updating a Cloud Key (UCK Gen2, UCK Gen2 Plus) use:
scp </foldername/firmwarefile.bin> <user>@<IP-of-console>:/tmp/fw.bin
3. Connect to the console via SSH and use the upgrade command followed by the path to the file (as determined in the previous step).
- If using a Dream Machine (UDM, UDM Pro) use:
ubnt-upgrade /mnt/data/fw.bin - If updating a Cloud Key (UCK Gen2, UCK Gen2 Plus) use:
ubnt-systool fwupdate /tmp/fw.bin
UniFi Network application update via SSH
We recommend using the UniFi OS Settings or UniFi Network application to update your application’s version. You can choose to stay with a release channel of your choice (i.e. Official, Release Candidate, Beta) without needing to use SSH. Learn how here.
1. Copy the link of the UniFi Network application version from its Release post. You will use it in step 5. See the Custom Upgrade section for more details on where to find the firmware link.
You may use the Debian/Ubuntu and UniFi Cloud Key file if you do not see a Dream Machine one.
2. Connect to the console via SSH and access the UniFi OS Shell by inputting the following command: unifi-os
shell
3. Navigate to the /tmp directory using: cd /tmp
4. Verify if there are any previous installation files present in the directory and delete them if applicable:
ls -l
rm unifi_sysvinit_all.deb
5. Use the curl command followed by the previously copied link to download the UniFi installation file and store it in the /tmp directory.
curl -o "unifi_sysvinit_all.deb" <network application link.deb>
For example:
curl -o "unifi_sysvinit_all.deb" https://dl.ui.com/unifi/6.2.26-a79cb15f05/unifi_sysvinit_all.deb
6. Once the file download process finishes, install the new new version using the dpkg command:
dpkg -i unifi_sysvinit_all.deb
7. Once the installation process finishes, remove the file using the rm command: rm unifi_sysvinit_all.deb
1. Copy the link of the UniFi Network application version of your choice from the Release post. You will use it in step 4.
2. Connect to the console via SSH and navigate to the /tmp directory:
cd /tmp
3. Verify if there are any previous installation files present in the directory and delete them if applicable:
ls -l
rm unifi_sysvinit_all.deb
4. Use the wget command, followed by the download link copied in step 1 to place it in the tmp directory.
wget <download link>
For example:
wget
https://dl.ui.com/unifi/6.2.26-a79cb15f05/unifi_sysvinit_all.deb
5. Once the file finished saving, type in the following to install:
sudo dpkg -i unifi_sysvinit_all.deb
6. Wait for the installation process to complete, and use the rm command to remove the file.
rm unifi_sysvinit_all.deb
Troubleshooting
A firmware error could be caused by different things. Confirm that the firmware file you are using is the correct one for your device. In the Release post you must copy or download the link specific to your device model.
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 application).
Sometimes the SSH session will end automatically with a “closed by remote host” message, but the upgrade is still happening in the background. You’ll see the device’s LED blink while it’s upgrading.
Wait until the device’s LED is a solid blue again for the upgrade change to be seen.
You can see your device’s IP address in the UniFi Devices section of the application by clicking on your device, or by changing the Column Visibility options in the Filter settings.
Go to the known_hosts file in your computer. The SSH output error will tell you where this file is. You can delete all the keys in the file, leaving an empty document and save your changes to fix this.
This folder may be hidden, so access the folder directly (Finder > Go > Go to Folder on macOS, for example).
- Access your Cloud Key by typing in its IP address in a browser. The default credentials are ubnt/ubnt or root/ubnt.
- Go to the Maintenance tab. Update the Cloud Key firmware under the Firmware header. You can check for updates to get the latest publicly released version, or to update to a specific version, select the Update Manually option. Use the firmware download link from the firmware Release post.
To upgrade via SSH, follow the same instructions as in the SSH section abovebut use the appropriate firmware release post and firmware download link for your specific model.
Remember you must be connected locally to the device you are connecting to via SSH. This means the computer you are using must be on the same network as the device.