Mounting NFS Shares on Warewulf Nodes Using Systemd Overlays

Introduction

This article describes how to configure persistent NFS mounts on Warewulf-provisioned compute nodes using Warewulf overlays and systemd unit files. This method provides more flexibility compared to traditional /etc/fstab entries. Warewulf overlays allow injecting custom files and configurations into nodes. We will create an overlay containing systemd mount units to manage NFS shares.

Prerequisites

Decide if you want a single overlay for all NFS mounts or separate overlays for different mount points. Separate overlays offer more granular control, allowing different nodes to receive different combinations of mounts. This guide demonstrates using a single overlay for multiple mounts. You can repeat this for any other mountpoints you wish to cover.

Ensure that your path is properly exported on your server.

Create Systemd Unit Files

First, create systemd .mount unit files for each NFS share on your Warewulf control server. The unit file name must correspond to the mount path, replacing slashes / with hyphens -. For example, a mount point of /data/common requires a unit file named data-common.mount.

Save the following example files (adjusting NFS server IP, export paths, and mount options as needed). For simplicity, we save them in /root on the Warewulf server.

/root/home.mount:

[Unit]
Description=NFS Mount /export/home to /home
Requires=network-online.target
After=network-online.target

[Mount]
What=10.10.10.5:/export/home
Where=/home
Type=nfs
Options=defaults,_netdev

[Install]
WantedBy=multi-user.target

/root/data-common.mount:

[Unit]
Description=NFS Mount /export/common to /data/common
Requires=network-online.target
After=network-online.target

[Mount]
What=10.10.10.5:/export/common
Where=/data/common
Type=nfs
Options=defaults,_netdev

[Install]
WantedBy=multi-user.target

Create Warewulf Overlay

Next, create a Warewulf overlay and import the systemd unit files into the correct location (/etc/systemd/system/).

wwctl overlay create nfs-mounts
wwctl overlay mkdir nfs-mounts /etc/systemd/system/
wwctl overlay import nfs-mounts /root/home.mount /etc/systemd/system/home.mount
wwctl overlay import nfs-mounts /root/data-common.mount /etc/systemd/system/data-common.mount

Enable Mounts at Boot

To ensure systemd automatically mounts these shares at boot, enable the units by creating symbolic links within the overlay structure on the Warewulf server.

wwctl overlay mkdir nfs-mounts /etc/systemd/system/multi-user.target.wants/

ln -s /var/lib/warewulf/overlays/nfs-mounts/rootfs/etc/systemd/system/home.mount \
      /var/lib/warewulf/overlays/nfs-mounts/rootfs/etc/systemd/system/multi-user.target.wants/home.mount

ln -s /var/lib/warewulf/overlays/nfs-mounts/rootfs/etc/systemd/system/data-common.mount \
      /var/lib/warewulf/overlays/nfs-mounts/rootfs/etc/systemd/system/multi-user.target.wants/data-common.mount

Assign Overlay to Nodes/Profiles

Assign the overlay to the desired nodes. Using profiles is recommended for managing groups of nodes. Create a new profile for the NFS mounts and assign the nfs-mounts overlay to its RuntimeOverlay list. Runtime overlays are applied during the node boot process and updated continually while the run node is running.

wwctl profile add nfs-profile --comment="Profile for NFS systemd mounts"

wwctl profile set nfs-profile --runtime-overlays="nfs-mounts"

Add this profile to your compute nodes:

wwctl node set compute01 --profile="<existing-profiles>,nfs-profile"

Build Overlays

Build the overlays for all your nodes with the build command:

wwctl overlay build

Reboot and Verify

Reboot the compute nodes that now have the nfs-profile assigned. If you set this as a Runtime Overlay, you should see the systemd units available within a few minutes. You will need to manually start these services if you chose not to reboot. Once logged in, verify the NFS shares are mounted correctly.

mount | grep nfs
df -hT | grep nfs
systemctl status home.mount
systemctl status data-common.mount

If this is not mounted, you can check the logs with

journalctl -u data-common.mount

Notes

• Remember that systemd unit file names for mounts must reflect the mount path, replacing / with - (e.g., /data/common becomes data-common.mount). This is critical for systemd to mount the folders correctly.
• Ensure the NFS server IP address, exported paths, and mount options in the .mount files are correct for your environment.
• The Requires=network-online.target and After=network-online.target directives along with the _netdev mount option help ensure networking is available before attempting the NFS mount.

References & related articles

Warewulf Overlays Documentation
Warewulf Node Profiles Documentation
systemd.mount Documentation
Rocky Linux NFS Service Guide