owut: OpenWrt 升级工具

owut 是 OpenWrt 下的保留配置升级固件的命令行工具，最简单的是运行owut upgrade，几分钟后设备会自动重启更新到最新版本的OpenWrt，有疑问请到 帖子寻找解决方法。

owut有多个子命令和选项，可让你检查固件状态、修改已安装软件包的列表以及执行其他与升级相关的任务。一些示例如下： 它的子命令和选项有以下功能

• owut check --verbose - 显示详细构建信息（--quiet：显示主要信息）
• owut versions - 列出所有可用的 OpenWrt 版本
• owut download - 仅下载固件
• owut install - 验证并安装之前下载的固件
• owut list - 生成已安装软件包的列表, 便于配合 Firmware Selector 或者 源码构建使用

使用download or upgrade生成固件时，您可以做以下操作：

• 在构建列表中增删插件
• 首次启动时自动运行自定义的 uci-defaults 脚本

在 x86 miniPCs、ARM/RISC-V SBCs 以及类似设备上，你可以：

• 设置大于默认数值的根分区

您可以在命令行上指定这些选项，也可以使用标准的 OpenWrt config系统来存储这些值，从而避免在每次升级时记住并重新设置。 owut 不是唯一选择！更多内容参阅：Attended Sysupgrade

owut 是一个标准的可选 OpenWrt 软件包， 在支持的主线 SNAPSHOT（测试版）或是 24.10 及之后的稳定版的所有平台上使用。

opkg update  &&  opkg install owut # 在 24.10 稳定版。
apk -U add owut                    # 在主线测试版。

与其他插件或方式不同，owut可以无损升级固件。如果您发现您需要的功能或是bug修复不在您当前版本的 owut中，您可以按如下方式升级。

opkg update  &&  opkg upgrade owut # 在 24.10 稳定版。
apk -U upgrade owut                # 在主线测试版。

注意：一般不需要专门升级 owut 会随固件更新。

如果您对安装或配置有任何疑问， 请在论坛发帖。

如果您的目标只是升级路由器的当前固件，保持相同的版本（例如，24.10 或 SNAPSHOT），那么只需使用 upgrade 命令即可。 如果各种预构建检查发现了任何问题，或者在构建过程中检测到错误，则升级将中止，并显示一条指示问题的消息。

如果 owut 发现软件包降级, 或者自上次升级以来没有进行任何更改，它会告诉您并停止. 您可以使用 --force 选项重新运行该命令，该选项将继续构建和安装，保留所有配置。如果你需要使用 -force 但你又不确定的时候，请在论坛中提问。

请注意， owut 目前仅在主线 SNAPSHOT（测试版） 或 24.x 之后稳定版上可用。

$ opkg update && opkg install owut # 在 24.10 稳定版。
$ apk -U add owut                  # 在主线测试版。

$ owut upgrade
owut - OpenWrt Upgrade Tool 2024.12.10~e38844ae-r1 (/usr/bin/owut)
ASU-Server     https://sysupgrade.openwrt.org
Upstream       https://downloads.openwrt.org
Target         x86/64
Profile        generic
Package-arch   x86_64
Root-FS-type   ext4
Sys-type       combined-efi
Version-from   24.10-SNAPSHOT r28242-1eff737906 (kernel 6.6.67)
Version-to     24.10-SNAPSHOT r28304-6dacba30a7 (kernel 6.6.69)
Build-FS-type  ext4
Build-at       2025-01-04T21:35:37Z (~66 hours ago)
Image-prefix   openwrt-24.10-snapshot-r28304-6dacba30a7-x86-64-generic
Image-URL      https://downloads.openwrt.org/releases/24.10-SNAPSHOT/targets/x86/64
Image-file     openwrt-24.10-snapshot-r28304-6dacba30a7-x86-64-generic-ext4-combined-efi.img.gz
Installed      284 packages
Top-level       83 packages
Default         43 packages
User-installed  51 packages (top-level only)

Package version changes:
  kmod-amazon-ena                6.6.67-r1                                  6.6.69-r1
  kmod-amd-xgbe                  6.6.67-r1                                  6.6.69-r1
...
  procd-ujail                    2024.12.17~fd01fb85-r1                     2024.12.22~42d39376-r1
  ubus                           2024.10.20~252a9b0c-r1                     2025.01.02~afa57cce-r1
  ubusd                          2024.10.20~252a9b0c-r1                     2025.01.02~afa57cce-r1
92 packages are out-of-date

Default package analysis:
  Default                        Provided-by
  dnsmasq                        dnsmasq-full
  kmod-dwmac-intel               not installed
  libustream-mbedtls             not installed
  nftables                       nftables-json

