Update v4.5.x docs

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

@@ -0,0 +1,109 @@
+Troubleshooting
+===============
+
+iPXE
+----
+
+If you're using iPXE to boot (the default), you can get a command prompt by pressing with C-b during boot.
+
+From the iPXE command prompt, you can run the same commands from `default.ipxe`_ (or `dracut.ipxe`_) to troubleshoot potential boot problems.
+
+.. _default.ipxe: https://github.com/warewulf/warewulf/blob/main/etc/ipxe/default.ipxe
+
+.. _dracut.ipxe: https://github.com/warewulf/warewulf/blob/main/etc/ipxe/dracut.ipxe
+
+For example, the following commands perform a (relatively) normal Warewulf boot.
+(Substitute your Warewulf server's IP address in place of 10.0.0.1,
+update the port number if you have changed it from the default of 9873,
+and substitute your cluster node's MAC addres in place of 00:00:00:00:00:00.)
+
+.. code-block::
+
+   set uri http://10.0.0.1:9873/provision/00:00:00:00:00:00
+   kernel --name kernel ${uri}?stage=kernel
+   imgextract --name container ${uri}?stage=container&compress=gz
+   imgextract --name system ${uri}?stage=system&compress=gz
+   imgextract --name runtime ${uri}?stage=runtime&compress=gz
+   boot kernel initrd=container initrd=kmods initrd=system initrd=runtime
+
+- The ``uri`` variable points to ``warewulfd`` for future reference.
+  This includes the cluster node's MAC address so that Warewulf knows what container and overlays to provide.
+
+- The ``kernel`` command fetches a kernel for later booting.
+
+- The ``imgextract`` command fetches and decompresses the images that will make up the booted noe image.
+  In a typical environment this is used to load a minimal "initial ramdisk" which, then, boots the rest of the system.
+  Warewulf, by default, loads the entire image as an initial ramdisk,
+  and also loads the system and runtime overlays at this time time.
+
+- The ``boot`` command tells iPXE to boot the system with the given kernel and ramdisks.
+
+.. note::
+
+   This example does not provide ``assetkey`` information to ``warewulfd``.
+   If your nodes have defined asset tags, provide it in the ``uri`` variable for the node you are trying to boot.
+
+For example, you may want to try booting to a pre-init shell with debug logging enabled.
+To do so, substitute the ``boot`` command above.
+
+.. code-block::
+
+   boot kernel initrd=container initrd=kmods initrd=system initrd=runtime rdinit=/bin/sh
+
+.. note::
+
+   You may be more familiar with specifying ``init=`` on the kernel command line.
+   ``rdinit`` indicates "ramdisk init."
+   Since Warewulf, by default, boots the node image as an initial ramdisk, we must use ``rdinit=`` here.
+
+GRUB
+----
+
+If you're using GRUB to boot, you can get a command prompt by pressing "c" when prompted during boot.
+
+From the GRUB command prompt, you can enter the same commands that you would otherwise find in `grub.cfg.ww`_.
+
+.. _grub.cfg.ww: https://github.com/warewulf/warewulf/blob/main/etc/grub/grub.cfg.ww
+
+For example, the following commands perform a (relatively) normal Warewulf boot.
+(Substitute your Warewulf server's IP address in place of 10.0.0.1,
+and update the port number if you have changed it from the default of 9873.)
+
+.. code-block::
+
+   uri="(http,10.0.0.1:9873)/provision/${net_default_mac}"
+   linux "${uri}?stage=kernel" wwid=${net_default_mac}
+   initrd "${uri}?stage=container&compress=gz" "${uri}?stage=system&compress=gz" "${uri}?stage=runtime&compress=gz"
+   boot
+
+- The ``uri`` variable points to ``warewulfd`` for future reference.
+  ``${net_default_mac}`` provides Warewulf with the MAC address of the booting node,
+  so that Warewulf knows what container and overlays to provide it.
+
+- The ``linux`` command tells GRUB what kernel to boot, as provided by ``warewulfd``.
+  The ``wwid`` kernel argument helps ``wwclient`` identify the node during runtime.
+
+- The ``initrd`` command tells GRUB what images to load into memory for boot.
+  In a typical environment this is used to load a minimal "initial ramdisk" which, then, boots the rest of the system.
+  Warewulf, by default, loads the entire image as an initial ramdisk,
+  and also loads the system and runtime overlays at this time time.
+
+- The ``boot`` command tells GRUB to boot the system with the previously-defined configuration.
+
+.. note::
+
+   This example does not provide ``assetkey`` information to ``warewulfd``.
+   If your nodes have defined asset tags, provide it in the ``uri`` variable for the node you are trying to boot.
+
+For example, you may want to try booting to a pre-init shell with debug logging enabled.
+To do so, substitute the ``linux`` command above.
+
+.. code-block::
+
+   linux "${uri}?stage=kernel" wwid=${net_default_mac} debug rdinit=/bin/sh
+
+.. note::
+
+   You may be more familiar with specifying ``init=`` on the kernel command line.
+   ``rdinit`` indicates "ramdisk init."
+   Since Warewulf, by default, boots the node image as an initial ramdisk, we must use ``rdinit=`` here.

static/docs/v4.5.x/_sources/index.rst.txt

@@ -28,6 +28,7 @@ Welcome to the Warewulf User Guide!
    Security <contents/security>
    Templating <contents/templating>
    dnsmasq <contents/dnsmasq>
+   Troubleshooting <contents/troubleshooting>
 
 .. toctree::
    :maxdepth: 2

static/docs/v4.5.x/contents/background.html

@@ -69,6 +69,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/boot-management.html

@@ -79,6 +79,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/configuration.html

@@ -79,6 +79,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/containers.html

@@ -94,6 +94,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/disks.html

@@ -81,6 +81,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/dnsmasq.html

@@ -23,7 +23,7 @@
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
-    <link rel="next" title="Enterprise Linux Quickstart (Rocky Linux, CentOS, and RHEL)" href="../quickstart/el.html" />
+    <link rel="next" title="Troubleshooting" href="troubleshooting.html" />
     <link rel="prev" title="Templating" href="templating.html" /> 
 </head>
 
@@ -75,6 +75,7 @@
 </li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>
@@ -171,7 +172,7 @@ <h3>Installation<a class="headerlink" href="#installation" title="Link to this h
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="templating.html" class="btn btn-neutral float-left" title="Templating" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-        <a href="../quickstart/el.html" class="btn btn-neutral float-right" title="Enterprise Linux Quickstart (Rocky Linux, CentOS, and RHEL)" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        <a href="troubleshooting.html" class="btn btn-neutral float-right" title="Troubleshooting" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>

static/docs/v4.5.x/contents/glossary.html

@@ -68,6 +68,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/initialization.html

@@ -76,6 +76,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/installation.html

@@ -82,6 +82,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/introduction.html

@@ -74,6 +74,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/ipmi.html

@@ -80,6 +80,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/kernel.html

@@ -76,6 +76,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/nodeconfig.html

@@ -87,6 +87,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/overlays.html

@@ -91,6 +91,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/profiles.html

@@ -76,6 +76,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/provisioning.html

@@ -74,6 +74,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/security.html

@@ -74,6 +74,7 @@
 </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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/setup.html

@@ -75,6 +75,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/stateless.html

@@ -74,6 +74,7 @@
 <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>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>

static/docs/v4.5.x/contents/templating.html

@@ -92,6 +92,7 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="dnsmasq.html">dnsmasq</a></li>
+<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
 </ul>
 <p class="caption" role="heading"><span class="caption-text">Quickstart</span></p>
 <ul>