Tiny PXE Server

Grub4dos

The following sections are covered in this page -

Introduction
Configuration File Path
Grub4dos Menu System
Chainloading iPXE Scripts

Introduction

grub4dos version 0.4.5c 2013-04-19 is included in the Tiny PXE Server Download. Two grub4dos files were included in previous versions of the Tiny PXE Server download, both standalone files without any file dependencies. Tiny PXE Server version 1.0.0.20 (dated 12/2/2017 (19:29)) includes only grldr. As it is possible that grub.exe may be reintroduced, I have decided to include in in this guide. In the scope of this guide the two versions and their usage are as follows -

grldr - Network Bootstrap Program that can be chainloaded - e.g. via iPXE. grldr uses a menu - if a menu is not found then an embedded menu will be loaded. grldr also has a command-line interface accessible from the menu by pressing the C key.

grub.exe - can be loaded by PXELINUX, iPXE, etc. grub.exe also uses a menu system with a built in menu (if a menu is not found) and a command-line interface. Unlike grldr it's possible to pass parameters directly to grub.exe.

grub4dos is a sophisticated boot manager with its own scripting language - due to the range of commands it supports I recommend that you refer to the following sites for more information -

Grub4dos Guide (diddy) - although it was written for an older version of Grub4dos (v 0.4.4) it covers basic usage relevant to newer versions.

Grub4dos Guide (RMPrepUSB) - up to date guide covering the grub4dos version included in the Tiny PXE Server download.

PXE related notes from the Grub4dos help file README_GRUB4DOS.txt -
****************************************************************************** *** PXE device *** ****************************************************************************** If PXE service is found at startup, GRUB4DOS will create a virtual device (pd), through which files from the tftp server can be accessed. You can setup a diskless boot environment using the following steps: Client side You need to boot from PXE ROM. Server side You need to configure a dhcp server and a tftp server. In the dhcp server, use grldr as boot file. You may also want to load a different menu.lst for different client. GRUB4DOS will scan the following location for configuration file: [/mybootdir]/menu.lst/01-88-99-AA-BB-CC-DD [/mybootdir]/menu.lst/C000025B [/mybootdir]/menu.lst/C000025 [/mybootdir]/menu.lst/C00002 [/mybootdir]/menu.lst/C0000 [/mybootdir]/menu.lst/C000 [/mybootdir]/menu.lst/C00 [/mybootdir]/menu.lst/C0 [/mybootdir]/menu.lst/C [/mybootdir]/menu.lst/default Here, we assume the network card mac for the client machine is 88:99:AA:BB:CC:DD, and the ip address is 192.0.2.91 (C000025B). /mybootdir is the directory of the boot file, for example, if boot file is /tftp/grldr, then mybootdir=tftp. If none of the above files is present, grldr will use its embeded menu.lst. This is a menu.lst to illstrate how to use files from the tftp server. title Create ramdisk using map map --mem (pd)/floppy.img (fd0) map --hook rootnoverify (fd0) chainloader (fd0)+1 title Create ramdisk using memdisk kernel (pd)/memdisk initrd (pd)/floppy.img You can see that the menu.lst is very similar to normal disk boot, you just need to replace device like (hd0,0) with (pd). There are some differences between disk device and pxe device: 1. You can't list files in the pxe device. 2. The blocklist command will not work with a file in the pxe device. 3. You must use --mem option if you want to map a file in the pxe device. When you use chainloader to load file from the pxe device, there is a option you can use: chainloader --raw (pd)/BOOT_FILE Option --raw works just like --force, but it load file in one go. This can improve performance in some situation. You can use the pxe command to control the pxe device. 1. pxe If used without any parameter, pxe command will display current settings. 2. pxe blksize N Set the packet size for tftp transmission. Minimum value is 512, maximum value is 1432. This parameter is used primarily for very old tftp server where packet larger than 512 byte is not supported. 3. pxe basedir /dir Set the base directory for files in the tftp server. If pxe basedir /tftp then all files in the pxe device is related to directory /tftp, for example, (pd)/aa.img correspond to /tftp/aa.img in the server. The default value of base directory is the directory of the boot file, for example, if boot file is /tftp/grldr, then default base directory is /tftp. 4. pxe keep Keep the PXE stack. The default behaviour of GRUB4DOS is to unload the PXE stack just before it exits. 5. pxe unload Unload the PXE stack immediately. ****************************************************************************** *** GRLDR as PXE boot file *** ****************************************************************************** GRLDR can be used as the PXE boot file on a remote/network server. The (pd) device is used to access files on the server. When GRLDR is booted through network, it will use its preset menu as the config file. However, you may use a "pxe detect" command, which acts the same way as PXELINUX: * First, it will search for the config file using the hardware type (using its ARP type code) and address, all in hexadecimal with dash separators; for example, for an Ethernet (ARP type 1) with address 88:99:AA:BB:CC:DD it would search for the filename 01-88-99-AA-BB-CC-DD. * Next, it will search for the config file using its own IP address in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B. If that file is not found, it will remove one hex digit and try again. At last, it will try looking for a file named default (in lower case). As an example, if the boot file name is /mybootdir/grldr, the Ethernet MAC address is 88:99:AA:BB:CC:DD and the IP address 192.0.2.91, it will try following files (in that order): /mybootdir/menu.lst/01-88-99-AA-BB-CC-DD /mybootdir/menu.lst/C000025B /mybootdir/menu.lst/C000025 /mybootdir/menu.lst/C00002 /mybootdir/menu.lst/C0000 /mybootdir/menu.lst/C000 /mybootdir/menu.lst/C00 /mybootdir/menu.lst/C0 /mybootdir/menu.lst/C /mybootdir/menu.lst/default You cannot directly map an image file on (pd). You must map it in memory using the --mem option. For example, map --mem (pd)/images/floppy.img (fd0) map --hook chainloader (fd0)+1 rootnoverify (fd0) boot One more example, map --mem (pd)/images/cdimage.iso (0xff) map --hook chainloader (0xff) boot ****************************************************************************** *** Use 'pxe detect' in preset-menu *** ****************************************************************************** Now the "pxe" command has a new subcommand "detect": pxe detect [BLOCK_SIZE] [MENU_FILE] BLOCK_SIZE specifies the block size for PXE. If it is not specified or it is 0, then grub4dos will go through a probing process and get a proper value for data transfer. MENU_FILE specifies the config file on the PXE server. If omitted, a standard config file in the menu.lst sub-dir will gain control. For a description on the config files in the menu.lst sub-dir, please refer to the section "GRLDR as PXE boot file" above. If MENU_FILE starts in a "/", then the MENU_FILE on the PXE server will gain control, else(if MENU_FILE does not start in a "/") no menu will be executed. Normally you want to use a "pxe blksize ..." or a "pxe detect ..." command before you access the (pd) device, since the default blocksize of 512 might not work on your system.

