iPXE


ipxe 

Reference material

Howto guides

Starting iPXE

DHCP

Operating systems

Troubleshooting

External documentation

  • NetworkBoot.org - a place where beginners can learn the fundamentals of network booting
  • Examples of complete solutions built around iPXE

Application notes

Developer documentation

iPXE source code is documented using Doxygen; you can browse the resulting documentation at http://dox.ipxe.org/files.html.

iPXE is verified using Travis CI for automated build and unit testing, and Coverity Scan for static analysis.

Build targets

iPXE is built using a command-line something like this:

  make bin/ipxe.pxe

The first part, bin in this case indicates platform. ipxe indicates driver, and .pxe indicates boot type.

  make [platform]/[driver].[extension]

The bin directory is included in git repo, but all platforms will be created automatically as part of the build process.

There are some other special targets as well.

Platforms

Currently supported platforms are:

  • bin (alias for bin-i386-pcbios)
  • bin-i386-pcbios
  • bin-i386-efi
  • bin-i386-linux
  • bin-x86_64-efi
  • bin-x86_64-linux
  • bin-x86_64-pcbios
  • bin-arm32-efi
  • bin-arm64-efi

-efi platforms can also have an additional -sb at the end. Used when submitting binaries for Secure Boot signing.

Driver

As the subtitle suggests this is the kind of driver to include in the build

  • ipxe builds one binary with (almost) all PCI based NIC drivers that iPXE has (for now not working on arm since some interfaces have not yet been implemented there, build specific drivers instead such as snp)
  • intel or other driver file found in the sources builds for that driver
  • 808610de binary with driver for specific PCI device with given pci-id. See list of hardware expected to work.
  • ecm--ncm double dash (--) adds multiple drivers to one file, in this case we pull in most USB based drivers (you can add double dash multiple times for more than two drivers)

