Tiny PXE Server

PXELINUX

PXELINUX version 4.06 (2012-10-23) is included in the Tiny PXE Download. The most recent PXELINUX release at the time of writing is 6.03, however an older version has been included in the download as newer versions have issues when chainloading other Network Bootstrap Programs.

Updating PXELINUX
Configuration File Path
PXELINUX Menu System
Additional Menu Settings
Chainloading iPXE Scripts

Updating PXELINUX

PXELINUX can be downloaded from https://www.kernel.org/.../syslinux/. If replacing the PXELINUX files included in the download then please note that as of PXELINUX version 5.00, file dependencies were introduced for the Network Bootstrap Program (pxelinux.0) and c32 modules. Previous versions (including PXELINUX version 4.06 in the download) do not have any file dependencies - the pxelinux.0 loader and c32 modules are all standalone files. The table below lists file dependencies for these files if version 5.00 (or newer) are used (information is from here) -

File	Dependencies	Notes
chain.c32	libutil.c32 libcom32.c32	"...can chainload MBRs, partition boot sectors, Windows bootloaders (ntldr, setupldr.bin and bootmgr), MS-DOS and PC-DOS io.sys, Freedos kernel.sys, isolinux.bin (only from ISOLINUX), grldr of grub4dos or a bootsector saved to a file. It can also swap BIOS drive numbers or hide partitions..."
hdt.c32	libutil.c32 libgpl.c32 libcom32.c32 libmenu.c32	"...HDT (for "Hardware Detection Tool") is a Syslinux com32 module designed to display low-level information for any x86 compatible system..."
mboot.c32	libcom32.c32	"...mboot.c32 is a Syslinux module that loads images using the Multiboot specification. A really good use case for this is booting Xen, or any other hypervisor-based virtualization pieces that also require an initrd/initramfs. If your Xen boot doesn't require an initrd, then it is possible to utilize the existing kernel/append method. Another use case for mboot.c32 is to boot FreeBSD ELF kernels with rootfs....."
menu.c32	libutil.c32	"...menu.c32 is a comboot module for Syslinux that renders a menu on the screen...."
pxelinux.0	ldlinux.c32	The PXELINUX Network Bootstrap Program
reboot.c32	libcom32.c32	"...reboot.c32 is a COM32 module for Syslinux that is able to reboot the PC. It supports cold and warm rebooting....."
sanboot.c32	libcom32.c32	"...sanboot.c32 is a comboot module for gpxelinux.0 that enables gPXE's SAN booting options (iSCSI and AoE currently). This is only available in >=syslinux-3.71 for gpxelinux.0..."
sdi.c32	libcom32.c32	Can be used to boot Microsoft System Deployment Images (.SDI type files) - SDI files are often used in Windows Embedded and can be used to boot WinPE 1.*
vesamenu.c32	libutil.c32 libcom32.c32	Graphical version of menu.c32 (see above) - supports the use of .jpg wallpaper in boot menus. Note that vesamenu.c32 is not included in the Tiny PXE Server download.

Please note that gpxelinux.0, a hybrid bootloader containing gPXE/iPXE, has been deprecated and replaced with lpxelinux.0 since PXELINUX version 5.10.

Since version 6.00 .c32 files are platform specific and the PXELINUX download now includes separate directories for BIOS (\bios), 32-bit UEFI (\efi32) and 64-bit UEFI (\efi64) binary files. The menu.c32 module for example has three separate binary files in the following locations -

\bios\com32\menu\menu.c32
\efi32\com32\menu\menu.c32
\efi64\com32\menu\menu.c32

Dependencies can be found in the following paths (where * is either bios, efi32 or efi64) -

\*\com32\libutil\libutil.c32
\*\com32\gpllib\libgpl.c32
\*\com32\lib\libcom32.c32
\*\com32\cmenu\libmenu\libmenu.c32

Configuration File Path

The default path for the PXELINUX configuration file is the \pxelinux.cfg\ directory - the path is relative to the PXELINUX Network Bootstrap Program - pxelinux.0. It's possible to use separate configuration files for each client PC by using a filename based upon information unique to each client. Configuration file names are parsed in the following order -

