From 0518af3da2f9beab76cc4330be5e08389894e824 Mon Sep 17 00:00:00 2001
From: Jonathon Anderson <janderson@ciq.com>
Date: Tue, 3 Dec 2024 16:24:32 -0700
Subject: [PATCH] Initial documentation for "known issues"

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
---
 CHANGELOG.md                       |  1 +
 userdocs/contents/known-issues.rst | 37 ++++++++++++++++++++++++++++++
 userdocs/index.rst                 |  1 +
 3 files changed, 39 insertions(+)
 create mode 100644 userdocs/contents/known-issues.rst

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 02e789e7..194dbb19 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/userdocs/contents/known-issues.rst b/userdocs/contents/known-issues.rst
new file mode 100644
index 00000000..438a5665
--- /dev/null
+++ b/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/``.
diff --git a/userdocs/index.rst b/userdocs/index.rst
index d5d4e7b1..7677ef4e 100644
--- a/userdocs/index.rst
+++ b/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