Distinguish between OS images and overlay images in documentation

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2026-03-18 08:10:49 -06:00
parent 1fd8b65ebf
commit 7909598a3d
20 changed files with 89 additions and 87 deletions

View File

@@ -67,9 +67,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
- Runtime overlay download failure during dracut/wwinit boot is now non-fatal; - Runtime overlay download failure during dracut/wwinit boot is now non-fatal;
the node continues to boot and `wwclient` retries the download at runtime. the node continues to boot and `wwclient` retries the download at runtime.
- `hosts` overlay added to the default system overlay list - `hosts` overlay added to the default system overlay list
- Distinguish between OS images and overlay images in documentation
### Changed
- Updated `MAINTAINING.md` to document golang version policy - Updated `MAINTAINING.md` to document golang version policy
## v4.6.5, 2026-01-12 ## v4.6.5, 2026-01-12

View File

@@ -1,6 +1,6 @@
# Node images have moved # OS images have moved
Warewulf node images are now being maintained in a separate repository: Warewulf OS images are now being maintained in a separate repository:
https://github.com/warewulf/warewulf-node-images. https://github.com/warewulf/warewulf-node-images.

View File

@@ -19,9 +19,7 @@ var baseCmd = &cobra.Command{
DisableFlagsInUseLine: true, DisableFlagsInUseLine: true,
Use: "image COMMAND [OPTIONS]", Use: "image COMMAND [OPTIONS]",
Short: "Operating system image management", Short: "Operating system image management",
Long: "Starting with version 4, Warewulf uses images to build the bootable\n" + Long: "Import, manage, and transform OS images as bootable Warewulf images.",
"node images. These commands will help you import, manage, and transform\n" +
"images into bootable Warewulf images.",
Aliases: []string{"vnfs", "container"}, Aliases: []string{"vnfs", "container"},
Args: cobra.NoArgs, Args: cobra.NoArgs,
} }

View File

