OpenWrt owut: controlled upgrades and package handling

owut is a shell-based OpenWrt upgrade tool. It cannot make an image for the wrong target safe, and it is not a substitute for a backup. A controlled upgrade checks the board, release, packages, and free space before allowing a reboot and flash.

Do not start with owut upgrade. Keep a spare SSH/LuCI access path and copy the configuration off the router first.

Inspect the router and create a backup

ubus call system board
cat /etc/openwrt_release
df -h
sysupgrade -b /tmp/config-backup.tar.gz

Copy /tmp/config-backup.tar.gz to another machine. Record the model, target/subtarget, current release, extra packages, and the device’s recovery method.

Install and inspect owut

opkg update
opkg install owut
owut --version

Read the help and run the preflight check:

owut --help
owut check

Review the check output: target, destination release, package changes, image size, and package retention/removal warnings. Stop when an external feed or overlay is incompatible. Do not use --force to hide a package-selection error.

Perform a controlled upgrade

Confirm stable power and make sure no other process is writing flash.
Read the owut check result again.
If the checks are acceptable, run:

owut upgrade

Do not interrupt image creation, flashing, or reboot.
After the router returns, wait for networking to settle and sign in again.
Verify the board, packages, storage, and recent log entries:

ubus call system board
opkg list-installed | head
df -h
logread | tail -50

When the upgrade cannot proceed

If owut check reports low space, package conflicts, or no matching image, do not immediately flash by hand. Remove only confirmed-unused packages/cache, or follow the target-specific sysupgrade procedure. If the router loses access after reboot, use the off-device backup and the model’s recovery path. A configuration backup does not contain the bootloader, ART, calibration, or a full flash image; never use it to restore another device.

Source

Official documentation: https://openwrt.org/docs/guide-user/installation/sysupgrade.owut