fwupd - ArchWiki

Jump to content

# fwupd

From ArchWiki

Related articles

- Secure Boot
- Unified Extensible Firmware Interface

fwupd is a simple daemon to allow session software to update device firmware on your local machine. It's designed for desktops, but also usable on phones and headless servers.

Supported devices are listed here and more are to come.

## Installation

Install the fwupd package.

Most peripherals can be updated directly in the OS. However, BIOS/UEFI updates generally require UEFI mode (UpdateCapsule), where the firmware applies the update safely on reboot. See #Setup for UEFI upgrade if you intend such use.

### Graphical front-ends

Certain desktop environments front-end solutions have built-in fwupd support:

- Discover — Software center used with Plasma. With the release of KDE Plasma 5.14, a new fwupd backend has been implemented in KDE Discover for firmware updates. These firmware updates are shown with other system updates. Part of plasma.

  https://apps.kde.org/discover/ || discover

- GNOME Firmware — Application to upgrade, downgrade and reinstall firmware on devices supported by fwupd. It can unlock locked fwupd devices, verify firmware on supported devices and display all releases for a fwupd device.

  https://gitlab.gnome.org/World/gnome-firmware || gnome-firmware

- GNOME Software — Will check for updates periodically and automatically download firmwares in the background on GNOME. After a firmware has been downloaded a popup will be displayed in Gnome Software to perform the update. Part of gnome.

  https://apps.gnome.org/Software/ || gnome-software

## Usage

This article or section needs expansion.

Reason: Need to explain the meaning and usage of the package's other executables and systemd units. (Discuss in Talk:Fwupd)

The package provides a `fwupd.service` which will automatically start the fwupd daemon when the first query is received. [1]

To display all devices detected by fwupd:

    $ fwupdmgr get-devices

Note Listed devices may not be updatable through fwupd (e.g. Intel integrated graphics). Alternative vendor solutions may be provided instead.

To download the latest metadata from the Linux Vendor firmware Service (LVFS):

    $ fwupdmgr refresh

Note This can be done automatically by enabling `fwupd-refresh.timer`.

To list updates available for any devices on the system:

    $ fwupdmgr get-updates

To install updates:

    $ fwupdmgr update

Note

- Updates that can be applied live will be done immediately.
- Updates that run at bootup will be staged for the next reboot.
- The root user may be required to perform certain device updates.
- Some hardware components may not be covered by fwupd and may require updates to be manually applied (such as downloading the required files, flashing them to a USB stick and then manually applying the update). This is specially the case for motherboard (BIOS/UEFI) firmware updates (which go through a process called "Q-Flash" or similar).

## Configuration

### Disable local cache server (passim)

fwupd v1.9.5 from September 2023 introduced a dependency on passim, a local cache server intended to help reduce LVFS bandwidth usage by making each machine able to serve the metadata file it downloads everyday to others[2][3].

passimd is a daemon which listens for connections on port `27500` from any IP addresses (i.e. it listens on `0.0.0.0:27500`). This has led to some criticism regarding the security implications[4][5], and indeed several vulnerabilities were reported just a few weeks later[6][7].

On Arch the request from FS#79614 to make the dependency optional at compile-time was denied because it would require creating a split-package for a library.

As a consequence, if you wish to disable passimd you should follow the advice given by the author[8]: add `P2pPolicy=nothing` to `/etc/fwupd/fwupd.conf` under the `[[fwupd]]` section and mask `passim.service`.

## Setup for UEFI upgrade

Warning An update to your UEFI firmware may discard the current boot loader installation. It may be necessary to recreate the NVRAM entry (for example using efibootmgr) after the firmware update has been installed successfully.

The following requirements should be met:

1. Make sure you are booted in UEFI mode, because it will not work in legacy boot mode.
2. Verify your EFI variables are accessible.
3. Mount your EFI system partition (ESP) properly. `esp` is used to denote the mountpoint in this section.
4. Make sure the optional dependency udisks2 is installed and the associated systemd unit is started before fwupd unit; it will provide UEFI firmware upgrade support.

### Prepare ESP

fwupd will copy all the necessary files over to the `esp`, but for this to work, a basic folder layout must be present on your `esp`; this constitutes the creation of an `EFI` directory on your `esp`:

Note Depending on your boot loader or the presence of other operating systems, this directory may already exist.

    # mkdir esp/EFI/

Warning The `EFI` directory must be in all upper-case; if you used lower-case, fwupd may detect the `esp` as `esp/efi/` and look for `esp/efi/EFI/` instead.

Restart the `fwupd.service` unit afterwards. You can now `fwupdmgr refresh` and `fwupdmgr update`. You will be prompted to reboot (into the firmware updater).

Note On some devices, for example the Lenovo ThinkPad P50 laptop, the firmware updater displays a black screen without any messages—do not panic, and do not interrupt or force-reset the device. After a few seconds, or minutes, depending on the update—the machine will be rebooted back into the operating system.

### Secure Boot

Currently, fwupd relies on shim to chainload the fwupd EFI binary on systems with Secure Boot enabled; for this to work, shim has to be installed correctly.

#### Using your own keys

##### Assisted process with sbctl

