Booting a Root Filesystem from Network

In KIWI NG, the kiwi-overlay dracut module can be used to boot from a remote exported root filesystem. The exported device is visible as block device on the network client. KIWI NG supports the two export backends NBD (Network Block Device) and AoE (ATA over Ethernet) for this purpose. A system that is booted in this mode will read the contents of the root filesystem from a remote location and targets any write action into RAM by default. The kernel cmdline option rd.root.overlay.write can be used to specify an alternative device to use for writing. The two layers (read and write) are combined using the overlayfs filesystem.

For remote boot of a network client, the PXE boot protocol is used. This functionality requires a network boot server setup on the system. Details how to setup such a server can be found in Setting Up a Network Boot Server.

Before the KIS image can be build, the following configuration step is required:

  • Create dracut configuration to include the kiwi-overlay module

    $ cd kiwi/build-tests/x86/tumbleweed/test-image-pxe
$ mkdir -p root/etc/dracut.conf.d
$ cd root/etc/dracut.conf.d
$ echo 'add_dracutmodules+=" kiwi-overlay "' > overlay.conf

Now the KIS image can be build as shown in Build KIS Image (Kernel, Initrd, System). After the build, the following configuration steps are required to boot from the network:

  1. Copy initrd/kernel from the KIS build to the PXE server

    The PXE boot process loads the configured kernel and initrd from the PXE server. For this reason, the following files must be copied to the PXE server as follows:

    $ cp *.initrd /srv/tftpboot/boot/initrd
$ cp *.kernel /srv/tftpboot/boot/linux

  2. Export Root FileSystem to the Network

    Access to the root filesystem is implemented using either the AoE or the NBD protocol. This requires the export of the root filesystem image as remote block device:

    Export via AoE:

    Install the vblade package on the system which is expected to export the root filesystem

    Note

    Not all versions of AoE are compatible with any kernel. This means the kernel on the system exporting the root filesystem image must provide a compatible aoe kernel module compared to the kernel used inside of the root filesystem image.

    Once done, export the filesystem from the KIS build above as follows:

    $ vbladed 0 1 IFACE {exc_image_base_name}.x86_64-1.15.3

    The above command exports the given filesystem image file as a block storage device to the network of the given IFACE. On any machine except the one exporting the file, it will appear as /dev/etherd/e0.1 once the aoe kernel module was loaded. The two numbers, 0 and 1 in the above example, classifies a major and minor number which is used in the device node name on the reading side, in this case e0.1.

    Note

    Only machines in the same network of the given INTERFACE can see the exported block device.

    Export via NBD:

    Install the nbd package on the system which is expected to export the root filesystem

    Once done, export the filesystem from the KIS build above as follows:

    $ losetup /dev/loop0 {exc_image_base_name}.x86_64-1.15.3

$ vi /etc/nbd-server/config

  [generic]
      user = root
      group = root
  [export]
      exportname = /dev/loop0

$ nbd-server

  3. Setup boot entry in the PXE configuration

    Note

    The following step assumes that the pxelinux.0 loader has been configured on the boot server to boot up network clients

    Edit the file /srv/tftpboot/pxelinux.cfg/default and create a boot entry of the form:

    Using NBD:
    LABEL Overlay-Boot
    kernel boot/linux
    append initrd=boot/initrd root=overlay:nbd=server-ip:export

    The boot parameter root=overlay:nbd=server-ip:export specifies the NBD server IP address and the name of the export as used in /etc/nbd-server/config

    Using AoE:
    LABEL Overlay-Boot
    kernel boot/linux
    append initrd=boot/initrd root=overlay:aoe=AOEINTERFACE

    The boot parameter root=overlay:aoe=AOEINTERFACE specifies the interface name as it was exported by the vbladed command

  4. Boot from the Network

    Within the network which has access to the PXE server and the exported root filesystem image, any network client can now boot the system. A test based on QEMU can be done as follows:

    $ sudo qemu -boot n