From 2214aea474ec57345dbd98e0f5e2d6bd7a970c1f Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Fri, 18 Dec 2020 09:29:47 -0500
Subject: [PATCH] Add a bootupd section (#203)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Let's describe the status quo.

Co-authored-by: Benjamin Gilbert <bgilbert@backtick.net>
Co-authored-by: Timothée Ravier <travier@redhat.com>

Co-authored-by: Benjamin Gilbert <bgilbert@backtick.net>
Co-authored-by: Timothée Ravier <travier@redhat.com>
---
 modules/ROOT/nav.adoc                      |  1 +
 modules/ROOT/pages/bootloader-updates.adoc | 74 ++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 modules/ROOT/pages/bootloader-updates.adoc

diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
index 21c8a3df..efc6919c 100644
--- a/modules/ROOT/nav.adoc
+++ b/modules/ROOT/nav.adoc
@@ -34,6 +34,7 @@
 ** OS updates
 *** xref:update-streams.adoc[Update Streams]
 *** xref:auto-updates.adoc[Auto-Updates]
+*** xref:bootloader-updates.adoc[Bootloader Updates]
 ** Troubleshooting
 *** xref:manual-rollbacks.adoc[Manual Rollbacks]
 *** xref:access-recovery.adoc[Access Recovery]
diff --git a/modules/ROOT/pages/bootloader-updates.adoc b/modules/ROOT/pages/bootloader-updates.adoc
new file mode 100644
index 00000000..c882d5d4
--- /dev/null
+++ b/modules/ROOT/pages/bootloader-updates.adoc
@@ -0,0 +1,74 @@
+= Updating the bootloader
+
+== bootupd
+
+Updating the bootloader is not currently automatic.  The https://github.com/coreos/bootupd/[bootupd]
+project is included in Fedora CoreOS and may be used for manual updates.
+
+This is usually only relevant on bare metal scenarios, or virtualized
+hypervisors that support Secure Boot.  An example reason to update the
+bootloader is for https://eclypsium.com/2020/07/29/theres-a-hole-in-the-boot/[the BootHole vulnerability].
+
+At the moment, only the EFI system partition (i.e. not the BIOS MBR) can be updated by bootupd.
+
+Inspect the system status:
+
+[source,bash]
+----
+# bootupctl status
+Component EFI
+  Installed: grub2-efi-x64-1:2.04-31.fc33.x86_64,shim-x64-15-8.x86_64
+  Update: At latest version
+#
+----
+
+If an update is available, use `bootupctl update` to apply it; the
+change will take effect for the next reboot.
+
+[source,bash]
+----
+# bootupctl update
+...
+Updated: grub2-efi-x64-1:2.04-31.fc33.x86_64,shim-x64-15-8.x86_64
+#
+----
+
+.Example systemd unit to automate bootupd updates
+[source,yaml]
+----
+variant: fcos
+version: 1.1.0
+systemd:
+  units:
+    - name: custom-bootupd-auto.service
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Bootupd automatic update
+
+        [Service]
+        ExecStart=/usr/bin/bootupctl update
+        RemainAfterExit=yes
+
+        [Install]
+        WantedBy=multi-user.target
+----
+
+=== Using images that predate bootupd
+
+Older CoreOS images that predate the existence of bootupd need
+an explicit "adoption" phase.  If `bootupctl status` says the component
+is `Adoptable`, perform the adoption with `bootupctl adopt-and-update`.
+
+[source,bash]
+----
+# bootupctl adopt-and-update
+...
+Updated: grub2-efi-x64-1:2.04-31.fc33.x86_64,shim-x64-15-8.x86_64
+#
+----
+
+=== Future versions may default to automatic updates
+
+It is possible that future Fedora CoreOS versions may default
+to automating bootloader updates similar to the above.