You can sign the UEFI executable with sbctl. For an explanation of how to setup sbctl, see Unified Extensible Firmware Interface/Secure Boot with sbctl.

    # sbctl sign -s -o /usr/lib/fwupd/efi/fwupdx64.efi.signed /usr/lib/fwupd/efi/fwupdx64.efi

Then after each update of fwupd, the UEFI executable will be automatically signed, thanks to the sbctl pacman hook (`/usr/share/libalpm/hooks/zz-sbctl.hook`).

Finally, you have to set `DisableShimForSecureBoot` in `/etc/fwupd/fwupd.conf` and restart `fwupd.service`:

    /etc/fwupd/fwupd.conf

    ...

    [uefi_capsule]
    DisableShimForSecureBoot=true

##### Manual process

Alternatively, you can manually sign the UEFI executable used to perform upgrades, which is located in `/usr/lib/fwupd/efi/fwupdx64.efi`. The signed UEFI executable is expected in `/usr/lib/fwupd/efi/fwupdx64.efi.signed`. Using sbsigntools, this can be achieved by running:

    # sbsign --key keyfile --cert certfile /usr/lib/fwupd/efi/fwupdx64.efi

To automatically sign this file when installed or upgraded, a Pacman hook can be used:

    /etc/pacman.d/hooks/sign-fwupd-secureboot.hook

    [Trigger]
    Operation = Install
    Operation = Upgrade
    Type = Path
    Target = usr/lib/fwupd/efi/fwupdx64.efi

    [Action]
    When = PostTransaction
    Exec = /usr/bin/sbsign --key keyfile --cert certfile /usr/lib/fwupd/efi/fwupdx64.efi
    Depends = sbsigntools

Make sure to replace `keyfile` and `certfile` with the corresponding paths of your keys.

Instead of a pacman hook, you can also create a symlink from `/usr/lib/fwupd/efi/fwupdx64.efi` to `/usr/lib/fwupd/efi/fwupdx64.efi.signed`, and add the file to the `EXTRA_SIGN` list in `/etc/sbupdate.conf`.

Finally, you have to set `DisableShimForSecureBoot` in `/etc/fwupd/fwupd.conf` and restart `fwupd.service`:

    /etc/fwupd/fwupd.conf

    ...

    [uefi_capsule]
    DisableShimForSecureBoot=true

Note

- If you set this up before fwupd 1.9, this option is located in `/etc/fwupd/uefi_capsule.conf`.
- If you set this up before fwupd 1.4, be aware of the subtle change to the configuration option name.

See https://github.com/fwupd/fwupd/issues/669 for more information.

## Troubleshooting

### Stuck when rebooting

`fwupdmgr update` reports no error, but the reboot it prompts stuck and holding the power button has no response. Try switching off the power, or press the reset button (on a laptop, it might be a hole on the back) to force-reboot.

### No error but no upgrade on reboot

Symptom: `fwupdmgr update` reports no error and prompts for reboot (e.g., on BIOS update). However, the system reboots normally (or stuck) and the firmware update does NOT happen.

Possible cause: In BIOS settings changing the boot order must be allowed.

Possible other solution if there are multiple updates pending: Try updating packages one at a time. Use the following to select packages:

    $ fwupdmgr update update_ID

(Where `update_ID` is something like `f95c9218acd12697af946874bfe4239587209232`.)

### read-only filesystem error

At least `fwupdmgr` 1.5.2 deduces the wrong mount point if bind is used to mount the EFI system partition to /boot. Consequently it fails to write the UEFI update file to `/boot/EFI/arch/fw` (`fwupdmgr` while it should be written to `esp/EFI/arch/fw`.) This results in a (misleading) `file system is read-only` error message. In case the update was performed by `Discover` (or any other fwupd-capable Update GUI), no error or misleading errors may be shown.

As a workaround, run `umount /boot` first if it was bind-mounted to `esp/EFI/arch` before, then run `fwupdmgr update` to write the UEFI update file to `esp/EFI/arch/fw`, `mount /boot` and reboot the system to perform the UEFI update.

### UEFI ESP partition not detected or configured

If the EFI system partition (ESP) is still not detected after all requirements in #Setup for UEFI upgrade are met, the mount point can be specified manually:

    /etc/fwupd/fwupd.conf

    [fwupd]
    EspLocation=/efi

See the relevant article in the fwupd wiki for additional reasons that this might occur.

Setting the ESP location prevents `fwupdx64.efi` from being installed in unwanted EFI system partitions located on other disks.

### MSR plugin is failing to load

The MSR plugin allows querying the state of DCI, a debugging interface available for Intel CPUs that should be disabled on production machines according to fwupd's documentation.

This plugin needs the `msr` kernel module loaded. `msr` is a built-in kernel module in all the official Arch Linux kernel packages, but unofficial kernel packages might have it as a loadable kernel module. In the latter case, we need to explicitly load the module at boot.

### Failed to load daemon: failed to load engine: No ESP with path

When starts fwupd, it checks the esp location as `EspLocation` from `/etc/fwupd/fwupd.conf`. Modify it to your corresponding setup if encounter this error.

Category:

- Hardware

Hidden category:

- Pages or sections flagged with Template:Expansion

fwupd
Add topic