Use fwupd to deploy Linux firmware updates and more

The fwupd project is an open source framework that allows end users to update firmware on thousands of different devices. Although it was initially designed for the laptop and desktop use case, it is now being used on everything from Chromebooks, IoT devices, mobile phones, and headless servers in datacenters.

While the desktop UX flow of pop-up notifications, graphical application buttons, and progress bars is fully implemented in Red Hat Enterprise Linux (RHEL), the "embedded" use cases where firmware is being auto-deployed to hundreds of servers in a datacenter, or thousands of edge nodes buried under the ground is less well defined. Rather than trying to cater for every possible use case, we instead made it possible to build a lightweight policy agent written in an existing high-level language with the desired customer business logic. This might include something like "download metadata and updates from a NFS server, deploy the update to 50% of devices on each day."

Although updating firmware is the primary focus of fwupd, there is also another equally important task it performs on every machine start: calculating the platform security level. These checks build a Host Security Index ranging from 0 (critically insecure) to 4 (very secure) on supported machines, which allows UI components like gnome-control-center to show high-level translated issues to the end user (as shown in Figure 1)—some of which can be fixed by fwupd automatically. These might include UEFI SecureBoot being turned off, or a misconfiguration of the BootGuard configuration by the OEM. If the Host Security Index changes, for example, from HSI-3 to HSI-0, then this should cause some kind of notification for investigation as the security level of the platform has critically degraded.

Vendor update process

The firmware updates themselves are uploaded by the OEM or ODM vendor to the Linux Vendor Firmware Service. There, they are verified, analyzed, checked, signed and then added to a metadata catalog that is downloaded by a fwupd front end (such as gnome-software GUI, or fwupdmgr on the command line) and then sent to the fwupd daemon over a D-Bus socket. The daemon then processes the metadata, calculating any ordering dependencies and checking system requirements before offering the client a list of possible firmware updates for each enumerated device.

Each update payload archive is then downloaded by the front-end client at a convenient time, possibly using idle bandwidth. The archive is then sent to the daemon over a socket, where the daemon decompresses the archive, verifies the payload is designed for the target device, re-checks any requirements, and then gets ready to deploy the payload onto the device. The user is notified of any required action. This might be opening the laptop lid or removing then reinserting the USB cable; in most cases, no manual interaction is required. The update is then either deployed to the device "live" (typical for USB devices) or a reboot is scheduled to perform the update "offline"—typically for UEFI updates. The device will return with the new firmware version installed, and fwupd will then record the failure or success in its internal database.

Using a service like Ansible and the existing CLI tools like fwupdmgr works well, but sometimes an agent running on the actual machine is a more appropriate method—either from a scalability point of view or so that it can work alongside existing (perhaps proprietary) tools running on the host.

Parsing console output

The simplest way to interact with fwupd as a developer is to use the existing CLI tools and then scrape the stdout output in JSON format. For example:

