From 0808f76317a90d7b60c117243e042d805f1f971d Mon Sep 17 00:00:00 2001 From: Christian Goll Date: Mon, 14 Aug 2023 17:26:58 +0200 Subject: [PATCH] added Documentation for grub boot Signed-off-by: Christian Goll --- userdocs/conf.py | 2 +- userdocs/contents/grub.rst | 131 +++++++++++++++++++++++++++++++++ userdocs/contents/security.rst | 7 +- userdocs/index.rst | 1 + 4 files changed, 139 insertions(+), 2 deletions(-) create mode 100644 userdocs/contents/grub.rst diff --git a/userdocs/conf.py b/userdocs/conf.py index b03f4737..92c28443 100644 --- a/userdocs/conf.py +++ b/userdocs/conf.py @@ -14,7 +14,7 @@ release = 'main' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.autosectionlabel'] +extensions = ['sphinx.ext.autosectionlabel','sphinx.ext.graphviz'] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] diff --git a/userdocs/contents/grub.rst b/userdocs/contents/grub.rst new file mode 100644 index 00000000..80b3d463 --- /dev/null +++ b/userdocs/contents/grub.rst @@ -0,0 +1,131 @@ +=========== +Use of Grub +=========== + +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 bootm the field `boot method` has +to be set to `grub` at least for the `default` profile in `nodes.conf`. +This can also be done with the command + +.. code-block:: console + + # wwctl profile set default --bootmethod grub + + +Boot process +============ + +The boot process can be summarized with following diagram + +.. graphviz:: + + digraph foo { + node [shape=box]; + subgraph boot { + "EFI" [label="EFI",row=boot]; + "Shim" [label="Shim",row=boot]; + "Grub" [label="Grub",row=boot]; + "Kernel" [label="kernel",row=boot]; + EFI -> Shim[label="Check for Microsoft signature"]; + Shim -> Grub[label="Check for Distribution signature"]; + Grub->Kernel[label="Check for Distribution or MOK signature"]; + } + } + +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. + +For the case when the node is unknown to warewulf or +can't be identified during the `tFTP`` boot phase, the binaries are +extracted from the container defined in the `default` profile. + +PXE/tFTP boot +------------- + +The standard network boot process with `grub` and `iPXE` has following steps + +.. graphviz:: + + 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|extracted from container of default profile}"]; + grub[shape=record label="{grubx64.efi | name hardcoded in shim.efi|extracted from container of default profile}"] + 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"]; + } + +As the tFTP server is independent of warewulf, the `shim` and `grub` EFI binaries +for the tFTP server are copied from the container defined in the `default` profile. +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. + +http boot +--------- + +Modern EFI systems have the possibility to directly boot per http. The flow diagram +is the following: + +.. graphviz:: + + digraph G{ + node [shape=box]; + efi [shape=record label="{EFI|boots from URI defined in filename}"]; + shim [shape=record label="{shim.efi|replaces shim.efi with grubx64.efi in URI|extracted from node container}"]; + grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from node container}"] + kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node container"]; + efi->shim [label="http"]; + shim->grub [label="http"]; + 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 \ No newline at end of file diff --git a/userdocs/contents/security.rst b/userdocs/contents/security.rst index 1f585de1..c016a1b4 100644 --- a/userdocs/contents/security.rst +++ b/userdocs/contents/security.rst @@ -55,7 +55,7 @@ when a user lands on a compute node, there is generally nothing stopping them from spoofing a provision request and downloading the provisioned raw materials for inspection. -In Warewulf there are two ways to secure the provisioning process: +In Warewulf there are ways to secure the provisioning process: #. The provisioning connections and transfers are not secure due to not being able to manage a secure root of trust through a PXE @@ -77,6 +77,11 @@ In Warewulf there are two ways to secure the provisioning process: provision and communicate with requests from that system matching that asset tag. +#. When the nodes are booted via `shim` and `grub` Secure Boot can be + enabled. This means that the nodes only boot the kernel which is + provided by the distributor and also custom complied modules can't + be loaded. + Summary ======= diff --git a/userdocs/index.rst b/userdocs/index.rst index 71fb9da5..ab2f65c3 100644 --- a/userdocs/index.rst +++ b/userdocs/index.rst @@ -18,6 +18,7 @@ Welcome to the Warewulf User Guide! Warewulf Initialization Container Management Kernel Management + Boot Management Node Configuration Node Profiles Warewulf Overlays