Differences

This shows you the differences between two versions of the page.

Link to this comparison view

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] someothertimedocs: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:techref:flash.layout|Flash Layout]]: provides background on how OpenWrt uses device storage space+    * [[docs:techref:flash.layout|OpenWrt flash Layout]]
     * [[docs:guide-user:installation:sysupgrade.cli|Upgrading OpenWrt firmware using CLI]]     * [[docs:guide-user:installation:sysupgrade.cli|Upgrading OpenWrt firmware using CLI]]
     * [[docs:guide-quick-start:sysupgrade.luci|Upgrading OpenWrt firmware using LuCI]]     * [[docs:guide-quick-start:sysupgrade.luci|Upgrading OpenWrt firmware using LuCI]]
     * [[docs:guide-quick-start:admingui_sysupgrade_keepsettings#upgrade_compatibility|Keep Settings and Upgrade Compatibility]]     * [[docs:guide-quick-start:admingui_sysupgrade_keepsettings#upgrade_compatibility|Keep Settings and Upgrade Compatibility]]
 +    * [[docs:guide-user:installation:sysupgrade.packages|Saving/restoring user-installed packages]]
  
- +===== 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/ext4/ubifs/JFFS2/other OS partition/s. This is NOT the same as a first time installation (factory). 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).
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/sysupgrade-with-extroot.html|this howto]] about extroot procedure.+See [[https://web.archive.org/web/20220919082336/https://blog.mbirth.de/archives/2014/05/26/openwrt-sysupgrade-with-extroot.html|this howto]] about extroot procedure.
  
-For [[tag:dual_firmware|Dual Firmware Devices]] please consult your device page for additional information+For [[tag:dual_firmware|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 ===== 
-=== Part Prepare ===+===1Prepare ====
 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' 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. 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.
  
----- +===2Upgrade ==== 
- +Next is the actual upgrade. The two common upgrade methods to perform the upgrade are:
- +
-=== Part 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 ''sysupgrade'' command over console or ssh   * Command-line using ''sysupgrade'' command over console or ssh
  
-Both use the same '...sysupgrade.bin/img.gz' file (more below). +Both use the same ''...sysupgrade.bin/img.gz'' file (more below).
- +
----- +
- +
-=== Part 3 - Post Install Configuration, Setup or Restore ===+
  
 +==== 3. Post Install Configuration, Setup or Restore ====
 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 new OpenWrt functionality or to +  * Configure new OpenWrt functionality or to 
-  * update configuration files to reflect new settings or updated packages+  * Update configuration files to reflect new settings or updated packages
  
 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, it is possible to remove the need to perform many of the steps above. 
- 
----- 
- 
  
 ===== Preparing for upgrade ===== ===== Preparing for upgrade =====
 ==== Can you keep settings? ==== ==== Can you keep settings? ====
 +See also:
 +[[docs:guide-quick-start:admingui_sysupgrade_keepsettings#upgrade_compatibility|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. 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.
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:guide-user:installation:generic.sysupgrade#upgrade_compatibility|Upgrade Compatibility]] for more information 
 ==== 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/restoring user-installed packages ==== 
-=== Opkg Extras === 
-:!: Set up [[docs:guide-user:advanced:opkg_extras|Opkg extras]] and [[docs:guide-user:advanced:hotplug_extras|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 [[docs:guide-user:troubleshooting:backup_restore|back up]] as usual. 
-  * Automatically restore the profile if you [[docs:guide-quick-start:admingui_sysupgrade_keepsettings|keep settings]], or you can restore it manually. 
  
-<code bash> 
-# Before upgrade 
-opkg save 
- 
-# After upgrade 
-opkg restore 
-</code> 
- 
-=== Opkgscript === 
-This is an alternative to opkgextras above. 
-Copy [[https://github.com/richb-hanover/OpenWrtScripts/blob/master/opkgscript.sh|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: 
- 
-<code bash> 
-chmod +x /path/to/the/opkgscript.sh 
-</code> 
- 
-Create a snapshot of the installed packages: 
- 
-<code bash> 
-/path/to/the/opkgscript.sh -v write 
-</code> 
- 
-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: 
- 
-<code bash> 
-/path/to/the/opkgscript.sh -v install 
-</code> 
- 
- 
-For more examples see: [[docs:guide-user:installation:generic.sysupgrade#additional_package_export_or_restore_methods|Additional Package Export or Restore Methods]] 
 ==== Configure your backup ==== ==== Configure your backup ====
-Follow: [[docs:guide-user:troubleshooting:backup_restore|Backup and restore]] +{{section>docs:guide-user:installation:sysupgrade.cli#back_up_openwrt_configuration&noheader&nofooter&noeditbutton}}
- +
-Based on the list of [[docs:guide-user:installation:generic.sysupgrade#savingrestoring_user-installed_packages|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 ==== ==== 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 **''...-sysupgrade.bin''** ...
  
   * Images labelled "factory" or otherwise are generally not intended to be installed via an existing OpenWrt web interface.   * Images labelled "factory" or otherwise are generally not intended to be installed via an existing OpenWrt web interface.
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 **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.+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... 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:guide-quick-start:sysupgrade.luci|Upgrading OpenWrt firmware using LuCI]]+[[docs:guide-quick-start:sysupgrade.luci|Upgrading OpenWrt firmware using LuCI]]
  
   * 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:guide-user:installation:sysupgrade.cli|Upgrading OpenWrt firmware using CLI]]     * [[docs:guide-user:installation:sysupgrade.cli|Upgrading OpenWrt firmware using CLI]]
 +
 === 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 ''/tmp'' directory is stored in RAM (using [[wp>tmpfs]]), not in the permanent flash storage.   * Download the desired upgrade file to the local /tmp RAM drive on your OpenWrt system. The ''/tmp'' directory is stored in RAM (using [[wp>tmpfs]]), not in the permanent flash storage.
Line 187: Line 128:
  
 # the desired result is that the downloaded firmware filename is listed with "OK" afterwards # the desired result is that the downloaded firmware filename is listed with "OK" afterwards
- 
  
 #################################################### ####################################################
Line 194: Line 134:
 #################################################### ####################################################
 sysupgrade -v /tmp/openwrt-15.05-ar71xx-generic-tl-wr1043nd-v1-squashfs-sysupgrade.bin sysupgrade -v /tmp/openwrt-15.05-ar71xx-generic-tl-wr1043nd-v1-squashfs-sysupgrade.bin
- 
 </code> </code>
- 
  
 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:guide-user:additional-software:opkg#upgrading_packages|Upgrading packages]] 
 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 ''df -h /'' and ensure there is at least 600KB or so free. 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.
  
-{{page>meta:infobox:upgrade_packages_warning&noheader&nofooter&noeditbtn}}+==== Reinstall user-installed packages ==== 
 +See also: 
 +[[docs:guide-user:installation:sysupgrade.packages|Preserving packages]]
  
-==== Upgrade installed packages ==== 
-:!: Read the [[docs:guide-user:installation:generic.sysupgrade#package_upgrade_warning|package upgrade warning]] and follow [[docs:guide-user:advanced:opkg_extras|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. 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:guide-user:additional-software:opkg|Opkg]], or follow the section [[docs:guide-user:installation:generic.sysupgrade#savingrestoring_user-installed_packages|Saving/restoring user-installed packages]] to automate the process. 
  
 ==== Configure user-installed packages ==== ==== Configure user-installed packages ====
 +See also:
 +[[docs:guide-user:installation:sysupgrade.cli#comparing_new_package_config_options|Comparing configurations]]
 +
 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 ''/etc/config/*-opkg'' filenames. 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.
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 ''diff'' tool is helpful for this. The ''diff'' tool is helpful for this.
- 
-  * See [[docs:guide-user:installation:sysupgrade.cli#comparing_new_package_config_options|CLI - Comparing New Package Config Options]] 
- 
-===== Upgrade compatibility ===== 
- 
-In some cases it is not possible to 'keep settings' due to incompatibilities 
- 
-See: [[docs:guide-quick-start:admingui_sysupgrade_keepsettings#upgrade_compatibility|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. 
- 
-<code bash> 
-uci show luci.flash_keep 
-</code> 
- 
-==== Device Low Memory Workarounds: /tmp is too small to hold the downloaded file ==== 
-  * See [[docs:guide-user:installation:sysupgrade.cli#low_memory_workaroundstmp_is_too_small_to_hold_the_downloaded_file|CLI - Low Memory Workarounds]] 
- 
-==== Additional Package Export or Restore Methods ==== 
- 
-fixme: these need their own page 
- 
-=== Script by gsenna === 
-[[https://forum.openwrt.org/viewtopic.php?id=43480|Default packages attitude 12.09rc2 tplink 1043nd]] 
- 
-<code bash> 
-# Save the script 
-cat << "EOF" > /tmp/listuserpackages.sh 
-echo >&2 User-installed packages are the following: 
-sed -ne '/^Package:[[:blank:]]*/ { 
-    s/// 
-    h 
-} 
-/user installed/ { 
-    g 
-    p 
-}' /usr/lib/opkg/status 
-EOF 
- 
-# Run the script 
-chmod +x /tmp/listuserpackages.sh 
-/tmp/listuserpackages.sh 
-</code> 
- 
-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 << "EOF" > /tmp/listuserpackages.awk 
-#!/usr/bin/awk -f 
-/^Package:/{PKG= $2} 
-/^Status: .*user installed/{print PKG} 
-EOF 
- 
-# Run the script 
-chmod +x /tmp/listuserpackages.awk 
-/tmp/listuserpackages.awk /usr/lib/opkg/status 
-</code> 
- 
-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: 
- 
-<code bash> 
-cat << "EOF" > /tmp/listuserpackages.awk 
-#!/usr/bin/awk -f 
-BEGIN { 
-    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 script 
-chmod +x /tmp/listuserpackages.awk 
-/tmp/listuserpackages.awk 
-</code> 
- 
-=== Script by mforkel and Rafciq === 
-[[https://forum.openwrt.org/viewtopic.php?id=42739|Identify packages to be re-installed after system upgrade]] 
-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 "Barrier Breaker" or earlier 
-find /overlay/ | while read -r FILE; do opkg search "${FILE#/overlay}"; done | sed -n -e "s/\s.*//p" | sort -u 
- 
-# OpenWrt 15.05 or later 
-find /overlay/upper/ | while read -r FILE; do opkg search "${FILE#/overlay/upper}"; done | sed -n -e "s/\s.*//p" | sort -u 
-</code> 
  
  • Last modified: 2024/10/19 20:05
  • by efahlgren