Some commonly used variants and why:

  • ipxe all native drivers, commonly used for usb based boot media or where iPXE is not used in a chainloaded manner.
  • undionly driver used for building chainable iPXE for pcbios platforms (not included in ipxe since UNDI stack can't be reliably kept and still having device available for possible native iPXE driver) use with .kpxe extension
  • snponly similar to undionly but for efi uses snp (Simple Network Protocol) or nii (Network Interface

Identifier Protocol) provided by something else in EFI land, should only find and boot the specific NIC device it was chained from.

  • snp same as snponly but tries to boot all devices and not just the one it was chained via, this is also included in ipxe builds
  • tests the Linux test suite example: make bin-x86_64-linux/tests.linux && ./bin-x86_64-linux/tests.linux post on mailinglist with more examples
  • tap the Linux tap driver, use with .linux boot type

Boot type

Determines what kind of header should be added to the binary and how entrypoints should be handled.

extension Valid platforms Description
.pxe pcbios Headerless X86 assembly code, PXE- or NBP-booted, sometimes renamed to .0 to work on older DHCP/TFTP servers
.efi efi EFI executable
.kpxe pcbios Same as .pxe but will Keep the original UNDI stack/driver present. This is needed for undionly ref
.kkpxe pcbios Same as .kpxe but will not unload (Keep) the PXE base code. only use with buggy BIOSes
.lkrn pcbios Builds with kernel header similar to Linux so it can be started by many bootloaders
.iso pcbios Builds .lkrn and adds ISOLINUX to create CD-ROM image, can be started by many bootloaders
.hd pcbios Direct executable i386 code put on a harddisk image (32KB blocks)
.dsk pcbios Direct executable i386 code put on a floppy disk image (512 Byte blocks)
.pdsk pcbios Padded .dsk to work with loaders that requires exact size such as iLO
.usb pcbios, efi Same as .dsk for pcbios, in efi mode it's an 1440K image with partition and [driver].efi added as /efi/boot/boot[arch].efi, mostly used for making USB stick images
.rom pcbios File intended to be flashed into PCI-based NIC ROM
.mrom pcbios File intended to be flashed into PCI-based NIC ROM. See notes for ''.mrom''
.pcirom pcbios Same as .rom
.isarom pcbios File intended to be flashed into ISA-based NIC ROM, must be used with e.g. VirtualBox
.efidrv efi Driver for NIC which can be used by other EFI firmware
.efirom efi File intended to be flashed into NIC ROM for EFI
.linux linux Linux ELF executable, use for tests and tap drivers

Special targets

  • make Same as make all
  • make all Predefined list of most common targets and prints some helpfully suggestive message
  • make everything tries to build targets for multiple platforms
  • make vmware ROMs for VMware
  • make doc Same as make bin/doc
  • make [platform]/doc Builds doxygen documentation
  • make docview Tries to open doxygen documentation in browser

Command line

iPXE includes an interactive command line that can be used for manual booting and for diagnosing problems. Commands can also be used as part of an iPXE script.

When iPXE starts up, you will see a welcome banner message:

  iPXE -- Open Source Network Boot Firmware -- http://ipxe.org
  Features: HTTP iSCSI DNS TFTP AoE FCoE TFTP COMBOOT ELF PXE PXEXT
  
  Press Ctrl-B for the iPXE command line...

If you press Ctrl-B at this point, you should reach the iPXE command line:

  iPXE>

The iPXE command line

Manual booting

If your DHCP server is not configured to allow automatic booting, then you could use the iPXE command line to boot manually. For example, you could obtain an IP address using the dhcp command, then boot the iPXE demonstration image using the chain command:

  iPXE> dhcp
  DHCP (net0 52:54:00:12:34:56).... ok
  iPXE> chain http://boot.ipxe.org/demo/boot.php

Diagnostics

You can use the iPXE command line to diagnose problems that are preventing you from booting successfully. For example, you could check the IP address configuration provided by your DHCP server using the route command:

  iPXE> dhcp
  DHCP (net0 52:54:00:12:34:56).... ok
  iPXE> route
  net0: 192.168.0.101/255.255.255.0 gw 192.168.0.1

Commands

You can use the help command to show a list of all available commands. Full documentation for each command is provided in the iPXE command reference.

Scripting

Overview

You can create a script to automate a sequence of iPXE commands. Any command that can be typed at the iPXE command line can also be used in a script. You can find a full list of commands in the iPXE command reference.

An iPXE script is a plain text file starting with the magic line #!ipxe and containing a sequence of iPXE commands. For example, here is a simple script that acquires an IP address via DHCP and then boots the iPXE demonstration image:

  #!ipxe
  
  dhcp
  chain http://boot.ipxe.org/demo/boot.php

Here is another simple script that creates a VLAN and then boots from it:

  #!ipxe
  
  vcreate --tag 24 net0
  autoboot net0-24

Here is a slightly more sophisticated script that persistently retries DHCP until it succeeds in obtaining a boot filename:

  #!ipxe
  
  :retry_dhcp
  dhcp && isset ${filename} || goto retry_dhcp
  echo Booting from ${filename}
  chain ${filename}

You can create an iPXE script using any text editor, such as emacs, or vi, or even Windows Notepad. An iPXE script does not need to have any particular file extension (such as .txt or .ipxe); iPXE will recognise it as a script provided that it starts with the magic line #!ipxe.1)

Flow control

You can use the goto command to jump to a predefined script label. You can define a label using

A flowchart

  :<label>

and jump to this label using

  goto label

For example:

  #!ipxe
  
  :loop
  echo Hello world
  goto loop

You can use the && and || operators to conditionally execute commands depending on the status of previous commands. For example:

  dhcp && echo DHCP succeeded
  dhcp || echo DHCP failed

These operators can usefully be combined with the goto command to implement simple conditional flow control. For example, to keep retrying DHCP until it succeeds:

  #!ipxe
  
  :retry_dhcp
  dhcp || goto retry_dhcp

You can use the ; operator to execute commands regardless of the status of previous commands. For example:

  echo IP address: ${net0/ip} ; echo Subnet mask: ${net0/netmask}

You can terminate a script at any point using the exit command.

Error handling

Warning

iPXE will terminate a script immediately if any line of the script fails. For example, if you have the script:

  #!ipxe
  
  dhcp
  route

then the script will terminate immediately if the dhcp command fails, without proceeding to the next line. You can override this behaviour using the || operator:

  #!ipxe
  
  dhcp ||
  route

In this example, the empty command after the || operator is treated as “do nothing, successfully” (similar to /bin/true on a Unix-like operating system). Even if the dhcp command fails, the overall status of this line of the script will therefore always be “successful”.

Comments

You can start a comment using the # symbol. For example:

  # Obtain an address using DHCP
  :retry
  dhcp || goto retry # Keep retrying indefinitely

Advanced topics

An iPXE ROM

Embedded scripts

You can embed a script within iPXE to override its default behaviour. For example, you may wish to build a version of iPXE containing an embedded script that uses DHCP to obtain an IP address but then boots from a predefined SAN target.

Dynamic scripts

An iPXE script does not have to be a static text file. For example, you could direct iPXE to boot from the URL

  http://192.168.0.1/boot.php?mac=${net0/mac}&asset=${asset:uristring}

which would expand to a URL such as

  http://192.168.0.1/boot.php?mac=52:54:00:12:34:56&asset=BKQ42M1

The boot.php program running on the web server could dynamically generate a script based on the information provided in the URL. For example, boot.php could look up the asset tag in a MySQL database to determine the correct iSCSI target to boot from, and then dynamically generate a script such as

  #!ipxe
  
  set initiator-iqn iqn.2010-04.org.ipxe:BKQ42M1
  sanboot iscsi:192.168.0.20::::iqn.2010-04.org.ipxe:winxp
1) For the sake of backwards compatibility, iPXE will also recognise legacy gPXE scripts starting with the magic line #!gpxe. However, gPXE is not capable of running iPXE scripts, since the iPXE script language is substantially more advanced than the gPXE script language.

