Embedded scripts

You can change the default behaviour of iPXE by using an embedded script. For example, you could embed the script:

  #!ipxe
  
  dhcp
  chain http://bootserver/boot.php

This script would cause iPXE to use DHCP to obtain an IP address and then boot from the fixed URL http://bootserver/boot.php (ignoring any boot filename provided by DHCP). This can be useful if you are unable to reconfigure your DHCP server to provide an appropriate boot filename.

There are several methods that you can use to embed a script within iPXE.

You can embed a script within the iPXE binary when you build iPXE using the EMBED=... build parameter. For example, to embed a script saved as myscript.ipxe into a chainloadable iPXE image:

  make bin/undionly.kpxe EMBED=myscript.ipxe

This will create a custom version of the iPXE binary undionly.kpxe which includes your embedded script.

This method works with all iPXE binary formats (.rom, .iso, .kpxe and so on). To change the embedded script, you would need to rebuild the iPXE binary.

You can embed a script by passing in a command line to iPXE. For example, to embed a script into an iPXE image loaded by GRUB:

  timeout 10
  default 0
  
  title iPXE
  kernel (hd0,0)/ipxe.lkrn dhcp && chain http://bootserver/boot.php

This uses a standard version of the iPXE binary ipxe.lkrn. You can change the embedded script simply by editing the GRUB configuration file, with no need to rebuild the iPXE binary.

This method works only with iPXE binary formats that support a command line, such as .lkrn.

Note that you may need to escape some special characters to allow them to be passed through to iPXE.

You can embed a script by passing in an initrd to iPXE. For example, to embed a script saved as myscript.ipxe into an iPXE image loaded by GRUB:

  timeout 10
  default 0
  
  title iPXE
  kernel (hd0,0)/ipxe.lkrn
  initrd myscript.ipxe

This uses a standard version of the iPXE binary ipxe.lkrn. The myscript.ipxe file is a plain iPXE script file; there is no need to use a tool such as mkinitrd.

You can change the embedded script by editing the myscript.ipxe file, with no need to rebuild the iPXE binary.

This method works only with iPXE binary formats that support an initrd, such as .lkrn.

When you embed a script, you will no longer see the “Press Ctrl-B for the iPXE command line” prompt at startup or if booting fails.¹⁾

If you would like to provide the user an opportunity to access the iPXE command line, then you can provide your own replacement prompt using the prompt command. For example:

  prompt --key 0x02 --timeout 2000 Press Ctrl-B for the iPXE command line... && shell ||