There are currently package build failures for 24.10-SNAPSHOT x86_64:
  Feed: telephony
    freeswitch                   Mon Jan  6 05:37:57 2025 - not installed
    freeswitch-mod-bcg729        Mon Jan  6 05:46:38 2025 - not installed
    freetdm                      Mon Jan  6 05:46:40 2025 - not installed
Failures don't affect this device, details at
  https://downloads.openwrt.org/releases/faillogs-24.10/x86_64/
  
WARNING: There are 2 missing default packages, confirm this is expected before proceeding
Request:
  Version 24.10-SNAPSHOT r28304-6dacba30a7 (kernel 6.6.69)
Request hash:
  fc626783b488e9a7e5a5914495a7ebbbf9fb079cff7abbf2a2165a25d02c8eb6
--
Status:   queued - 0 ahead of you
Progress:   0s total =   0s in queue +   0s in build
--
Status:   init
Progress:   1s total =   0s in queue +   1s in build
--
Status:   container_setup
Progress:  17s total =   0s in queue +  17s in build
--
Status:   validate_manifest
Progress: 101s total =   0s in queue + 101s in build
--
Status:   building_image
Progress: 185s total =   0s in queue + 185s in build
--
Status:   done
Progress: 187s total =   0s in queue + 187s in build

Build succeeded in 187s total =   0s in queue + 187s to build:
  version_number = 24.10-SNAPSHOT
  version_code   = r28304-6dacba30a7 (requested r28304-6dacba30a7)
  kernel_version = 6.6.69
  rootfs_size_mb = default
  init-script    = no-init-script

Image source: http://asu-dev.brain.lan:8000/store/fc626783b488e9a7e5a5914495a7ebbbf9fb079cff7abbf2a2165a25d02c8eb6/openwrt-24.10-snapshot-r28304-6dacba30a7-8e0b0deb02c0-x86-64-generic-ext4-combined-efi.img.gz
Image saved : /tmp/firmware.bin
Manifest    : /tmp/firmware-manifest.json
Verifying   : /tmp/firmware.bin (32751632 bytes) against /tmp/firmware.sha256sums
  Saved sha256 matches
  Tue Jan  7 07:54:20 PST 2025 upgrade: Image metadata not present
  Tue Jan  7 07:54:20 PST 2025 upgrade: Reading partition table from bootdisk...
  Tue Jan  7 07:54:20 PST 2025 upgrade: Extract boot sector from the image
  Tue Jan  7 07:54:21 PST 2025 upgrade: Reading partition table from image...
Checks complete, image is valid.
Installing /tmp/firmware.bin and rebooting...

... system reboots ...

$ owut -h
owut - OpenWrt Upgrade Tool 2025.01.06~e623a900-r1 (/usr/bin/owut)
 
owut is an upgrade tool for OpenWrt.
 
Usage: owut COMMAND [-V VERSION_TO] [-R REV_CODE] [-v] [-q] [-k] [--force] [-a ADD] [-r REMOVE] [--ignored-defaults IGNORED_DEFAULTS] [-I INIT_SCRIPT] [-F FSTYPE] [-S ROOTFS_SIZE] [-i IMAGE] [-f FORMAT] [-p PRE_INSTALL] [-T POLL_INTERVAL]
  -h/--help            - Show this message and quit.
  --version            - Show the program version and terminate.
 
  COMMAND - Sub-command to execute, must be one of:
    check    - Collect all resources and report stats.
    list     - Show all the packages installed by user.
    blob     - Display the json blob for the ASU build request.
    download - Build, download and verify an image.
    verify   - Verify the downloaded image.
    install  - Install the specified local image.
    upgrade  - Build, download, verify and install an image.
    versions - Show available versions.
    dump     - Collect all resources and dump internal data structures.
 
  -V/--version-to VERSION_TO - Specify the target version, defaults to installed version.
  -R/--rev-code REV_CODE - Specify a 'version_code', literal 'none' allowed, defaults to latest build.
  -v/--verbose         - Print various diagnostics.  Repeat for even more output.
  -q/--quiet           - Reduce verbosity.  Repeat for total silence.
  -k/--keep            - Save all downloaded working files.
  --force              - Force a build even when there are downgrades or no changes.
  -a/--add ADD         - New packages to add to build list.
  -r/--remove REMOVE   - Installed packages to remove from build list.
  --ignored-defaults IGNORED_DEFAULTS - List of explicitly ignored default package names.
  --ignored-changes IGNORED_CHANGES - List of explicitly ignored package changes.
  -I/--init-script INIT_SCRIPT - Path to uci-defaults script to run on first boot ('-' use stdin).
  -F/--fstype FSTYPE   - Desired root file system type (squashfs, ext4, ubifs, jffs2).
  -S/--rootfs-size ROOTFS_SIZE - DANGER: See wiki before using!  Root file system size in MB (1-1024).
  -i/--image IMAGE     - Image name for download, verify, install and upgrade.
  -f/--format FORMAT   - Format for 'list' output (fs-user, fs-all, config).
  -p/--pre-install PRE_INSTALL - Script to exec just prior to launching final sysupgrade.
  -T/--poll-interval POLL_INTERVAL - Poll interval for build monitor, in milliseconds.
 