UUID - the UUID should be specified using the xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format where xx are lowercase hexadecimal digits. E.g. 656635c7-d786-4912-9797-d66d2da61652

MAC Address - lowercase hexadecimal with - separators. The MAC address needs to be preceded with its ARP type. E.g. for MAC address 08 00 27 7A 13 19 on a card with ARP type 1, use filename 01-08-00-27-7a-13-19.

Clients IP (v4) address in a hexadecimal format. E.g. IP address 192.168.2.3 resolves to C0A80203 - therefore use filename C0A80203.

Clients IP (v4) address in a hexadecimal format minus last digit from previous attempt. E.g. if C0A80203 was just attempted, try C0A8020, then try C0A802, etc.

default

On a test system with the following setup...

UUID = 656635c7-d786-4912-9797-d66d2da61652
MAC = 01-08-00-27-7a-13-19
IP Address = C0A80202

...the attempted load order will be as follows -

\pxelinux.cfg\d786-4912-9797-d66d2da61652
\pxelinux.cfg\01-08-00-27-7a-13-19
\pxelinux.cfg\C0A80202
\pxelinux.cfg\C0A8020
\pxelinux.cfg\C0A802
\pxelinux.cfg\C0A80
\pxelinux.cfg\C0A8
\pxelinux.cfg\C0A
\pxelinux.cfg\C0
\pxelinux.cfg\C
\pxelinux.cfg\default

PXELINUX Menu System

PXELINUX can be configured to display a menu when the Network Bootstrap Program pxelinux.0 is loaded. The SysLinux website lists a comprehensive range of options that can be used for a basic menu system. The Tiny PXE Server package includes a COM32 module for displaying a text based menu - menu.c32. It's possible to replace this with vesamenu.c32 if you want to add support for graphics - i.e. a splash screen.

A quick note on the graphics mode supported in vesamenu.32 - the default is a resolution of 640x480 pixels. It's possible to change this using the MENU RESOLUTION command (e.g. "MENU RESOLUTION 1024 768") - if the selected resolution is not supported then a text mode menu will be displayed. Image files in .PNG, .JPG and LSS16 formats are supported.

Although the focus here is on using menu.c32, the syntax for vesamenu.c32 is almost identical. Notepad.exe can be used to create a menu configuration file - all entries are text based. A basic menu using menu.c32 (note that all paths are relative to the directory containing pxelinux.0 - in the example below menu.c32 is located in the same directory as pxelinux.0) -

DEFAULT menu.c32
MENU TITLE PXELinux Boot Options

A vesamenu alternative (note the addition of the MENU BACKGROUND line with a path to a .jpg file) -

     DEFAULT vesamenu.c32
     MENU BACKGROUND /pxelinux.cfg/splash.jpg
     MENU TITLE PXELinux Boot Options

The PXELINUX menu entries in this guide have been kempt as simple as possible. The majority of options here use the format -

     LABEL ipxe
     MENU LABEL iPXE
     KERNEL ipxe.lkrn

or

     LABEL ipxe_menu
     MENU LABEL iPXE (Load menu.ipxe)
     KERNEL ipxe.lkrn
     APPEND initrd=menu.ipxe

It's also possible to load submenus -

     LABEL submenu1
     MENU LABEL Floppy Disk Image Submenu
     KERNEL menu.c32
     APPEND pxelinux.cfg/submenu1.txt

Putting all this together -
DEFAULT menu.c32 MENU TITLE PXELinux Boot Options LABEL ipxe MENU LABEL iPXE KERNEL ipxe.lkrn LABEL ipxe_menu MENU LABEL iPXE (Load menu.ipxe) KERNEL ipxe.lkrn APPEND initrd=menu.ipxe label submenu1 MENU LABEL Floppy Disk Image Submenu KERNEL menu.c32 APPEND pxelinux.cfg/submenu1.txt

Screenshot of the above menu as displayed on the client system -

Now let's take a closer look at the menu entry syntax -

MENU TITLE - display a title ("PXELinux Boot Options" in the example above) for the menu/submenu.

LABEL - this is a place marker - each menu entry should use a unique name in it's LABEL line.

