diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bf51bf4..3823697c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/userdocs/server/configuration.rst b/userdocs/server/configuration.rst index 9f66d3f6..5a5b52ba 100644 --- a/userdocs/server/configuration.rst +++ b/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``. diff --git a/userdocs/server/wwctl.rst b/userdocs/server/wwctl.rst index 904764ab..3512a45d 100644 --- a/userdocs/server/wwctl.rst +++ b/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`). diff --git a/userdocs/troubleshooting/troubleshooting.rst b/userdocs/troubleshooting/troubleshooting.rst index 4fe6a5b9..acfcdcc5 100644 --- a/userdocs/troubleshooting/troubleshooting.rst +++ b/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``.