Full documentation
  https://openwrt.org/docs/guide-user/installation/sysupgrade.owut
 
Questions and discussion
  https://forum.openwrt.org/t/owut-openwrt-upgrade-tool/200035
 
Issues and bug reports
  https://github.com/efahl/owut/issues

当您未明确指定 --version-to 值时， owut 会查找已安装分支的最新版本并将其设置为目标版本。

对于所有示例，假设 21.02 分支上的最新版本是 21.02.7 版本, 在 23.05 分支上是 23.05.4 版本。

例外情况是，如果安装的版本是 SNAPSHOT，在这种情况下，版本目标将保留为已安装的版本。

当您指定 --version-to 时，它必须命名有效的版本或分支。如果您提供的值无效， owut 将显示所有可用版本（或者您可以使用 owut versions 手动选择）。

指定完整版本时，将根据可用版本检查输入，并保持原样：

如果您仅指定一个分支（即没有最终“点值”的版本号），则 version-to 目标将设置为该分支上的最新版本。

请注意，字符大小写在命名版本时并不重要， owut 会在内部转换为升级服务器所需的内容。 你可以 snapshot, SnapShot 或 SNAPSHOT 或 rc1 或 rC1 ， owut 知道该怎么做。

owut的正常行为是在未找到更改时停止生成请求，从而避免执行不需要的工作。 --force 选项用于覆盖此权限并重新安装当前系统。 如果您无意中删除了软件包或类似内容，并且无法弄清楚如何恢复，这可能很有用。

当 owut 检测到 package 中的降级时，它会通过在 Package version changes: 列表中将新版本号着色为红色来表示这一点，并在列表底部报告降级次数。这也会导致 owut 止处理任何正在进行的 download 或 upgrade ， 除非您指定 --force 选项。

--add 和 --remove 选项 允许您将包添加到 owut 构建服务器的构建列表中或从中删除包。这些选项在命令行中只能出现一次;如果您想添加或删除多个包，请用逗号分隔包名称或用引号将它们分组。

例如，如果您想升级并同时切换到 dnsmasq 和 tc的完整版本，您可以：

$ owut upgrade -r dnsmasq,tc-tiny -a "dnsmasq-full tc-full"
...

从版本 2025.01.06 开始， --add 和 --remove 的命令行参数都可以用逗号或任意空格（包括换行符）分隔（在该版本之前，只允许使用逗号）。这样做的主要目的是允许您使用包名称的简单平面文件作为包列表的输入源，如本例所示。

$ cat additions
nmap
bind-dig
tcpdump
 
$ owut download --add "$(cat additions)"
...

1. 如果您添加了一个已经安装的软件包，owut 会静默地忽略它并继续。
2. 如果您添加的包不存在、尚未移植到您的设备或当前不可用，则 owut 会报告错误并停止。

1. 如果您尝试删除未安装的软件包，owut 会报告错误并停止。
2. 如果您删除了设备的默认软件包之一，owut 将产生警告，该软件包将被删除，owut 将继续您的请求。 请注意，这可能会在构建期间或安装到您的设备上之后破坏一切，您有责任确保删除软件包是适当的。

   $ owut check -r kmod-igb
   WARNING: package 'kmod-igb' is a default package, removal may have unknown side effects
   ...

3. 如果你试图删除一个有依赖项的包（即 “非顶级包” -- 作为另一个包的要求安装的东西），owut 会警告你这一点，这个包将从构建列表中删除，owut 将继续。 请注意，这通常没有效果，因为该软件包将被最初安装它的同一顶级软件包拉回。

   $ owut check -r kernel
   WARNING: package 'kernel' has dependents and removal will have no effect on the build
   ...

如果 Default package analysis: 显示已删除但希望忽略的默认包，只需将它们作为参数提供给 --ignored-defaults 选项，即可抑制有关缺少默认值的警告。

