使用LuCI和CLI允许OpenWrt固件

• Related pages:
  • Flash Layout: provides background on how OpenWrt uses device storage space
  • Upgrading OpenWrt firmware using CLI
  • Upgrading OpenWrt firmware using LuCI

这些命令是最重要对允许升级固件。

1，基本升级，保留设置。

sysupgrade /tmp/firmware.bin

2，基本升级，不保留设置。

sysupgrade -n /tmp/firmware.bin

高级升级，使用这个方法如果要安装固件对路由器不在支持的设备列表里。错误信息是：

Device: 《您的设备的名》not supported by this image.  
...
Image check 'fwtool_check_image' failed.

仅在完全确定图像兼容或不关心是否损坏设备的情况下，才使用此方法。

命令差一样的，只加一个-F，F的意思是“强迫”，英文是“Force“.

sysupgrade -F -n /tmp/firmware.bin

如果您的OpenWrt固件有《scp》命令，您可以使用它下载新固件。这些命令下载新固件，放他在RAM里（/tmp/)，和开始安装的固件。您得换：用户名（user），服务器名成（your.server.net），和文件路径（/path/to/firmware.bin)所以匹配您自己的。

scp user@your.server.net:/path/to/firmware.bin /tmp/firmware.bin
sysupgrade -n /tmp/firmware.bin

An OpenWrt upgrade will replace the entire current OpenWrt installation with a new version. This includes the Linux kernel, the SquashFS partition and the JFFS2 partition. This is NOT the same as a first time installation.

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 /etc/config). 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 sysupgrade command. Both use the same '...sysupgrade.bin' upgrade file (more below). 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 or to update configuration files to reflect new settings or updated packages. Please see the section below with more details.

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.

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.

Enable additional Opkg functions to be able to use the following commands.

opkg_backup

This function uses the code from sysupgrade.

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 login back after the upgrade configure the internet connectivity, run and wait until it finished with the installation:

/path/to/the/opkgscript.sh -v install

and was originally posted in the forum discussion “Default packages attitude 12.09rc2 tplink 1043nd” at https://forum.openwrt.org/viewtopic.php?id=43480

# 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

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.

# 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

This script will only output a list of user (and default) installed packages.

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 -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

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 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

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.

For x86 systems there is no “sysupgrade” image, just be sure to use the new firmware image has the same family of filesystem (if the current firmware uses squashfs then the new will use squashfs as well and if the current has ext the new will use ext filesystem. Note that an upgrade from ext2 [10.03.1] to ext4 [12.09] seems not working. Tested 10.03.1 squashfs to 12.09 squashfs, working ; 10.03.1 squashfs to 12.09 ext4 failed; 10.03.1 ext2 to 12.09 ext4 failed)

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.
  • SEARCH USING MODEL: Table of Hardware: Firmware downloads
  • OFFICIAL DOWNLOAD PAGE: https://downloads.openwrt.org/releases/

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.

• Download the desired upgrade file to your PC using a web browser
• Proceed to the LuCI upgrade procedure, below

• 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
wget http://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/generic/md5sums
# via sha256sums
wget http://downloads.openwrt.org/chaos_calmer/15.05/ar71xx/generic/sha256sums
# the desired result is that the downloaded firmware filename is listed with "OK" afterwards
# via md5sums
md5sum -c md5sums 2> /dev/null | grep OK
# via sha256sums
sha256sum -c sha256sums 2> /dev/null | grep OK

• Proceed to the “Ensure desired configuration files will be saved” section, above

If your device's /tmp filesystem is not large enough to store the OpenWrt upgrade image, this section provides tips to temporarily free up RAM.

First check memory usage with the free or top or cat /proc/meminfo commands; proceed if you have as much free RAM as the image is in size plus an some additional MiB of free memory.

# free
             total         used         free       shared      buffers
Mem:         29540        18124        **11416**         0         1248
-/+ buffers:              16876        12664
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:

