Upgrading OpenWrt firmware using LuCI and CLI
See also:
How the OpenWrt upgrade works
An OpenWrt sysupgrade will replace the entire current OpenWrt installation with a new version. This includes the Linux kernel and SquashFS/ext4/ubifs/JFFS2/other OS partition/s. This is NOT the same as a first time installation (factory).
Sysupgrade via LuCI or CLI works by optionally saving specified configuration files, wiping the entire file system, installing the new version of OpenWrt and then restoring back the saved configuration files. This means that any parts of the file system that are not specifically saved will be lost.
In particular, any manually installed software packages you may have installed after the initial OpenWrt installation have to be reinstalled after an OpenWrt upgrade. That way everything will match, e.g. the updated Linux kernel and any installed kernel modules.
Any configuration files or data files placed in locations not specifically listed as being preserved below will also be lost in an OpenWrt upgrade. Be sure to check any files you have added or customized from a default OpenWrt install to back up these items before an upgrade.
IMPORTANT: Most of the upgrade procedure can be automated by using the attended.sysupgrade service. Attended sysupgrade will request the build of custom image including all your currently installed packages from a central server, download it when ready, and install it keeping your settings. The service can be accessed from LuCI by installing the `luci-app-attendedsysupgrade` package, or from the shell with the `auc` package. Note that you can upgrade systems using attended sysupgrade via LuCI even if they are not connected to the internet, as long as your browser has internet access.
See this howto about extroot procedure.
For Dual Firmware Devices please consult your device page for additional information.
By compiling your own custom image with an OpenWrt buildroot or generating with the imagebuilder, it is possible to remove the need to perform many of the steps above.
Upgrade steps
1. Prepare
The first part of the upgrade process is to prepare for the upgrade.
- Setup for data migration ( keep settings ) and additional sysupgrade.conf entries
- Export / save installed package list / manifest
- Obtain / verify new installation sysupgrade image (and current / known good one to revert to)
This includes documenting programs and settings that will need to be re-installed or restored after the upgrade, locating and downloading the correct OpenWrt upgrade image for your hardware.
When it is possible to 'keep settings' sysupgrade will automatically preserve much of the OpenWrt OS configuration by saving and then restoring configuration files in specific common locations (including /etc/config
). This will preserve things like OpenWrt network settings, Wi-Fi settings, the device hostname, and so on. Some data files and directories for additional services will need to be configured manually.
2. Upgrade
Next is the actual upgrade. The two common upgrade methods to perform the upgrade are:
- LuCI web interface System → Backup / Flash Firmware → “Flash new firmware image”
- Command-line using
sysupgrade
command over console or ssh
Both use the same ...sysupgrade.bin/img.gz
file (more below).
3. Post Install Configuration, Setup or Restore
After the OS upgrade, there are usually some additional configuration steps required to;
- Re-install additional packages not part of the base OpenWrt install
- Configure new OpenWrt functionality or to
- Update configuration files to reflect new settings or updated packages
Please see the section below with more details.
Preparing for upgrade
Can you keep settings?
See also: Upgrade compatibility
Most of the time you can, jumping several versions, downgrading, if the release notes or upgrade message informs you it's not possible, then you will need to plan ahead of time and factor in the time and information required to re-apply some or most of your previous configuration manually.
- It is worthwhile not keeping settings once every 12-16 months
- Trying to get around the advice to start with new settings when needed can result in odd issues that can be difficult to troubleshoot
Will you need to revert?
A time may come when you attempt an upgrade and for whatever reason it is unsuccessful. Contingency planning is a good skill for anything in IT.
- Have you made a backup of your current settings? (for restoration to same or earlier OS versions)
- Do you have a copy of your current (pre-upgrade) OS version if you need to re-install? (both factory and sysupgrade or even vendor firmware may be required)
- Do you have a spare device in case things go pear shaped or you need much more time than expected?
Configure your backup
Follow Backup and restore, or skip this section if you do not want to preserve existing configuration.
Downloading the OpenWrt upgrade image
Getting the right image
In most cases, platforms that support sysupgrade, have a downloadable image labelled ...-sysupgrade.bin
...
- Images labelled “factory” or otherwise are generally not intended to be installed via an existing OpenWrt web interface.
- FIRMWARE SELECTOR https://firmware-selector.openwrt.org/
- SEARCH USING MODEL: Table of Hardware: Firmware downloads
- OFFICIAL DOWNLOAD PAGE: https://downloads.openwrt.org/releases/
OpenWrt on x86
For x86 use the same image you used to install OpenWrt as a sysupgrade image as well. So if you installed OpenWrt x86-64 openwrt-version-number-x86-64-combined-ext4.img.gz
you need to choose same image to do a sysupgrade if you installed Openwrt with openwrt-version-number-x86-64-combined-squashfs.img.gz
you need that image to do a firmware upgrade.
WARNING: Double check you have the exact model number and in some cases country... If in any doubt about compatibility, read instructions on your device page thoroughly. If your are still unsure ask on the Forum.
NOTE: Keep a copy of images you use, you never know if you may need them again and that may be difficult if your internet is down!
Upgrade procedure
For LuCI-based upgrades
See also: Upgrading OpenWrt firmware using LuCI
- Download the desired upgrade file to your PC using a web browser
- Proceed to the LuCI upgrade procedure, below
Web interface instructions
- Navigate to LuCI → System → Backup / Flash Firmware → Actions: Flash new firmware image.
- Click Choose File button to select firmware image.
- Click Flash image... to upload firmware image.
- Verify firmware image checksum and proceed.
- Wait until the router comes back online.
Command-line instructions
OpenWrt provides sysupgrade utility for firmware upgrade procedure.
- See CLI instructions page below:
For sysupgrade cli based upgrades
- Download the desired upgrade file to the local /tmp RAM drive on your OpenWrt system. The
/tmp
directory is stored in RAM (using tmpfs), not in the permanent flash storage.
# example downloading the OpenWrt 15.05 upgrade image for a TP-LINK TL-WR1043ND ver. 1.x router cd /tmp wget http://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/generic/openwrt-15.05-ar71xx-generic-tl-wr1043nd-v1-squashfs-sysupgrade.bin # check the integrity of the image file via md5sums (older images) wget http://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/generic/md5sums md5sum -c md5sums 2> /dev/null | grep OK # check the integrity of the image file via sha256sums wget http://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/generic/sha256sums sha256sum -c sha256sums 2> /dev/null | grep OK # the desired result is that the downloaded firmware filename is listed with "OK" afterwards #################################################### # Initiate sysupgrade with your desired options # by default ( no -n ) settings are kept #################################################### sysupgrade -v /tmp/openwrt-15.05-ar71xx-generic-tl-wr1043nd-v1-squashfs-sysupgrade.bin
NOTE: see extras at end of page for low memory device workarounds
Extras
Verify the new OS version
- In LuCI, go to Status > Overview to verify you are running the new OpenWrt release
- In SSH, the login banner has the release information
Upgrade installed packages
Follow: Upgrading packages
After the initial update, it is good to check for any updated packages released after the base OS firmware image was built.
Note that on a device with only 4MB of NVRAM, these updates may not fit – check free space first with df -h /
and ensure there is at least 600KB or so free.
Reinstall user-installed packages
See also: Preserving packages
After a successful upgrade, you will need to reinstall all previously installed and saved packages.
Configure user-installed packages
See also: Comparing configurations
The new package installations will have installed new, default versions of package configuration files.
If existing configuration files are in place, opkg displays a warning about this and saves the new configuration file versions under /etc/config/*-opkg
filenames.
The new package-provided config files should be compared with your older customized files to merge in any new options or changes of syntax.
The diff
tool is helpful for this.