$ owut check
...
Default package analysis:
  Default                        Provided-by
  dnsmasq                        dnsmasq-full
  kmod-drm-i915                  not installed
  kmod-dwmac-intel               not installed
  nftables                       nftables-json
...
WARNING: There are 2 missing default packages, confirm this is expected before proceeding

请注意，这些包仍列在分析表中，确认您的选择，但不显示警告消息。

$ owut check --ignored-defaults kmod-drm-i915,kmod-dwmac-intel
...
Default package analysis:
  Default                        Provided-by
  dnsmasq                        dnsmasq-full
  kmod-drm-i915                  user ignored
  kmod-dwmac-intel               user ignored
  nftables                       nftables-json

您可以将这些包添加到配置文件中，而无需每次都在命令行中键入它们。

$ cat /etc/config/attendedsysupgrade
...
config owut 'owut'
        option verbosity      1
        option poll_interval  2000
        list   ignored_defaults "kmod-drm-i915"
        list   ignored_defaults "kmod-dwmac-intel"

注意，当处理像 wpad-basic-mbedtls 及其多种替代版本之类的包时，这一点非常有用，因为这些包的依赖关系导致 owut 和其他 ASU 客户端无法判断缺失的默认包是已被其他包替代，还是确实缺失。例如，如果你只是将默认包替换为 wpad-mbedtls（“完整”版本），你会看到如下提示：

Default package analysis:
  Default                      Provided-by
  nftables                     nftables-json
  wpad-basic-mbedtls           not installed

WARNING: There are 1 missing default packages, confirm this is expected before proceeding

当你看到这个提示时，请首先确认你已正确安装了替代包，然后只需在 /etc/config/attendedsysupgrade 文件的 owut 部分添加：

        list   ignored_defaults 'wpad-basic-mbedtls'

这样 owut 就不会再对此发出警告。

Default package analysis:
  Default                      Provided-by
  nftables                     nftables-json
  wpad-basic-mbedtls           user ignored

It is safe to proceed with an upgrade

Attended Sysupgrade（ASU）服务器提供有关版本升级的元数据，各种 ASU 客户端（包括 LuCI ASU 应用、owut 以及 owut 的前身 auc）都会使用这些数据。这些元数据包含在 overview.json 文件 中，你可以在其中查看服务器提供的每个分支的信息。例如，在 branches.SNAPSHOT.package_changes 下，包含了从 firewall 迁移到 firewall4 的相关信息，该变更发生在版本 18611。

owut 使用此表在跨版本升级时自动替换包（注意：owut 不支持跨这些边界的降级；如果因此遇到问题，请 在论坛提问）。

以 firewall 为例，假设你当前的系统版本早于 18611 版本（如何确定当前版本请见下文），现在要升级到更新的版本。当 owut 扫描你已安装的包时，会按以下方式使用 package_changes 信息：

1. 当前检查的包是否是该分支 package_changes 列表中的一个 source 条目？
2. 如果是，当前版本号是否小于或等于该包变更的版本号？
3. 如果是，则：
   1. 移除当前包；
   2. 如果 target 为空，则操作完成（表示当前包已被删除或合并到其他包中）；
   3. 否则，安装对应的 target 包。

这种方式使得在升级过程中对包进行拆分、合并、替换或删除的操作基本无缝，通常你无需担心这些问题。

但以下情况仍可能出现问题：

1. OpenWrt 中进行了包变更，但未在 package_changes 表中注册。这属于缺陷，应通过 论坛或 https://github.com/openwrt/asu/issues 进行报告。
2. 你实际上希望保留某些包变更不被执行。

对于后者，可以在运行 owut 时使用 --ignored-changes 选项，逐个包地禁用此行为。仍以 firewall 为例，你可以如下指定希望保留 firewall 包，并会收到一条信息性消息作为确认：

$ owut upgrade --ignored-changes firewall
owut - OpenWrt Upgrade Tool 2025.03.14~52e7d44c-r1 (/root/bin/owut)
Ignoring package change firewall to firewall4
...

注意，--ignored-changes 选项的参数解析方式与 --add 和 --remove 选项相同，即使用以逗号或空格分隔的包名字符串（详见这些命令的说明）。

你可以通过将该选项作为列表项添加到配置文件中，使其设置“永久生效”，从而使 owut 使用配置文件中的数据而非命令行参数：

$ uci add_list attendedsysupgrade.owut.ignored_changes='firewall'
$ uci commit attendedsysupgrade
$ uci show attendedsysupgrade
attendedsysupgrade.owut=owut
attendedsysupgrade.owut.verbosity='1'
attendedsysupgrade.owut.poll_interval='2000'
attendedsysupgrade.owut.ignored_changes='firewall'

