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
andsnponly.efi
and place them in thetftpRoot
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.