NFS Limitations for Warewulf Image Storage

Stephen Simpson
Senior Customer Support Engineer

Jul 16, 2026

Introduction

Warewulf builds and imports node images into a chroot directory on the control node, set by wwchrootdir in warewulf.conf (package default /var/lib/warewulf/chroots). This directory should reside on a block-backed filesystem (a local disk, or a network block device such as iSCSI), not on NFS. Pointing it at an NFS share can cause failed builds, incorrect image contents, and hung wwctl processes. Applies to Warewulf 4.6 and later.

Problem

Image build and import is a privileged, metadata-heavy operation. wwctl image import and wwctl image build unpack image layers into <wwchrootdir>/<image-name>/rootfs/, creating thousands of small files, setting ownership and permissions, and writing extended attributes such as SELinux contexts. NFS handles these operations differently from a local filesystem, which produces one or more of the following failures.

Root squashing

Most NFS exports enable root_squash, which maps the root user to an anonymous account. Image unpacking runs as root and sets file ownership directly. Under root_squash the server remaps those writes, so files that should be owned by root or by specific system accounts are created with the wrong owner. The image builds without an obvious error but has incorrect ownership.

Extended attributes and SELinux contexts

Warewulf images carry SELinux security contexts and other extended attributes. Whether NFS preserves extended attributes depends on the protocol version and export configuration, and many deployments drop them silently. Images built on NFS can boot with missing or incorrect SELinux labels.

Metadata performance

An image contains thousands of small files. Over NFS, each file creation, ownership change, and attribute write is a separate round trip to the server, so an import or build that takes seconds on a local disk can take many minutes.

Interrupted mounts block the build

NFS shares are typically mounted hard. If the server or network path stalls during a build, the wwctl process enters uninterruptible sleep (state D) and cannot be killed until the mount recovers or is unmounted. A block-backed filesystem does not have this failure mode.

Symptoms

Confirm this article applies by checking whether wwchrootdir is on an NFS mount. Read the configured path first, then check that path's filesystem type. Substitute your configured wwchrootdir below if it differs from the default:

grep -A6 '^paths:' /etc/warewulf/warewulf.conf
findmnt -T /var/lib/warewulf/chroots -o SOURCE,FSTYPE

If FSTYPE is nfs or nfs4, the image directory is on NFS and this article applies.

Observable symptoms include:

wwctl image import or wwctl image build runs far slower than expected, or stops progressing at the unpack stage.
The wwctl process sits in uninterruptible sleep (state D) in ps -ef and does not respond to kill, including SIGKILL, until the mount recovers or is unmounted.
dmesg reports a blocked task in the NFS writeback path.
Nodes boot with incorrect file ownership or SELinux denials.

Resolution

Move wwchrootdir onto block storage.

Check the current value in the paths section of /etc/warewulf/warewulf.conf:
```
grep -A6 '^paths:' /etc/warewulf/warewulf.conf
```
Set wwchrootdir to a path on a block-backed filesystem with enough free space. The package default already lives on the control node's root filesystem:
```
paths:
  wwchrootdir: /var/lib/warewulf/chroots
```
If you need more capacity, use a dedicated local filesystem or a network block device such as iSCSI rather than an NFS export:
```
paths:
  wwchrootdir: /srv/warewulf/chroots
```
Restart the daemon so the new path takes effect:
```
sudo systemctl restart warewulfd
```
Re-import or rebuild each image so it exists under the new local path. Images under the old path are not moved automatically.
After confirming the nodes boot correctly, remove the leftover directories from the old NFS location.

Notes

NFS is appropriate for other cluster storage, including user home directories, shared application trees, and datasets served to compute nodes. Warewulf can generate and serve those NFS exports itself. Only the image build and import directory (wwchrootdir) must stay off NFS.

The provisioning directory (wwprovisiondir, package default /var/lib/warewulf/provision), which holds the compressed images served to nodes, should also stay off NFS.

References & related articles

Warewulf Documentation - Node Images
Warewulf Documentation - Server Configuration
Warewulf Documentation - SELinux-enabled Images
Mounting NFS Shares on Warewulf Nodes Using Systemd Overlays