# free
Mem:         13388        12636          752            0         1292
Swap:            0            0            0
Total:       13388        12636          752
 
# df
Filesystem           1K-blocks      Used Available Use% Mounted on
/dev/root                 2304      2304         0 100% /rom
tmpfs                     6696        60      6636   1% /tmp
tmpfs                      512         0       512   0% /dev
/dev/mtdblock3             576       288       288  50% /overlay
mini_fo:/overlay          2304      2304         0 100% /

One has actually 752+6636 KiB of free memory available.

• quickest and safest way to free up, some RAM is to delete the opkg packages file:

rm -r /tmp/opkg-lists/

• drop caches:

sync && echo 3 > /proc/sys/vm/drop_caches

• prevent wireless drivers to be loaded at next boot and then reboot:

rm /etc/modules.d/*80211*
rm /etc/modules.d/*ath9k*
rm /etc/modules.d/b43*
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 etc/modules.d so these are not loaded into memory at the next reboot.

1. Navigate to LuCI → System → Backup / Flash Firmware → Actions: Flash new firmware image.
2. Click Choose File button to select firmware image.
3. Click Flash image... to upload firmware image.
4. Verify firmware image checksum and proceed.
5. Wait until the router comes back online.

OpenWrt provides sysupgrade utility for firmware upgrade procedure.

Verify firmware image checksum. Verify the router has enough free RAM. Upload the firmware from local PC. Flash the firmware.

# Check the free RAM 
free
 
# Upload firmware
scp firmware_image.bin root@openwrt.lan:/tmp
 
# Flash firmware
sysupgrade -v /tmp/firmware_image.bin

If sysupgrade is not available.

# Flash firmware
mtd -r write /tmp/firmware_image.bin firmware

If free RAM is limited.

# Upload and flash firmware
cat firmware_image.bin | ssh root@openwrt.lan mtd write - firmware

• The sysupgrade verbose-option should give some output similar to this. The list of configuration files saved will change depending on what packages you have installed and which files you have configured to be saved, as per above.

Saving config files...
etc/config/dhcp
etc/config/dropbear
etc/config/firewall
etc/config/luci
etc/config/network
etc/config/snmpd
etc/config/system
etc/config/ubootenv
etc/config/ucitrack
etc/config/uhttpd
etc/config/wireless
etc/dropbear/authorized_keys
etc/dropbear/dropbear_dss_host_key
etc/dropbear/dropbear_rsa_host_key
etc/firewall.user
etc/group
etc/hosts
etc/inittab
etc/passwd
etc/profile
etc/rc.local
etc/shadow
etc/shells
etc/sudoers
etc/sudoers.d/custom
etc/sysctl.conf
etc/sysupgrade.conf
killall: watchdog: no process killed
Sending TERM to remaining processes ... ubusd askfirst logd logread netifd odhcpd snmpd uhttpd ntpd dnsmasq
Sending KILL to remaining processes ... askfirst
Switching to ramdisk...
Performing system upgrade...
Unlocking firmware ...

Writing from <stdin> to firmware ...  [w]
Appending jffs2 data from /tmp/sysupgrade.tgz to firmware...TRX header not found
Error fixing up TRX header
Upgrade completed
Rebooting system...

Note: The “TRX header not found” and “Error fixing up TRX header” errors are not a problem as per OpenWrt developer jow's post at https://dev.openwrt.org/ticket/8623

• Wait until the router comes back online
• After the automatic reboot, the system should come up the same configuration settings as before: the same network IP addresses, same SSH password, etc.
• Proceed to the “Additional configuration after an OpenWrt upgrade” section, below

In case it does not help, try a cold reset (= interrupt the electrical current to the device, wait a couple of seconds and then connect it again). Be careful about /etc/opkg.conf as explained here. For unknown reasons such a cold reset has often been reported to be necessary after a sysupgrade. This is very very bad in case you performed this remotely.

• In LuCI, go to Status > Overview to verify you are running the new OpenWrt release
• In SSH, the login banner has the release information

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.

Read the package upgrade warning and enable additional Opkg functions to be able to use the following commands.

# Update package lists
opkg update
 
# Show upgradable packages
opkg list-upgradable
 
# Upgrade overlay packages
opkg_upgrade_all overlay
 
# Upgrade all packages
opkg_upgrade_all
 
# Verify no more packages can be upgraded
opkg list-upgradable

After a successful upgrade, you will need to reinstall all previously installed packages. You made a list of these above. Package configuration files should have been preserved due to steps above, but not the actual packages themselves.

• Restore pre-upgrade packages “automagically”

Enable additional Opkg functions to be able to use the following commands.

If you have used sysupgrade -k you should be able to restore all packages:

# Update package lists
opkg update
 
# Import Opkg configuration from sysupgrade backup
opkg_import
 
# Install missing packages from the list
opkg_restore
 
# Install packages on devices with no overlay
opkg_restore rwm
 
# Add packages to the custom list
uci add_list opkg.custom.pkg="tor"
uci add_list opkg.custom.pkg="wireguard"
uci commit opkg
 
# Install packages from the custom list
opkg_restore custom

• Install packages manually

opkg update
opkg install snmpd-static

The new package installations will have installed new, default versions of package configuration files. As your existing configuration files were already in place, opkg would have displayed a warning about this and saved the new configuration file versions under ...-opkg filenames.

The new package-provided configuration files should be compared with your older customized files to merge in any new options or changes of syntax in these files. The diff tool is helpful for this.

Enable additional Opkg functions and additional UCI functions to be able to use the following commands.

# 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 /etc/config/snmpd
rm /etc/config/snmpd-opkg
 
# Or replace the current version with the new one
mv /etc/config/snmpd-opkg /etc/config/snmpd
 
# Apply new configuration
/etc/init.d/snmpd restart

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 default value “1.0” is assumed. 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→1.1) or the major version (1.0→2.0).

Minor version increment:

This will still allow sysupgrade, but require to reset config (uncheck “Keep Settings”, run sysupgrade with -n or SAVE_CONFIG=0). 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 “break” the device. In this case, a warning will be printed, and resetting config (sysupgrade -n) won't help. 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 which be printed with the warnings above and give a first hint about the problem.

In any case, upgrade can still be forced (sysupgrade -F) as usual, but then you will obviously run into the very problem the mechanism tries to save you from.

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: system.@system[0].compat_version

Consequently, as a forced update won't reset your config, it also won't bump your compat-version, and you will have to do that manually afterwards, e.g.

uci set system.@system[0].compat_version="1.1"
uci commit system

As stated above, all devices and images without compat-version set will be treated as “1.0”.

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 “incompatible” image, incompatibility warnings and hint message will be printed. However, upgrade has to be forced in all cases (sysupgrade -F -n). Make sure to also reset config in addition to the “force” parameter, as otherwise you will end up as described in “Forcing upgrade” section above. The only exception applies to early DSA-adopters, which can keep their config. Details are found in “Forcing upgrade” section above.

This section is focussed on developers wanting to implement compat-version after introducing an incompatible change.

Setup consists of two parts:

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:

define Device/somedevice
  ...
  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 “1.0”. The DEVICE_COMPAT_MESSAGE is optional and should be used to provide a hint about the problem and/or possibly measures for the user.

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 “ucidef_set_compat_version” to set the compat_version in board.d files, e.g.

    ucidef_set_compat_version "1.1"

During firstboot, this will then add a string to /etc/board.json, which will be translated into uci system config.

By this, the compat_version, being a version of the config, will also be exposed to the user.

Therefore, the on-device compat-version is a property of the config, not of the installation. Consequently, it will be affected by Backup/Restore, but can also be adjusted by the user if necessary.

Information herein that pertains to 17 or older releases and/or no longer generally advised.

• Forum post Identify packages to be re-installed after system upgrade (contains a promising script by forum members mforkel and Rafciq that automates package re-installation)

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