gitea-pages/admin-guide/deployment/ipxe.rst

PXE-booting with iPXE

UEFI

iPXE supports UEFI and so do we. This requires the ipxe.efi boot image.

Process

When a system PXE boots, the DHCP server will boot either pxelinux in legacy mode or grub on UEFI. It is still possible to load ipxe from either of these. With the right option, the boot process is pointed to boot00.psi.ch and one of the following boot images:

• ipxe.efi for systems using UEFI
• ipxe.lkrn for all other systems

The system downloads the image and executes it.

The image contains a small iPXE script, which makes iPXE retrieve its actual configuration from a web service running (usually) on boot00.psi.ch. Specifically, it queries the URL https://boot00.psi.ch/ipxe/v1/config?mac=<MAC>, where <MAC> is the MAC address of the interface used by iPXE.

The web service on boot00.psi.ch will generate the iPXE configuration on the fly, depending on whether the system is supposed to be reinstalled and if so, which distribution it is supposed to use. The menu offers other options as well, e.g. an interactive iPXE shell and a memory test.

Building the iPXE boot image

The steps for building an iPXE image are

1. Clone git@git.psi.ch:linux-infra/ipxe-build.git
2. Change into the new directory
3. Run the refresh-ipxe.sh script. This will check out the iPXE source code mirror from git.psi.ch.
4. Run the build.sh script. This will use the named configurations in the ipxe-build repository to compile two iPXE images: src/bin/ipxe.lkrn (legacy boot) and src/bin-x86_64-efi/ipxe.efi (UEFI).

As described above, we use an iPXE boot image with an embedded script looking roughly like the following:

#!ipxe

dhcp && goto dhcp_succeeded

shell
#prompt for network info

:dhcp_succeeded

chain http://boot00.psi.ch/ipxe/v1/config?mac=${netX/mac}