Network and Boot Configuration

To communicate with attached test machines and boot images, you’ll need some DHCP and TFTP configuration. The example shows how to set up such a configuration using the popular tool dnsmasq.

Some parts of the network configuration are specific to the deployment method. These are mentioned at the end of this page and described in further detail in the respective pages for the deployment method.

When getting started with SoTest, you can use QEMU virtual machines instead of real hardware. That way, you can skip the network setup and get everything else sorted out first.

Boot Process

All test machines connected to SoTest need to be configured to boot via network in their BIOS settings. When booting, each machine obtains an IP address via DHCP and then receives an address for a boot configuration file (ipxe.kpxe or snponly.efi) that it then downloads from a TFTP server.

We therefore need to provide both a DHCP server and a TFTP server.

The DHCP server assigns each machine a static IP address. When using dnsmasq, this is achieved by the dhcp-host command. The test machine sends information on its architecture in the DHCP request and we can use that to determine which boot configuration file to serve (BIOS machines use ipxe.kpxe while EFI machines use snponly.efi.) We use the dhcp-match option in dnsmasq to determine the machine architecture and then dhcp-boot to define which boot file to use. Currently we also provide a slightly different version of the ipxe.kpxe, which includes some patches to enable the “Client V” machine. Therefore, we tag its dhcp-host entry with a name tag which we can use in the dhcp-boot option, so that this machine uses ipxe-client-v.kpxe.

For more information about the PXE boot process, check out Understanding PXE Booting, Configuring Dnsmasq to Support PXE Clients and RFC 4578, section Client System Architecture Type Option Definition.

Generate Boot Configuration Files

If you want to manually generate the boot configuration files ipxe.kpxe, ipxe-client-v.kpxe and snponly.efi, you may use the following commands:

cd sotest
# Build ipxe.kpxe --> file: result/ipxe.kpxe
nix-build nix/release.nix -A tools.ipxe
# Build snponly.efi --> file: result/snponly.efi
nix-build nix/release.nix -A tools.ipxe-snponly
# Build ipxe-client-v.kpxe --> file: result/ipxe-client-v.kpxe
nix-build nix/release.nix -A tools.ipxe-client-v

When using the SoTest NixOS module, this step is not needed.

Dnsmasq configuration

When configuring the DHCP and TFTP server to serve the correct boot configuration files, we end up with a dnsmasq configuration file that looks something like this:

# File: dnsmasq_example_configuration.conf

# The interface that is attached to the private SoTest network
interface=eth1

# Restrict dnsmasq to only the above interface
bind-interfaces

# Improve performance when dnsmasq is the only DHCP server on this network
dhcp-authoritative

# Disables the default route, as the iSCSI windows installation does not work with
# a gateway different than 0.0.0.0.
# See: RFC 2132, Router option https://datatracker.ietf.org/doc/html/rfc2132#section-3.5
dhcp-option=3

# List of static IP addresses for all configured machines

# hpbook
dhcp-host=fc:15:b4:eb:c6:ca,192.168.1.157

#
# Additional machines...
#

# Machines that are not assigned a static address receive one from this range
# This is useful when new machines are added
dhcp-range=192.168.1.101,192.168.1.200,12h

# Tag all machines that send BIOS x86 in the DHCP options as "x86PC"
# Boot these machines with the ipxe.kpxe file
dhcp-match=x86PC, option:client-arch, 0
dhcp-boot=tag:x86PC,ipxe.kpxe

# Tag all machines that send EFI x86-64 in the DHCP options as "BC_EFI"
# Boot these machines with the snponly.efi file
dhcp-match=BC_EFI, option:client-arch, 7
dhcp-boot=tag:BC_EFI,snponly.efi

# TFTP configuration
enable-tftp

# TFTP root folder also configured in the sotest-controller
tftp-root=${tftpFolder}

# Logging
log-queries
log-facility=/var/log/dnsmasq.log
log-dhcp

To make the configuration work, some additional settings are also needed. These look different depending on the used SoTest deployment method and operating system.

  • Assign an IP address to the network interface the machines can connect to
  • Allow ports 67 and 69 in your firewall configuration as they are used by DHCP and TFTP
  • Configure additional network privileges, for example when running dnsmasq in a docker or podman container
  • Generate ipxe.kpxe and snponly.efi and place them in the tftpRoot folder. This is required only for manual deployments that don’t use the SoTest NixOS module.

Check out Deployment without NixOS and Deployment with NixOS modules for additional information that pertains to your deployment method.