@@ -54,7 +54,7 @@ func getImages() usecase.Interactor {
} }
}) })
u.SetTitle("Get images") u.SetTitle("Get images")
u.SetDescription("Get all node images") u.SetDescription("Get all OS images")
u.SetTags("Image") u.SetTags("Image")
return u return u
} }
@@ -74,7 +74,7 @@ func getImageByName() usecase.Interactor {
} }
}) })
u.SetTitle("Get an image") u.SetTitle("Get an image")
u.SetDescription("Get a node image by its name") u.SetDescription("Get an OS image by its name")
u.SetTags("Image") u.SetTags("Image")
return u return u
} }
@@ -110,7 +110,7 @@ func importImage() usecase.Interactor {
} }
}) })
u.SetTitle("Import an image") u.SetTitle("Import an image")
u.SetDescription("Import a node image from an OCI registry") u.SetDescription("Import an OS image from an OCI registry")
u.SetTags("Image") u.SetTags("Image")
return u return u
@@ -146,7 +146,7 @@ func deleteImage() usecase.Interactor {
return image_api.ImageDelete(cdp) return image_api.ImageDelete(cdp)
}) })
u.SetTitle("Delete an image") u.SetTitle("Delete an image")
u.SetDescription("Delete an existing node image") u.SetDescription("Delete an existing OS image")
u.SetTags("Image") u.SetTags("Image")
return u return u
@@ -156,7 +156,7 @@ func updateImage() usecase.Interactor {
type renameImageInput struct { type renameImageInput struct {
Name string `path:"name" required:"true" description:"Name of image to update"` Name string `path:"name" required:"true" description:"Name of image to update"`
NewName string `json:"name" description:"New name to rename the image to"` NewName string `json:"name" description:"New name to rename the image to"`
Build bool `query:"build" default:"true" description:"Build the image image after renaming, default:'true'"` Build bool `query:"build" default:"true" description:"Build the OS image after renaming, default:'true'"`
} }
u := usecase.NewInteractor(func(ctx context.Context, input renameImageInput, output *Image) error { u := usecase.NewInteractor(func(ctx context.Context, input renameImageInput, output *Image) error {
@@ -179,7 +179,7 @@ func updateImage() usecase.Interactor {
return nil return nil
}) })
u.SetTitle("Update or rename an image") u.SetTitle("Update or rename an image")
u.SetDescription("Update or rename an existing node image") u.SetDescription("Update or rename an existing OS image")
u.SetTags("Image") u.SetTags("Image")
return u return u
@@ -188,7 +188,7 @@ func updateImage() usecase.Interactor {
func buildImage() usecase.Interactor { func buildImage() usecase.Interactor {
type buildImageInput struct { type buildImageInput struct {
Name string `path:"name" required:"true" description:"Name of image to build"` Name string `path:"name" required:"true" description:"Name of image to build"`
Force bool `query:"force" default:"false" description:"Build the image image even if it appears unnecessary, default:'false'"` Force bool `query:"force" default:"false" description:"Build the OS image even if it appears unnecessary, default:'false'"`
} }
u := usecase.NewInteractor(func(ctx context.Context, input buildImageInput, output *Image) error { u := usecase.NewInteractor(func(ctx context.Context, input buildImageInput, output *Image) error {
@@ -206,7 +206,7 @@ func buildImage() usecase.Interactor {
return nil return nil
}) })
u.SetTitle("Build an image") u.SetTitle("Build an image")
u.SetDescription("Build a node image") u.SetDescription("Build an OS image")
u.SetTags("Image") u.SetTags("Image")
return u return u

View File

@@ -155,10 +155,10 @@ configure --all``.
you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label
files written to ``tftpboot``. files written to ``tftpboot``.
Add a base node image Add an OS image
===================== ===============
This will pull a basic node image from Docker Hub This will pull a basic OS image from Docker Hub
and set it for the "default" node profile. and set it for the "default" node profile.
.. code-block:: bash .. code-block:: bash

View File

@@ -12,13 +12,7 @@ External services
configures a DHCP server (either ISC DHCP or dnsmasq) and a TFTP server. configures a DHCP server (either ISC DHCP or dnsmasq) and a TFTP server.
Image Image
The node images that Warewulf manages and provisions. Images may be imported See "Operating System (OS) Image" or "Overlay Image."
from OCI image registries, OCI image archives, Apptainer sandboxes, and
manual chroot directories.
Warewulf images are maintained as an uncompressed "virtual node file system"
(VNFS, sometimes also referred to as a "chroot"). These virtual file systems
are then built as single-file images which may be used to provision a node.
Kernel Kernel
In addition to an image, Warewulf also requires a kernel (typically a Linux In addition to an image, Warewulf also requires a kernel (typically a Linux
@@ -42,6 +36,14 @@ nodes.conf
This file is sometimes referred to as the "nodes database" or "node This file is sometimes referred to as the "nodes database" or "node
registry." registry."
Operating System (OS) Image
An operating system image (or OS image) contains a bootable operating
system. When provisioning a cluster node, Warewulf combines the OS image
with the node's overlay images to provision the complete, configured image.
OS images may be imported from OCI image registries, OCI image archives,
Apptainer sandboxes, and manual chroot directories.
Overlay Overlay
Warewulf overlays provide customization for the provisioned image. Overlays Warewulf overlays provide customization for the provisioned image. Overlays
may be configured on nodes or profiles, as either **system** or **runtime** may be configured on nodes or profiles, as either **system** or **runtime**
@@ -56,6 +58,15 @@ Overlay
Warewulf includes a number of **distribution overlays**; but additional Warewulf includes a number of **distribution overlays**; but additional
**site overlays** can be added to a Warewulf environment. **site overlays** can be added to a Warewulf environment.
Overlay Image
An overlay image contains the rendered contents of multiple overlays for a
given cluster node. Nodes have a "system overlay" image and a "runtime
overlay" image, based on the system and runtime overlays associated with each
node.
Overlay images are not managed directly, but are built by the ``wwctl
overlay build`` command.
Profile Profile
Warewulf profiles are abstract nodes that carry the same configuration Warewulf profiles are abstract nodes that carry the same configuration
attributes but do not provision any specific node. Warewulf nodes may then attributes but do not provision any specific node. Warewulf nodes may then

View File

@@ -9,10 +9,10 @@ Warewulf is known for its massive scalability and simple management of stateless
(disk optional) provisioning. (disk optional) provisioning.
Warewulf leverages a simple administrative model centralizing administration Warewulf leverages a simple administrative model centralizing administration
around virtual node images which are used to provision out to the cluster nodes. around virtual OS images which are used to provision cluster nodes. This means
This means you can have hundreds or thousands of cluster nodes all booting and you can have hundreds or thousands of cluster nodes all booting and running on
running on the same node image. As of Warewulf v4, the node image can be managed the same OS image. As of Warewulf v4, the OS image can be managed using
using industry-standard container tooling and/or CI/CD pipelines. This can be as industry-standard container tooling and/or CI/CD pipelines. This can be as
simple as DockerHub or your own private GitLab CI infrastructure. With this simple as DockerHub or your own private GitLab CI infrastructure. With this
architecture, Warewulf combines the best of High Performance Computing (HPC), architecture, Warewulf combines the best of High Performance Computing (HPC),
Cloud, Hyperscale, and Enterprise deployment principles to create and maintain Cloud, Hyperscale, and Enterprise deployment principles to create and maintain
@@ -47,7 +47,7 @@ flexible provisioning system for all types of clusters.
any environment. any environment.
* **Secure**: Warewulf supports SELinux out-of-the-box. Just install SELinux in * **Secure**: Warewulf supports SELinux out-of-the-box. Just install SELinux in
your node image and let Warewulf do the rest! your OS image and let Warewulf do the rest!
* **Open Source**: Warewulf is and has always been open source. It can be used * **Open Source**: Warewulf is and has always been open source. It can be used
in any environment, whether public, private, non-profit, or commercial. And in any environment, whether public, private, non-profit, or commercial. And
@@ -70,14 +70,14 @@ configuration and image and overlay assignments.
**Node profiles** provide a flexible abstraction for applying configuration to **Node profiles** provide a flexible abstraction for applying configuration to
multiple nodes. multiple nodes.
**Node images** provide a bootable operating system image, including the kernel **Operating system images** provide a bootable image, including the kernel
that will be used to boot the cluster node. Node images provide a base operating that will be used to boot the cluster node. OS images provide the base operating
system and, by default, run entirely in memory. This means that when you system and, by default, run entirely in memory. This means that when you
reboot the node, the node retains no information about Warewulf or how it reboot the node, the node retains no information about Warewulf or how it
booted; but it also means that they return to their initial known-good state. booted; but it also means that they return to their initial known-good state.
**Overlays** customize the provisioned operating system image with static files **Overlays** customize the provisioned operating system image with static files
and dynamic templates applied with the node image and, optionally, periodically and dynamic templates applied with the OS image and, optionally, periodically
at runtime. at runtime.
Beowulf overview Beowulf overview

View File

@@ -1,15 +1,15 @@
.. _images: .. _images:
=========== =========
Node Images OS Images
=========== =========
Warewulf node images are a "Virtual Node File System" (VNFS) that serves as a Warewulf operating system (OS) images are a "Virtual Node File System" (VNFS)
base image for cluster nodes. This is similar to a "golden master" image, except that serves as an image for cluster nodes. This is similar to a "golden master" image, except
that the image source exists mutably within a directory on the Warewulf control that the image source exists mutably within a directory on the Warewulf control
node (e.g. a ``chroot()``). node (e.g. a ``chroot()``).
Warewulf node images have several similarities to Linux containers; so Warewulf Warewulf OS images have several similarities to Linux containers; so Warewulf
v4 integrates directly within the container ecosystem to facilitate the process v4 integrates directly within the container ecosystem to facilitate the process
of image creation and image management: images can be built, for example, with of image creation and image management: images can be built, for example, with
Docker, Podman, or Apptainer, and imported directly from OCI registries or local Docker, Podman, or Apptainer, and imported directly from OCI registries or local
@@ -58,7 +58,7 @@ or Apptainer sandbox.
OCI Registry OCI Registry
------------ ------------
You can import node images from an OCI registry, public or private. You can import OS images from an OCI registry, public or private.
.. code-block:: console .. code-block:: console
@@ -76,10 +76,10 @@ You can import node images from an OCI registry, public or private.
Most images in Docker Hub are not "bootable": they typically do not include Most images in Docker Hub are not "bootable": they typically do not include
a kernel, and likely don't include any init system. For this reason, don't a kernel, and likely don't include any init system. For this reason, don't
expect a base image from DockerHub (e.g. ``docker://rockylinux`` or expect just any image from DockerHub (e.g. ``docker://rockylinux`` or
``docker://debian``) to boot properly with Warewulf. ``docker://debian``) to boot properly with Warewulf.
The Warewulf project maintains a set of `example node images The Warewulf project maintains a set of `example OS images
<https://github.com/warewulf/warewulf-node-images>`_ that are configured to <https://github.com/warewulf/warewulf-node-images>`_ that are configured to
boot when used with Warewulf. These images can be imported directly into boot when used with Warewulf. These images can be imported directly into
Warewulf or used as base images for local custom images. Warewulf or used as base images for local custom images.
@@ -300,7 +300,7 @@ Exit Script
Warewulf executes the script ``/etc/warewulf/image_exit.sh`` in the image after Warewulf executes the script ``/etc/warewulf/image_exit.sh`` in the image after
a ``wwctl image shell`` or ``wwctl image exec`` and prior to (re)building the a ``wwctl image shell`` or ``wwctl image exec`` and prior to (re)building the
final node image for delivery. This is typically used to remove cache or log final OS image for delivery. This is typically used to remove cache or log
files that may have been generated by the executed command or interactive files that may have been generated by the executed command or interactive
session. session.
@@ -310,7 +310,7 @@ package repository caches that may have been generated.
Defining New Images Defining New Images
=================== ===================
It is absolutely possible to import a base image into Warewulf and make all It is absolutely possible to import an OS image into Warewulf and make all
changes interactively with ``wwctl image shell``; but it is often better to changes interactively with ``wwctl image shell``; but it is often better to
define new images with a container image definition file. This can be done using define new images with a container image definition file. This can be done using
the OCI and Singularity (Apptainer) ecosystems. the OCI and Singularity (Apptainer) ecosystems.

View File

@@ -16,8 +16,8 @@ for SELinux context labeling.)
.. note:: .. note::
Versions of Warewulf prior to v4.5.8 also required a kernel argument Versions of Warewulf prior to v4.5.8 also required a kernel argument
"rootfstype=ramfs" in order for wwinit to copy the node image to tmpfs; but "rootfstype=ramfs" in order for wwinit to copy the image to tmpfs; but this
this is no longer required. is no longer required.
Once that is done, enable SELinux in ``/etc/sysconfig/selinux`` and install the Once that is done, enable SELinux in ``/etc/sysconfig/selinux`` and install the
appropriate packages in the image. `An example`_ of such an image is available appropriate packages in the image. `An example`_ of such an image is available

View File

@@ -45,7 +45,7 @@ Welcome to the Warewulf User Guide!
:maxdepth: 1 :maxdepth: 1
:caption: Images :caption: Images
Node Images <images/images> OS Images <images/images>
Image Kernels <images/kernel> Image Kernels <images/kernel>
Syncuser <images/syncuser> Syncuser <images/syncuser>
SELinux <images/selinux> SELinux <images/selinux>

View File

@@ -12,11 +12,6 @@ sfdisk, mkfs, and mkswap during boot.
Ignition can, for example, create ``swap`` partitions or ``/scratch`` file Ignition can, for example, create ``swap`` partitions or ``/scratch`` file
systems. systems.
.. note::
Warewulf is not currently able to provision the node image onto an explicitly
provisioned root file system.
Requirements Requirements
============ ============
@@ -153,7 +148,7 @@ See the `upstream ignition documentation`_ for additional information.
Swap and image memory usage Swap and image memory usage
=========================== ===========================
Warewulf node images run entirely in memory. Configuring a local swap partition Warewulf images run entirely in memory. Configuring a local swap partition
can allow the kernel to reclaim that RAM for applications — but only under the can allow the kernel to reclaim that RAM for applications — but only under the
right conditions. Whether swap can free image memory depends on which root right conditions. Whether swap can free image memory depends on which root
filesystem type the node uses. filesystem type the node uses.
@@ -162,7 +157,7 @@ tmpfs root
---------- ----------
When the root filesystem is ``tmpfs`` (the default for two-stage dracut boot, or When the root filesystem is ``tmpfs`` (the default for two-stage dracut boot, or
when ``--root=tmpfs`` is set explicitly), the node image lives in the page cache. when ``--root=tmpfs`` is set explicitly), the image lives in the page cache.
The Linux kernel can swap ``tmpfs`` pages to a local swap device exactly as it The Linux kernel can swap ``tmpfs`` pages to a local swap device exactly as it
would any other anonymous memory. Adding swap therefore lets the kernel evict would any other anonymous memory. Adding swap therefore lets the kernel evict
cold image pages to disk and reclaim that RAM for running workloads. cold image pages to disk and reclaim that RAM for running workloads.
@@ -176,7 +171,7 @@ initramfs root (single-stage boot default)
The default single-stage boot places the image in an ``initramfs`` root, which The default single-stage boot places the image in an ``initramfs`` root, which
is an instance of ``ramfs``. Unlike ``tmpfs``, ``ramfs`` pages are pinned in is an instance of ``ramfs``. Unlike ``tmpfs``, ``ramfs`` pages are pinned in
memory: the kernel will never swap them out. Configuring swap on a node with an memory: the kernel will never swap them out. Configuring swap on a node with an
``initramfs`` root will **not** free any memory used by the node image. ``initramfs`` root will **not** free any memory used by the image.
If you are using single-stage boot and want swap to help with image memory, If you are using single-stage boot and want swap to help with image memory,
switch to ``tmpfs`` root first: switch to ``tmpfs`` root first:
@@ -284,9 +279,9 @@ needs memory, first note the image size with ``df -h /``:
df -h / df -h /
This shows how much tmpfs space the image occupies — that is the amount of RAM This shows how much tmpfs space the image occupies — that is the amount of RAM
currently holding the node image. currently holding the image.
Now apply memory pressure using ``stress-ng`` (install it in the node image if Now apply memory pressure using ``stress-ng`` (install it in the OS image if
not already present). The allocation must exceed **available** RAM — not just not already present). The allocation must exceed **available** RAM — not just
total RAM — to force the kernel to evict image pages. Compute the target from total RAM — to force the kernel to evict image pages. Compute the target from
``MemTotal``: ``MemTotal``:
@@ -310,7 +305,7 @@ While ``stress-ng`` is running, observe memory usage:
Mem: 15Gi 15Gi 32Mi 120Mi 512Mi 192Mi Mem: 15Gi 15Gi 32Mi 120Mi 512Mi 192Mi
Swap: 8.0Gi 4.2Gi 3.8Gi Swap: 8.0Gi 4.2Gi 3.8Gi
The ``Swap: used`` value has grown by roughly the size of the node image. The The ``Swap: used`` value has grown by roughly the size of the image. The
kernel has evicted cold image pages to swap, making that RAM available to the kernel has evicted cold image pages to swap, making that RAM available to the
application. The application can access the full physical memory of the node, application. The application can access the full physical memory of the node,
not just what is left over after the image is loaded. not just what is left over after the image is loaded.
@@ -320,7 +315,7 @@ they are accessed again, so ``free -h`` will continue to show swap usage until
the node is under less pressure and pages are faulted back in as needed. the node is under less pressure and pages are faulted back in as needed.
Moving image pages to swap proactively Moving image pages to swap proactively
--------------------------------------- --------------------------------------
Rather than simulating a workload, you can instruct the kernel to push image Rather than simulating a workload, you can instruct the kernel to push image
pages to swap directly. On Linux 6.1 and later with cgroup v2, write the pages to swap directly. On Linux 6.1 and later with cgroup v2, write the
@@ -352,7 +347,7 @@ systemd unit to a custom overlay that runs at ``local-fs.target``:
.. code-block:: ini .. code-block:: ini
[Unit] [Unit]
Description=Reclaim node image memory to swap Description=Reclaim OS image memory to swap
After=local-fs.target After=local-fs.target
ConditionPathExists=/sys/fs/cgroup/memory.reclaim ConditionPathExists=/sys/fs/cgroup/memory.reclaim
@@ -472,7 +467,7 @@ functionality is used:
Configuring the root device Configuring the root device
--------------------------- ---------------------------
Set the desired storage device for the node image using the ``--root`` Set the desired storage device for the image using the ``--root``
parameter. parameter.
.. code-block:: shell .. code-block:: shell

View File

@@ -2,7 +2,7 @@
Overlays Overlays
======== ========
Warewulf supplements provisioned node images with an "overlay" system. Overlays Warewulf supplements provisioned OS images with an "overlay" system. Overlays
are collections of files and :ref:`templates` that are rendered are collections of files and :ref:`templates` that are rendered
and built per-node and then applied over the image during the provisioning and built per-node and then applied over the image during the provisioning
process. process.
@@ -239,7 +239,7 @@ provisioning actions:
wwclient wwclient
-------- --------
All configured overlays are provisioned initially along with the node image All configured overlays are provisioned initially along with the OS image
itself; but **wwclient** periodically fetches and applies the runtime overlay to itself; but **wwclient** periodically fetches and applies the runtime overlay to
allow configuration of some settings without a reboot. allow configuration of some settings without a reboot.
@@ -521,8 +521,8 @@ include wipefs to detect existing file systems.
wwctl image exec rockylinux-9 -- /usr/bin/dracut --force --no-hostonly --add wwinit --install mkswap --regenerate-all wwctl image exec rockylinux-9 -- /usr/bin/dracut --force --no-hostonly --add wwinit --install mkswap --regenerate-all
For a complete walkthrough of configuring swap to free memory consumed by the For a complete walkthrough of configuring swap to free memory consumed by the
in-memory node image, including which root filesystem types support swap in-memory image, including which root filesystem types support swap reclamation,
reclamation, see :ref:`swap-and-image-memory`. see :ref:`swap-and-image-memory`.
systemd mounts systemd mounts
-------------- --------------

View File

@@ -3,7 +3,7 @@ v4.6.2 Release Notes
==================== ====================
v4.6.2 is a regularly-scheduled minor release in the v4.6.x series. It also v4.6.2 is a regularly-scheduled minor release in the v4.6.x series. It also
includes a preview implementation of the ability to provision the node image to includes a preview implementation of the ability to provision the OS image to
a local disk. a local disk.
Significant changes are described below. Additional changes are listed in the Significant changes are described below. Additional changes are listed in the

View File

@@ -95,7 +95,7 @@ systems to mount properly. The ``wwinit`` dracut module also no longer runs the
wwinit module if root is not set to ``root=wwclient*``. wwinit module if root is not set to ``root=wwclient*``.
These fixes require installing the updated ``warewulf-dracut`` package in the These fixes require installing the updated ``warewulf-dracut`` package in the
node image. OS image.
Other fixes Other fixes
=========== ===========

View File

@@ -32,7 +32,7 @@ the Warewulf configuration process to configure the ``ipxe`` service.
bios->iPXE [lhead=cluster0,label="iPXE.efi"]; bios->iPXE [lhead=cluster0,label="iPXE.efi"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"]; kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"];
ipxe_cfg->kernel[ltail=cluster0,label="http"]; ipxe_cfg->kernel[ltail=cluster0,label="http"];
} }
@@ -235,7 +235,7 @@ Warewulf as a technology preview.
grubcfg[shape=record label="{grub.cfg|static under TFTP root}"]; grubcfg[shape=record label="{grub.cfg|static under TFTP root}"];
grub->grubcfg[label="TFTP"]; grub->grubcfg[label="TFTP"];
} }
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"]; kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"];
grubcfg->kernel[ltail=cluster1,label="http"]; grubcfg->kernel[ltail=cluster1,label="http"];
} }
@@ -308,9 +308,9 @@ diagram is the following:
digraph G{ digraph G{
node [shape=box]; node [shape=box];
efi [shape=record label="{EFI|boots from URI defined in filename}"]; efi [shape=record label="{EFI|boots from URI defined in filename}"];
shim [shape=record label="{shim.efi|replaces shim.efi with grubx64.efi in URI|extracted from node image}"]; shim [shape=record label="{shim.efi|replaces shim.efi with grubx64.efi in URI|extracted from OS image}"];
grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from node image}"] grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from OS image}"]
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"]; kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"];
efi->shim [label="http"]; efi->shim [label="http"];
shim->grub [label="http"]; shim->grub [label="http"];
grub->kernel [label="http"]; grub->kernel [label="http"];