Command reference

The following commands are supported by iPXE. Commands may be entered at the iPXE command line or used in a script.

Boot commands
autoboot Boot system from network interface
Network interface commands
ifstat Display interfaces
ifopen Open interfaces
ifclose Close interfaces
ifconf or
dhcp
Automatically configure interfaces
route Display routing table
nstat Display neighbour table
ipstat Display IP statistics
vcreate Create VLAN
vdestroy Destroy VLAN
Image management commands
imgstat Display images
chain or
imgexec or
boot
Download and boot an executable image
imgfetch or
module or
initrd
Download an image
kernel or
imgselect or
imgload
Download and select an executable image
imgfree Discard images
imgargs Set image command-line arguments
imgtrust Set image trust requirement
imgverify Verify an image as trusted
SAN commands
sanhook Attach SAN device
sanboot Boot from SAN device
sanunhook Detach SAN device
fcstat Display Fibre Channel ports
fcels Issue Fibre Channel ELS request
Configuration setting commands
config Start interactive configuration tool
show Display configuration setting
set Set configuration setting
clear Delete configuration setting
read Prompt user to enter configuration setting
inc Increment numeric value of configuration setting
login Prompt user to enter user name and password
Flow control commands
isset Test for existence
iseq Test for equality
goto Jump to script label
exit Exit current shell or script
Menu commands
menu Create menu
item Add menu item
choose Choose menu item
Certificate management commands
certstat Display certificates
certstore Manage certificates
certfree Discard certificates
Console management commands
console Configure console
colour Define colour
cpair Define colour pair
Form parameter commands
params Create form parameter list
param Add form parameter
Miscellaneous commands
echo Print text to console
prompt Prompt user to press key
shell Start new interactive shell
help Display list of available commands
sleep Delay for fixed period of time
reboot Reboot system
poweroff Power off system
cpuid Check x86 CPU feature
sync Wait for background operations to complete
nslookup Resolve host name to network address
ping Check network connectivity
ntp Get time and date via NTP
pciscan Scan for PCI devices
Obscure commands
lotest Perform loopback testing
pxebs Perform PXE boot server discovery
time Measure time taken to execute command
gdbstub Start remote debugging
profstat Display profiling statistics
© RemiZOffAlex