MENU LABEL - text that will be displayed on the screen for this menu entry. MENU LABEL statements do not have to be unique.

KERNEL - the file to be loaded if the menu entry is selected. Supported files include linux kernel files, *.c32 modules, Network Boot Programs, etc.

APPEND - parameter(s) to pass to the file loaded by the KERNEL statement in the same menu entry.

Additional Menu Settings

The previous section lists some basic menu options - for more comprehensive range of settings refer to http://www.syslinux.org/.../menu.c32 and http://www.syslinux.org/.../SYSLINUX.

Hotkeys -

"...The ^ symbol in a MENU LABEL statement defines a hotkey. The hotkey will be highlighted in the menu and will move the menu cursor immediately to that entry. Reusing hotkeys is disallowed, subsequent entries will not be highlighted, and will not work..."

In the following example the hotkey i is assigned to this entry -

     LABEL ipxe
     MENU LABEL ^iPXE
     KERNEL ipxe.lkrn

TIMEOUT - used to boot the first (or default) menu entry after the time period specified (in 1/10's of a second - e.g. TIMOUT 100 is equal to 10 seconds) -

"...If more than one label entry is available, this directive indicates how long to pause at the boot: prompt until booting automatically, in units of 1/10 s. The timeout is cancelled when any key is pressed, the assumption being the user will complete the command line. A timeout of zero will disable the timeout completely. The default is 0...."

MENU DEFAULT -

"...(Only valid after a LABEL statement.) Indicates that this entry should be the default for the particular (sub)menu. See also the DEFAULT directive. If no default is specified, use the first one...."

TEXT HELP -

"...(Only valid after a LABEL statement.) Specifies a help text that should be displayed when a particular selection is highlighted...."

Needs to end with ENDTEXT argument. E.g. -

     TEXT HELP
     text to display when option is highlighted
     ENDTEXT

MENU BEGIN - create a submenu within the menu file. This command must be followed by a tag (e.g. MENU BEGIN floppies) -

"...Begin/end a submenu. The entries between MENU BEGIN and MENU END form a submenu, which is marked with a > mark on the right hand of the screen. Submenus inherit the properties of their parent menus, but can override them, and can thus have their own backgrounds, master passwords, titles, timeouts, messages and so forth. ...."

Check the following sample menu for examples of the additional commands listed above -
DEFAULT menu.c32 TIMEOUT 100 MENU TITLE PXELinux Boot Options MENU BEGIN ipxe_menu LABEL ipxe MENU LABEL ^iPXE KERNEL ipxe.lkrn LABEL ipxe_menu MENU LABEL i^PXE (Load menu.ipxe) KERNEL ipxe.lkrn APPEND initrd=menu.ipxe MENU END LABEL win98 MENU LABEL ^Windows 98 Boot Disk MENU DEFAULT TEXT HELP Windows 98 based DOS boot disk - use for BIOS flashing, etc. ENDTEXT KERNEL memdisk APPEND initrd=images/win98.ima

Screenshot of the above sample menu when loaded on the client system -

Chainloading iPXE Scripts

iPXE supports HTTP and SANBOOT - consequently there are times when it might be useful to chainload ipxe.lkrn from PXELINUX. The following menu entry shows the syntax for loading ipxe.lkrn (kernel) with a script (initrd) -
label ipxe menu label iPXE loading menu.ipxe kernel ipxe.lkrn append initrd=menu.ipxe

If chainloading ipxe.lkrn the iPXE scripts used in this guide may need to be edited to add commands for configuring the Client PCs network interface. This is not required when using iPXE as the network bootstrap program with a script set as altfilename in config.ini as the network interface is automatically configured. To configure the first network adapter, simply add the following code at the start of any scripts to run the dhcp command -
#!ipxe dhcp net0 && echo IP address: ${net0/ip} ; echo Subnet mask: ${net0/netmask}

E.g. -
#!ipxe dhcp net0 && echo IP address: ${net0/ip} ; echo Subnet mask: ${net0/netmask} chain ${boot-url}/pxeboot.0

Document date - 28^th February 2017(DRAFT)