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:sysupgrade.owut [2024/07/30 02:06] – [Usage] Update help page to include new options efahlgrendocs:guide-user:installation:sysupgrade.owut [2024/08/18 20:34] – [List formatting] efahlgren
Line 22: Line 22:
 You can specify these options on the command line, or you can use the standard OpenWrt ''config'' system to store these values and avoid having to remember and retype them on every upgrade. You can specify these options on the command line, or you can use the standard OpenWrt ''config'' system to store these values and avoid having to remember and retype them on every upgrade.
  
 +===== Installation and Upgrading =====
 +
 +''owut'' is a standard, optional OpenWrt package, available on all platforms supported by SNAPSHOT or release builds from 24.x and later.
 +<code>
 +opkg update  &&  opkg install owut
 +</code>
 +
 +If you find that you need a feature that is not in your current version of ''owut'', you can upgrade as follows.
 +
 +<code>
 +opkg update  &&  opkg upgrade owut
 +</code>
 +
 +There is usually no need to specifically upgrade ''owut'', as once installed ''owut'' will be upgraded along with everything else whenever you do a full firmware upgrade.
 +
 +If you have questions about installation or configuration, [[https://forum.openwrt.org/t/owut-openwrt-upgrade-tool/200035|post on the support forum thread]].
 ===== Quick Start ===== ===== Quick Start =====
  
Line 190: Line 206:
  
 ^ Option ^ Default ^ Description ^ ^ Option ^ Default ^ Description ^
-| ''-V/--version-to VERSION''    | newest version on current branch | Search for updates for this version or branch. |+| ''-V/--version-to VERSION''    | newest version on current branch | Search for updates for this version or branch.  [[#list_formatting|Detailed description.]]|
 | ''-v/--verbose''         | - | Print various diagnostics and operational messages; repeat for even more output. | | ''-v/--verbose''         | - | Print various diagnostics and operational messages; repeat for even more output. |
 | ''-k/--keep''            | false | Save all downloaded working files, primarily for diagnostics and debugging.  Look in ''/tmp/'' after using this option; turn on ''-v'' to watch as they are saved. | | ''-k/--keep''            | false | Save all downloaded working files, primarily for diagnostics and debugging.  Look in ''/tmp/'' after using this option; turn on ''-v'' to watch as they are saved. |
-| ''--force''              | false | Force ''download'' or ''upgrade'' when there are package downgrades, or when there are no changes detected. | +| ''--force''              | false | Force ''download'' or ''upgrade'' when there are package downgrades, or when there are no changes detected. [[#forcing_a_build|Detailed description.]] 
-| ''-a/--add ADD''         | none | Comma-separated list of new packages to add to build list. | +| ''-a/--add ADD''         | none | Comma-separated list of new packages to add to build list.  [[#about_adding_packages|Detailed description.]] 
-| ''-r/--remove REMOVE''   | none | Comma-separated list of installed packages to remove from build list. | +| ''-r/--remove REMOVE''   | none | Comma-separated list of installed packages to remove from build list. [[#about_removing_packages|Detailed description.]] 
-| ''-I/--init-script INIT_SCRIPT'' | none | Path to uci-defaults script to run on first boot ('-' use stdin). | +| ''-I/--init-script INIT_SCRIPT'' | none | Path to uci-defaults script to run on first boot ('-' use stdin).  [[#using_a_uci-defaults_script|Detailed description.]] 
-| ''-F/--fstype FSTYPE''   | current | Desired root file system type.  May be one of ''squashfs'', ''ext4'', ''ubifs'' or ''jffs2'' depending on platform constraints. | +| ''-F/--fstype FSTYPE''   | current | Desired root file system type.  May be one of ''squashfs'', ''ext4'', ''ubifs'' or ''jffs2'' depending on platform constraints.  [[#changing_file_system_type|Detailed description.]] 
-| ''-S/--rootfs-size ROOTFS_SIZE'' | current | Root file system size in MB (1-1024). |+| ''-S/--rootfs-size ROOTFS_SIZE'' | current | Root file system size in MB (1-1024). [[#expanding_root_file_system|Detailed description.]] |
 | ''-i/--image IMAGE''     | ''/tmp/firmware.bin'' | The image name used for the ''download'', ''verify'', ''install'' and ''upgrade'' sub-commands. | | ''-i/--image IMAGE''     | ''/tmp/firmware.bin'' | The image name used for the ''download'', ''verify'', ''install'' and ''upgrade'' sub-commands. |
-| ''-f/--format FORMAT''   | ''fs-user'' | Format for ''list'' output.  Valid formats are ''fs-user'', ''fs-all'' and ''config''. |+| ''-f/--format FORMAT''   | ''fs-user'' | Format for ''list'' output.  Valid formats are ''fs-user'', ''fs-all'' and ''config'' [[#list_formatting|Detailed description.]] | 
 +| ''-p/--pre-install PRE_INSTALL'' | none | Path to a user-defined script that will be run after image verification and before the actual installation of the image.  [[#pre-install_script|Detailed description.]] |
  
 ==== Selecting a version ==== ==== Selecting a version ====
Line 381: Line 398:
   * ''fs-all'' - produces a package list for FS containing all top-level packages, which you'd paste //over// the values in the FS 'Installed Packages' field.   * ''fs-all'' - produces a package list for FS containing all top-level packages, which you'd paste //over// the values in the FS 'Installed Packages' field.
   * ''config'' - produces a build ''.config'' snippet of user-installed, top-level packages that you can use when doing source builds. Each output line looks like ''CONFIG_PACKAGE_collectd-mod-thermal=y''.   * ''config'' - produces a build ''.config'' snippet of user-installed, top-level packages that you can use when doing source builds. Each output line looks like ''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.
 +
 +For example, if you have installed ''dnsmasq-full'', then the default ''dnsmasq'' basic package must be removed.  That would look like this (trimmed down for clarity):
 +
 +<code bash>
 +$ owut list
 +... dnsmasq-full ... -dnsmasq ...
 +</code>
 +
 +There are several packages provided by the defaults that are named using a generic package name, and actually provided by something with a different name, ''nftables'' is a prominent one (it is provided by either ''nftables-json'' or ''nftables-nojson'', there is no ''nftables'' package).  ''owut'' appears to be removing it, but it really is just saying, "use the default, whatever that is" In the following example, we see only the ''-nftables'' removal, but not default package ''nftables-json'' as it will be added implicitly.
 +
 +<code bash>
 +$ opkg whatprovides nftables
 +What provides nftables
 +    nftables-json
 +
 +$ owut list
 +... -nftables ...
 +</code>
 +
 +This can happen for other files that appear to be "deleted from nowhere" due to dependencies.  As an example of this, if you are using ''luci-ssl-openssl'', then the list output will contain ''-libustream-mbedtls'' which would otherwise be added by defaults resulting in an "impossible package selection" error.
 +
 +You'll often see other evidence of these mappings when using ''check'' in the default package analysis results:
 +<code>
 +$ owut check
 +...
 +Default package analysis:
 +  Default                        Provided-by
 +  dnsmasq                        dnsmasq-full
 +  kmod-dwmac-intel               not installed
 +  nftables                       nftables-json
 +...
 +</code>
 +
 +==== Pre-install Script ====
 +
 +''owut'' has a hook between image verification and image install, allowing you to do automatic backups, archiving of build artifacts or any other final modifications to the system prior to the installation.  Use the ''--pre-install /path/to/script'' option from the command line, or add ''option pre_install '/path/to/script''' to the ''owut'' section of the config file.
 +
 +The standard installation of ''owut'' provides several examples in ''/etc/owut.d/pre-install.sh''.
 +
 +Note that the directory ''/etc/owut.d/'' is part of the standard sysupgrade backup, so any files you store there will become part of system backups and persist across upgrades (assuming you "keep config").
 +
  
 ===== Configuration ===== ===== Configuration =====
  • Last modified: 2024/11/29 17:07
  • by efahlgren