Update v4.5.x docs

static/docs/v4.5.x/.buildinfo

@@ -0,0 +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: 000aa872ae49209e7dd10d9c94d85f7f
+tags: 645f666f9bcd5a90fca523b33c5a78b7

static/docs/v4.5.x/_images/graphviz-45530e0b437388de246c86a5b4638e7b3654235b.png.map

@@ -0,0 +1,2 @@
+<map id="G" name="G">
+</map>

static/docs/v4.5.x/_images/graphviz-5cb5701ea7fd182b13828ac567d21b2e09945929.png.map

@@ -0,0 +1,2 @@
+<map id="G" name="G">
+</map>

static/docs/v4.5.x/_images/graphviz-87f2b5a9fa342f42cc8028f4a60d24c3ea795fd3.png.map

@@ -0,0 +1,2 @@
+<map id="foo" name="foo">
+</map>

static/docs/v4.5.x/_images/graphviz-8be43717679b33953ee198ed82f1999c0ddd0b61.png.map

@@ -0,0 +1,2 @@
+<map id="G" name="G">
+</map>

static/docs/v4.5.x/_sources/contents/background.rst.txt

@@ -0,0 +1,38 @@
+==========
+Background
+==========
+
+Warewulf is based on the design of the original Beowulf Cluster design
+(and thus the name, soft\ **WARE** implementation of the beo\
+**WULF**)
+
+The `Beowulf Cluster <https://en.wikipedia.org/wiki/Beowulf_cluster>`_
+design was developed in 1996 by Dr. Thomas Sterling and Dr. Donald
+Becker at NASA. The architecture is defined as a group of similar
+compute worker nodes all connected together using standard commodity
+equipment on a private network segment. The control node (historically
+referred to as the "master" or "head" node) is dual homed (has two
+network interface cards) with one of these network interface cards
+attached to the upstream public network and the other connected to a
+private network which connects to all of the compute worker nodes (as
+seen in the figure below).
+
+.. image:: beowulf_architecture.png
+    :alt: Beowulf architecture
+
+This simple topology is the foundation for creating every scalable HPC
+cluster resource. Even today, almost 30 years after the inception of
+this architecture, this is the baseline architecture that traditional
+HPC systems are built to.
+
+Other considerations for a working HPC-type cluster are storage,
+scheduling and resource management, monitoring, interactive systems,
+etc. For smaller systems, much of these requirements can be managed
+all from a single control node, but as the system scales, it may need
+to have groups of nodes dedicated to these different services.
+
+Warewulf is easily capable of building simple and turnkey HPC
+clusters, to giant massive complex multi-purpose computing clusters,
+through next generation computing platforms.
+
+Anytime a cluster of systems is needed, Warewulf is your tool!

static/docs/v4.5.x/_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/v4.5.x/_sources/contents/configuration.rst.txt