View File

@@ -93,7 +93,7 @@ kernel is taken from the node's assigned image.
``/image/{wwid}`` ``/image/{wwid}``
----------------- -----------------
Serves the raw node image file for the node identified by ``{wwid}``. Serves the raw OS image file for the node identified by ``{wwid}``.
**Query parameters:** ``assetkey``, ``uuid``, ``compress`` **Query parameters:** ``assetkey``, ``uuid``, ``compress``

View File

@@ -11,7 +11,7 @@ Provisioning Security
Provisioning is, by default, a relatively "insecure" process: there is generally Provisioning is, by default, a relatively "insecure" process: there is generally
nothing preventing a user on a cluster node from spoofing a provision request nothing preventing a user on a cluster node from spoofing a provision request
and downloading the node image and overlays for inspection. If any of these and downloading the OS image and overlays for inspection. If any of these
include secrets (e.g., private keys) they are at risk of exposure. include secrets (e.g., private keys) they are at risk of exposure.
There are multiple ways to secure the Warewulf provisioning process: There are multiple ways to secure the Warewulf provisioning process:
@@ -50,7 +50,7 @@ SELinux
The Warewulf server can be run with SELinux enabled in "targeted" and The Warewulf server can be run with SELinux enabled in "targeted" and
"enforcing" mode. "enforcing" mode.
For more information about running SELinux-enabled cluster node images, see For more information about running SELinux-enabled cluster OS images, see
:ref:`SELinux-Enabled Images <selinux_images>`. :ref:`SELinux-Enabled Images <selinux_images>`.
firewalld firewalld