你可以通过以下命令确定当前的版本号。版本号位于 r 和 - 之间，例如下面的例子中为 28521。（或者如果你已经安装了 owut，只需运行 owut check | grep Version-，它会同时显示当前安装的版本和可升级的目标版本。）

$ ubus call system board | jsonfilter -e '$.release.revision'
r28521-f3a210b742

如果您不熟悉 uci-defaults（又名“首次启动脚本”）， 您可以在此处阅读： UCI defaults。实现 owut（以及 auc 和 LuCI 有人值守的系统升级和固件选择器）构建的底层机制是固件生成器，因此其描述也可能很有用: 固件生成器 - 自定义文件。

--init-script 选项允许您指定包含 uci-defaults 脚本的文件的名称，该脚本将在首次启动时执行。ASU 服务器获取你的 init-script 源，并将其放在 /etc/uci-defaults/99-asu-defaults 的镜像中（无法更改此名称）。在不可变文件系统（比如 squashfs）上，这也会导致文件存储在 /rom/etc/uci-defaults/99-asu-defaults 中，这与 LuCI Attended Sysupgrade 有关。

以下是 owut 与其他升级工具如何实现此功能的比较。

• auc 不实现此功能 (但是有 补丁)。
• 固件选择器的行为与 owut 的行为相同，其Script to run on first boot (uci-defaults) 输入字段。
• LuCI Attended Sysupgrade 通过查找 /rom/etc/uci-defaults/99-asu-defaults 来实现这一点，然后隐式中继该文件的内容。 LuCI ASU 的缺点是它不允许您删除或更改已经存在的内容。owut 明确表示，如果您希望脚本包含在新固件中，则必须在请求构建时指定它。

以下两种场景（包括 7 个使用案例）中使用的术语是：

• “mutable system” - 使用读写文件系统作为其主存储的设备。 通常在 OpenWrt 中，这是一个 ext4 文件系统。

  $ mount | grep '(ro'
  ... no output ...

• “immutable system” - 在 /rom 上安装了只读分区的设备，原始系统映像存储在其中。通常，但不总是，这是一个squashfs文件系统。

  $ mount | grep '(ro'
  /dev/root on /rom type squashfs (ro,relatime,errors=continue)

• “asu-defaults” - 文件 /rom/etc/uci-defaults/99-asu-defaults ，它仅存在于具有不可变文件系统且其映像已由ASU构建服务器构建的设备上。

在 immutable system ，有五种情况需要考虑：

1. asu-defaults 文件不存在，您不需要或不想要：

   owut upgrade

2. asu-defaults 文件存在，您希望保持它不变：

   owut upgrade --init-script /rom/etc/uci-defaults/99-asu-defaults

3. 存在 asu-defaults 文件并且您想修改它：

   cp /rom/etc/uci-defaults/99-asu-defaults my-modified-init-script.sh
   vi my-modified-init-script.sh  # Change it.
   owut upgrade --init-script my-modified-init-script.sh

4. asu-defaults 文件不存在，但您想添加一个：

   vi my-new-init-script.sh
   owut upgrade --init-script my-new-init-script.sh

5. 存在 asu-defaults 文件，您想从构建中删除它：

   owut upgrade  # Just ignore the warning.

在 mutable system, 由于没有 /rom/etc/uci-defaults ，您只有两个选择：

1. 您不想在构建中创建 asu-defaults ：

   owut upgrade

2. 您想创建一个：

   owut upgrade --init-script my-init-script.sh

请注意，对于上述所有情况，如果您确实使用了asu-defaults，那么您必须保留备份。有关最佳实践，请参阅 持久默认值示例。

在极少数情况下，可能需要更改安装的文件系统类型。通常这是在具有可扩展文件系统的设备上完成的， x86, RISC-V 和 ARM SBCs，这类存储设备不是固定容量的FLASH（事实上，如果您尝试在基于FLASH的一体化设备上更改文件系统类型，构建过程几乎总会失败）。

但是，举个例子，假设您有一台配备SSD的x86设备，并且想要从当前的 squashfs 文件系统切换到 ext4 。只需使用所需的文件系统进行升级，重启后即可运行目标文件系统。

$ owut upgrade --fstype ext4
...
Target         x86/64
Profile        generic
Package-arch   x86_64
Root-FS-type   squashfs                   <<< Installed
Version-from   SNAPSHOT r26504-d4acd05218 (kernel 6.6.32)
Version-to     SNAPSHOT r26733-2b6772c82c (kernel 6.6.34)
Build-FS-type  ext4                       <<<  Requested
...

