Update main docs

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

@@ -1,71 +1,73 @@
-/Exa===============
+===============
 Disk Management
 ===============
 
-Warewulf itself does not manage disks, partitions, or file systems
-directly, but provides structures in the configuration for these
-objects. At the moment warewulf supports `ignition` to create the
-partitions and file systems.
+Warewulf itself does not manage disks, partitions, or file systems directly, but provides structures in the configuration for these objects.
+At the moment warewulf supports `ignition`_ to create the partitions and file systems.
+
+.. _ignition: https://coreos.github.io/ignition/
 
 .. note::
 
    It is not currently possible to manage the root file system with
    Warewulf.
 
-Warewulf can be used, for example, to create `swap` partitions or
-`/scratch` file systems.
+Warewulf can be used, for example, to create ``swap`` partitions or ``/scratch`` file systems.
+
+Requirements
+============
+
+Partition and file system creation requires both ``ignition`` and ``sgdisk`` to be installed in the container image.
+
+Rocky Linux
+-----------
+
+.. code-block:: shell
+
+   dnf install ignition gdisk
+
+openSuse Leap
+-------------
+
+.. code-block:: shell
+
+   zypper install ignition gptfdisk
 
 Storage objects
 ===============
 
-The format of the storage objects is inspired by `butane/ignition`;
-but, where `butane/ignition` uses lists for holding disks, partitions
-and file systems, Warewulf uses maps instead.
-
-A node or profile can have several disks, where each disk is
-identified by the path to its block device. Every disks holds a map to
-its partitions and a `bool` switch to indicate if an existing
-partition table should be overwritten if it does not matched the
-desired configuration.
-
-Each partition is identified by its label. The partition number can be
-omitted, but specifying it is recommended as `ignition` may fail
-without it. Partition sizes should also be set (specified in MiB),
-except of the last partition: if no size is given, the maximum
-available size is used. Each partition has the switches `should_exist`
-and `wipe_partition_entry` which control the partition creation
-process.
-
-File systems are identified by their underlying block device,
-preferably using the `/dev/by-partlabel` format. Except for a `swap`
-partition, an absolute path for the mount point must be specified for
-each file system. Depending on the container used, valid formats are
-`btrfs`, `ext3`, `ext4`, and `xfs`. Each file system has the switch
-`wipe_filesystem` to control whether an existing file system is wiped.
+The format of the storage objects is inspired by ``butane/ignition``;
+but, where ``butane/ignition`` uses lists for holding disks, partitions and file systems, Warewulf uses maps instead.
+
+A node or profile can have several disks, where each disk is identified by the path to its block device.
+Every disks holds a map to its partitions and a ``bool`` switch to indicate if an existing partition table should be overwritten if it does not matched the desired configuration.
+
+Each partition is identified by its label.
+The partition number can be omitted, but specifying it is recommended as ``ignition`` may fail without it.
+Partition sizes should also be set (specified in MiB), except of the last partition:
+if no size is given, the maximum available size is used.
+Each partition has the switches ``should_exist`` and ``wipe_partition_entry`` which control the partition creation process.
+
+File systems are identified by their underlying block device, preferably using the ``/dev/by-partlabel`` format.
+Except for a ``swap`` partition, an absolute path for the mount point must be specified for each file system.
+Depending on the container used, valid formats are ``btrfs``, ``ext3``, ``ext4``, and ``xfs``.
+Each file system has the switch ``wipe_filesystem`` to control whether an existing file system is wiped.
 
 Ignition Implementation
 =======================
 
-The ignition implementation uses systemd services, as the underlying
-`sgdisk` command relies on dbus notifications. All necessary services
-are distributed by the `wwinit` overlay and depends on the existence
-of the file `/warewulf/ignition.json`. This file is created by the
-template function `{{ createIgnitionJson }}` only if the configuration
-contains necessary specifications for disks, partitions, and file
-systems.  If the file `/warewulf/ignition.json` exists, the service
-`ignition-disks-ww4.service` calls the ignition binary which takes
-creates partitions and file systems. A systemd `.mount` unit is
-created for each configured file system, which also creates the
-necessary mount points in the root file system. These mount units are
-required by the enabled `ww4-disks.target`. Entries in `/etc/fstab`
-are created with the `no_auto` option so that file systems can be
-easily mounted.
+The ignition implementation uses systemd services, as the underlying ``sgdisk`` command relies on dbus notifications.
+All necessary services are distributed by the ``wwinit`` overlay and depends on the existence of the file ``/warewulf/ignition.json``.
+This file is created by the template function ``{{ createIgnitionJson }}`` only if the configuration contains necessary specifications for disks, partitions, and file systems.
+If the file ``/warewulf/ignition.json`` exists, the service ``ignition-disks-ww4.service`` calls the ignition binary which takes creates partitions and file systems.
+A systemd ``.mount`` unit is created for each configured file system, which also creates the necessary mount points in the root file system.
+These mount units are required by the enabled ``ww4-disks.target``.
+Entries in ``/etc/fstab`` are created with the ``no_auto`` option so that file systems can be easily mounted.
 
 Example disk configuration
 ==========================
 
