Merge pull request #1579 from anderbubble/known-issues

Initial documentation for "known issues"

CHANGELOG.md

@@ -25,6 +25,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Add `wwctl upgrade <config|nodes>`. #230, #517
 - Better handling of InfiniBand udev net naming. #1227
 - use templating mechanism for power commands. #1004
+- Document "known issues."
 
 ### Changed
 

userdocs/contents/known-issues.rst

@@ -0,0 +1,37 @@
+============
+Known issues
+============
+
+SELinux and IPMI write not working when using two-stage boot
+============================================================
+
+The dracut implementation of two-stage boot in versions of Warewulf prior to v4.6.0 bypasses the
+``wwinit`` process by default, invoking the image's init system directly. While cluster nodes will
+often still boot mostly successfully this way, features implemented by wwinit will not complete. In
+particular, SELinux relabeling and IPMI write are not executed.
+
+To ensure that dracut runs the full ``wwinit`` process, pass ``init=/init`` or
+``init=/warewulf/wwinit`` on the kernel command line.
+
+.. code-block:: bash
+
+   # wwctl profile set default --kernelargs="init=/init"
+
+Containers are read-only
+========================
+
+Warewulf v4.5 uses the permissions on a container's ``rootfs/`` to determine a "read-only" state of
+the container: if the root directory of the container image is ``u-w``, it will be mounted read-only
+during ``wwctl container <exec|shell``, preventing interactive changes to the container image.
+
+In the past, the root directory was ``u+w``, but Enterprise Linux 9.5 (including Red Hat, Rocky, _et
+al._) includes an update to the ``filesystem`` package that marks the root directory ``u-w``. This
+causes Warewulf container images to be "read only" by default.
+
+To mark a Warewulf container as writeable, use `chmod u+w`.
+
+.. code-block:: bash
+
+   # chmod u+w $(wwctl container show rockylinux-9.5)
+
+This behavior is changed in v4.6 to use an explicit ``readonly`` file stored outside of ``rootfs/``.

userdocs/index.rst

@@ -29,6 +29,7 @@ Welcome to the Warewulf User Guide!
    Templating <contents/templating>
    dnsmasq <contents/dnsmasq>
    Troubleshooting <contents/troubleshooting>
+   Known issues <contents/known-issues>
 
 .. toctree::
    :maxdepth: 2