View File

@@ -63,7 +63,7 @@ v4.6.0. <https://github.com/warewulf/warewulf/issues/892>`_
Image Size Considerations Image Size Considerations
========================= =========================
Node images can grow quickly as packages and other files are added to them. Even OS images can grow quickly as packages and other files are added to them. Even
these larger images are often not an issue in modern environments; but some these larger images are often not an issue in modern environments; but some
architectural limits exist that can impede the use of images larger than a few architectural limits exist that can impede the use of images larger than a few
gigabytes. Workarounds exist for these issues in most circumstances: gigabytes. Workarounds exist for these issues in most circumstances:
@@ -94,7 +94,7 @@ gigabytes. Workarounds exist for these issues in most circumstances:
* Some BIOS / firmware retain a "memory hole" feature for legacy devices, e.g., * Some BIOS / firmware retain a "memory hole" feature for legacy devices, e.g.,
reserving a 1MB block of memory at the 15MB-16MB address range. This feature reserving a 1MB block of memory at the 15MB-16MB address range. This feature
can interfere with booting stateless node images. can interfere with booting stateless OS images.
If you are still getting "Not enough memory" or "No space left on device" If you are still getting "Not enough memory" or "No space left on device"
errors, try disabling any "memory hole" features or updating your system BIOS errors, try disabling any "memory hole" features or updating your system BIOS

