The fw_update utility explained and how it works

What is fw_update?

OpenBSD has great man pages, so let’s see what fw_update(8) has to say: “install non-free firmware”. The fw_update tool is to deal with firmware, or in other words, low-level software that runs on hardware (a device) itself. Another important part is the non-free, meaning firmware components that have a license that does not allow it to be bundled within OpenBSD directly.

The fw_update utility, written in shell script, helps you with downloading, installing, removing, and showing available firmware. Typical moments that the tool is being used is at the first boot of the system, after a system upgrade, or manually when new firmware is needed.

When to use fw_update?

Under normal conditions you don’t need to run fw_update manually as it is scheduled to do this at the first boot of the system. After a system upgrade or when experiencing problems with firmware, then it might be worth to see if the tool finds new firmware.

An example where fw_update is being executed during the first boot of the system:

starting network daemons: sshd smtpd sndiod.
running rc.firsttime
fw_update: add vmm; update none; keep intel
Checking for available binary patches...

In this example the ‘vmm’ firmware is being added, no firmware is updated, and the ‘intel’ firmware is kept as-is.

How is required firmware detected?

The way fw_update works is like a train of smaller steps. Let’s have a look.

Pattern matching in kernel messages

OpenBSD will keep a log with kernel messages. You will recognize parts of this log when running the dmesg command. Another option is to have a look at the /var/run/dmesg.boot file. For fw_update both the output of dmesg as this file will be used as a source to determine available hardware components.

Based on the text strings available from the kernel messages, it will try to do pattern matching for available firmware. This is by doing the text string comparison against the file /usr/share/misc/firmware_patterns and see if anything returns. If so, then there is a candidate for installation.

Download and validation

Upon the phase of installation, the firmware will be downloaded from a web server. Then it will be checked against a signed database with SHA256 hashes. This way the tool knows there is no corruption or unauthorized alterations of the files.

Firmware installation

After the validation step, the downloaded tar file is then extracted under a subdirectory within /etc/firmware. For tracking purposes, the firmware is then marked ‘installed’ like as they were normal packages, by creating a dummy package within the /var/db/pkg directory.

# ls -l /var/db/pkg/ | grep firmware
drwxr-xr-x  2 root  wheel  512 Aug 11 14:03 intel-firmware-20260512v0
drwxr-xr-x  2 root  wheel  512 Aug 11 15:31 vmm-firmware-1.16.3p1

Within these directories there will be two files:

+CONTENTS
+DESC

This first file contains the related files on disk, which are typically stored within their respective subdirectory under the /etc/firmware directory. The second file contains a small description of the firmware, the maintainer, and the location where to find more details.

If you use pkg_info command to see what packages are installed, the firmware will show up nicely as well

# pkg_info
gettext-runtime-1.0 GNU gettext runtime libraries and programs
intel-firmware-20260512v0 microcode update binaries for Intel CPUs
libiconv-1.19       character set conversion library
libsodium-1.0.22    library for network communications and cryptography
quirks-7.194        exceptions to pkg_add rules
updatedb-0p0        pkg_add speed up cache
vim-9.2.843         vi clone with many additional features
vmm-firmware-1.16.3p1 firmware binary images for vmm(4) driver

Examples of using fw_update

To display the currently installed firmware on your system, run it with the -l option.

# fw_update -l
intel
vmm

To see the files that would be downloaded, combine options -F and -l.

# fw_update -F -l
http://firmware.openbsd.org/firmware/7.9/SHA256.sig
http://firmware.openbsd.org/firmware/7.9/intel-firmware-20260512v0.tgz
http://firmware.openbsd.org/firmware/7.9/vmm-firmware-1.16.3p1.tgz

Manually deleting firmware is easy as well.

# fw_update -d intel
fw_update: delete intel

Need the firmware again? Just run it without any arguments.

# fw_update
fw_update: add intel; update none; keep vmm

Now you know the most important parts of how fw_update operates.