Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| docs:guide-user:installation:generic.sysupgrade [2021/09/03 08:16] – [Command-line instructions] link to CLI page someothertime | docs:guide-user:installation:generic.sysupgrade [2023/01/18 10:38] – [Can you keep settings?] update link vgaetera | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Upgrading OpenWrt firmware using LuCI and CLI ====== | ====== Upgrading OpenWrt firmware using LuCI and CLI ====== | ||
| - | * Related pages: | + | See also: |
| - | * [[docs: | + | * [[docs: |
| * [[docs: | * [[docs: | ||
| * [[docs: | * [[docs: | ||
| + | * [[docs: | ||
| + | * [[docs: | ||
| - | An OpenWrt **upgrade** will replace the entire current OpenWrt installation with a new version. | + | ===== How the OpenWrt upgrade works ===== |
| - | This includes the Linux kernel, the SquashFS partition | + | An OpenWrt **sysupgrade** will replace the entire current OpenWrt installation with a new version. |
| + | This includes the Linux kernel and SquashFS/ | ||
| - | The common upgrade paths below will automatically preserve much of the OpenWrt OS configuration by saving and then restoring configuration files in specific common locations (including ''/ | + | Sysupgrade via LuCI or CLI works by optionally |
| - | This will preserve things like OpenWrt network settings, Wi-Fi settings, the device hostname, and so on. | + | |
| - | + | ||
| - | The first part of the upgrade process is to prepare for the upgrade. | + | |
| - | 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. | + | |
| - | + | ||
| - | Next is the actual upgrade. | + | |
| - | There are two common upgrade paths to actually perform the upgrade. | + | |
| - | One uses the LuCI web interface "Flash new firmware image" command and one uses the command-line '' | + | |
| - | You can use either approach. | + | |
| - | + | ||
| - | After the OS upgrade, there are usually some additional configuration steps required to re-install additional packages not part of the base OpenWrt install, to configure new OpenWrt functionality | + | |
| - | Please see the section below with more details. | + | |
| - | + | ||
| - | ===== Preparing for upgrade ===== | + | |
| - | ==== How the OpenWrt upgrade | + | |
| - | Both the LuCI and sysupgrade upgrade procedures work by 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.** | **This means that any parts of the file system that are not specifically saved will be lost.** | ||
| Line 33: | Line 20: | ||
| Be sure to check any files you have added or customized from a default OpenWrt install to back up these items before an 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 [[https://wiki.mbirth.de/know-how/software/openwrt/ | + | See [[https://web.archive.org/ |
| - | ==== Will you need to revert? ==== | + | For [[tag: |
| - | A time may come when you attempt | + | By compiling your own custom image with an OpenWrt buildroot or generating with the imagebuilder, |
| - | - Have you made a backup of your current settings? (for restoration to same or earlier OS versions) | + | ===== Upgrade steps ===== |
| - | - 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) | + | ==== 1. Prepare |
| - | - Do you have a spare device in case things go pear shaped or you need much more time than expected? | + | The first part of the upgrade process is to prepare for the upgrade. |
| - | ==== Saving/ | + | - Setup for data migration ( keep settings ) and additional sysupgrade.conf entries |
| - | :!: Set up [[docs: | + | |
| - | | + | - Obtain / verify new installation sysupgrade image (and current / known good one to revert to) |
| - | | + | |
| - | | + | |
| - | <code bash> | + | 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. |
| - | opkg save | + | |
| - | opkg restore | + | |
| - | </ | + | |
| - | ==== Alternatives | + | When it is possible |
| - | === Opkgscript === | + | |
| - | Copy [[https://github.com/richb-hanover/ | + | |
| - | Ideally in a directory which will be preserved after flashing so you don't have to copy it again. | + | |
| - | Make it executable: | + | |
| - | <code bash> | + | ==== 2. Upgrade ==== |
| - | chmod +x /path/to/the/ | + | Next is the actual upgrade. The two common upgrade methods |
| - | </code> | + | * LuCI web interface System -> Backup |
| + | * Command-line using '' | ||
| - | Create a snapshot of the installed packages: | + | Both use the same '' |
| - | <code bash> | + | ==== 3. Post Install Configuration, |
| - | /path/to/the/ | + | 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 | ||
| - | By default | + | Please see the section below with more details. |
| - | When you log back in after the upgrade configure the internet connectivity, | + | |
| - | <code bash> | + | ===== Preparing for upgrade ===== |
| - | / | + | ==== Can you keep settings? ==== |
| - | </ | + | See also: |
| + | [[docs: | ||
| + | Most of the time you can, jumping several versions, downgrading, | ||
| + | - 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 | ||
| - | ==== Configure your backup | + | ==== Will you need to revert? |
| - | Follow: [[docs: | + | A time may come when you attempt an upgrade |
| - | Based on the list of [[docs: | + | - Have you made a backup |
| - | Verify your backup configuration and ensure that all OpenWrt configurations and user data are going to be preserved. | + | - 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 ==== | ||
| + | {{section> | ||
| - | === 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. | ||
| ==== Downloading the OpenWrt upgrade image ==== | ==== Downloading the OpenWrt upgrade image ==== | ||
| === Getting the right image === | === Getting the right image === | ||
| - | In most cases, platforms that support sysupgrade, have a downloadable image labelled **"...-sysupgrade.bin"** ... | + | In most cases, platforms that support sysupgrade, have a downloadable image labelled **'' |
| * Images labelled " | * Images labelled " | ||
| Line 94: | Line 80: | ||
| * SEARCH USING MODEL: [[toh: | * SEARCH USING MODEL: [[toh: | ||
| * OFFICIAL DOWNLOAD PAGE: [[https:// | * OFFICIAL DOWNLOAD PAGE: [[https:// | ||
| + | |||
| + | === 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 '' | ||
| WARNING: Double check you have the exact model number and in some cases country... | WARNING: Double check you have the exact model number and in some cases country... | ||
| Line 99: | Line 88: | ||
| If your are still unsure ask on the Forum. | If your are still unsure ask on the Forum. | ||
| - | === For LuCI-based upgrades === | + | 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: | ||
| + | [[docs: | ||
| * Download the desired upgrade file to your PC using a web browser | * Download the desired upgrade file to your PC using a web browser | ||
| * Proceed to the LuCI upgrade procedure, below | * Proceed to the LuCI upgrade procedure, below | ||
| - | === For sysupgrade-based upgrades === | + | === 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. | ||
| + | - [[docs: | ||
| + | - Wait until the router comes back online. | ||
| + | |||
| + | ==== Command-line instructions ==== | ||
| + | OpenWrt provides [[docs: | ||
| + | |||
| + | * See CLI instructions page below: | ||
| + | * [[docs: | ||
| + | |||
| + | === For sysupgrade cli based upgrades === | ||
| * Download the desired upgrade file to the local /tmp RAM drive on your OpenWrt system. The ''/ | * Download the desired upgrade file to the local /tmp RAM drive on your OpenWrt system. The ''/ | ||
| Line 111: | Line 119: | ||
| wget http:// | wget http:// | ||
| - | # check the integrity of the image file | + | # check the integrity of the image file via md5sums |
| - | # via md5sums | + | |
| wget http:// | wget http:// | ||
| - | # via sha256sums | ||
| - | wget http:// | ||
| - | # the desired result is that the downloaded firmware filename is listed with " | ||
| - | # via md5sums | ||
| md5sum -c md5sums 2> /dev/null | grep OK | md5sum -c md5sums 2> /dev/null | grep OK | ||
| - | # via sha256sums | + | |
| + | # check the integrity of the image file via sha256sums | ||
| + | wget http:// | ||
| sha256sum -c sha256sums 2> /dev/null | grep OK | sha256sum -c sha256sums 2> /dev/null | grep OK | ||
| - | </ | ||
| - | * Proceed to the " | + | # the desired |
| - | 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! | + | #################################################### |
| + | # Initiate sysupgrade with your desired options | ||
| + | # by default ( no -n ) settings are kept | ||
| + | #################################################### | ||
| + | sysupgrade -v / | ||
| + | </ | ||
| NOTE: see extras at end of page for low memory device workarounds | NOTE: see extras at end of page for low memory device workarounds | ||
| - | |||
| - | ===== Upgrade procedure ===== | ||
| - | ==== 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. | ||
| - | - [[docs: | ||
| - | - Wait until the router comes back online. | ||
| - | |||
| - | ==== Command-line instructions ==== | ||
| - | OpenWrt provides [[docs: | ||
| - | |||
| - | * See CLI instructions page below: | ||
| - | * [[docs: | ||
| ===== Extras ===== | ===== Extras ===== | ||
| ==== Verify the new OS version ==== | ==== Verify the new OS version ==== | ||
| Line 148: | Line 143: | ||
| * In SSH, the login banner has the release information | * In SSH, the login banner has the release information | ||
| - | ==== Package upgrade warning | + | ==== Upgrade installed packages |
| + | Follow: | ||
| + | [[docs: | ||
| After the initial update, it is good to check for any updated packages released after the base OS firmware image was built. | 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 '' | Note that on a device with only 4MB of NVRAM, these updates may not fit – check free space first with '' | ||
| - | {{page> | + | ==== Reinstall user-installed packages ==== |
| + | See also: | ||
| + | [[docs:guide-user: | ||
| - | ==== Upgrade installed packages ==== | ||
| - | :!: Read the [[docs: | ||
| - | |||
| - | ==== Reinstall user-installed packages ==== | ||
| After a successful upgrade, you will need to reinstall all previously installed and saved 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 [[docs: | ||
| ==== Configure user-installed packages ==== | ==== Configure user-installed packages ==== | ||
| + | See also: | ||
| + | [[docs: | ||
| + | |||
| The new package installations will have installed new, default versions of package configuration files. | The new package installations will have installed new, default versions of package configuration files. | ||
| - | As your existing configuration files were already | + | If existing configuration files are in place, opkg displays |
| - | The new package-provided | + | The new package-provided |
| The '' | The '' | ||
| - | |||
| - | :!: Set up [[docs: | ||
| - | |||
| - | <code bash> | ||
| - | # Install packages | ||
| - | opkg update | ||
| - | opkg install diffutils | ||
| - | |||
| - | # Find new configurations | ||
| - | opkg newconf | ||
| - | |||
| - | # Compare UCI configurations | ||
| - | uci diff snmpd | ||
| - | |||
| - | # Merge needed changes to the current version | ||
| - | vi / | ||
| - | rm / | ||
| - | |||
| - | # Or replace the current version with the new one | ||
| - | mv / | ||
| - | |||
| - | # Apply new configuration | ||
| - | / | ||
| - | </ | ||
| - | |||
| - | ===== Upgrade compatibility ===== | ||
| - | //**The following section only applies if image metadata is used for the upgrade process.**// | ||
| - | |||
| - | We regularly encounter the situation that devices are subject to changes that will make them incompatible to previous versions. | ||
| - | This typically happens when the setup of a device has changed in a way so that the configuration cannot be migrated or filesystem changes won't allow sysupgrade. | ||
| - | |||
| - | Since August 2020 (20.xx release), an additional mechanism will make sure that users are warned when upgrading between incompatible versions like that. | ||
| - | |||
| - | The is achieved by a compatibility version number that is stored on the device and the images. | ||
| - | The compat-version is built from a major revision x and a minor revision y: **x.y** | ||
| - | |||
| - | For all devices and image before the introduction, | ||
| - | The value is assigned for individual devices, so it does not tell anything about the general revision of OpenWrt. | ||
| - | |||
| - | If an incompatible change is introduced, one can increase either the minor version (1.0-> | ||
| - | |||
| - | **Minor version increment: | ||
| - | |||
| - | This will still allow sysupgrade, but require to reset config (uncheck "Keep Settings", | ||
| - | If sysupgrade is called without, a corresponding message will be printed. | ||
| - | If sysupgrade is called and settings are reset, it will just pass, with supported devices being checked as usual. | ||
| - | |||
| - | **Major version increment: | ||
| - | |||
| - | This is meant for potential (rare) cases where sysupgrade is not possible at all, because it would " | ||
| - | In this case, a warning will be printed, and resetting config ('' | ||
| - | You will need to research instructions on how to proceed. | ||
| - | |||
| - | Typically, in addition to the increment of the compatibility version, developers will also specify a message to be printed with the warnings above giving a first hint about the problem. | ||
| - | |||
| - | ==== Forcing upgrade ==== | ||
| - | In any case, upgrade can still be forced ('' | ||
| - | |||
| - | If you do that, please note that the compatibility version on the device is a property of the config, i.e. the value is stored in uci: '' | ||
| - | |||
| - | Consequently, | ||
| - | |||
| - | <code bash> | ||
| - | uci set system.@system[0].compat_version=" | ||
| - | uci commit system | ||
| - | </ | ||
| - | |||
| - | ==== Backward compatibility ==== | ||
| - | As stated above, all devices and images without compat-version set will be treated as " | ||
| - | |||
| - | However, the new compat-version-aware upgrade mechanism will only be available on devices flashed after that point. | ||
| - | |||
| - | For older devices, the metadata in new images has been altered to provide a similar experience for incremented compat-version: | ||
| - | |||
| - | On those devices, when upgrading into an " | ||
| - | However, upgrade has to be forced in all cases ('' | ||
| - | Make sure to also reset config in addition to the " | ||
| - | The only exception applies to early DSA-adopters, | ||
| - | Details are found in " | ||
| - | |||
| - | ==== Implementation details ==== | ||
| - | //**This section is focussed on developers wanting to implement compat-version after introducing an incompatible change.**// | ||
| - | |||
| - | Setup consists of two parts: | ||
| - | |||
| - | === Image metadata === | ||
| - | To set the version of an image, which is checked against the locally installed OpenWrt config version, the variables DEVICE_COMPAT_VERSION and DEVICE_COMPAT_MESSAGE may be added to a device definition: | ||
| - | |||
| - | <code bash> | ||
| - | define Device/ | ||
| - | ... | ||
| - | DEVICE_COMPAT_VERSION := 1.1 | ||
| - | DEVICE_COMPAT_MESSAGE := Config cannot be migrated from swconfig to DSA | ||
| - | endef | ||
| - | </ | ||
| - | |||
| - | The DEVICE_COMPAT_VERSION is mandatory for any value other than " | ||
| - | The DEVICE_COMPAT_MESSAGE is optional and should be used to provide a hint about the problem and/or possibly measures for the user. | ||
| - | |||
| - | === Device config === | ||
| - | Beyond the image metadata, the compat-version also needs to be available on the running device, so it can be compared against any images. | ||
| - | |||
| - | Like for the LED/network setup, this will be achieved by a command " | ||
| - | |||
| - | <code bash> | ||
| - | ucidef_set_compat_version " | ||
| - | </ | ||
| - | |||
| - | During // | ||
| - | |||
| - | By this, the compat_version, | ||
| - | |||
| - | Therefore, the on-device compat-version is a property of the config, not of the installation. | ||
| - | Consequently, | ||
| - | |||
| - | ==== Legacy: LuCI flash_keep section of / | ||
| - | 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. | ||
| - | |||
| - | <code bash> | ||
| - | uci show luci.flash_keep | ||
| - | </ | ||
| - | |||
| - | ==== Device Low Memory Workarounds: | ||
| - | If your device' | ||
| - | |||
| - | First check memory usage with the '' | ||
| - | |||
| - | <code bash> | ||
| - | # free | ||
| - | | ||
| - | Mem: | ||
| - | -/+ buffers: | ||
| - | Swap: 0 0 0 | ||
| - | </ | ||
| - | |||
| - | In this example there are precisely 11416 KiB of RAM unused. | ||
| - | All the rest 32768 - 11416 = 21352 KiB are used somehow and a portion of it can and will be made available by the kernel, if it be needed, the problem is, we do not know how much exactly that is. | ||
| - | Make sure //enough// is available. | ||
| - | Free space in /tmp also counts towards free memory. | ||
| - | Therefore with: | ||
| - | |||
| - | <code bash> | ||
| - | # free | ||
| - | Mem: | ||
| - | Swap: 0 0 0 | ||
| - | Total: | ||
| - | |||
| - | # df | ||
| - | Filesystem | ||
| - | / | ||
| - | tmpfs | ||
| - | tmpfs 512 | ||
| - | / | ||
| - | mini_fo:/ | ||
| - | </ | ||
| - | |||
| - | One has actually 752+6636 KiB of free memory available. | ||
| - | |||
| - | * quickest and safest way to free up, some RAM is to delete the package lists: | ||
| - | |||
| - | <code bash> | ||
| - | rm -r / | ||
| - | </ | ||
| - | |||
| - | * drop caches: | ||
| - | |||
| - | <code bash> | ||
| - | sync && echo 3 > / | ||
| - | </ | ||
| - | |||
| - | * prevent wireless drivers to be loaded at next boot and then reboot: | ||
| - | |||
| - | <code bash> | ||
| - | rm / | ||
| - | rm / | ||
| - | rm / | ||
| - | reboot | ||
| - | </ | ||
| - | |||
| - | The wireless drivers, usually take up quite some amount of RAM and are not required (unless you are connected via wireless of course ;-)), so an easy way to free up some RAM is to delete the symlinks in '' | ||
| - | |||
| - | ==== Additional Package Export or Restore Methods ==== | ||
| - | |||
| - | fixme: these need their own page | ||
| - | |||
| - | === Script by gsenna === | ||
| - | [[https:// | ||
| - | |||
| - | <code bash> | ||
| - | # Save the script | ||
| - | cat << " | ||
| - | echo >&2 User-installed packages are the following: | ||
| - | sed -ne '/ | ||
| - | s/// | ||
| - | h | ||
| - | } | ||
| - | /user installed/ { | ||
| - | g | ||
| - | p | ||
| - | }' / | ||
| - | EOF | ||
| - | |||
| - | # Run the script | ||
| - | chmod +x / | ||
| - | / | ||
| - | </ | ||
| - | |||
| - | 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 === | ||
| - | <code bash> | ||
| - | # Save the script | ||
| - | cat << " | ||
| - | # | ||
| - | / | ||
| - | /^Status: .*user installed/ | ||
| - | EOF | ||
| - | |||
| - | # Run the script | ||
| - | chmod +x / | ||
| - | / | ||
| - | </ | ||
| - | |||
| - | 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), | ||
| - | 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: | ||
| - | |||
| - | <code bash> | ||
| - | cat << " | ||
| - | # | ||
| - | BEGIN { | ||
| - | ARGV[ARGC++] = "/ | ||
| - | cmd=" | ||
| - | cmd | getline FLASH_TIME | ||
| - | close(cmd) | ||
| - | FLASH_TIME=substr(FLASH_TIME, | ||
| - | } | ||
| - | / | ||
| - | / | ||
| - | INSTALLED_TIME= $2 | ||
| - | # Find all packages installed after FLASH_TIME | ||
| - | if ( INSTALLED_TIME > FLASH_TIME ) { | ||
| - | cmd=" | ||
| - | cmd | getline WHATDEPENDS | ||
| - | close(cmd) | ||
| - | # If nothing depends on the package, it is installed by user | ||
| - | if ( WHATDEPENDS == 3 ) print PKG | ||
| - | } | ||
| - | } | ||
| - | EOF | ||
| - | |||
| - | # Run the script | ||
| - | chmod +x / | ||
| - | / | ||
| - | </ | ||
| - | |||
| - | === Script by mforkel and Rafciq === | ||
| - | [[https:// | ||
| - | Information 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. | ||
| - | |||
| - | <code bash> | ||
| - | # OpenWrt 14.07 " | ||
| - | find /overlay/ | while read -r FILE; do opkg search " | ||
| - | |||
| - | # OpenWrt 15.05 or later | ||
| - | find / | ||
| - | </ | ||