View File

@@ -66,7 +66,7 @@ cluster node's MAC address in place of 00:00:00:00:00:00.)
- The ``kernel`` command fetches a kernel for later booting. - The ``kernel`` command fetches a kernel for later booting.
- The ``imgextract`` command fetches and decompresses the images that will make - The ``imgextract`` command fetches and decompresses the images that will make
up the booted node image. In a typical environment this is used to load a up the booted OS image. In a typical environment this is used to load a
minimal "initial ramdisk" which, then, boots the rest of the system. Warewulf, 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 by default, loads the entire image as an initial ramdisk, and also loads the
system and runtime overlays at this time. system and runtime overlays at this time.
@@ -91,7 +91,7 @@ enabled. To do so, substitute the ``boot`` command above.
You may be more familiar with specifying ``init=`` on the kernel command You may be more familiar with specifying ``init=`` on the kernel command
line. ``rdinit`` indicates "ramdisk init." Since Warewulf, by default, boots line. ``rdinit`` indicates "ramdisk init." Since Warewulf, by default, boots
the node image as an initial ramdisk, we must use ``rdinit=`` here. the OS image as an initial ramdisk, we must use ``rdinit=`` here.
GRUB GRUB
==== ====
@@ -149,7 +149,7 @@ enabled. To do so, substitute the ``linux`` command above.
You may be more familiar with specifying ``init=`` on the kernel command You may be more familiar with specifying ``init=`` on the kernel command
line. ``rdinit`` indicates "ramdisk init." Since Warewulf, by default, boots line. ``rdinit`` indicates "ramdisk init." Since Warewulf, by default, boots
the node image as an initial ramdisk, we must use ``rdinit=`` here. the OS image as an initial ramdisk, we must use ``rdinit=`` here.
Dracut Dracut
====== ======
@@ -217,8 +217,8 @@ the new configuration.
.. note:: .. note::
The node image itself must have Podman (or the desired container runtime) The OS image itself must have Podman (or the desired container runtime)
installed. See :ref:`images` for guidance on customizing node images. installed. See :ref:`images` for guidance on customizing OS images.
For information on tuning tmpfs memory usage and NUMA interleaving behavior, For information on tuning tmpfs memory usage and NUMA interleaving behavior,
see :ref:`tmpfs-and-numa` below. see :ref:`tmpfs-and-numa` below.
@@ -231,7 +231,7 @@ tmpfs and NUMA
Warewulf can optionally mount the root filesystem as ``tmpfs`` instead of the Warewulf can optionally mount the root filesystem as ``tmpfs`` instead of the
default ``initramfs``. Warewulf will add ``mpol=interleave`` to the mount point default ``initramfs``. Warewulf will add ``mpol=interleave`` to the mount point
which will distribute the memory across all NUMA nodes. This avoids the which will distribute the memory across all NUMA nodes. This avoids the
hotspotting that occurs when the default initramfs stores large node images on a hotspotting that occurs when the default initramfs stores large OS images on a
single NUMA node. To enable this, set the rootfs type to tmpfs: single NUMA node. To enable this, set the rootfs type to tmpfs:
.. code-block:: shell .. code-block:: shell

View File

@@ -253,7 +253,7 @@ Warewulf is a stateless and diskless provisioning system for large clusters of
bare metal and/or virtual systems. bare metal and/or virtual systems.
This subpackage contains a dracut module that can be used to generate an This subpackage contains a dracut module that can be used to generate an
initramfs that can fetch and boot a Warewulf node image from a Warewulf server. initramfs that can fetch and boot a Warewulf OS image from a Warewulf server.
%files dracut %files dracut
%defattr(-, root, root) %defattr(-, root, root)