$ fwupdmgr get-devices --json
{
  "Devices": [
    {
      "Name": "USB2.0 Hub",
      "DeviceId": "7622d5fdbf1d1e08138156da7d83bf693986ad16",
      "ParentDeviceId" : "b5540761dfe33d9abccd3bb21f1d725f9e69f541",
      "CompositeId" : "b5540761dfe33d9abccd3bb21f1d725f9e69f541",
      "InstanceIds": [
        "USB\\VID_17EF&PID_3080",
        "USB\\VID_17EF&PID_3080&REV_5163",
        "USB\\VID_17EF&PID_3080&HUB_20",
        "USB\\VID_17EF&PID_3080&SPI_C220",
        "USB\\VID_17EF&PID_3080&SPI_C220&REV_5163",
        "USB\\VID_17EF&PID_3080&DEV_VL820Q7"
      ],
      "Guid": [
        "8ee94f0e-9b44-596a-bdd9-6f90401664cc",
        "35199e34-cf82-5b09-9287-622d225056e4",
        "0987e3c9-b1ee-5763-ac6e-51329b034e4b",
        "163cea66-5a78-58af-80ba-21be960aae5c",
        "c7def18d-66ae-5531-924b-2020c3638181"
      ],
      "Summary": "USB 3.x hub",
      "Plugin": "vli",
      "Protocol" : "com.vli.usbhub",
      "Flags": [
        "updatable",
        "registered",
        "can-verify",
        "can-verify-image",
        "dual-image",
        "self-recovery",
        "add-counterpart-guids",
        "unsigned-payload"
      ],
      "Vendor": "VIA Labs, Inc.",
      "VendorId" : "USB:0x17EF",
      "Version": "51.63",
      "VersionFormat" : "bcd",
      "VersionRaw": 20835,
      "Icons": [
        "usb-hub"
      ],
      "InstallDuration" : 15,
      "Created": 1686048073
    },
…

Most of the fwupdmgr commands (e.g., get-releases, get-updates, get-remotes) can display the JSON output like above. The format is API stable and fields will only be added in the future. There are obvious downsides to consuming the information like this; it's not efficient for the application to spawn several new fwupdmgr processes, each of which talks to the daemon using D-Bus and converts the output to JSON for it to be parsed back into memory-loaded objects. We also don't get any information about what the daemon is doing, as it might not already be running. The daemon can also auto-quit on idle, so it might take a few seconds to start.

There has to be a much better way to communicate with the daemon directly, perhaps just using D-Bus directly. Using raw D-Bus calls would work very well. However, it would be very verbose and error prone—you'd have to be comfortable unwrapping dictionaries of dictionaries (of dictionaries!) and handling all the type conversions manually. It's also non-trivial to send a file descriptor using raw D-Bus, and that's what we'll have to do when updating the metadata and deploying firmware onto devices.

Using higher-level languages

With GObject introspection, we can use the libfwupd library (written in C) from any higher-level language like Go, Python, or even JavaScript. The C library carefully defines the memory ownership of each parameter and return value so that the higher-level language can safely call into the C interface. For instance, in Python:

import gi
gi.require_version("Fwupd", "2.0")
from gi.repository import Fwupd
from gi.repository import Gio
client = Fwupd.Client.new()
client.set_feature_flags(Fwupd.FeatureFlags.NONE)
cancellable = Gio.Cancellable.new()
for dev in client.get_devices(cancellable):
    print(f"{dev.get_id()}: {dev.get_name()}")

...gives us:

$ ./hardware.py
7622d5fdbf1d1e08138156da7d83bf693986ad16: USB2.0 Hub
b0d4430dfa6bde9f0c22680df36dbc8c15c80753: BootGuard Configuration
a45df35ac0e948ee180fe216a5f703f32dda163f: System Firmware
362301da643102b9f38477387e2193e57abaa590: UEFI dbx

All the data available in the JSON dump is available, as are the same helpers that fwupd uses to filter and query devices. The API docs can be found online with each method, signal, and property documented. Using this API, it is possible to enable remotes, send files using file descriptors, and update device firmware. Signals can be connected using async mainloop code like client.connect("notify::percentage", _percentage_cb), which even allows handling the progress dialogs and interactive user requests.

A more useful example is to update the UEFI DBX list to mitigate the BlackLotus security issue:

# the SHA1 is the Device ID for the UEFI dbx device
client.install("362301da643102b9f38477387e2193e57abaa590",
               "/usr/share/dbxtool/DBXUpdate-20230509-x64.cab",
               Fwupd.InstallFlags.ALLOW_REINSTALL,
               cancellable)
print(dev.get_update_state())
#<enum FWUPD_UPDATE_STATE_NEEDS_REBOOT of type Fwupd.UpdateState>

This shows deploying the update onto the local machine and then getting the device update state, which indicates that a reboot is required before the device version is updated to the new value. Notably, before deploying the update, fwupd will also check the contents of the EFI System Partition to ensure the update is safe to apply.

Querying platform security attributes

Although some fwupd security attribute information is available in Red Hat Lightspeed, it's also available from the JSON output, the D-Bus interface, and using GObject Introspection—just like the device data. For example, on the console, the fwupdmgr security output shows sections for each HSI security level. Each level has attributes, each with a status that indicates either a pass or fail. On most server, desktop, and laptop systems, this would look similar to what is shown in Figure 2.

But with fwupdmgr security --json:

…
{
  "AppstreamId" : "org.fwupd.hsi.EncryptedRam",
  "Created": 1686056222,
  "HsiLevel": 4,
  "HsiResult": "not-supported",
  "Name": "Encrypted RAM",
  "Description": "Encrypted RAM makes it impossible for information that is stored in device memory to be read if the memory chip is removed and accessed.",
  "Plugin": "cpu",
  "Uri" : "https://fwupd.github.io/libfwupdplugin/hsi.html#org.fwupd.hsi.EncryptedRam",
  "Guid": [
    "b9a2dd81-159e-5537-a7db-e7101d164d3f",
    "30249f37-d140-5d3e-9319-186b1bd5cac3",
    "a45b0522-5722-54bd-b802-86cd044262df",
    "7b9b6e8c-226c-5db6-86cb-ea3187578013"
  ]
}
…

or with GObject Introspection:

for attr in client.get_host_security_attrs(cancellable):
    print(f"{attr.to_string()}")

Conclusion

The fwupd project is a mature, safe, and reliable service that can easily be integrated into existing security endpoint solutions and deployment agents. Using three different methods, developers can enumerate devices, query security levels, and control the fwupd daemon to deploy firmware updates.