mirror of
https://git.proxmox.com/git/fwupd
synced 2026-03-27 21:30:22 +00:00
52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
Building Firmware
|
||
=================
|
||
|
||
Most of the time when you’re distributing firmware you have permission from the
|
||
OEM or ODM to redistribute the non-free parts of the system firmware, e.g.
|
||
Dell can re-distribute the proprietary Intel Management Engine as part as the
|
||
firmware capsule that gets flashed onto the hardware.
|
||
|
||
In some cases that’s not possible, for example for smaller vendors or people
|
||
selling OpenHardware. For reasons (IFD, FMAP and CBFS…) you need to actually
|
||
build the target firmware on the system you’re deploying onto, where build
|
||
means executing random low-level tools to push random blobs of specific sizes
|
||
into specific unnecessarily complex partition formats rather than actually
|
||
compiling .c into executable code.
|
||
|
||
The solution of a manually updated interactive bash script isn’t awesome from a
|
||
user-experience or security point of view.
|
||
|
||
The other things that might be required is a way to `dd` a few bytes of
|
||
randomness into the target image at a specific offset and also to copy the old
|
||
network MAC address into the new firmware.
|
||
|
||
The firmware-builder functionality allows you to ship an archive (typically
|
||
in `.tar` format, as the `.cab` file will be compressed already) within the
|
||
`.cab` file as the main “release”.
|
||
|
||
Within the `.tar` archive will be a startup.sh file and all the utilities or
|
||
scripts needed to run the build operation, statically linked if required.
|
||
At firmware deploy time fwupd will explode the tar file into a newly-created
|
||
temp directory, create a bubblewrap container which has no network and
|
||
limited file-system access and then run the startup.sh script. Once complete,
|
||
fwupd will copy out just the `firmware.bin` file and then destroy the bubblewrap
|
||
container and the temporary directory.
|
||
|
||
This is the directory that is available to the bubble-wrap confined script.
|
||
If, for instance, a plugin needs the old system firmware blob (for a bsdiff)
|
||
then the plugin can write to this directory and the startup.sh script will be
|
||
able to access it as the chroot-ed `/boot`.
|
||
|
||
Firmware `.cab` files using this functionality should list the `.tar` file:
|
||
|
||
<release>
|
||
<checksum filename="firmware.tar" target="content"/>
|
||
</release>
|
||
|
||
and also should include the name of the script to run as additional metadata:
|
||
|
||
<custom>
|
||
<value key="fwupd::BuilderScript">startup.sh</value>
|
||
<value key="fwupd::BuilderOutput">firmware.bin</value>
|
||
</custom>
|