--rootfs-size 选项允许那些具有可扩展文件系统（通常是x86、RISC-V和ARM SBC）的设备指定根文件系统的大小。默认值因目标而异，但通常为104 MB，--rootfs-size 选项允许您将其增加到1024 MB（请看下面的备注），从而允许安装更多或更大的包。

最佳实践是在配置文件中定义此值，原因如下：

1. 可以避免每次升级时都需要在命令行中手动输入；
2. 防止因遗忘设置而导致重新调整为 104MB，从而造成配置丢失或升级失败。

将该值设置为 256 MB 的示例命令如下，请根据实际需求调整数值：

$ uci set attendedsysupgrade.owut=owut
$ uci set attendedsysupgrade.owut.rootfs_size=256
$ uci commit
$ uci show attendedsysupgrade.owut
attendedsysupgrade.owut=owut
attendedsysupgrade.owut.rootfs_size='256'

备注：rootfs_size 允许设置的最大值取决于 ASU 服务器的配置。例如，OpenWrt 上 rootfs 分区的最大为 1024 MB。查看各个 sysupgrade 服务器来确认，该值会在页面底服务器配置（Server Configuration）部分的最大请求的根文件系统大小：（Maximum requested root filesystem size:）中列出。 详情参阅下面的ASU服务器名单

owut list命令使用 --format 选项，该选项采用以下值之一。

• fs-user - (默认值) 生成一个包列表供固件选择器使用，该列表仅包含顶级用户安装的包修改。您可以将此复制并粘贴到FS “已安装包” 字段中的默认列表之后。
• fs-all - 为FS生成一个包含所有顶级包的包列表，您可以将粘贴到FS “已安装包” 字段中的值上。
• config - 生成用户安装的顶级包的构建 .config 片段，您可以在进行源构建时使用这些包。每个输出行看起来像 CONFIG_PACKAGE_collectd-mod-thermal=y 。

The fs-* options generate lists in the Image Builder syntax, where mentioning a package name adds it to the list, and prefixing a package name with a dash removes it.

例如，如果您安装了 dnsmasq-full 软件包，则必须移除默认的 dnsmasq 基础软件包。具体操作示例如下（为清晰起见已简化）：

$ owut list
... dnsmasq-full ... -dnsmasq ...

默认值提供了几个包，它们使用通用包名命名，实际上是由不同名称的东西提供的， nftable 是一个突出的包（它由 nftables-json 或 nftables-nojson 提供，没有 nftables-nojson 包）。 owut似乎正在删除它，但它实际上只是说，“使用默认值，不管是什么”。在下面的示例中，我们只看到删除了 -nftable ，但没有看到默认包 nftables-json ，因为它将被隐式添加。

$ opkg whatprovides nftables  # Or 'apk list --providers nftables'
What provides nftables
    nftables-json
 
$ owut list
... -nftables ...

这可能发生在其他由于依赖关系而看起来“无处删除”的文件上。例如，如果您使用 luci-ssl-openssl ，则列表输出将包含 -libustream-mbedtls ，否则将由默认值添加，从而导致“不可能的包选择”错误。

在默认包分析结果中使用 check 时，您经常会看到这些映射的其他证据：

$ owut check
...
Default package analysis:
  Default                        Provided-by
  dnsmasq                        dnsmasq-full
  kmod-dwmac-intel               not installed
  nftables                       nftables-json
...

owut 在图像验证和图像安装之间有一个钩子，允许你在安装之前对系统进行自动备份、构建工件的存档或任何其他最终修改。使用命令行中的 --pre-install /path/to/script 选项。一旦你对你的脚本工作方式感到满意，最佳实践是将 option pre_install '/path/to/script 添加到配置文件的 owut 部分。

正常安装的owut 在路径 /etc/owut.d/ 中提供示例脚本（例如：pre-install.sh）。如果你探索出其他有趣的用法，欢迎分享！。

请注意，目录 /etc/owut.d/ 是标准系统升级备份的一部分，因此您存储在那里的任何文件都将成为系统备份的一部分，并在升级过程中持续存在（假设您“保留配置”）。使用sysupgrade -l | grep owut.d命令会列出该目录下的所有文件。

正因如此，上述提示中提到的示例脚本才将 /etc/owut.d/ 用作归档文件的存储目录。

预安装脚本被执行时，它是在一个极简的环境中被启动的。 HOME 或者 其他环境变量不存在。唯一可以确定存在的变量是 PATH，包含所有标准系统路径。这意味着，在 owut 之外测试你的脚本时，应在一个空白的环境（即清空所有环境变量）下进行，具体方法如下所示：

env -i  PATH=/usr/sbin:/usr/bin:/sbin:/bin  /path/to/your/pre-install-script

