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, 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’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 https://en.wikibooks.org/wiki/QEMU/Networking
  1. Make sure you have checked out the example image descriptions, see Example Appliance Descriptions.

  2. Build the image with KIWI:

    $ sudo kiwi-ng --profile netboot --type pxe system build \
        --description kiwi-descriptions/suse/x86_64/suse-leap-42.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-netboot-suse-*.gz /srv/tftpboot/boot/initrd
    $ cp initrd-netboot-suse-*.kernel /srv/tftpboot/boot/linux
    
  5. Copy the system image and its MD5 sum to /srv/tftpboot/image:

    $ cp LimeJeOS-Leap-42.1.x86_64-1.42.1 /srv/tftpboot/image
    $ cp LimeJeOS-Leap-42.1.x86_64-1.42.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 PXE Client Setup Configuration.

  7. Create the image client configuration file:

    $ vi /srv/tftpboot/KIWI/config.default
    
    IMAGE=/dev/ram1;LimeJeOS-Leap-42.1.x86_64;1.42.1;192.168.100.2;4096
    UNIONFS_CONFIG=/dev/ram2,/dev/ram1,overlay
    

    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 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