From 7909598a3d1f46239b7f4655e0225f09036026bd Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 18 Mar 2026 08:10:49 -0600 Subject: [PATCH] Distinguish between OS images and overlay images in documentation Signed-off-by: Jonathon Anderson --- CHANGELOG.md | 4 +--- containers/README.md | 4 ++-- internal/app/wwctl/image/root.go | 8 +++---- internal/pkg/warewulfd/api/image.go | 16 ++++++------- userdocs/getting-started/el-quickstart.rst | 6 ++--- userdocs/getting-started/glossary.rst | 25 ++++++++++++++------ userdocs/getting-started/introduction.rst | 16 ++++++------- userdocs/images/images.rst | 22 ++++++++--------- userdocs/images/selinux.rst | 4 ++-- userdocs/index.rst | 2 +- userdocs/nodes/disks.rst | 23 +++++++----------- userdocs/overlays/overlays.rst | 8 +++---- userdocs/release/v4.6.2.rst | 2 +- userdocs/release/v4.6.5.rst | 2 +- userdocs/server/bootloaders.rst | 10 ++++---- userdocs/server/routes.rst | 2 +- userdocs/server/security.rst | 4 ++-- userdocs/troubleshooting/known-issues.rst | 4 ++-- userdocs/troubleshooting/troubleshooting.rst | 12 +++++----- warewulf.spec.in | 2 +- 20 files changed, 89 insertions(+), 87 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca451188..f99fff5b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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; the node continues to boot and `wwclient` retries the download at runtime. - `hosts` overlay added to the default system overlay list - -### Changed - +- Distinguish between OS images and overlay images in documentation - Updated `MAINTAINING.md` to document golang version policy ## v4.6.5, 2026-01-12 diff --git a/containers/README.md b/containers/README.md index 5782dc7d..46afbb40 100644 --- a/containers/README.md +++ b/containers/README.md @@ -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. diff --git a/internal/app/wwctl/image/root.go b/internal/app/wwctl/image/root.go index f26fecf9..ffdf2f09 100644 --- a/internal/app/wwctl/image/root.go +++ b/internal/app/wwctl/image/root.go @@ -19,11 +19,9 @@ var baseCmd = &cobra.Command{ DisableFlagsInUseLine: true, Use: "image COMMAND [OPTIONS]", Short: "Operating system image management", - Long: "Starting with version 4, Warewulf uses images to build the bootable\n" + - "node images. These commands will help you import, manage, and transform\n" + - "images into bootable Warewulf images.", - Aliases: []string{"vnfs", "container"}, - Args: cobra.NoArgs, + Long: "Import, manage, and transform OS images as bootable Warewulf images.", + Aliases: []string{"vnfs", "container"}, + Args: cobra.NoArgs, } func init() { diff --git a/internal/pkg/warewulfd/api/image.go b/internal/pkg/warewulfd/api/image.go index 4156f196..46836196 100644 --- a/internal/pkg/warewulfd/api/image.go +++ b/internal/pkg/warewulfd/api/image.go @@ -54,7 +54,7 @@ func getImages() usecase.Interactor { } }) u.SetTitle("Get images") - u.SetDescription("Get all node images") + u.SetDescription("Get all OS images") u.SetTags("Image") return u } @@ -74,7 +74,7 @@ func getImageByName() usecase.Interactor { } }) 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") return u } @@ -110,7 +110,7 @@ func importImage() usecase.Interactor { } }) 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") return u @@ -146,7 +146,7 @@ func deleteImage() usecase.Interactor { return image_api.ImageDelete(cdp) }) u.SetTitle("Delete an image") - u.SetDescription("Delete an existing node image") + u.SetDescription("Delete an existing OS image") u.SetTags("Image") return u @@ -156,7 +156,7 @@ func updateImage() usecase.Interactor { type renameImageInput struct { Name string `path:"name" required:"true" description:"Name of image to update"` 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 { @@ -179,7 +179,7 @@ func updateImage() usecase.Interactor { return nil }) 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") return u @@ -188,7 +188,7 @@ func updateImage() usecase.Interactor { func buildImage() usecase.Interactor { type buildImageInput struct { 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 { @@ -206,7 +206,7 @@ func buildImage() usecase.Interactor { return nil }) u.SetTitle("Build an image") - u.SetDescription("Build a node image") + u.SetDescription("Build an OS image") u.SetTags("Image") return u diff --git a/userdocs/getting-started/el-quickstart.rst b/userdocs/getting-started/el-quickstart.rst index 112c4e3a..d3e06ce7 100644 --- a/userdocs/getting-started/el-quickstart.rst +++ b/userdocs/getting-started/el-quickstart.rst @@ -155,10 +155,10 @@ configure --all``. you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label 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. .. code-block:: bash diff --git a/userdocs/getting-started/glossary.rst b/userdocs/getting-started/glossary.rst index dca5d241..bcdbdac9 100644 --- a/userdocs/getting-started/glossary.rst +++ b/userdocs/getting-started/glossary.rst @@ -12,13 +12,7 @@ External services configures a DHCP server (either ISC DHCP or dnsmasq) and a TFTP server. Image - The node images that Warewulf manages and provisions. Images may be imported - 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. + See "Operating System (OS) Image" or "Overlay Image." Kernel 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 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 Warewulf overlays provide customization for the provisioned image. Overlays 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 **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 Warewulf profiles are abstract nodes that carry the same configuration attributes but do not provision any specific node. Warewulf nodes may then diff --git a/userdocs/getting-started/introduction.rst b/userdocs/getting-started/introduction.rst index 8a1d5500..b5778309 100644 --- a/userdocs/getting-started/introduction.rst +++ b/userdocs/getting-started/introduction.rst @@ -9,10 +9,10 @@ Warewulf is known for its massive scalability and simple management of stateless (disk optional) provisioning. Warewulf leverages a simple administrative model centralizing administration -around virtual node images which are used to provision out to the cluster nodes. -This means you can have hundreds or thousands of cluster nodes all booting and -running on the same node image. As of Warewulf v4, the node image can be managed -using industry-standard container tooling and/or CI/CD pipelines. This can be as +around virtual OS images which are used to provision cluster nodes. This means +you can have hundreds or thousands of cluster nodes all booting and running on +the same OS image. As of Warewulf v4, the OS image can be managed using +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 architecture, Warewulf combines the best of High Performance Computing (HPC), Cloud, Hyperscale, and Enterprise deployment principles to create and maintain @@ -47,7 +47,7 @@ flexible provisioning system for all types of clusters. any environment. * **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 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 multiple nodes. -**Node images** provide a bootable operating system image, including the kernel -that will be used to boot the cluster node. Node images provide a base operating +**Operating system images** provide a bootable image, including the kernel +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 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. **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. Beowulf overview diff --git a/userdocs/images/images.rst b/userdocs/images/images.rst index aa223a69..d2d3d09b 100644 --- a/userdocs/images/images.rst +++ b/userdocs/images/images.rst @@ -1,15 +1,15 @@ .. _images: -=========== -Node Images -=========== +========= +OS Images +========= -Warewulf node images are a "Virtual Node File System" (VNFS) that serves as a -base image for cluster nodes. This is similar to a "golden master" image, except +Warewulf operating system (OS) images are a "Virtual Node File System" (VNFS) +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 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 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 @@ -58,7 +58,7 @@ or Apptainer sandbox. 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 @@ -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 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. - The Warewulf project maintains a set of `example node images + The Warewulf project maintains a set of `example OS images `_ that are configured to boot when used with Warewulf. These images can be imported directly into 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 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 session. @@ -310,7 +310,7 @@ package repository caches that may have been generated. 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 define new images with a container image definition file. This can be done using the OCI and Singularity (Apptainer) ecosystems. diff --git a/userdocs/images/selinux.rst b/userdocs/images/selinux.rst index 981a24f7..43399a29 100644 --- a/userdocs/images/selinux.rst +++ b/userdocs/images/selinux.rst @@ -16,8 +16,8 @@ for SELinux context labeling.) .. note:: 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 - this is no longer required. + "rootfstype=ramfs" in order for wwinit to copy the image to tmpfs; but this + is no longer required. 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 diff --git a/userdocs/index.rst b/userdocs/index.rst index 03b8b6b5..dade4741 100644 --- a/userdocs/index.rst +++ b/userdocs/index.rst @@ -45,7 +45,7 @@ Welcome to the Warewulf User Guide! :maxdepth: 1 :caption: Images - Node Images + OS Images Image Kernels Syncuser SELinux diff --git a/userdocs/nodes/disks.rst b/userdocs/nodes/disks.rst index c9fb6f3c..04cb2abf 100644 --- a/userdocs/nodes/disks.rst +++ b/userdocs/nodes/disks.rst @@ -12,11 +12,6 @@ sfdisk, mkfs, and mkswap during boot. Ignition can, for example, create ``swap`` partitions or ``/scratch`` file systems. -.. note:: - - Warewulf is not currently able to provision the node image onto an explicitly - provisioned root file system. - Requirements ============ @@ -153,7 +148,7 @@ See the `upstream ignition documentation`_ for additional information. 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 right conditions. Whether swap can free image memory depends on which root 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 ``--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 would any other anonymous memory. Adding swap therefore lets the kernel evict 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 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 -``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, switch to ``tmpfs`` root first: @@ -284,9 +279,9 @@ needs memory, first note the image size with ``df -h /``: df -h / 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 total RAM — to force the kernel to evict image pages. Compute the target from ``MemTotal``: @@ -310,7 +305,7 @@ While ``stress-ng`` is running, observe memory usage: Mem: 15Gi 15Gi 32Mi 120Mi 512Mi 192Mi 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 application. The application can access the full physical memory of the node, 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. Moving image pages to swap proactively ---------------------------------------- +-------------------------------------- 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 @@ -352,7 +347,7 @@ systemd unit to a custom overlay that runs at ``local-fs.target``: .. code-block:: ini [Unit] - Description=Reclaim node image memory to swap + Description=Reclaim OS image memory to swap After=local-fs.target ConditionPathExists=/sys/fs/cgroup/memory.reclaim @@ -472,7 +467,7 @@ functionality is used: 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. .. code-block:: shell diff --git a/userdocs/overlays/overlays.rst b/userdocs/overlays/overlays.rst index 0ee6a0ac..7d2625c7 100644 --- a/userdocs/overlays/overlays.rst +++ b/userdocs/overlays/overlays.rst @@ -2,7 +2,7 @@ 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 and built per-node and then applied over the image during the provisioning process. @@ -239,7 +239,7 @@ provisioning actions: 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 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 For a complete walkthrough of configuring swap to free memory consumed by the -in-memory node image, including which root filesystem types support swap -reclamation, see :ref:`swap-and-image-memory`. +in-memory image, including which root filesystem types support swap reclamation, +see :ref:`swap-and-image-memory`. systemd mounts -------------- diff --git a/userdocs/release/v4.6.2.rst b/userdocs/release/v4.6.2.rst index 623dffc1..2f9baff6 100644 --- a/userdocs/release/v4.6.2.rst +++ b/userdocs/release/v4.6.2.rst @@ -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 -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. Significant changes are described below. Additional changes are listed in the diff --git a/userdocs/release/v4.6.5.rst b/userdocs/release/v4.6.5.rst index 8a3ca000..af92e8b4 100644 --- a/userdocs/release/v4.6.5.rst +++ b/userdocs/release/v4.6.5.rst @@ -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*``. These fixes require installing the updated ``warewulf-dracut`` package in the -node image. +OS image. Other fixes =========== diff --git a/userdocs/server/bootloaders.rst b/userdocs/server/bootloaders.rst index 01f15c88..214aa497 100644 --- a/userdocs/server/bootloaders.rst +++ b/userdocs/server/bootloaders.rst @@ -32,7 +32,7 @@ the Warewulf configuration process to configure the ``ipxe`` service. 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"]; } @@ -235,7 +235,7 @@ Warewulf as a technology preview. grubcfg[shape=record label="{grub.cfg|static under TFTP root}"]; 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"]; } @@ -308,9 +308,9 @@ diagram is the following: digraph G{ node [shape=box]; 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}"]; - grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from node image}"] - kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|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 OS image}"] + kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"]; efi->shim [label="http"]; shim->grub [label="http"]; grub->kernel [label="http"]; diff --git a/userdocs/server/routes.rst b/userdocs/server/routes.rst index 265f13a9..24dbd98e 100644 --- a/userdocs/server/routes.rst +++ b/userdocs/server/routes.rst @@ -93,7 +93,7 @@ kernel is taken from the node's assigned image. ``/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`` diff --git a/userdocs/server/security.rst b/userdocs/server/security.rst index 2876e59d..5693e24b 100644 --- a/userdocs/server/security.rst +++ b/userdocs/server/security.rst @@ -11,7 +11,7 @@ Provisioning Security Provisioning is, by default, a relatively "insecure" process: there is generally 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. 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 "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 `. firewalld diff --git a/userdocs/troubleshooting/known-issues.rst b/userdocs/troubleshooting/known-issues.rst index 51cac30b..9f796513 100644 --- a/userdocs/troubleshooting/known-issues.rst +++ b/userdocs/troubleshooting/known-issues.rst @@ -63,7 +63,7 @@ v4.6.0. `_ 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 architectural limits exist that can impede the use of images larger than a few 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., 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" errors, try disabling any "memory hole" features or updating your system BIOS diff --git a/userdocs/troubleshooting/troubleshooting.rst b/userdocs/troubleshooting/troubleshooting.rst index ad584e3c..d4ccbf7a 100644 --- a/userdocs/troubleshooting/troubleshooting.rst +++ b/userdocs/troubleshooting/troubleshooting.rst @@ -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 ``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, by default, loads the entire image as an initial ramdisk, and also loads the 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 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 ==== @@ -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 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 ====== @@ -217,8 +217,8 @@ the new configuration. .. note:: - The node image itself must have Podman (or the desired container runtime) - installed. See :ref:`images` for guidance on customizing node images. + The OS image itself must have Podman (or the desired container runtime) + installed. See :ref:`images` for guidance on customizing OS images. For information on tuning tmpfs memory usage and NUMA interleaving behavior, 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 default ``initramfs``. Warewulf will add ``mpol=interleave`` to the mount point 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: .. code-block:: shell diff --git a/warewulf.spec.in b/warewulf.spec.in index 855e1821..df59e810 100644 --- a/warewulf.spec.in +++ b/warewulf.spec.in @@ -253,7 +253,7 @@ Warewulf is a stateless and diskless provisioning system for large clusters of bare metal and/or virtual systems. 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 %defattr(-, root, root)