Prerequisite: DHCP service

Prerequisite: DHCP Service

Automatic DHCP Proxy

Sidero v0.6 comes with DHCP proxy which augments the DHCP service provided by the network environment with PXE boot instructions automatically. There is no configuration required besides configuring the network environment DHCP server to assign IPs to the machines.

If the Sidero Metal DHCP proxy server is not enabled, follow the next section to set up the DHCP server.

Manual DHCP Server Configuration

Note: This section is only required if you are not using the automatic DHCP proxy.

In order to network boot Talos, we need to set up our DHCP server to supply the network boot parameters to our servers. For maximum flexibility, Sidero makes use of iPXE to be able to reference artifacts via HTTP. Some modern servers support direct UEFI HTTP boot, but most servers still rely on the old TFTP-based PXE boot first. Therefore, we need to tell our DHCP server to find the iPXE binary on a TFTP server.

Conveniently, Sidero comes with a TFTP server which will serve the appropriate files. We need only set up our DHCP server to point to it.

The tricky bit is that at different phases, we need to serve different assets, but they all use the same DHCP metadata key.

In fact, we have as many as six different client types:

  • Legacy BIOS-based PXE boot (undionly.kpxe via TFTP)
  • UEFI-based PXE boot (snp.efi/ipxe.efi via TFTP)
  • UEFI HTTP boot (snp.efi/ipxe.efi via HTTP URL)
  • iPXE (boot.ipxe via HTTP URL)
  • UEFI-based PXE arm64 boot (ipxe-arm64.efi via TFTP)
  • UEFI HTTP boot on arm64 (ipxe-arm64.efi via HTTP URL)

UEFI iPXE modules

There are two iPXE modules available with Sidero Metal:

  • snp.efi uses iPXE network drivers to configure networking.
  • ipxe.efi uses the UEFI network drivers to configure networking.

It is recommended to use snp.efi for UEFI-based PXE boot, since it is more reliable. However, some UEFI implementations do not support snp.efi and require ipxe.efi instead.

Common client types

If you are lucky and all of the machines in a given DHCP zone can use the same network boot client mechanism, your DHCP server only needs to provide two options:

  • Server-Name (option 66) with the IP of the Sidero TFTP service
  • Bootfile-Name (option 67) with the appropriate value for the boot client type:
    • Legacy BIOS PXE boot: undionly.kpxe
    • UEFI-based PXE boot: snp.efi (fallback to ipxe.efi if snp.efi doesn’t work)
    • UEFI HTTP boot: http://sidero-server-url/tftp/ipxe.efi (fallback to ipxe.efi if snp.efi doesn’t work)
    • iPXE boot: http://sidero-server-url/boot.ipxe
    • arm64 UEFI PXE boot: snp-arm64.efi (fallback to ipxe-arm64.efi if snp-arm64.efi doesn’t work)
    • arm64 UEFI HTTP boot: http://sidero-server-url/tftp/ipxe-arm64.efi (fallback to ipxe-arm64.efi if snp-arm64.efi doesn’t work)

In the ISC DHCP server, these options look like:

next-server 172.16.199.50;
filename "snp.efi";

Multiple client types

If you have a mix of machines, you may need a way to provide different images for different machine types.

Most DHCP servers provide ways to supply such conditional responses: the examples below are for ISC DHCP.

In our example below, 172.16.199.50 is the IP address of our Sidero service.

ipxe-metal.conf:

allow bootp;
allow booting;

# IP address for PXE-based TFTP methods
next-server 172.16.199.50;

# Configuration for iPXE clients
class "ipxeclient" {
  match if exists user-class and (option user-class = "iPXE");
  filename "http://172.16.199.50/boot.ipxe";
}

# Configuration for legacy BIOS-based PXE boot
class "biosclients" {
  match if not exists user-class and substring (option vendor-class-identifier, 15, 5) = "00000";
  filename "undionly.kpxe";
}

# Configuration for UEFI-based PXE boot
class "pxeclients" {
  match if not exists user-class and substring (option vendor-class-identifier, 0, 9) = "PXEClient";
  filename "snp.efi";
}

# Configuration for UEFI-based HTTP boot
class "httpclients" {
  match if not exists user-class and substring (option vendor-class-identifier, 0, 10) = "HTTPClient";
  option vendor-class-identifier "HTTPClient";
  filename "http://172.16.199.50/tftp/snp.efi";
}

Once this file is created, we can include it from our main dhcpd.conf inside a subnet section.

shared-network sidero {
  subnet 172.16.199.0 netmask 255.255.255.0 {
    option domain-name-servers 8.8.8.8, 1.1.1.1;
    option routers 172.16.199.1;
    include "/config/ipxe-metal.conf";
  }
}

Since we use a number of Ubiquiti EdgeRouter devices in our home test networks, it is worth mentioning the syntax gymnastics we must go through there. Essentially, the quotes around the path need to be entered as HTML entities: ".

Ubiquiti EdgeRouter configuration statement:

set service dhcp-server shared-network-name sidero \
  subnet 172.16.199.1 \
  subnet-parameters "include "/config/ipxe-metal.conf";"

Also note the fact that there are two semicolons at the end of the line. The first is part of the HTML-encoded " (") and the second is the actual terminating semicolon.

Troubleshooting

Getting the netboot environment correct is tricky and debugging it is difficult: the problem is nearly always one of a missing or incorrect configuration, since the process involves several different components.

See the Sidero Troubleshooting guide for more assistance.