Update main docs

static/docs/main/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: d5aac98cdcf95f901be68eb89c0c7153
+config: 7c31dffbf408f08559eea510cf2c0bc8
 tags: 645f666f9bcd5a90fca523b33c5a78b7

static/docs/main/_sources/contents/boot-management.rst.txt

@@ -0,0 +1,138 @@
+===============
+Boot Management
+===============
+
+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
+<https://www.suse.com/c/uefi-secure-boot-details/>`_ 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`.
+
+.. code-block: yaml
+
+   warewulf:
+     grubboot: true
+
+Nodes which are not known to Warewulf are booted with the shim/grub from the
+Warewulf server host.
+
+Secure boot
+-----------
+
+.. 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 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.
+
+Install shim and efi
+--------------------
+
+`shim.efi` and `grub.efi` must be installed in the container for it to be
+booted by GRUB.
+
+.. code-block:: console
+
+  # wwctl container shell leap15.5 
+  [leap15.5] Warewulf> zypper install grub2 shim
+
+  # wwctl container shell rocky9
+  [rocky9] Warewulf> dnf install shim-x64.x86_64 grub2-efi-x64.x86_64
+
+These packages must also be installed on the Warewulf server host to enable
+node discovery using GRUB.
+
+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"];
+    }
+
+Warewulf delivers the initial `shim.efi` and `grub.efi` via http as taken
+directly from the node's assigned container.

static/docs/main/_sources/contents/security.rst.txt

@@ -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 multiple 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
 =======
 

static/docs/main/_sources/index.rst.txt

@@ -18,6 +18,7 @@ Welcome to the Warewulf User Guide!
    Warewulf Initialization <contents/initialization>
    Container Management <contents/containers>
    Kernel Management <contents/kernel>
+   Boot Management <contents/boot-management>
    Node Configuration <contents/nodeconfig>
    Node Profiles <contents/profiles>
    Warewulf Overlays <contents/overlays>

static/docs/main/_static/graphviz.css

@@ -0,0 +1,19 @@
+/*
+ * graphviz.css
+ * ~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- graphviz extension.
+ *
+ * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+img.graphviz {
+    border: 0;
+    max-width: 100%;
+}
+
+object.graphviz {
+    max-width: 100%;
+}

static/docs/main/contents/background.html

@@ -7,6 +7,7 @@
   <title>Background &mdash; Warewulf User Guide main documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
       <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
+      <link rel="stylesheet" type="text/css" href="../_static/graphviz.css?v=eafc0fe6" />
 
 
     <link rel="shortcut icon" href="../_static/favicon.png"/>
@@ -58,6 +59,7 @@
 <li class="toctree-l1"><a class="reference internal" href="initialization.html">Warewulf Initialization</a></li>
 <li class="toctree-l1"><a class="reference internal" href="containers.html">Container Management</a></li>
 <li class="toctree-l1"><a class="reference internal" href="kernel.html">Kernel Management</a></li>
+<li class="toctree-l1"><a class="reference internal" href="boot-management.html">Boot Management</a></li>
 <li class="toctree-l1"><a class="reference internal" href="nodeconfig.html">Node Configuration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="profiles.html">Node Profiles</a></li>
 <li class="toctree-l1"><a class="reference internal" href="overlays.html">Warewulf Overlays</a></li>