# PXE-booting with iPXE

## UEFI

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

Instructions how to copy the necessary grub files to the tftp server:
https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/installation_guide/chap-installation-server-setup#sect-network-boot-setup-uefi
(alternatively one can also copy the files from the /boot/efi/EFI/redhat/ directory of an installed system)

```
[root@ tmp]# cd /tmp
[root@ tmp]# curl -OL http://repos.psi.ch/rhel9/iso/rhel-baseos-9.1-x86_64-dvd/BaseOS/Packages/shim-x64-15.6-1.el9.x86_64.rpm
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  471k  100  471k    0     0  92.0M      0 --:--:-- --:--:-- --:--:-- 92.0M
[root@lx-repos-01  tmp]# curl -LO http://repos.psi.ch/rhel9/iso/rhel-baseos-9.1-x86_64-dvd/BaseOS/Packages/grub2-efi-x64-2.06-46.el9.x86_64.rpm
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1333k  100 1333k    0     0  8550k      0 --:--:-- --:--:-- --:--:-- 8550k
[root@ tmp]# rpm2cpio shim-x64-15.6-1.el9.x86_64.rpm | cpio -dimv
./boot/efi/EFI/BOOT/BOOTX64.EFI
./boot/efi/EFI/BOOT/fbx64.efi
./boot/efi/EFI/redhat/BOOTX64.CSV
./boot/efi/EFI/redhat/mmx64.efi
./boot/efi/EFI/redhat/shim.efi
./boot/efi/EFI/redhat/shimx64-redhat.efi
./boot/efi/EFI/redhat/shimx64.efi
9232 blocks
[root@ tmp]# rpm2cpio grub2-efi-x64-2.06-46.el9.x86_64.rpm | cpio -dimv
./boot/efi/EFI/redhat/grubx64.efi
./boot/grub2/fonts
./boot/grub2/fonts/unicode.pf2
./boot/grub2/grubenv
./boot/loader/entries
./etc/dnf/protected.d/grub2-efi-x64.conf
./etc/grub2-efi.cfg
./etc/grub2.cfg
9612 blocks
[root@ tmp]# ls boot/efi/EFI/redhat/
BOOTX64.CSV  grubx64.efi  mmx64.efi  shim.efi  shimx64.efi  shimx64-redhat.efi
[root@ tmp]# ls -la boot/efi/EFI/redhat/
total 6088
drwxr-xr-x. 2 root root     122 Mar  1 16:16 .
drwxr-xr-x. 4 root root      32 Mar  1 16:16 ..
-rwx------. 1 root root     108 Jun  7  2022 BOOTX64.CSV
-rwx------. 1 root root 2524792 Aug 25  2022 grubx64.efi
-rwx------. 1 root root  856528 Jun  7  2022 mmx64.efi
-rwx------. 1 root root  946736 Jun  7  2022 shim.efi
-rwx------. 1 root root  946736 Jun  7  2022 shimx64.efi
-rwx------. 1 root root  938808 Jun  7  2022 shimx64-redhat.efi
[root@ tmp]#
```


## 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 ``sysdb.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 `sysdb.psi.ch`.
Specifically, it queries the URL
`https://sysdb.psi.ch/ipxe/v1/config?mac=<MAC>`, where `<MAC>` is the MAC
address of the interface used by iPXE.

The web service on ``sysdb.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.


## Sequence Diagram of the UEFI Boot Process
![UEFI boot process](_static/uefi_boot.png)


## Sequence Diagram of the BIOS (Legacy) Boot Process
![Legacy boot process](_static/legacy_boot.png)


## 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://sysdb.psi.ch/ipxe/v1/config?mac=${netX/mac}
```