Add a bootupd section

Let's describe the status quo.

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

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]

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.