From 65078525eb421f3ebea034b18806b8fa5d3f5e85 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Sun, 19 Jan 2025 14:13:13 -0700 Subject: [PATCH] Move information about image size limitations to known issues Signed-off-by: Jonathon Anderson --- userdocs/contents/images.rst | 38 --------------------------- userdocs/contents/known-issues.rst | 42 ++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 38 deletions(-) diff --git a/userdocs/contents/images.rst b/userdocs/contents/images.rst index 35fa872c..1a22d509 100644 --- a/userdocs/contents/images.rst +++ b/userdocs/contents/images.rst @@ -396,44 +396,6 @@ openSUSE Leap image and import it to Warewulf: # podman save localhost/leap-ww:latest -o ~/leap-ww.tar # wwctl image import file://root/leap-ww.tar leap-ww -Image Size Considerations -========================= - -Base compute node images start quite small (a few hundred -megabytes), but can grow quickly as packages and other files are added -to them. Even these larger images are typically 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: - -* Systems booting in legacy / BIOS mode, being a 32-bit environment, - cannot boot an image that requires more than 4GB to decompress. This - means that the compressed image and the decompressed image together - must be < 4GB. This is typically reported by the system as "No space - left on device (https://ipxe.org/34182006)." - - The best work-around for this limitation is to switch to UEFI. UEFI - is 64-bit and should support booting significantly larger images, - though sometimes system-specific implementation details have led to - artificial limitations on image size. - -* The Linux kernel itself can only decompress an image up to 4GB due - to the use of 32-bit integers in critical sections of the kernel - initrd decompression code. - - The best work-around for this limitation is to use an iPXE with - support for `imgextract `_. This - allows iPXE to decompress the image rather than the kernel. - -* 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. - - 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 or firmware. - Duplicating an image ==================== diff --git a/userdocs/contents/known-issues.rst b/userdocs/contents/known-issues.rst index 0ead49cd..be279259 100644 --- a/userdocs/contents/known-issues.rst +++ b/userdocs/contents/known-issues.rst @@ -54,3 +54,45 @@ To resolve this, remove the sockets from the source directory. This issue was fixed in an upstream library and `should be resolved in Warewulf v4.6.0. `_ + +Image Size Considerations +========================= + +Node 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: + +* Warewulf's :ref:`two-stage boot support ` effectively + eliminates this problem by handling the bulk of the image management within + Linux. This feature is currently in preview, and is subject to change; but it + is likely to become the default boot method in a future release. + +* Systems booting in legacy / BIOS mode, being a 32-bit environment, + cannot boot an image that requires more than 4GB to decompress. This + means that the compressed image and the decompressed image together + must be < 4GB. This is typically reported by the system as "No space + left on device (https://ipxe.org/34182006)." + + The best work-around for this limitation is to switch to UEFI. UEFI + is 64-bit and should support booting significantly larger images, + though sometimes system-specific implementation details have led to + artificial limitations on image size. + +* The Linux kernel itself can only decompress an image up to 4GB due + to the use of 32-bit integers in critical sections of the kernel + initrd decompression code. + + The best work-around for this limitation is to use an iPXE with + support for `imgextract `_. This + allows iPXE to decompress the image rather than the kernel. + +* 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. + + 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 or firmware.