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.


Sequence Diagram of the UEFI Boot Process
--------------------------------------------------
.. image:: _static/uefi_boot.png


Sequence Diagram of the BIOS (Legacy) Boot Process
--------------------------------------------------
.. image:: _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://boot00.psi.ch/ipxe/v1/config?mac=${netX/mac}