Fwtool - please explain

image/Makefile for some targets contains

doimagestuff | append-metadata

which i assume calls fwtool...> this line...

echo '{  "metadata_version": "1.0", "supported_devices":["abc","xyz"], "version": { "dist": "OpenWrt", "version": "SNAPSHOT", "revision": "r11618-416d2cc71e", "target": "TARGET/SUBTARGET", "board": "xyz" } }' | fwtool -I - PATHTOGENERATINGIMAGE

test on sysupgrade;

[ "$REQUIRE_IMAGE_METADATA" = 1 -a "$FORCE" != 1 ] && {
if ! fwtool -q -i /tmp/sysupgrade.meta "$1"
  • questions ( most important ones in bold )
  1. What is a buildroot command to use staging_dir/host/bin/fwtool to get metadata from an image... everything I try just prints the help... and in what ways is the buildroot tool different from the on-router binary? ( is there a good online document about it? )
  2. Where within the image is it stored ( is it only compatible with tar.xz... is it an appended trailer? )
  3. There is a note somewhere that says this ( or something related to validity checks ) isn't actually used at the moment... what is the "state" regarding this
  4. is this eventually intended to replace or just augment CONTROL files?
./fwtool -i - ~/owrt/r11616-291d79935e/ipq806x-ath10k-ct/targets/ipq806x/generic/openwrt-ipq806x-generic-zyxel_nbg6817-squashfs-sysupgrade.bin 
{  "metadata_version": "1.0", "supported_devices":["zyxel,nbg6817","nbg6817"], "version": { "dist": "OpenWrt", "version": "SNAPSHOT", "revision": "r11616-291d79935e", "target": "ipq806x/generic", "board": "nbg6817" } }

Yes, it's appended to the end of the image.

1 Like

thankyou slh... all good now

( note: to fwtool devs... )

  1. possibly update the help to include a reference to the "-" parameter
current help output for someone trying the command
Usage: ./fwtool <options> <firmware>

  -S <file>:		Append signature file to firmware image
  -I <file>:		Append metadata file to firmware image
  -s <file>:		Extract signature file from firmware image
  -i <file>:		Extract metadata file from firmware image
  -t:			Remove extracted chunks from firmare image (using -s, -i)
  -T:			Output firmware image without extracted chunks to stdout (using -s, -i)
  -q:			Quiet (suppress error messages)
  1. the following command corrupts an image
fwtool -q -i openwrt-ipq806x-generic-netgear_r7500-squashfs-sysupgrade.bin
$ wget https://downloads.openwrt.org/snapshots/targets/ipq806x/generic/openwrt-ipq806x-generic-tplink_c2600-squashfs-sysupgrade.bin

$ ./fwtool -i - openwrt-ipq806x-generic-tplink_c2600-squashfs-sysupgrade.bin
{  "metadata_version": "1.0", "supported_devices":["tplink,c2600","c2600"], "version": { "dist": "OpenWrt", "version": "SNAPSHOT", "revision": "r11675-16b01fb1b9", "target": "ipq806x/generic", "board": "c2600" } }

$ ./fwtool -q -i openwrt-ipq806x-generic-tplink_c2600-squashfs-sysupgrade.bin

$ ./fwtool -i - openwrt-ipq806x-generic-tplink_c2600-squashfs-sysupgrade.bin
unable to extract trailer header

- is used for STDIN/ STDOUT in traditional UN*X, so instead of writing the result to a file called /tmp/sysupgrade.meta, you'll get it right on your terminal by using -i -.


A subtly of the target.mk syntax for the assembly of images lines is that | is not “shell pipe” but just a separator for “next step is”. You also can’t, that I could easily figure out, combine with && or || on those lines, unfortunately.

CONTROL is pretty empty. I don’t know future intent. Checking the various platform upgrade scripts is the only way I know to determine if the metadata is used. I believe ar71xx does not use it and that ath79 does.

1 Like

Appended meta data isn't compatible with legacy build recipes, those don't exist for ath79 or other newer targets, but are still around among several ar71xx devices.

1 Like

I think you're just missing the - in that command:
fwtool -q -i - openwrt-ipq806x-generic-netgear_r7500-squashfs-sysupgrade.bin
It's still not good something is written to the output-file (-i <file>) when no <firmware> is specified unless of course fwtool uses the running/local firmware when no file is specified and that is intentional behavior.

Just tested it on a router and fwtool -q -i <somefile> prints the help on console and overwrites the <somefile> with an empty file (or creates an empty file when it didn't exist before).
Definitely not good behavior (it should do nothing when no input is specified) but strictly speaking it's the fault of the user (expecting an output-file not to be overwritten/changed) :-/

1 Like

thankyou to all the help from above... some time has passed and I now have a better grasp of these tools...

came across this thread again and can semi-answer my own question above... which seems relevant now and movements are underway in a few places in this regard...

if your image is built (or post installed) with a ucert package... then upgrade logic activates cert checking... ( pretty sure 21.02 now rolls in ucert... so expect to see a few of these messages in the future )

cert identity failures will result in needing to use the -F param... (or make sure your image is correct/bono-fide) or uninstall ucert(-full)...