IPXE

iPXE is a PXE boot firmware which can be used to PXE boot systems that may not have support. iPXE supersedes the older and no longer actively maintained gPXE boot firmware.

Building

You can build the iPXE image from source pretty easily with the added benefit of being able to customize the image with custom embedded iPXE scripts (see scripting section below).

Example

The following script will build iPXE with an embedded script which automatically boots from a HTTP resource.

# git clone git://git.ipxe.org/ipxe.git
# cd git

# cat <<EOF > arch.ipxe
#!ipxe
dhcp
set 209:string cfg/arch.cfg
set 210:string http://linbuild.cs.ucalgary.ca/archlinux/boot/
chain ${210:string}pxelinux.0
EOF

# make bin/ipxe.lkrn EMBED=arch.ipxe

You may also make a USB image by making bin/ipxe.usb and then dd'ing the image to the USB device.

Troubleshooting

If you get the following error while building:

[VERSION] bin/version.udionly.kpxe.o
[LD] bin/udionly.kpxe.tmp
--defsym:2: undefined symbol `obj_udionly' referenced in expression
make: *** [bin/udionly.kpxe.tmp] Error 1
rm bin/version.udionly.kpxe.o

Install the syslinux-devel package.

Scripting

For more information, see iPXE's documentation.

Commands

See iPXE's command reference

Common commands that will be used are:

Command	Description
dhcp	Obtain IP address via DHCP
boot, imgexec, chain	Downloads and boots an executable image
initrd, module, imgfetch	Downloads an executable image
isset	Checks if a value exists (typically for settings).
echo	Prints text to console
goto	Go to a specific label

When booting a kernel with arguments, put it after the kernel uri or path, and not after the initrd command.

Eg:

#!ipxe

kernel vmlinuz-3.16.0-rc4 bootfile=http://boot.ipxe.org/demo/boot.php fastboot initrd=initrd.img
initrd initrd.img
boot

Flow Control

Create a script label using a colon followed by the label name. Program execution will jump to the label using the goto command.

Use the bash-like || to run a command when something fails or && when something succeeds. Eg:

true && echo Success
false || echo Failure

Script Termination

Script execution will stop whenever a command fails.

To make the script continue even if a command can error out (such as dhcp, use the || operator at the end of the command which will always make the command succeed. (ie. dhcp || is analogous to dhcp || true).

Settings

iPXE autodetects a bunch of settings based on the network and hardware it is running on. These include the hardware type (models, IDs) and also network settings (IP, MAC addresses, DHCP settings, etc).

One use case I had with ${product} was to make an auto BIOS update boot option that requests for a boot image from a web server by chaining a URL with the variable.

Example:

:menu
set conn_type https
chain --autofree https://${base_url}/update.ipxe?product=${product}

It's entirely possible to make use of these exposed config settings and make iPXE a quick ROM that updates an inventory server.

See more at:

• http://ipxe.org/cfg

Example Scripts

#!ipxe

:retry_dhcp
dhcp && isset ${filename} | goto retry_dhcp

# Boot image provided by DHCP
echo Booting from ${filename}
chain {$filename}

Booting into SCCM

Suppose you have a customized SCCM .iso that you want to boot instead of having to manually boot each computer.

At a glance, to get iPXE booting the SCCM image:

1. Set up boot files by extracting files from the iso and modify boot.wim and place them on a web server
2. Set up iPXE to boot WinPE from the modified boot.wim file

Setup SCCM Files

Extract the following files from the iso.

• bootmgr
• bcd
• boot.sdi
• boot.wim

Obtain wimboot from http://git.ipxe.org/releases/wimboot/wimboot-latest.zip

Customization made to the SCCM image will be under the SMS directory in the iso. Since we are only loading the boot.wim image rather than the entire iso, these customization must be copied into the boot.wim file using ImageX (from the Windows Automated Installation Kit or WAIK).

While there is a linux utility of the same name from wimlib, it didn't work for me as it just creates a corrupt .wim that doesn't boot properly.

Create winpeshl.ini:

[LaunchApps]
"wscript.exe","%SYSTEMDRIVE%\sms\bin\x64\bootstrap.vbs"

Create bootstrap.vbs:

Set os = WScript.CreateObject ( "WScript.Shell" )
os.Run "%COMSPEC%", 7, false
os.Run "%COMSPEC% /c title Initialising... && wpeinit " & "&& net start dnscache", 1, true
os.RegWrite "HKLM\SYSTEM\CurrentControlSet\Control\PEBootType", "Ramdisk:OpticalDrive", "REG_SZ"
os.Run WScript.ScriptFullName & "\..\TsmBootStrap.exe /env:WinPE " & "/configpath:%SYSTEMDRIVE%\sms\data", 1, true

Copy the SMS directory, the winpeshl.ini, and the bootstrap.vbs files into the wim image.

# mkdir mnt
# imagex /mountrw boot.wim 1 mnt
ImageX Tool for Windows
Copyright (C) Microsoft Corp. All rights reserved.
Version: 6.1.7600.16385

Mounting: [C:\Users\admin\Desktop\boot.wim, 1] -> [C:\Users\admin\Desktop\mnt]...

[ 100% ] Mounting progress

Successfully mounted image.

Total elapsed time: 34 sec

# xcopy /e /f /y iso\sms mnt\sms
# copy winpeshl.ini mnt\windows\system32\
# copy bootstrap.vbs mnt\sms\bin\x64\
# imagex /unmount /commit mnt
ImageX Tool for Windows
Copyright (C) Microsoft Corp. All rights reserved.
Version: 6.1.7600.16385

Committing: [C:\Users\admin\Desktop\mnt]...

[ 100% ] Committing Image progress

Successfully committed image.

Unmounting: [C:\Users\admin\Desktop\mnt]...


[ 100% ] Mount cleanup progress

Successfully unmounted image.

Total elapsed time: 22 sec

Copy these files to a web server:

1. wimboot
2. bootmgr
3. bcd
4. boot.sdi
5. boot.wim

Booting the SCCM Image

Create a custom iPXE ROM with the following script. Modify the URL so that it goes to your web server containing the files from above.

#!ipxe

:retry_dhcp
dhcp || goto retry_dhcp

:boot
set url http://pages.cpsc.ucalgary.ca/~leo/boot/win/

kernel ${url}/wimboot
initrd ${url}/bootmgr bootmgr
initrd ${url}/bcd bcd
initrd ${url}/boot.sdi boot.sdi
initrd ${url}/boot.wim boot.wim
boot || goto boot

Troubleshooting

Issue: The image doesn't run the vbscript on start up. Instead, a command prompt opens with the following message:

A winpeshl.ini file is present, but no commands were successfully launched. This could be caused by incorrect formatting or an invalid executable name. Please consult the documentation for more information.

Solution: I messed up the ini file. Copy it as it is shown above. I did not copy the interpreter which was the first argument.

Issue: When using imagexfrom wimlib, I got weird boot errors including:

unrecognized block type 0

bad MZ magic d5e9

Solution: Use Microsoft's WAIK imagex utility instead.

See Also

• http://ipxe.org/howto/sccm
• http://www.thesccm.com/ipxe-sccm/

Public Boot Servers

There are public boot servers that make use of iPXE's ability to boot from HTTP servers.

netboot.xyz is one such service.

• https://netboot.xyz/
• https://github.com/antonym/netboot.xyz