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/21 01:12] – [Command-line instructions] 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: | ||
| + | * [[docs: | ||
| - | + | ===== How the OpenWrt upgrade works ===== | |
| - | ==== How the OpenWrt upgrade works ==== | + | |
| An OpenWrt **sysupgrade** will replace the entire current OpenWrt installation with a new version. | An OpenWrt **sysupgrade** will replace the entire current OpenWrt installation with a new version. | ||
| This includes the Linux kernel and SquashFS/ | This includes the Linux kernel and SquashFS/ | ||
| Line 20: | 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/ |
| - | For [[tag: | + | For [[tag: |
| - | ---- | + | By compiling your own custom image with an OpenWrt buildroot or generating with the imagebuilder, |
| - | + | ===== Upgrade steps ===== | |
| - | === Part 1 - Prepare === | + | ==== 1. Prepare |
| The first part of the upgrade process is to prepare for the upgrade. | The first part of the upgrade process is to prepare for the upgrade. | ||
| - | |||
| - Setup for data migration ( keep settings ) and additional sysupgrade.conf entries | - Setup for data migration ( keep settings ) and additional sysupgrade.conf entries | ||
| - Export / save installed package list / manifest | - Export / save installed package list / manifest | ||
| Line 38: | Line 37: | ||
| When it is possible to 'keep settings' | When it is possible to 'keep settings' | ||
| - | ---- | + | ==== 2. Upgrade ==== |
| - | + | Next is the actual upgrade. The two common upgrade methods to perform the upgrade are: | |
| - | + | ||
| - | === 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" | * LuCI web interface System -> Backup / Flash Firmware -> "Flash new firmware image" | ||
| * Command-line using '' | * Command-line using '' | ||
| - | Both use the same ' | + | Both use the same '' |
| - | + | ||
| - | ---- | + | |
| - | + | ||
| - | === Part 3 - Post Install Configuration, | + | |
| + | ==== 3. Post Install Configuration, | ||
| After the OS upgrade, there are usually some additional configuration steps required to; | After the OS upgrade, there are usually some additional configuration steps required to; | ||
| - | * re-install additional packages not part of the base OpenWrt install | + | * Re-install additional packages not part of the base OpenWrt install |
| - | * configure | + | * Configure |
| - | * update | + | * Update |
| Please see the section below with more details. | Please see the section below with more details. | ||
| - | |||
| - | ---- | ||
| - | |||
| - | NOTE: By compiling your own custom image with an OpenWrt buildroot or generating with the imagebuilder, | ||
| - | |||
| - | ---- | ||
| - | |||
| ===== Preparing for upgrade ===== | ===== Preparing for upgrade ===== | ||
| ==== Can you keep settings? ==== | ==== Can you keep settings? ==== | ||
| + | See also: | ||
| + | [[docs: | ||
| Most of the time you can, jumping several versions, downgrading, | Most of the time you can, jumping several versions, downgrading, | ||
| Line 76: | Line 62: | ||
| - Trying to get around the advice to start with new settings when needed can result in odd issues that can be difficult to troubleshoot | - 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: [[docs: | ||
| ==== Will you need to revert? ==== | ==== 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. | 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. | ||
| Line 84: | Line 68: | ||
| - 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 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? | - Do you have a spare device in case things go pear shaped or you need much more time than expected? | ||
| - | ==== Saving/ | ||
| - | === Opkg Extras === | ||
| - | :!: Set up [[docs: | ||
| - | * Automatically identify user-removed and user-installed packages. | ||
| - | * Save the resulting Opkg profile to ''/ | ||
| - | * Automatically restore the profile if you [[docs: | ||
| - | <code bash> | ||
| - | # Before upgrade | ||
| - | opkg save | ||
| - | |||
| - | # After upgrade | ||
| - | opkg restore | ||
| - | </ | ||
| - | |||
| - | === Opkgscript === | ||
| - | This is an alternative to opkgextras above. | ||
| - | Copy [[https:// | ||
| - | Ideally in a directory which will be preserved after flashing so you don't have to copy it again. | ||
| - | Make it executable: | ||
| - | |||
| - | <code bash> | ||
| - | chmod +x / | ||
| - | </ | ||
| - | |||
| - | Create a snapshot of the installed packages: | ||
| - | |||
| - | <code bash> | ||
| - | / | ||
| - | </ | ||
| - | |||
| - | By default the script will save the list in / | ||
| - | When you log back in after the upgrade configure the internet connectivity, | ||
| - | |||
| - | <code bash> | ||
| - | / | ||
| - | </ | ||
| - | |||
| - | |||
| - | For more examples see: [[docs: | ||
| ==== Configure your backup ==== | ==== Configure your backup ==== | ||
| - | Follow: [[docs: | + | {{section> |
| - | + | ||
| - | Based on the list of [[docs: | + | |
| - | Verify your backup configuration and ensure that all OpenWrt configurations and user data are going to be preserved. | + | |
| ==== 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 140: | Line 82: | ||
| === OpenWrt on x86 === | === 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 | + | 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 147: | Line 89: | ||
| 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! | 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 ===== | ===== Upgrade procedure ===== | ||
| - | |||
| ==== For LuCI-based upgrades ==== | ==== For LuCI-based upgrades ==== | ||
| - | See also full guide: | + | 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 | ||
| Line 170: | Line 110: | ||
| * See CLI instructions page below: | * See CLI instructions page below: | ||
| * [[docs: | * [[docs: | ||
| + | |||
| === For sysupgrade cli based upgrades === | === 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 187: | Line 128: | ||
| # the desired result is that the downloaded firmware filename is listed with " | # the desired result is that the downloaded firmware filename is listed with " | ||
| - | |||
| #################################################### | #################################################### | ||
| Line 194: | Line 134: | ||
| #################################################### | #################################################### | ||
| sysupgrade -v / | 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 | ||
| - | |||
| - | |||
| ===== Extras ===== | ===== Extras ===== | ||
| Line 207: | 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. | ||
| If existing configuration files are in place, opkg displays a warning about this and saves the new configuration file versions under ''/ | If existing configuration files are in place, opkg displays a warning about this and saves the new configuration file versions under ''/ | ||
| Line 227: | Line 165: | ||
| 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 new package-provided config files should be compared with your older customized files to merge in any new options or changes of syntax. | ||
| The '' | The '' | ||
| - | |||
| - | * See [[docs: | ||
| - | |||
| - | ===== Upgrade compatibility ===== | ||
| - | |||
| - | In some cases it is not possible to 'keep settings' | ||
| - | |||
| - | See: [[docs: | ||
| - | |||
| - | ==== 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: | ||
| - | * See [[docs: | ||
| - | |||
| - | ==== 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 / | ||
| - | </ | ||