Diskless system

From ArchWiki

From Wikipedia:Diskless node:

A diskless node (or diskless workstation) is a workstation or personal computer without disk drives, which employs network booting to load its operating system from a server.

Server configuration

First of all, we must install the following components:

  • A DHCP server to assign IP addresses to our diskless nodes.
  • A TFTP server to transfer the boot image (a requirement of all PXE option roms).
  • A form of network storage (NFS, Samba or NBD) to export the Arch installation to the diskless node.
  • dnsmasq is capable of simultaneously acting as both DHCP and TFTP server. For more information, see the dnsmasq article.
  • You can also boot Arch Linux without using PXE at all. See the SKUF item below.


Install ISC dhcp and configure it:

allow booting;
allow bootp;


option domain-name-servers;

option architecture code 93 = unsigned integer 16;

group {

    if option architecture = 00:07 {
        filename "/grub/x86_64-efi/core.efi";
    } else {
        filename "/grub/i386-pc/core.0";

    subnet netmask {
        option routers;
Note: next-server should be the address of the TFTP server; everything else should be changed to match your network

RFC:4578 defines the "Client System Architecture Type" dhcp option. In the above configuration, if the PXE client requests an x86_64-efi binary (type 0x7), we appropriately give them one, otherwise falling back to the legacy binary. This allows both UEFI and legacy BIOS clients to boot simultaneously on the same network segment.

Start ISC DHCP systemd service.


The TFTP server will be used to transfer the bootloader, kernel, and initramfs to the client.

Set the TFTP root to /srv/arch/boot. See TFTP for installation and configuration.

Network storage

The primary difference between using NFS and NBD is while with both you can in fact have multiple clients using the same installation, with NBD (by the nature of manipulating a filesystem directly) you will need to use the copyonwrite mode to do so, which ends up discarding all writes on client disconnect. In some situations however, this might be highly desirable.


Install nfs-utils on the server.

You will need to add the root of your Arch installation to your NFS exports:

/srv       *(rw,fsid=0,no_root_squash,no_subtree_check)
/srv/arch  *(rw,no_root_squash,no_subtree_check)

Next, start NFS services: nfs-idmapd nfs-mountd.


Install nbd and configure it.

    user = nbd
    group = nbd
    exportname = /srv/arch.img
    copyonwrite = false
Note: Set copyonwrite to true if you want to have multiple clients using the same NBD share simultaneously; refer to nbd-server(5) for more details. Also use chown to change the ownership of the exportname directory to the user nbd.

Start nbd systemd service.


You can boot Arch Linux using the SKUF Network Boot System project, where the root of the file system will be a sparse file located on Samba server.

To get started, install samba and create a configuration file:

	workgroup = WORKGROUP
	security = user

	path = /srv/samba
	valid users = @skuf
	write list = @skuf
	guest ok = no
	read only = no
	writeable = yes
	browseable = yes
Note: All your sparse images will lie in the specified directory (in this example /srv/samba).

Start smb systemd service

Then, create a skuf group and users who will be members of it and through whom SAMBA mounting on the client machine will happen.

# groupadd skuf
# useradd test -g skuf
# smbpasswd -a test

Client installation

Next we will create a full Arch Linux installation in a subdirectory on the server. During boot, the diskless client will get an IP address from the DHCP server, then boot from the host using PXE and mount this installation as its root.

Directory setup

Note: Creating a separate filesystem is required for NBD but optional for NFS and can be skipped/ignored.

Create a sparse file of at least 2 gibibytes, and create a btrfs filesystem on it (you can of course also use a real block device or LVM if you want).

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

Bootstrapping installation

Install devtools and arch-install-scripts, and run pacstrap to install the essential packages for the client:

# pacstrap -K "$root" base linux linux-firmware mkinitcpio-nfs-utils nfs-utils
Note: In all cases mkinitcpio-nfs-utils is still required. ipconfig used in early-boot is provided only by the latter.

Now the initramfs needs to be constructed.


Trivial modifications to the net hook are required in order for NFSv4 mounting to work (not supported by nfsmount – the default for the net hook).

# sed s/nfsmount/mount.nfs4/ "$root/usr/lib/initcpio/hooks/net" > "$root/usr/lib/initcpio/hooks/netnfs4"
# cp $root/usr/lib/initcpio/install/net{,nfs4}

The copy of net is unfortunately needed so it does not get overwritten when mkinitcpio-nfs-utils is updated on the client installation.

Edit $root/etc/mkinitcpio.conf and add nfsv4 to MODULES, netnfs4 to HOOKS, and /usr/bin/mount.nfs4 to BINARIES.

Next, we chroot our installation and run mkinitcpio:

# arch-chroot "$root" mkinitcpio -p linux


The mkinitcpio-nbdAUR package needs to be installed on the client. Build it with makepkg and install it:

# pacman --root "$root" --dbpath "$root/var/lib/pacman" -U mkinitcpio-nbd-0.4-1-any.pkg.tar.xz

You will then need to append nbd to your HOOKS array after net; net will configure your networking for you, but not attempt a NFS mount if nfsroot is not specified in the kernel line.


To install Arch Linux on sparse file using SKUF Network Boot System, clone the git repository:

$ git clone https://github.com/BiteDasher/skuf.git
$ cd skuf
$ ./switch-tag latest

Then, build the skuf package and ISO image which will later be used as a "kickstart" to start the main system using kexec

First of all, you need to tune the method of encrypting your passwords for SAMBA (see [1] for more details):

1234 Test password!

Set up defaults:


And finally, build skuf package:

$ ./tune_crypt.sh
$ ./tune_password.sh
$ ./setup_defaults.sh
$ ./build_rootfs_tar.sh
$ ./build_package.sh

ISO image:

# ./setup_repo.sh
# ./build_iso.sh

And sparse file with Arch Linux:

# ./create_image.sh -s SIZE_IN_GIGABYTES additional_packages

Then, move arch.ext4 in /srv/samba.

Client configuration

In addition to the setup mentioned here, you should also set up your hostname, timezone, locale, and keymap, and follow any other relevant parts of the Installation guide.



This article or section is a candidate for merging with GRUB.

Notes: (Discuss in Talk:Diskless system)

Though poorly documented, GRUB supports being loaded via PXE.

# pacman --root "$root" --dbpath "$root/var/lib/pacman" -S grub

Create a grub prefix on the target installation for both architectures using grub-mknetdir.

# arch-chroot "$root" grub-mknetdir --net-directory=/boot --subdir=grub

Luckily for us, grub-mknetdir creates prefixes for all currently compiled/installed targets, and the grub maintainers were nice enough to give us both in the same package, thus grub-mknetdir only needs to be run once.

Note: This example config assumes the NFS/NBD server's IP being

Now we create a trivial GRUB configuration:

# vim "$root/boot/grub/grub.cfg"
menuentry "Arch Linux" {
    linux /vmlinuz-linux quiet add_efi_memmap ip=:::::eth0:dhcp nfsroot=
    initrd /initramfs-linux.img

menuentry "Arch Linux (NBD)" {
    linux /vmlinuz-linux quiet add_efi_memmap ip=:::::eth0:dhcp nbd_host= nbd_name=arch root=/dev/nbd0
    initrd /initramfs-linux.img

GRUB will set root=(tftp, automatically, so that the kernel and initramfs are transferred via TFTP without any additional configuration, though you might want to set it explicitly if you have any other non-tftp menuentries.

  • All GRUB files and initcpio files must be available through TFTP. For example, for a NBD install with TFTP root set to /srv/tftp, /srv/tftp/grub/x86_64-efi/core.efi, /srv/tftp/vmlinuz-linux must be present to boot successfully. You may copy all the /boot files inside the image to TFTP server's root.
  • You may generate grub config by grub-mkconfig to ensure video settings are set correctly. However, it is needed to edit boot.cfg afterwards, to remove search --no-floppy ... and ensure linux initrd options (paths, NBD settings, NFS settings) are set correctly.
  • Modify your kernel line as-necessary, refer to PXELINUX for NBD-related options.


PXELINUX is provided by syslinux, see PXELINUX for details.

Additional mountpoints

NBD root

In late boot, you will want to switch your root filesystem mount to both rw, and enable compress=lzo, for much improved disk performance in comparison to NFS.

# vim "$root/etc/fstab"
/dev/nbd0  /  btrfs  rw,noatime,compress=lzo  0 0

Program state directories

The factual accuracy of this article or section is disputed.

Reason: systemd does not use persistent logging by default when /var/log/journal is in tmpfs and/or does not exist (Discuss in Talk:Diskless system)

You could mount /var/log, for example, as tmpfs so that logs from multiple hosts do not mix unpredictably, and do the same with /var/spool/cups, so the 20 instances of cups using the same spool do not fight with each other and make 1,498 print jobs and eat an entire ream of paper (or worse: toner cartridge) overnight.

# vim "$root/etc/fstab"
tmpfs   /var/log        tmpfs     nodev,nosuid    0 0
tmpfs   /var/spool/cups tmpfs     nodev,nosuid    0 0

It would be best to configure software that has some sort of state/database to use unique state/database storage directories for each host. If you wanted to run puppet, for example, you could simply use the %H specifier in the puppet unit file:

# vim "$root/etc/systemd/system/puppetagent.service"
Description=Puppet agent
After=basic.target network.target

ExecStartPre=/usr/bin/install -d -o puppet -m 755 /run/puppet
ExecStart=/usr/bin/puppet agent --vardir=/var/lib/puppet-%H --ssldir=/etc/puppet/ssl-%H


Puppet-agent creates vardir and ssldir if they do not exist.

If neither of these approaches are appropriate, the last sane option would be to create a systemd.generator(7) that creates a mount unit specific to the current host (specifiers are not allowed in mount units, unfortunately).

Client boot


The factual accuracy of this article or section is disputed.

Reason: When using COW on the server, the clients all effectively have read-only mounts of the original filesystem; it should theoretically be safe to do a read-write mount on the NBD server (Discuss in Talk:Diskless system)

If you are using NBD, you will need to umount the arch.img before/while you boot your client.

This makes things particularly interesting when it comes to kernel updates. You cannot have your client filesystem mounted while you are booting a client, but that also means you need to use a kernel separate from your client filesystem in order to build it.

You will need to first copy $root/boot from the client installation to your tftp root (i.e. /srv/boot).

# cp -r "$root/boot" /srv/boot

You will then need to umount $root before you start the client.

# umount "$root"
Note: To update the kernel in this setup, you either need to mount /srv/boot using NFS in fstab on the client (prior to doing the kernel update) or mount your client filesystem after the client has disconnected from NBD


Write skuflinux-smth.iso to your USB drive, plug it in client computer and select in UEFI/BIOS settings as a boot device.

Note: If the client computer has UEFI, you can install SKUF on a ESP partition so you don't have to use a USB flash drive/CD/DVD. To do this, mount skuflinux-smth.iso somewhere (like /mnt), then copy /mnt/skuf/boot/x86_64/{vmlinuz-linux,initramfs-linux.img} to ESP partition and execute efibootmgr -c -d /dev/sdX -p Y -u 'initrd=\initramfs-linux.img' -l '\vmlinuz-linux' -L 'SKUF' where /dev/sdX is the target disk and Y is the target ESP partition number.

See also