Merge pull request #1245 from Dasharo/freebsd-fwupd-capsules

mkopec · web-flow · commit 642d7bc81512 · 2026-03-31T18:07:59.000+02:00
fwupd guide for FreeBSD
diff --git a/docs/kb/fwupd.md b/docs/kb/fwupd.md
@@ -11,27 +11,27 @@ The `fwupd` daemon relies on the Linux Vendor Firmware Service (LVFS)
 for distributing and managing the firmware binaries to the users.
 
 !!! note
-     `fwupd` depends on
+     The use of `fwupd` for firmware updates depends on
      [Capsule Updates](../guides/capsule-update.md)
-     support. Refer to the "Firmware update" section of your device
-     documentation (like [this one](../unified/novacustom/firmware-update.md)).
+     support. Check that your device and its firmware are listed in the
+     ["Supported devices" section](../guides/capsule-update.md#supported-devices)
+     there.
 
 ## Firmware Update Prerequisites
 
 ### Intel ME
 
-This only applies to devices with an Intel Management Engine that are not fused
-using the [Dasharo Trust Root](../glossary.md#dasharo-trustroot)
-technology, and use Dasharo versions released before 2026. Check your release
-notes to verify if the step is required.
+This only applies to devices with the Intel Management Engine that are not fused
+using the [Dasharo Trust Root](../glossary.md#dasharo-trustroot) technology and
+don't yet use Capsules V2.
 
 Intel Management Engine needs to be disabled manually to successfully perform an
 fwupd update. Failing to do so won't do any harm to the system, but the update
 will be rejected.
 
-Intel ME needs to be switched to the `Disabled (HAP)` state using the Setup Menu
-to perform the update. It cannot be done automatically by fwupd. Afterwards,
-Intel ME needs to be manually turned back on if desired.
+Intel ME needs to be switched to the `Disabled (HAP)` state in the Setup Menu
+to perform the update. This step cannot be done automatically by fwupd.
+Afterwards, Intel ME needs to be manually turned back on if desired.
 
 Check [Intel Management Engine Options](../dasharo-menu-docs/dasharo-system-features.md#intel-management-engine-options)
 documentation for details on how to set ME mode to `Disabled (HAP)`.
@@ -42,7 +42,7 @@ for more context.
 ### Charger connected
 
 On battery-powered devices (laptops), the AC charger must be connected
-before running fwupdmgr to start the update. It must be connected
+before running `fwupdmgr` to start the update. It must be connected
 for the whole duration of the update, until the device boots back up normally.
 
 ## Usage
@@ -63,21 +63,21 @@ are met.
 ### CLI
 
 For more advanced users or in a more lightweight
-DEs/WMs `fwupdmgr` can be used in the terminal.
+DEs/WMs `fwupdmgr` command can be used in the terminal.
 
 #### Installation
 
 Most Operating Systems come with fwupd preinstalled and use
 it to perform firmware updates.
 
 === "Windows"
-    Dasharo Capsule Updates using fwupdmgr are not currently supported on
+    Dasharo Capsule Updates using `fwupdmgr` are not currently supported on
     Windows. If that is the only Operating System you wish to use, other update
     methods need to be considered.
 
 === "Ubuntu"
-    Check if fwupdmgr is installed. Executing the command should
-    print the versions of all fwupdmgr components:
+    Check if `fwupdmgr` is installed. Executing the command should
+    print the versions of all `fwupdmgr` components:
 
     ```bash
     $ fwupdmgr --version
@@ -108,8 +108,8 @@ it to perform firmware updates.
     ```
 
 === "Fedora"
-    Check if fwupdmgr is installed. Executing the command should
-    print the versions of all fwupdmgr components:
+    Check if `fwupdmgr` is installed. Executing the command should
+    print the versions of all `fwupdmgr` components:
 
     ```bash
     $ fwupdmgr --version
@@ -139,12 +139,12 @@ it to perform firmware updates.
 
 === "QubesOS"
 
-    To use fwupdmgr on QubesOS, the program needs to be run on
+    To use `fwupdmgr` on QubesOS, the program needs to be run on
     the `dom0` qube, and it requires an internet connection.
-    For that reason, a fwupdmgr wrapper for QubesOS exists,
+    For that reason, a `fwupdmgr` wrapper for QubesOS exists,
     that sets up the network tunnels for the firmware update
-    downloads to be possible from dom0.
-    The qubes-fwupdmgr package should be installed out of the box.
+    downloads to be possible from `dom0`.
+    The `qubes-fwupdmgr` package should be installed out of the box.
     Executing the command should print the help screen:
 
     ```bash
@@ -182,9 +182,76 @@ it to perform firmware updates.
         ```
     </details>
 
+=== "FreeBSD"
+
+    !!! warning
+        `fwupd` on FreeBSD is very much work in progress as of March 2026.  The
+        basic elements are there, but user experience may be far from perfect.
+        In particular, not all functionality is available (e.g., `fwupd` won't
+        reboot for you, update may be reported as "in progress" after it has
+        been applied) or works reliably (may complain about missing ESP,
+        although this error may be gone on second try or after restarting
+        `fwupd`).  In addition to that, FreeBSD loader and/or kernel has issues
+        with ESRT which may prevent `uefi_capsule` plugin of `fwupd` from
+        working.
+
+    `fwupd` is available in ports, but the version there lacks UEFI capsules.
+    The necessary changes are being [upstreamed][D55590], until then a
+    relatively complicated setup in necessary to have a chance of firmware
+    updates working.  The following instructions assume the system isn't
+    configured much, make adjustments to not overwrite existing configuration if
+    that's not the case.
+
+    Start by switching from "quaterly" to "latest" packages to have an already
+    updated `bsdisks` (necessary to find ESP):
+
+    ```terminal
+    # mkdir -p /usr/local/etc/pkg/repos
+    # sed 's!/quarterly!/latest!' /etc/pkg/FreeBSD.conf > /usr/local/etc/pkg/repos/FreeBSD.conf
+    ```
+
+    Then install `fwupd`, `bsdisks` and various build dependencies.  A few ports
+    will be reinstalled later, this step is just to reuse binary packages and
+    not build everything from sources.  Run the following command:
+
+    ```terminal
+    # pkg install fwupd bsdisks meson help2man noto-sans py311-Jinja2 py311-pygobject py311-pangocffi gettext-tools pkgconf vala dbus cmake ninja git
+    ```
+
+    Now get the version of ports with necessary fixes and reinstall the
+    packages (cloning will take time, building can too; there will also be a few
+    dialogs about port options, just agreeing should do but can choose to not
+    build documentation):
+
+    ```terminal
+    # git clone --branch=fwupd-2026 --depth=1 --filter=blob:none https://github.com/3mdeb/freebsd-ports /usr/ports
+    # make -C /usr/ports/devel/efivar/ deinstall
+    # make -C /usr/ports/devel/gnu-efi/ reinstall
+    # make -C /usr/ports/sysutils/fwupd-efi/ reinstall
+    # make -C /usr/ports/sysutils/fwupd/ reinstall
+    ```
+
+    `fwupd` communicates with `bsdisks` over D-Bus, so it must be running
+    (`fwupdmgr` also depends on D-Bus, otherwise using `fwupdtool` as root is
+    the only option).  It can be enabled permanently and then launched like
+    this:
+
+    ```terminal
+    # echo 'dbus_enable="YES"' >> /etc/rc.conf
+    # service dbus start
+    ```
+
+    This is how to start D-Bus temporarily:
+
+    ```terminal
+    # service dbus onestart
+    ```
+
+[D55590]: https://reviews.freebsd.org/D55590
+
 ### Checking the current firmware version
 
-=== "Ubuntu, Fedora"
+=== "Ubuntu, Fedora, FreeBSD"
     To check the currently used firmware version, run the following command
 
     ```bash
@@ -212,7 +279,7 @@ it to perform firmware updates.
     </details>
 
 === "QubesOS"
-    To check for available updates for your device, run the following command
+    To check the currently used firmware version, run the following command
 
     ```bash
     $ sudo qubes-fwupdmgr get-devices
@@ -246,7 +313,7 @@ it to perform firmware updates.
             UpdateState         2
         ```
         As of QubesOS R4.2.3, the firmware version is not interpreted correctly
-        by fwupdmgr.
+        by `fwupdmgr`.
         As a fallback on Dasharo firmware, use `dmidecode` to verify the firmware version.
         Run:
         ```bash
@@ -260,7 +327,7 @@ it to perform firmware updates.
 
 ### Checking for updates
 
-=== "Ubuntu, Fedora"
+=== "Ubuntu, Fedora, FreeBSD"
     To check for available updates for your device, run the following commands
 
     ```bash
@@ -330,7 +397,7 @@ it to perform firmware updates.
     ```
 
     !!! warning
-        As of QubesOS R4.3 on 02-2026, qubes-fwupdmgr might not work correctly
+        As of QubesOS R4.3 on 02-2026, `qubes-fwupdmgr` might not work correctly
         and the updates on LVFS may not be found using this tool. Refer to
         [troubleshooting](#no-updates-available-qubesos).
 
@@ -398,18 +465,52 @@ are met.
     ```
 
     !!! warning
-        As of QubesOS R4.3 on 02-2026, qubes-fwupdmgr might not work correctly
+        As of QubesOS R4.3 on 02-2026, `qubes-fwupdmgr` might not work correctly
         and the updates on LVFS may not be found using this tool. Refer to
         [troubleshooting](#no-updates-available-qubesos).
 
+=== "FreeBSD"
+    To update your firmware, run the following commands:
+
+    ```terminal
+    # fwupdmgr refresh
+    # fwupdmgr update --no-reboot-check
+    # reboot
+    ```
+
+    <details><summary>Example of an update process:</summary>
+        ```
+        # fwupdmgr update --no-reboot-check
+        Devices with no available firmware updates:
+        • UEFI dbx
+        • SSDPR-PX600-250-80
+        ╔══════════════════════════════════════════════════════════════════════════════╗
+        ║ Upgrade System Firmware from 1.0.0 to 1.0.1?                                 ║
+        ╠══════════════════════════════════════════════════════════════════════════════╣
+        ║ New Dasharo firmware release for the NovaCustom Meteor Lake laptops          ║
+        ║                                                                              ║
+        ║ with integrated graphics, featuring numerous bug fixes, performance          ║
+        ║                                                                              ║
+        ║ improvements and stability fixes.                                            ║
+        ║                                                                              ║
+        ║ V54x_6x_TU must remain plugged into a power source for the duration of the   ║
+        ║ update to avoid damage.                                                      ║
+        ╚══════════════════════════════════════════════════════════════════════════════╝
+        Perform operation? [Y|n]: y
+        Waiting…                 [***************************************]
+        Successfully installed firmware
+        Do not turn off your computer or remove the AC adapter while the update is in progress.
+        ```
+    </details>
+
 !!! warning
-    After the command finishes, fwupd will instruct the device to reboot.
+    After the command finishes, a reboot is necessary to apply the update.
     The fwupd UEFI application that performs the update will be booted
-    automatically after a reboot, unless there's user interaction
+    automatically after a reboot, unless there is a user interaction.
     Entering the Setup Menu, Boot Manager, or interfering in any other way will
     abort the update.
     Allow the device to reboot freely, and do not press any buttons until the
-    update finishes.
+    update finishes unless there is a dialog related to the update.
 
     Devices that have an Embedded Controller
     [might stay powered off after the update][dts-ec-update] and need to be
@@ -438,11 +539,28 @@ source. We will use `novacustom_v54x_mtl_igpu_v1.0.1_btg_prod.cab` downloaded fr
         $ sudo fwupdmgr local-install novacustom_v54x_mtl_igpu_v1.0.1_btg_prod.cab
         ```
 
+=== "FreeBSD"
+    To update your firmware using a locally available cabinet file, follow the
+    steps:
+
+    1. Allow updates from untrusted sources
+        ```terminal
+        # printf '[fwupd]\nOnlyTrusted=false\n' > /usr/local/etc/fwupd/fwupd.conf
+        ```
+    2. Perform a local install
+        ```terminal
+        # fwupdmgr local-install --no-reboot-check novacustom_v54x_mtl_igpu_v1.0.1_btg_prod.cab
+        ```
+    3. Reboot to apply the update
+        ```terminal
+        # reboot
+        ```
+
 #### Update troubleshooting
 
 ##### No output from fwupdmgr update
 
-Depending on the version of fwupdmgr, issues like the AC being disconnected on
+Depending on the version of `fwupdmgr`, issues like the AC being disconnected on
 battery-powered devices might not be printed explicitly right away after
 trying to perform an update. In such a case, try running the `get-devices` command
 and look for the `Problems` header and red text under device entries.
@@ -538,12 +656,12 @@ The check for an AC charger being connected in Linux fails when the firmware
 configures a [charging threshold](http://127.0.0.1:8000/unified/novacustom/features/#charge-thresholds)
 for the battery that disconnects the charger once the battery reaches the threshold.
 If the battery is considered full and not charging at the moment, the check in
-fwupdmgr will think the charger is disconnected.
+`fwupdmgr` will think the charger is disconnected.
 
 There are two options to work around this issue:
 
 - Deplete battery charge a couple of percent, so that it
-    doesn't stop charging for the duration of fwupdmgr running the checks.
+  doesn't stop charging for the duration of `fwupdmgr` running the checks.
 - Disable battery charging thresholds in the firmware.
 
 ##### No updates available (QubesOS)
@@ -602,17 +720,26 @@ manually from fwupd.org.
     </details>
 
     This output means the firmware version has changed to the expected one.
-    To manually verify this has really happened, refer to
-    [Checking The Current Firmware Version](#checking-the-current-firmware-version).
 
 === "QubesOS"
-    To update your firmware, run the following commands:
+    `qubes-fwupdmgr` doesn't currently support `get-results` command of
+    `fwupdmgr`.
+
+=== "FreeBSD"
+    The following command is supposed to report update results:
 
     ```bash
-    $ sudo qubes-fwupdmgr refresh
-    $ sudo qubes-fwupdmgr update
+    $ fwupdmgr get-results
     ```
 
+    However, this is likely to not produce any results because fwupd fails to
+    finalize the update.  `fwupdmgr get-devices` incorrectly states that "An
+    update is in progress" along with displaying version that shows the update
+    has already happened.
+
+For another way to verify an update has really happened refer to
+[Checking The Current Firmware Version](#checking-the-current-firmware-version).
+
 #### Update result troubleshooting
 
 ##### Failed to run update on reboot: expected ... and got
@@ -651,14 +778,14 @@ Device Flags:         • Internal device
 ```
 </details>
 
-When that happens after rebooting, instead of am update
+When that happens after rebooting, instead of an update
 progress bar, a message like this will appear on top of the screen:
 
 ```txt
 [FIRMWARE WARNING] Capsule Updates are only supported while Intel ME is in HAP mode!
 ```
 
-Make sure the Intel ME mode in the Setup menu is `Disabled (HAP)`. Refer to the
+Make sure the Intel ME mode in the Setup Menu is `Disabled (HAP)`. Refer to the
 [prerequisites section](#firmware-update-prerequisites) and try again.
 
 ## References