如果你需要运行一些无法控制的进程，而这些进程又依赖特定的环境变量，那么你必须在预安装脚本中显式地定义这些变量。此外，如果你使用的脚本或可执行文件不在标准系统路径中，则必须使用其完整路径进行调用，或者手动扩展 PATH 环境变量。

#!/bin/sh
 
export HOME=/root
export USER=root
 
/root/bin/helper.sh  # Run my helper script from ~/bin.
 
...

任何命令行选项都可以存储在 owut 部分的 /etc/config/attendedsysupgrade 中。例如，如果在每次升级时都在命令行上使用 --rootfs-size 256 ，则可以编辑配置并按如下方式添加该选项：

config server 'server'
        option url 'https://sysupgrade.openwrt.org'

config owut 'owut'
       option rootfs_size 256

请注意，命令行中 “long” 选项名称中的破折号在配置选项名称中变为下划线，但除此之外，语法几乎完全相同。

命名约定有一个例外，命令行 --verbose 和 --quiet 在配置文件中都映射到 verbosity 。 verbosity 的配置文件值是一个整数；命令行上每次提到 -v 都会使其递增， 而 -q 会使其递减： option verbosity 1, 然后 owut check -v -v -q -v 会导致输出详细程度为 3 (即，比你想象的更多的输出)。

一种查看默认值以及验证对配置文件所做的任何更改是否正确的便捷方法是执行 owut dump 并检查输出的 options 部分。

