diff --git a/userdocs/contents/boot-management.rst b/userdocs/contents/boot-management.rst index 572cd33e..4437a39a 100644 --- a/userdocs/contents/boot-management.rst +++ b/userdocs/contents/boot-management.rst @@ -2,10 +2,65 @@ Boot Management =============== -Instead of the iPXE starter a combination of `shim and GRUB `_ -can be used with the advantage that secure boot can be used. That means -that only the signed kernel of a distribution can be booted. This can -be a huge security benefit for some scenarios. +Warewulf uses iPXE to for network boot by default. As a tech preview, support +for GRUB is also available, which adds support for secure boot. + +Booting with iPXE +================= + +.. graphviz:: + + digraph G{ + node [shape=box]; + compound=true; + edge [label2node=true] + bios [shape=record label="{BIOS | boots from DHCP/next-server via TFTP}"] + + subgraph cluster0 { + label="iPXE boot" + iPXE; + ipxe_cfg [shape=record label="{ipxe.cfg|generated for each node}"]; + iPXE -> ipxe_cfg [label="http"]; + } + + bios->iPXE [lhead=cluster0,label="iPXE.efi"]; + + kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node container"]; + ipxe_cfg->kernel[ltail=cluster0,label="http"]; + } + +Booting with GRUB +================= + +Support for GRUB as a network bootloader (replacing iPXE) is available in +Warewulf as a technology preview. + +.. graphviz:: + + digraph G{ + node [shape=box]; + compound=true; + edge [label2node=true] + bios [shape=record label="{BIOS | boots from DHCP/next-server via TFTP}"] + + bios->shim [lhead=cluster1,label="shim.efi"]; + subgraph cluster1{ + label="Grub boot" + shim[shape=record label="{shim.efi|from ww4 host}"]; + grub[shape=record label="{grubx64.efi | name hardcoded in shim.efi|from ww4 host}"] + shim->grub[label="TFTP"]; + grubcfg[shape=record label="{grub.cfg|static under TFTP root}"]; + grub->grubcfg[label="TFTP"]; + } + kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node container"]; + grubcfg->kernel[ltail=cluster1,label="http"]; + } + +Instead of the iPXE starter a combination of `shim and GRUB +`_ can be used with the +advantage that secure boot can be used. That means that only the signed kernel +of a distribution can be booted. This can be a huge security benefit for some +scenarios. In order to enable the grub boot method it has to be enabled in `warewulf.conf`. @@ -14,14 +69,11 @@ In order to enable the grub boot method it has to be enabled in `warewulf.conf`. warewulf: grubboot: true -Nodes which are not known to warewulf will then booted with the shim/grub from -the host on which warewulf is installed. +Nodes which are not known to Warewulf are booted with the shim/grub from the +Warewulf server host. - -Boot process -============ - -The boot process can be summarized with following diagram +Secure boot +----------- .. graphviz:: @@ -38,54 +90,30 @@ The boot process can be summarized with following diagram } } -If secure boot is enabled at every step a signature is checked and the boot process -will fail if this check fails. Also at moment a Shim only includes the key -of one Distribution, which means that every Distribution needs a separate -`shim` and `grub` executable and warewulf extracts these binaries from -the containers. +If secure boot is enabled at every step a signature is checked and the boot +process fails if this check fails. The shim typically only includes the key for +a single operating system, which means that each distribution needs separate +`shim` and `grub` executables. Warewulf extracts these binaries from the +containers. If the node is unknown to Warewulf or can't be identified during +the TFTP boot phase, the shim/grub binaries of the host in which Warewulf is +running are used. -For the case when the node is unknown to warewulf or -can't be identified during the `tFTP`` boot phase, the shim/grub binaries of -the host in which warewulf is running will be used. +Install shim and efi +-------------------- -PXE/tFTP boot -------------- +`shim.efi` and `grub.efi` must be installed in the container for it to be +booted by GRUB. -The standard network boot process with `grub` and `iPXE` has following steps +.. code-block:: console -.. graphviz:: + # wwctl container shell leap15.5 + [leap15.5] Warewulf> zypper install grub2 shim - digraph G{ - node [shape=box]; - compound=true; - edge [label2node=true] - bios [shape=record label="{Bios | boots filename from nextboot per tFTP}"] - subgraph cluster0 { - label="iPXE boot" - iPXE; - ipxe_cfg [shape=record label="{ipxe.cfg|generated for indivdual node}"]; - iPXE -> ipxe_cfg [label="http"]; - } - bios->iPXE [lhead=cluster0,label="filename=iPXE.efi"]; - bios->shim [lhead=cluster1,label="filename=shim.efi"]; - subgraph cluster1{ - label="Grub boot" - shim[shape=record label="{shim.efi|from ww4 host}"]; - grub[shape=record label="{grubx64.efi | name hardcoded in shim.efi|from ww4 host}"] - shim->grub[label="tFTP"]; - grubcfg[shape=record label="{grub.cfg|static under tFTP root}"]; - grub->grubcfg[label="tFTP"]; - } - kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node container"]; - grubcfg->kernel[ltail=cluster1,label="http"]; - ipxe_cfg->kernel[ltail=cluster0,label="http"]; - } + # wwctl container shell rocky9 + [rocky9] Warewulf> dnf install shim-x64.x86_64 grub2-pc.x86_64 -As the tFTP server is independent of warewulf, the `shim` and `grub` EFI binaries -for the tFTP server are copied from the host on which warewulf is running. -This means that for secure boot the distributor e.g. SUSE of the container in -the `default` profile must match the distributor of the container which then -also must be signed by the SUSE key. +These packages must also be installed on the Warewulf server host to enable +node discovery using GRUB. http boot --------- @@ -106,28 +134,5 @@ is the following: grub->kernel [label="http"]; } -The main difference is that the initial `shim.efi` and `grub.efi` are delivered by http with warewulf -and are taken directly from the container assigned to the node. This means that secure boot will work -for containers from different distributors. - -Install shim and efi --------------------- - -The `shim.efi` and `grub.efi` must be installed via the package manager directly into the container. - -Install on SUSE systems -^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: console - - # wwctl container shell leap15.5 - [leap15.5] Warewulf> zypper install grub2 shim - - -Install on EL system -^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: console - - # wwctl container shell rocky9 - [rocky9] Warewulf> dnf install shim-x64.x86_64 grub2-pc.x86_64 +Warewulf delivers the initial `shim.efi` and `grub.efi` via http as taken +directly from the node's assigned container.