Satellite 6 and iPXE

This article was originally published on the Red Hat Customer Portal. The information may no longer be current.

TFTP is slow and unreliable protocol on high-latency networks, but if your hardware is supported by iPXE (http://ipxe.org/appnote/hardware_drivers) or if UNDI driver of the NIC is compatible with iPXE, it is possible to configure PXELinux to chainboot iPXE and continue booting via HTTP protocol which is fast and reliable.

There are three scenarios described in this article. In the first two, PXELinux is loaded via TFTP and it chainloads iPXE directly or via UNDI which then carries over the kernel and init RAM disk (the largest artifact for transfer) via more robust protocol HTTP:

• hardware is turned on
• PXE driver gets network credentials from DHCP
• PXE driver gets PXELinux firmware from TFTP (pxelinux.0)
• PXELinux searches for configuration file on TFTP
• PXELinux chainloads iPXE (undionly-ipxe.0 or ipxe.lkrn)
• iPXE gets network credentials from DHCP again
• iPXE gets HTTP address from DHCP
• iPXE chainloads the iPXE template from Satellite
• iPXE loads kernel and init RAM disk of the installer

Requirements:

• a host entry is created in Satellite
• MAC address of the provisioning interface matches
• provisioning interface of the host has a valid DHCP reservation
• the host has special PXELinux template (below) associated
• the host has iPXE template associated
• hardware is capable of PXE booting
• hardware NIC is compatible with iPXE

The iPXE project offers two options: using PXE interface (UNDI) or using built-in linux network card driver. Both options have pros and cons and each gives different results with different hardware cards. Some NIC adapters can be slow with UNDI, some are actually faster. Not all network cards will work with either or both ways.

Both scenarios are meant for bare-metal hosts. There are known issues with chainloading iPXE from libvirt, because it already uses iPXE as PXE ROMs by default. To avoid PXE in virtual environments, use scenaio C below.

The third approach (B) is avoiding PXE (TFTP) completely by using iPXE as the primary firmware for virtual machines. It is only possible in virtual environments.

A1. Chainbooting iPXE directly

In this setup, iPXE uses build-in driver for network communication. Therefore this will only work on supported cards (see above).

Capsule setup

The following steps need to be done on all TFTP Capsules. Make sure ipxe-bootimgs RPM package is installed. Copy the iPXE firmware to the TFTP root directory:

cp /usr/share/ipxe/ipxe.lkrn /var/lib/tftpboot/

Do not use symbolic links as TFTP runs in chroot. When using SELinux, remember to correct file contexts:

restorecon -RvF /var/lib/tftpboot/

Satellite setup

In your Satellite instance, go to "Provisioning templates" and create new template of PXELinux kind with the following contents:

DEFAULT linux
LABEL linux
KERNEL ipxe.lkrn
APPEND dhcp && chain <%= foreman_url('iPXE') %>
IPAPPEND 2

Associate iPXE template which ships with Satellite which is named 'Kickstart default iPXE' containing something like (no changes required):

#!ipxe
kernel <%= "#{@host.url_for_boot(:kernel)}" %> ks=<%= foreman_url("provision")%>
initrd <%= "#{@host.url_for_boot(:initrd)}" %>
boot

If there was a host associated with PXELinux templates, you may need to cancel and re-enter Build state for the TFTP configuration to be redeployed via Cancel and Build button. Satellite 6.2+ do this automatically on template save.

A2. Chainbooting iPXE via UNDI

In this setup, iPXE uses UNDI for network communication. The hardware must support that.

Capsule setup

The following steps need to be done on all TFTP Capsules. Make sure ipxe-bootimgs RPM package is installed. Copy the iPXE firmware to the TFTP root directory and rename it:

cp /usr/share/ipxe/undionly.kpxe /var/lib/tftpboot/undionly-ipxe.0

Do not use symbolic links as TFTP runs in chroot. When using SELinux, remember to correct file contexts:

restorecon -RvF /var/lib/tftpboot/

Capsule setup (gPXELinux alternative)

This is alternative approach if none of the above configurations work (gPXE is an older generation of iPXE project). Make sure syslinux RPM package is installed and copy the gPXE firmware to the TFTP root directory:

cp /usr/share/syslinux/gpxelinuxk.0 /var/lib/tftpboot/

Do not use symbolic links as TFTP runs in chroot. When using SELinux, remember to correct file contexts:

restorecon -RvF /var/lib/tftpboot/

Satellite setup

In your Satellite instance, go to "Provisioning templates" and create new template of PXELinux kind with the following contents:

DEFAULT undionly-ipxe
LABEL undionly-ipxe
MENU LABEL iPXE UNDI
KERNEL undionly-ipxe.0
IPAPPEND 2

When using alternative gPXELinux, then use the following template contents:

DEFAULT gpxelinux
LABEL gpxelinux
MENU LABEL gPXELinux
KERNEL gpxelinuxk.0
IPAPPEND 2

Associate iPXE template which ships with Satellite which is named 'Kickstart default iPXE' containing something like (no changes required):

#!ipxe
kernel <%= "#{@host.url_for_boot(:kernel)}" %> ks=<%= foreman_url("provision")%>
initrd <%= "#{@host.url_for_boot(:initrd)}" %>
boot

When using gPXELinux, replace ipxe "shebang" with gpxe.

If there was a host associated with PXELinux templates, you may need to exit and re-enter Build state for the TFTP configuration to be redeployed. Satellite 6.2+ do this automatically on template save.

DHCP setup

The above configuration will lead to an endless loop of chainbooting iPXE/gPXE firmware. To break this loop, configure DHCP server to hand over correct URL to continue booting. In the /etc/dhcp/dhcpd.conf file change the "filename" global or subnet configuration as follows:

if exists user-class and option user-class = "iPXE" {
  filename "https://satellite:443/unattended/iPXE";
} else {
  filename "pxelinux.0";
}

This file is under foreman-installer (Puppet) control, make sure to do the change every time installer is executed (e.g. during upgrade).

On isolated networks, use Capsule URL (port 9090) instead of Satellite when templates feature is enabled. When using gPXE, use "gPXE" user-class instead or provide additional "elseif" block for both cases.

B. Chainbooting virtual machines

Since most virtualization hypervisors use iPXE as the primary firmware for PXE booting, the above configuration will directly work without TFTP and PXELinux involved. This is known to work with libvirt, oVirt and RHEV. If the hypervisor is capable of replacing PXE firmware, it will work too (e.g. VMWare is documented at http://ipxe.org/howto/vmware). The workflow is simplified in this case:

• VM is turned on
• iPXE gets network credentials from DHCP again
• iPXE gets HTTP address from DHCP
• iPXE chainloads the iPXE template from Satellite
• iPXE loads kernel and init RAM disk of the installer

To configure this, make sure your hypervisor is using iPXE, configure iPXE template for your host(s) and DHCP server to return valid URL:

Associate iPXE template which ships with Satellite which is named 'Kickstart default iPXE'. The contents is the same as in the workflows above. If there was a host associated with PXELinux templates, you may need to exit and re-enter Build state for the TFTP configuration to be redeployed (Satellite 6.2+ does this automatically).

Similarly to above configuration, this will lead to an endless loop of chainbooting iPXE firmware. To break this loop, configure DHCP server to hand over correct URL to iPXE to continue booting. In the /etc/dhcp/dhcpd.conf file change the "filename" global or subnet configuration as follows:

if exists user-class and option user-class = "iPXE" {
  filename "https://satellite:443/unattended/iPXE";
} else {
  filename "pxelinux.0";
}

On isolated networks, use Capsule URL instead of Satellite when templates feature is enabled. When using gPXE, use "gPXE" user-class instead.