$ owut dump | head -20
{
"version": "owut/2025.01.06~e623a900-r1",
"options": {
  "command": "dump",
  "version_to": null,
  "rev_code": null,
  "verbosity": 1,
  "keep": false,
  "force": false,
  "add": null,
  "remove": null,
  "init_script": null,
  "fstype": null,
  "rootfs_size": 256,
  "image": "/tmp/firmware.bin",
  "format": null,
  "pre_install": "/etc/owut.d/pre-install.sh",
  "poll_interval": 10000,
  "device": null
},

你可以通过在配置中设置此选项来强制设置 --version-to 的默认值。请注意，这与 owut的默认行为是多余的 (请参阅上文 选择版本 的详细信息)。

config owut 'owut'
        option version_to '24.10'

设置此项之前，请先阅读上文的 扩展根文件系统, 因为这可能不适用于你的设备。

对于具有可扩展存储的设备，通常是 x86、RISC-V 和 ARM 单板计算机，你可能会发现扩展根文件系统大小很有用，这样可以轻松安装更多软件包或存储更多持久数据。

config owut 'owut'
        option rootfs_size 512

如果您使用过自定义 uci-defaults, 您可能会意识到脚本在第一次启动时从 /etc/uci-defaults/ 中删除。对于不可变安装，通常使用 squashfs 文件系统，您可以从 /rom/etc/uci-defaults/ 查看和恢复自定义脚本，但在 ext4 文件系统上，没有 rom 分区，文件永远消失了。

owut 通过允许您将脚本放置在持久位置，然后设置配置文件使其成为已安装固件的一部分来解决此问题。

1. 在持久位置创建您的init-script。

   $ mkdir /etc/owut.d/
   $ echo "# My first boot script." > /etc/owut.d/custom-init.sh

2. 确保它在所有的 sysupgrade 备份中进行。

   # The /etc/owut.d/ directory is part of standard backups, lets make sure...
   $ sysupgrade -l | grep custom
   /etc/owut.d/custom-init.sh

3. 配置 owut 以将脚本包含到您的构建中。

   $ uci set attendedsysupgrade.owut=owut
   $ uci set attendedsysupgrade.owut.init_script=/etc/owut.d/custom-init.sh
   $ uci commit
   $ uci show attendedsysupgrade.owut
   attendedsysupgrade.owut=owut
   attendedsysupgrade.owut.init_script='/etc/owut.d/custom-init.sh'

4. 验证一切都设置正确。您的脚本应作为 defaults 条目出现在json中。

   $ owut blob
   {
     "client": "owut/%%VERSION%%",
     "target": "x86/64",
     "profile": "generic",
     "version": "SNAPSHOT",
     "version_code": "r26773-85d9fd6f0e",
     "filesystem": "ext4",
     "diff_packages": true,
     "packages": [
       "base-files",
       "btop",
       "busybox",
       ... a bunch more packages ...
       "ucode-mod-uloop",
       "urandom-seed",
       "urngd"
     ],
     "defaults": "# My first boot script.\n"
   }

* - 自2024年6月起，您还可以通过使用 OpenWrt 固件选择器 创建映像来完成后一部分，手动将脚本粘贴到其 Script to run on first boot (uci-defaults) 字段。

目前存在多个替代的 ASU 服务器，其中一些提供官方的 OpenWrt 固件，另一些则提供分支版本（forks）。以下是一些已知可用的服务器列表；如果您知道其他的服务器，请将其添加到此处，或在 相关帖子中发布。

• https://sysupgrade.openwrt.org - 官方 OpenWrt 系统升级服务器。截至 2025年8月15日，其 rootfs 分区最大容量为 1024 MB；uci-defaults 最大长度为 20480 字节。
• https://sysupgrade.guerra24.net - Guerra24 系统升级服务器，是官方 OpenWrt 服务器的镜像。截至 2025年9月15日，rootfs 最大容量为 4096 MB，其余部分与官方服务器及软件包源保持一致。
• https://sysupgrade.antennine.org - LibreMesh 系统升级服务器。提供官方 OpenWrt 固件，同时额外添加了 LibreMesh 软件包源（可使用下方的 curl 命令查看详细信息）。
• https://sysupgrade.kyarucloud.moe - ImmortalWrt 系统升级服务器。提供来自 ImmortalWrt 分支版本的固件，拥有独立的构建系统和软件包源。截至 2025年8月15日，rootfs 最大容量为 4096 MB。

要将这些服务器之一与 owut 或 LuCI Attended Sysupgrade 配合使用，您需要在配置中设置 server.url 的值。该值被两个组件共用，也可以在 LuCI 应用的 Configuration 选项卡中，通过设置 Address 字段来更改。

$ uci set attendedsysupgrade.server.url="https://sysupgrade.openwrt.org"
$ uci commit

您可以通过点击上方任一链接，并在每个页面底部打开 “Server Configuration” 来查看部分服务器限制。也可以通过运行以下 curl 命令并提取 server 部分，您可以查看服务器的所有限制和配置选项。

$ curl -s https://sysupgrade.openwrt.org/json/v1/overview.json | jsonfilter -e '$.server'
{ "version": "0.8.0.post329", "contact": "mail@aparcar.org", "allow_defaults": true, "repository_allow_list": [ ], "max_custom_rootfs_size_mb": 1024, "max_defaults_length": 20480 }

Q: owut 中没有在不保留配置的情况下升级的选项。我可以用 auc -n来做，为什么 owut 不可以?

A: 这是（或应该是）一件罕见的事情，所以使用 owut故意让它变得困难。解决方案是简单地使用 owut 来创建映像，然后运行 sysupgrade 表明您想要丢弃配置。因此，这样可以确保您真的打算这样做，因为这是极具破坏性的。

$ owut download
...
$ sysupgrade -n /tmp/firmware.bin

Q: 我有一台大型 miniPC 作为我的路由器。为什么我不能使用 --rootfs-size 120000 创建一个固件并使用我的整个 128GB 硬盘？

A: 出于实际原因，ASU 服务器规定上限为 1024MB。在某些设备上创建分区的方式要求先创建全尺寸图像，然后进行压缩，这需要大量的内存、磁盘空间和时间。

作过一个测试，我进行了几次图像构建器运行，根文件系统分区从 x86 的默认值（104MB）到 20000MB 不等，以查看它们需要多长时间。

这最后两行应该非常清楚地说明了为什么增加上限是不可行的，除非对构建过程进行重新设计以减少创建更大图像所需的时间。

注意：上述测试均在 AMD R9 7950x 5.8GHz CPU、64GB CL6000 RAM 和 PCIe 4 SSD 上运行，其速度通常是 ASU 服务器硬件的 3 倍，因此这些数字远低于在使用 ASU 服务器时看到的数字。

你可以通过 下载 并在支持的Linux桌面版运行一个 imagebuilder，运行 make info 来选择一个配置（profile），然后执行以下命令，自定义固件的大小。

profile=generic  # Set this to your desired profile from 'make info'.
for size in 104 256 512 1024 2048 4096 10240; do
    printf "Part size: %s" "$size"
    time /usr/bin/make image PROFILE=$profile ROOTFS_PARTSIZE=$size 2&>1 | grep -i error
done

• owut - github source, OpenWrt packaging
• ASU server - github source, API documentation
• auc - wiki page, see final commit removing auc from the package feed
• LuCI Attended Sysupgrade - wiki page, github source
• Firmware Selector - github source, build site
• Docker container builds - github source
• OpenWrt buildbots - github source
• Downloads site - OpenWrt build artifacts and release archive
• Dashboards - OpenWrt buildbot dashboards
• ucode - Reference Manual
• ucode-mod-uclient - github source