-The following command will create a `/scratch` file system on the node
-`n01`
+The following command will create a ``/scratch`` file system on the node ``n01``.
 
 .. code-block:: shell
 
@@ -85,5 +87,27 @@ A swap partition with 1Gig can be added with
      --partname swap --partsize=1024 --partnumber 1 \
      --fsname swap --fsformat swap --fspath swap
 
-which has the partition number `1` so that it will be added before the
-`/scratch` partition.
+which has the partition number ``1`` so that it will be added before the
+``/scratch`` partition.
+
+Troubleshooting
+===============
+
+If the partition creation didn't work as expected you have a few options to investigate:
+
+- Add ``systemd.log_level=debug`` and or ``rd.debug`` to the kernelArgs of the node you're working on.
+- After the next boot you should be able to find verbose information on the node with ``journalctl -u ignition-ww4-disks.service``.
+- You could also check the content of ``/warewulf/ignition.json``.
+- You could try to tinker with ``/warewulf/ignition.json`` calling
+
+  .. code-block:: shell
+
+     /usr/lib/dracut/modules.d/30ignition/ignition \
+       --platform=metal \
+       --stage=disks \
+       --config-cache=/warewulf/ignition.json \
+       --log-to-stdout
+
+  after each iteration on the node directly until you find the settings you need.
+  (Make sure to unmount all partitions if ``ignition`` was partially successful.)
+- Sometimes you need to add ``should_exist: "true"`` for the swap partiton as well.

static/docs/main/contents/background.html

@@ -65,9 +65,7 @@
 <li class="toctree-l1"><a class="reference internal" href="overlays.html">Warewulf Overlays</a></li>
 <li class="toctree-l1"><a class="reference internal" href="provisioning.html">Node Provisioning</a></li>
 <li class="toctree-l1"><a class="reference internal" href="ipmi.html">IPMI</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html">Storage objects</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#ignition-implementation">Ignition Implementation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#example-disk-configuration">Example disk configuration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="disks.html">Disk Management</a></li>
 <li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
 <li class="toctree-l1"><a class="reference internal" href="templating.html">Templating</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dnsmasq.html">dnsmasq</a></li>

static/docs/main/contents/boot-management.html

@@ -74,9 +74,7 @@
 <li class="toctree-l1"><a class="reference internal" href="overlays.html">Warewulf Overlays</a></li>
 <li class="toctree-l1"><a class="reference internal" href="provisioning.html">Node Provisioning</a></li>
 <li class="toctree-l1"><a class="reference internal" href="ipmi.html">IPMI</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html">Storage objects</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#ignition-implementation">Ignition Implementation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#example-disk-configuration">Example disk configuration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="disks.html">Disk Management</a></li>
 <li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
 <li class="toctree-l1"><a class="reference internal" href="templating.html">Templating</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dnsmasq.html">dnsmasq</a></li>

static/docs/main/contents/configuration.html

@@ -71,9 +71,7 @@
 <li class="toctree-l1"><a class="reference internal" href="overlays.html">Warewulf Overlays</a></li>
 <li class="toctree-l1"><a class="reference internal" href="provisioning.html">Node Provisioning</a></li>
 <li class="toctree-l1"><a class="reference internal" href="ipmi.html">IPMI</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html">Storage objects</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#ignition-implementation">Ignition Implementation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#example-disk-configuration">Example disk configuration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="disks.html">Disk Management</a></li>
 <li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
 <li class="toctree-l1"><a class="reference internal" href="templating.html">Templating</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dnsmasq.html">dnsmasq</a></li>

static/docs/main/contents/containers.html

@@ -88,9 +88,7 @@
 <li class="toctree-l1"><a class="reference internal" href="overlays.html">Warewulf Overlays</a></li>
 <li class="toctree-l1"><a class="reference internal" href="provisioning.html">Node Provisioning</a></li>
 <li class="toctree-l1"><a class="reference internal" href="ipmi.html">IPMI</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html">Storage objects</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#ignition-implementation">Ignition Implementation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="disks.html#example-disk-configuration">Example disk configuration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="disks.html">Disk Management</a></li>
 <li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
 <li class="toctree-l1"><a class="reference internal" href="templating.html">Templating</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dnsmasq.html">dnsmasq</a></li>