@@ -0,0 +1,182 @@
+======================
+Warewulf Configuration
+======================
+
+The default installation of Warewulf will put all of the configuration
+files into ``/etc/warewulf/``. In that directory, you will find the
+primary configuration files needed by Warewulf.
+
+warewulf.conf
+=============
+
+The Warewulf configuration exists as follows in the current version of
+Warewulf (4.4.0):
+
+.. code-block:: yaml
+
+   WW_INTERNAL: 45
+   ipaddr: 10.0.0.1
+   netmask: 255.255.252.0
+   network: 10.0.0.0
+   warewulf:
+     port: 9873
+     secure: false
+     update interval: 60
+     autobuild overlays: true
+     host overlay: true
+     syslog: false
+   dhcp:
+     enabled: true
+     range start: 10.0.1.1
+     range end: 10.0.1.255
+     systemd name: dhcpd
+   tftp:
+     enabled: true
+     systemd name: tftp
+   nfs:
+     enabled: true
+     export paths:
+     - path: /home
+       export options: rw,sync
+       mount options: defaults
+       mount: true
+     - path: /opt
+       export options: ro,sync,no_root_squash
+       mount options: defaults
+       mount: false
+     systemd name: nfs-server
+   container mounts:
+     - source: /etc/resolv.conf
+       dest: /etc/resolv.conf
+       readonly: true
+
+Generally you can leave this file as is, as long as you set the
+appropriate networking information. Specifically the following
+configurations:
+
+* ``ipaddr``: This is the control node's networking interface
+  connecting to the cluster's **PRIVATE** network. This configuration
+  must match the host's network IP address for the cluster's private
+  interface.
+
+* ``netmask``: Similar to the ``ipaddr``, this is the subnet mask for
+  the cluster's **PRIVATE** network and it must also match the host's
+  subnet mask for the cluster's private interface.
+
+* ``dhcp:range start`` and ``dhcp:range end``: This address range must
+  exist in the network defined above. If it is outside of this
+  network, failures will occur. This specifies the range of addresses
+  you want DHCP to use.
+
+The other configuration options are usually not touched, but they are
+explained as follows:
+
+* ``*:enabled``: This can be used to disable Warewulf's control of a
+  system service. This is useful if you want to manage that service
+  directly.
+
+* ``*:systemd name``: This is so Warewulf can control some of the
+  host's services. For the distributions that we've built and tested
+  this on, these will require no changes.
+
+* ``warewulf:port``: This is the port that the Warewulf web server
+  will be listening on. It is recommended not to change this so there
+  is no misalignment with node's expectations of how to contact the
+  Warewulf service.
+
+* ``warewulf:secure``: When ``true``, this limits the Warewulf server
+  to only respond to runtime overlay requests originating from a
+  privileged port. This prevents non-root users from requesting the
+  runtime overlay, which may contain sensitive information.
+
+  When ``true``, ``wwclient`` uses TCP port 987.
+
+  Changing this option requires rebuilding node overlays and rebooting
+  compute nodes, to configure them to use a privileged port.
+
+* ``warewulf:update interval``: This defines the frequency (in
+  seconds) with which the Warewulf client on the compute node fetches
+  overlay updates.
+
+* ``warewulf:autobuild overlays``: This determines whether per-node
+  overlays will automatically be rebuilt, e.g., when an underlying
+  overlay is changed.
+
+* ``warewulf:host overlay``: This determines whether the special
+  ``host`` overlay is applied to the Warewulf server during
+  configuration. (The host overlay is used to configure the dependent
+  services.)
+
+* ``warewulf:syslog``: This determines whether Warewulf server logs go
+  to syslog or are written directly to a log file. (e.g.,
+  ``/var/log/warewulfd.log``)
+
+* ``nfs:export paths``: Warewulf can automatically set up these NFS
+  exports.
+
+* ``container mounts``: These paths are mounted into the container
+  during ``container exec`` or ``container shell``, typically to allow
+  them to operate in the host environment prior to deployment.
+
+nodes.conf
+==========
+
+The ``nodes.conf`` file is the primary database file for all compute
+nodes. It is a flat text YAML configuration file that is managed by
+the ``wwctl`` command, but some sites manage the compute nodes and
+infrastructure via configuration management. This file being flat text
+and very light weight makes management of the node configurations very
+easy no matter what your configuration paradigm is.
+
+For the purpose of this document, we will not go into the detailed
+format of this file as it is recommended to edit with the ``wwctl``
+command.
+
+.. note::
+
+   This configuration is not written at install time; but, the first
+   time you attempt to run ``wwctl``, this file will be generated if
+   it does not exist already.
+
+defaults.conf
+=============
+
+The ``defaults.conf`` file configures default values used when none
+are specified in ``nodes.conf``. For example: if a node does not have
+a "runtime overlay" specified, the respective value from
+``defaultnode`` is used. If a network device does not specify a
+"device," the device value of the ``dummy`` device is used.
+
+If ``defaults.conf`` does not exist, the following values are used as
+compiled into Warewulf at build-time:
+
+.. code-block:: yaml
+
+  --
+  defaultnode:
+    runtime overlay:
+    - generic
+    system overlay:
+    - wwinit
+    kernel:
+      args: quiet crashkernel=no vga=791 net.naming-scheme=v238
+    init: /sbin/init
+    root: initramfs
+    ipxe template: default
+    profiles:
+    - default
+    network devices:
+      dummy:
+        device: eth0
+        type: ethernet
+        netmask: 255.255.255.0
+
+There should never be a need to change this file: all site-local
+parameters should be specified using either nodes or profiles.
+
+Directories
+===========
+
+The ``/etc/warewulf/ipxe/`` directory contains *text/templates* that
+are used by the Warewulf configuration process to configure the
+``ipxe`` service.