Configuration File Path

The default path for the Grub4dos configuration file is the \menu.lst\ directory - the path is relative to the Grub4dos Network Bootstrap Program - grldr (or grub.exe). 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 -

MAC Address - lowercase hexadecimal with - separators. The MAC address needs to be preceded with it's 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...

MAC = 01-08-00-27-7a-13-19
IP Address = C0A80202

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

\menu.lst\01-08-00-27-7a-13-19
\menu.lst\C0A80202
\menu.lst\C0A8020
\menu.lst\C0A802
\menu.lst\C0A80
\menu.lst\C0A8
\menu.lst\C0A
\menu.lst\C0
\menu.lst\C
\menu.lst\default

Grub4dos Menu System

The default Grub4dos menu (i.e. the embedded menu loaded if a menu file cannot be located) is text based. Grub4dos also has built in graphic support for splash images. The syntax for graphic support is covered in detail here.

The splashimage command can be used without defining a graphicsmode providing that a supported image type is specified and the image is of a resolution supported by the client systems VESA BIOS Extensions (VBE) mode.

"...0.4.5c and later versions of grub4dos support bmp files and compressed .bmp.gz files in 640x480, 800x600 and 1024x768, 8, 16, 24 or 32 bit colour!...

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

     title PXELINUX
     pxe keep
     chainloader --raw (pd)/pxelinux.0

and -

     title Win98 DOS Boot Disk
     map --mem (pd)/images/win98.ima (fd0)
     map --hook
     root (fd0)
     chainloader +1

and -

     title Win98 DOS Boot Disk (Memdisk)
     kernel (pd)/memdisk
     initrd (pd)/images/win98.ima

It's also possible to load submenus -

title Floppy Disk Image Submenu
configfile /menu.lst/submenu1.txt

Putting all this together -
title PXELINUX pxe keep chainloader --raw (pd)/pxelinux.0 title Win98 DOS Boot Disk map --mem (pd)/images/win98.ima (fd0) map --hook root (fd0) chainloader +1 title Win98 DOS Boot Disk (Memdisk) kernel (pd)/memdisk initrd (pd)/images/win98.ima title Floppy Disk Image Submenu configfile /menu.lst/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 -

title - this acts as a placemark and also contains the text that will be displayed for the menu entry.

map --mem - the README_GRUB4DOS.txt file states that "...You must use --mem option if you want to map a file in the pxe device...". Mapping a file to memory creates a RAMDisk.

kernel - "...Attempt to load the primary boot image from FILE. The rest of the line is passed verbatim as the "kernel command line". Any modules must be reloaded after using this command..." In the scope of this guide the file specified here (including path) is usually a linux kernel type file. Unlike PXELINUX menu entries, parameters are specified in the kernel entry - these parameters are usually listed in the APPEND entry in PXELINUX. Quick reminder about the file path - assuming the file is loaded from the server then the path must specify the (pd) device + path relative to the tftp root directory (see examples above).

initrd - linux initial ramdisk file with path.

pxe - options are pxe keep ("...Keep the PXE stack. The default behaviour of GRUB4DOS is to unload...") and pxe unload ("...Unload the PXE stack immediately..."). pxe keep is required if chainloading another Network Bootstrap Program (e.g. pxelinux.0).

Chainloading iPXE Scripts

iPXE supports HTTP and SANBOOT - consequently there are times when it might be useful to chainload ipxe.lkrn from grub4dos. The following menu entry shows the syntax for loading ipxe.lkrn (kernel) with a script (initrd) -
title iPXE loading menu.ipxe pxe keep kernel (pd)/ipxe.lkrn initrd (pd)/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)