docs/general/mdraid-esp: create guide for redundant ESP with mdraid

docs/general/mdraid-esp.rst

@@ -0,0 +1,67 @@
+Managing Redundant ESPs with mdraid
+===================================
+
+On a multi-device system, having multiple, redundant EFI system partitions may
+be desirable. This can be achieved by using a :zbm:`post-generation hook <contrib/esp-sync.sh>`
+to copy the generated ZFSBootMenu images between ESPs, but that requires generating
+images yourself.
+
+Using Linux's software RAID capabilities can allow for seamless and automatic ESP
+redundancy, without requiring scripts to update each ESP.
+
+1. Make an EFI System Partition on each disk::
+
+    ESP_DISKS="/dev/sda /dev/sdb"
+    for disk in $ESP_DISKS; do
+        sgdisk -n "1:1m:+512m" -t "1:ef00" "$disk"
+    done
+
+2. Create the mdraid array::
+
+    mdadm --create --verbose --level 1 --metadata 1.0 \
+        --homehost any --raid-devices 2 /dev/md/esp \
+        /dev/sda1 /dev/sdb1
+    mdadm --assemble --scan
+    mdadm --detail --scan >> /etc/mdadm.conf
+
+.. note::
+
+   Depending on the distribution, additional setup may be required to assemble the
+   mdraid array on boot. Consult your distribution's documentation for more information.
+
+3. Format the array as ``vfat``, create an fstab entry, and mount::
+
+    mkfs.vfat -F32 /dev/md/esp
+
+    cat << EOF >> /etc/fstab
+    /dev/md/esp /boot/efi vfat defaults 0 0
+    EOF
+
+    mkdir -p /boot/efi
+    mount /boot/efi
+
+4. Install ZFSBootMenu in ``/boot/efi`` as desired.
+
+If adding boot entries with ``efibootmgr``, add entries for each disk in the mdraid array.
+
+.. note::
+
+    This configuration exploits the fact that, with version 1.0, ``mdraid``
+    metadata will be written to the *end* of each partition. Newer metadata
+    versions would be written to the beginning of each partition, and the
+    system firmware would fail to recognize each component as a valid EFI
+    system partition.
+
+    In general, allowing systems to directly access the constituent partitions
+    of a Linux software RAID volume is inadvisable. However, the usual concerns
+    about data integrity do not generally apply to mirroring of the EFI system
+    partition. First, the firmware will generally read, but not write, the
+    contents of these partitions; under normal circumstances, the only
+    modifications made to the EFI system partitions will be by the Linux system
+    that assembles them into an array. Second, if the firmware *does* commit
+    any unintended writes to the partition from which it boots, inconsistencies
+    can be reconciled with periodic resilvering in the host Linux installation.
+    Finally, the contents of an EFI system partition are almost never critical.
+    Unintended corruption of your EFI system partition could potentially
+    prevent your system from booting, but the likelihood of such corruption is
+    low and the partition can generally be trivially recovered in any event.

docs/index.rst

@@ -57,6 +57,7 @@
   general/tailscale
   general/uefi-booting
   general/grub-migration
+  general/mdraid-esp
 
 .. toctree::
   :caption: Installation Guides