Build a PXE Root File System Image

PXE is a network boot protocol that is shipped with most BIOS implementations. The protocol sends a DHCP request to get an IP address. When an IP address is assigned, it uses the TFTP protocol to download a Kernel and boot instructions. Contrary to other images built with KIWI NG, a PXE image consists of separate boot, kernel and root filesystem images, since those images need to be made available in different locations on the PXE boot server.

A root filesystem image which can be deployed via KIWI NG’s PXE netboot infrastructure represents the system rootfs in a linux filesystem. A user could loop mount the image and access the contents of the root filesystem. The image does not contain any information about the system disk its partitions or the bootloader setup. All of these information is provided by a client configuration file on the PXE server which controlls how the root filesystem image should be deployed.

Many different deployment strategies are possible, e.g root over NBD (network block device), AoE (ATA over Ethernet), or NFS for diskless and diskfull clients. This particular example shows how to build an overlayfs-based union system based on openSUSE Leap for a diskless client which receives the squashfs compressed root file system image in a ramdisk overlayed via overlayfs and writes new data into another ramdisk on the same system. As diskless client, a QEMU virtual machine is used.

Things to know before

  • To use the image, all image parts need to be copied to the PXE boot server. If you have not set up such a server, refer to Setting Up a Network Boot Server for instructions.

  • The following example assumes you will create the PXE image on the PXE boot server itself (if not, use scp to copy the files on the remote host).

  • To let QEMU connect to the network, we recommend to setup a network bridge on the host system and let QEMU connect to it via a custom /etc/qemu-ifup. For details, see

  • The PXE root filesystem image approach is considered to be a legacy setup. The required netboot initrd code will be maintained outside of the KIWI NG appliance builder code base. If possible, we recommend to switch to the OEM disk image deployment via PXE.

  1. Make sure you have checked out the example image descriptions, see Example Appliance Descriptions.

  2. Build the image with KIWI NG:

    $ sudo kiwi-ng --type pxe system build \
        --description kiwi-descriptions/suse/x86_64/suse-leap-15.1-JeOS \
        --target-dir /tmp/mypxe-result
  3. Change into the build directory:

    $ cd /tmp/mypxe-result
  4. Copy the initrd and the kernel to /srv/tftpboot/boot:

    $ cp *.initrd.xz /srv/tftpboot/boot/initrd
    $ cp *.kernel /srv/tftpboot/boot/linux
  5. Copy the system image and its MD5 sum to /srv/tftpboot/image:

    $ cp LimeJeOS-Leap-15.1.x86_64-1.15.1/srv/tftpboot/image
    $ cp LimeJeOS-Leap-15.1.x86_64-1.15.1.md5 /srv/tftpboot/image
  6. Adjust the PXE configuration file. The configuration file controls which kernel and initrd is loaded and which kernel parameters are set. A template has been installed at /srv/tftpboot/pxelinux.cfg/default from the kiwi-pxeboot package. The minimal configuration required to boot the example image looks like to following:

       DEFAULT KIWI-Boot
       LABEL KIWI-Boot
           kernel boot/linux
           append initrd=boot/initrd
           IPAPPEND 2
    Additional configuration files can be found at :ref:`pxe_client_config`.
  7. Create the image client configuration file:

    $ vi /srv/tftpboot/KIWI/config.default

    All PXE boot based deployment methods are controlled by a client configuration file. The above configuration tells the client where to find the image and how to activate it. In this case the image will be deployed into a ramdisk (ram1) and overlay mounted such that all write operations will land in another ramdisk (ram2). KIWI NG supports a variety of different deployment strategies based on the rootfs image created beforehand. For details, refer to PXE Client Setup Configuration

  8. Connect the client to the network and boot. This can also be done in a virtualized environment using QEMU as follows:

    $ qemu -boot n -m 4096