Generating an Initial Ramdisk with NFSv4 Support in Arch Linux

When I first tried to boot my diskless Arch Linux node over PXE, I kept hitting the frustrating error:

ERROR: device '/dev/nfs' not found.

At first, I thought my NFS server was the problem, but the real issue was the initramfs. By default, initramfs generated with mkinitcpio only supports the legacy nfsmount helper. Modern systems (especially with NFSv4) rely on mount.nfs4. Since the initramfs didn’t know how to handle NFSv4, it failed to detect /dev/nfs and halted the boot process.

This means the problem isn’t with the server—it’s with the initramfs itself. To successfully mount a root filesystem over the network using NFSv4, we need to extend Arch’s initramfs with proper NFSv4 support. In this post, I’ll show you how to generate a custom initramfs that works seamlessly for diskless PXE clients.

1. Create a Btrfs Disk Image

First, create a loopback image that will act as the root filesystem and format it with Btrfs:

sudo truncate -s 5G /srv/arch.img
sudo mkfs.btrfs /srv/arch.img
export root=/srv/arch
sudo mount --mkdir -o loop,compress=lzo /srv/arch.img "$root"

2. Bootstrap a Minimal Arch System

Install the base system along with Linux kernel, firmware, and NFS tools:

sudo pacstrap -K "$root" base linux linux-firmware mkinitcpio-nfs-utils nfs-utils

3. Configure mkinitcpio

Edit $root/etc/mkinitcpio.conf and make these changes:

  • Add nfsv4 to MODULES.
  • Add netnfs4 to HOOKS.
  • Add /usr/bin/mount.nfs4 to BINARIES.

4. Patch the Net Hook for NFSv4

Enter the chroot and create a new hook for NFSv4 support:

sudo arch-chroot "$root"
sed 's/nfsmount/mount.nfs4/' /usr/lib/initcpio/hooks/net > /usr/lib/initcpio/hooks/netnfs4
cp /usr/lib/initcpio/install/net /usr/lib/initcpio/install/netnfs4

5. Generate Initramfs

Finally, rebuild the initramfs with the new hook being inside chroot:

mkinitcpio -p linux

This produces an initramfs-linux.img at $root/boot/ directory that supports mounting a root filesystem over NFSv4 during PXE boot.

References