Documented wwctl clean

Closes #2034

Signed-off-by: Jonathon Anderson <janderson@ciq.com>

CHANGELOG.md

@@ -56,12 +56,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   if TLS is enabled is not distributed over plain http.
   
 - Documented that booting a node twice fixes broken partition tables
-- TLS support for `warewulfd` and REST API
+- TLS support for `warewulfd` and REST API.
 - New `wwctl configure tls` command to generate and configure TLS keys and
-  certificates
+  certificates.
 - New dedicated `warewulfd` server routes (`/ipxe/`, `/kernel/`, `/image/`,
-  `/initramfs/`, `/system/`, `/runtime/`, `/grub/`, `/efiboot/`)
-- Documented how to detech shadowed overlays in troubleshooting
+  `/initramfs/`, `/system/`, `/runtime/`, `/grub/`, `/efiboot/`).
+- Documented how to detect shadowed overlays in troubleshooting.
+- Documented `wwctl clean`. #2034
+
 
 ### Changed
 

userdocs/server/configuration.rst

@@ -300,7 +300,8 @@ Override paths to images, overlays, and other Warewulf components.
   directory, which stores ``warewulf.conf`` and ``nodes.conf``.
 
 * ``paths::cachedir``: The parent directory for the ``warewulf`` cache of OCI
-  images during ``wwctl image import``.
+  images during ``wwctl image import``. The cache is stored at
+  ``$cachedir/warewulf`` and can be cleared with ``wwctl clean``.
 
 * ``paths:ipxesource``: Where to get iPXE binaries. These files are copied to
   ``warewulf.conf:tftp:tftproot`` by ``wwctl configure tftp``.

userdocs/server/wwctl.rst

@@ -12,6 +12,8 @@ functionality.
   to multiple nodes
 * ``image``: configures (node) images
 * ``overlays``: manages overlays
+* ``clean``: removes the OCI image cache and leftover overlay images from
+  deleted nodes
 
 ``wwctl`` also provides additional helpers for interacting with cluster nodes
 over SSH and IPMI.
@@ -56,3 +58,29 @@ For each node, there are 4 different stages:
 
 You can use the ``wwctl node status`` to check communication between the
 Warewulf server (``warewulfd``) and the Warewulf client (``wwclient``).
+
+Maintenance
+===========
+
+``wwctl clean`` reclaims disk space by removing two categories of data that
+accumulate over time:
+
+* The OCI blob cache, stored at ``$cachedir/warewulf`` (default:
+  ``/var/cache/warewulf``). This cache is populated during ``wwctl image
+  import`` and speeds up subsequent imports of images that share layers. It
+  is safe to remove: the next ``wwctl image import`` will re-download any
+  needed layers.
+
+* Provisioned overlay images for nodes that have been deleted from the node
+  database. These are stored under ``$wwprovisiondir/overlays`` and are no
+  longer needed once the corresponding node is removed.
+
+.. code-block:: console
+
+   # wwctl clean
+
+``wwctl clean`` is particularly useful after deleting a large number of nodes,
+or when disk space is limited on the Warewulf server. Note that ``wwctl clean``
+only removes the current cache location (``$cachedir/warewulf``); if you are
+upgrading from v4.5.x, the legacy cache at ``$datastore/oci`` must be removed
+manually (see :ref:`oci-blob-cache`).

userdocs/troubleshooting/troubleshooting.rst

@@ -311,3 +311,42 @@ and cannot be swapped. See :ref:`swap-and-image-memory` for a complete walkthrou
    On some systems, it may also be necessary to include the ``noefi`` kernel
    argument. This works around specific EFI firmware bugs that can prevent
    proper memory release during the transition from ``initramfs`` to ``tmpfs``.
+
+.. _oci-blob-cache:
+
+OCI Blob Cache
+==============
+
+Warewulf caches OCI image layers on disk to speed up repeated ``wwctl image
+import`` operations. The cache can grow large when many images — or many
+versions of the same image — are imported over time.
+
+**v4.6 and later**
+
+The cache is stored at ``$cachedir/warewulf`` (default: ``/var/cache/warewulf``
+on RPM-based distributions). It contains files and directories such as
+``blobs/``, ``index.json``, and ``oci-layout``.
+
+Use ``wwctl clean`` to remove the cache:
+
+.. code-block:: console
+
+   # wwctl clean
+
+The cache is rebuilt automatically on the next ``wwctl image import``.
+
+**v4.5.x and earlier (legacy cache location)**
+
+In v4.5.x and earlier releases, the OCI blob cache was stored at
+``$datastore/oci`` (default: ``/usr/share/oci`` in the Rocky Linux RPM
+packages). This location is not removed by ``wwctl clean``.
+
+If you are upgrading from v4.5.x and want to reclaim the space used by the
+old cache, you can safely delete this directory manually:
+
+.. code-block:: console
+
+   # rm -rf /usr/share/oci
+
+Adjust the path if your installation used a non-default ``datastore``
+setting in ``warewulf.conf``.