Related pages:
Flash Layout: provides background on how OpenWrt uses device storage space
Upgrading OpenWrt firmware using CLI
Upgrading OpenWrt firmware using LuCI
Keep Settings and Upgrade Compatibility
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.
See this howto about extroot procedure.
For Dual Firmware Devices please consult your device page for additional information
Part 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.
Part 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).
Part 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.
NOTE: 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.
Preparing for upgrade
Can you keep settings?
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
See: Upgrade Compatibility for more information
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?
Saving/restoring user-installed packages
Opkg Extras
Set up Opkg extras and Hotplug extras to be able to use the following features:
Automatically identify user-removed and user-installed packages.
Save the resulting Opkg profile to
/etc/config/opkg
, which you can back up as usual.Automatically restore the profile if you keep settings, or you can restore it manually.
# Before upgradeopkg save# After upgradeopkg restore
Opkgscript
This is an alternative to opkgextras above.Copy opkgscript to your router.Ideally in a directory which will be preserved after flashing so you don't have to copy it again.Make it executable:
chmod +x /path/to/the/opkgscript.sh
Create a snapshot of the installed packages:
/path/to/the/opkgscript.sh -v write
By default the script will save the list in /etc/config/opkg.installed, which is preserved over flashing.When you log back in after the upgrade configure the internet connectivity, run and wait until it finished with the installation:
/path/to/the/opkgscript.sh -v install
For more examples see: Additional Package Export or Restore Methods
Configure your backup
Follow: Backup and restore
Based on the list of user-installed packages customize your backup configuration to save the files not included in the default list.Verify your backup configuration and ensure that all OpenWrt configurations and user data are going to be preserved.
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 full guide:
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:
Upgrading OpenWrt firmware using CLI
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 routercd /tmpwget 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/md5sumsmd5sum -c md5sums 2> /dev/null | grep OK# check the integrity of the image file via sha256sumswget http://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/generic/sha256sumssha256sum -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
Package upgrade warning
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.
Blindly upgrading packages (manually or via script) can lead you into all sorts of trouble.
Just because there is an updated version of a given package does not mean it should be installed or that it will function properly. Inform yourself before doing any upgrades to determine if it is safe to upgrade. Avoid upgrading core packages.
There are two ways to manage/install packages in OpenWrt: with the LuCI web interface Software menu (System > Software), and via the command line interface (CLI). Both methods invoke the same CLI opkg executable, and as of OpenWrt 19.07.0, the LuCI interface now has an 'Updates' tab with a listing of packages that have available upgrades. The LuCI Upgrade…
button performs the same opkg upgrade
command that is discussed in this article.The same warnings apply to upgrading packages using LuCI and the CLI.
Generally speaking, the use of opkg upgrade
is very highly discouraged. It should be avoided in almost all circ*mstances. In particular, bulk upgrading is very likely to result in major problems, but even upgrading individual packages may cause issues. It is also important to stress that this is distinctly different from the sysupgrade
path for upgrading OpenWrt releases (major versions as well as maintenance upgrades). opkg upgrade
will not update the OpenWrt version. Only sysupgrade
can do that. The two are not equivalent.
Unlike the 'big distros' of Linux, OpenWrt is optimized to run on systems with limited resources. This includes the opkg package manager, which does not have built-in ABI (Application Binary Interface) compatibility and kernel version dependencies verification. Although sometimes there may be no issues, there is no guarantee and the upgrade can result in various types of incompatibilities that can range from minor to severe, and it may be very difficult to troubleshoot. In addition, the opkg upgrade
process will consume flash storage space. Since it does not (and cannot) overwrite the original (stored in ROM), it must store the upgraded packages in the r/w overlay.
In the vast majority of cases, any security patches of significant importance/risk will be rapidly released in an official stable maintenance release to be upgraded using the sysupgrade
system. This is the recommended method for keeping up-to-date.
Those looking to be on the bleeding edge can consider using the snapshot releases, but should be mindful of the differences between stable and snapshot. Or, alternatively, build a custom image with the desired updated packages included in that image. The remaining users who still want to use opkg upgrade
should only do so with selected individual packages (do not bulk update, and do not blindly update) and they should be aware that problems may occur that could necessitate a complete reset-to-defaults to resolve.
If you're already having issues, or wish to 'undo' the upgraded packages: create a backup (optional; can be restored after the reset is complete) and then perform a reset to defaults (firstboot
).
If you do choose to upgrade packages, especially with a script, you have been warned. Don't complain on the forum, and be ready to deal with the consequences, troubleshooting, and resolution yourself.
Upgrade installed packages
Read the package upgrade warning and follow Opkg extras to upgrade installed packages.
Reinstall user-installed packages
After a successful upgrade, you will need to reinstall all previously installed and saved packages.Package configuration files should have been preserved due to steps above, but not the actual packages themselves.You can reinstall packages manually with Opkg, or follow the section Saving/restoring user-installed packages to automate the process.
Configure user-installed packages
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.
See CLI - Comparing New Package Config Options
Upgrade compatibility
In some cases it is not possible to 'keep settings' due to incompatibilities
See: Upgrade Compatibility
Legacy: LuCI flash_keep section of /etc/config/luci
LuCI has a separate set of settings for configuration files to be preserved, however it appears to be obsolete since OpenWrt 14.07 and should be ignored.
uci show luci.flash_keep
Device Low Memory Workarounds: /tmp is too small to hold the downloaded file
See CLI - Low Memory Workarounds
Additional Package Export or Restore Methods
fixme: these need their own page
Script by gsenna
Default packages attitude 12.09rc2 tplink 1043nd
# Save the scriptcat << "EOF" > /tmp/listuserpackages.shecho >&2 User-installed packages are the following:sed -ne '/^Package:[[:blank:]]*/ { s/// h}/user installed/ { g p}' /usr/lib/opkg/statusEOF# Run the scriptchmod +x /tmp/listuserpackages.sh/tmp/listuserpackages.sh
Note that the script may list several packages that are part of the default OpenWrt install and will have their changed configuration files automatically backed up and restored.In addition, packages installed as dependencies of other packages may show here.It is only important to note the names of packages that you directly installed manually.Any dependencies of these packages will automatically be reinstalled when the primary package is reinstalled.
Script by valentijn
# Save the scriptcat << "EOF" > /tmp/listuserpackages.awk#!/usr/bin/awk -f/^Package:/{PKG= $2}/^Status: .*user installed/{print PKG}EOF# Run the scriptchmod +x /tmp/listuserpackages.awk/tmp/listuserpackages.awk /usr/lib/opkg/status
This script will only output a list of user (and default) installed packages.
Script by tboege
Shows every package installed after the rom was build (flash_time), if no packages are depending on it.Packages, that are manually installed may be omitted, since one of the listed packages must depends of such a package, all manually installed packages will be installed, if the listed packages are installed:
cat << "EOF" > /tmp/listuserpackages.awk#!/usr/bin/awk -fBEGIN { ARGV[ARGC++] = "/usr/lib/opkg/status" cmd="opkg info busybox | grep '^Installed-Time: '" cmd | getline FLASH_TIME close(cmd) FLASH_TIME=substr(FLASH_TIME,17)}/^Package:/{PKG= $2}/^Installed-Time:/{ INSTALLED_TIME= $2 # Find all packages installed after FLASH_TIME if ( INSTALLED_TIME > FLASH_TIME ) { cmd="opkg whatdepends " PKG " | wc -l" cmd | getline WHATDEPENDS close(cmd) # If nothing depends on the package, it is installed by user if ( WHATDEPENDS == 3 ) print PKG }}EOF# Run the scriptchmod +x /tmp/listuserpackages.awk/tmp/listuserpackages.awk
Script by mforkel and Rafciq
Identify packages to be re-installed after system upgradeInformation herein that pertains to 17 or older releases and/or no longer generally advised.
Legacy scripts
This is an alternative to the script above.This command will list all packages related to any file in the whole file system that has changed from the default OpenWrt default version.
Note that the script may list several packages that are part of the default OpenWrt install and will have their changed configuration files automatically backed up and restored.In addition, packages installed as dependences of other packages may show here.It is only important to note the names of packages that you directly installed manually. Any dependencies of these packages will automatically be reinstalled when the primary package is reinstalled.
# OpenWrt 14.07 "Barrier Breaker" or earlierfind /overlay/ | while read -r FILE; do opkg search "${FILE#/overlay}"; done | sed -n -e "s/\s.*//p" | sort -u# OpenWrt 15.05 or laterfind /overlay/upper/ | while read -r FILE; do opkg search "${FILE#/overlay/upper}"; done | sed -n -e "s/\s.*//p" | sort -u
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies