How to network boot operating systems with gPXE

How to network boot operating systems with gPXE

Introduction

gPXE is a new version of the well know Etherboot project.
The project created network booting code that allows computers to load their operating system from a network.
The code can be stored in a number of places, including BIOS Flash, EPROMs, floppy, CD, HD, or other bootable media.

Required software

Software used in this HowTo:

Ubuntu Linux 9.04
gPXE 0.9.7: http://etherboot.org/wiki/download
SysLinux 3.75: http://syslinux.zytor.com/
Internet Systems Consortium DHCP server V3.1.1 - http://www.isc.org
TFTP server from Linux NetKit - http://www.h cs.harvard.edu/~dholland/computers/netkit.html

NOTE: Although I used Linux in this HowTo you can use any O.S running DHCP and TFTP servers to make this work.
My boot server at home runs NetBSD and works great with this setup. All you need is compiled gPXE binary.

Installation

Run following commands to install TFTP and DHCP servers:

# apt-get install tftpd
# apt-get install dhcp3-server

Download tarball of gPXE from http://kernel.org/pub/software/utils/boot/gpxe/gpxe-0.9.7.tar.gz
Extract it and compile

# cd gpxe-0.9.7/src
# make

The file we need is called undionly.kpxe and you can find it in

# gpxe-0.9.7/src/bin

Configuration

How to setup the DHCP server

Edit the config file:

/etc/dhcp3/dhcpd.conf

so it looks like this:

allow booting;
allow bootp;
ddns-update-style none;
log-facility local7;
default-lease-time -1;
max-lease-time 7200;
authoritative;
option space gpxe;
option gpxe-encap-opts code 175 = encapsulate gpxe;
option gpxe.bus-id code 177 = string;
 
subnet 192.168.1.0 netmask 255.255.255.0 {
  use-host-decl-names on;
  range 192.168.1.26 192.168.1.30;
  option routers 192.168.1.1;
  option broadcast-address 192.168.1.255;
  option root-path "192.168.1.1:/home/tftpboot/";
  next-server 192.168.1.1;
  if not exists gpxe.bus-id {
        filename "gpxe/undionly.kpxe";
  } else {
#       filename "http://192.168.1.1/boot/boot.php";
        filename "gpxe/menu.gpxe";
  }
  server-name "lapdance";
  server-identifier 192.168.1.1;
}

I will not be going into details here. This config file is using the “conventional TFTP” configuration with /home/tftpboot as it's relative root directory fetching all the files from there.
The subnet definition will hand out IPs for our clients from defined range.
When PXE booting your client, it will first download the gPXE binary which will “take over” from there and download it's own configuration file.
The if not exists gpxe.bus-id option is used to first hand out the undionly.kpxe file to PXE and then the menu.gpxe configuration file to gPXE.

Note: Notice the filename “http://192.168.1.1/boot/boot.php”; option. It allows you to fetch config from a HTTP server.
It can be a dymamically created config or a simple txt file as menu.gpxe but downloaded over HTTP.
For more info read http://etherboot.org/wiki/appnotes/authmenus

How to setup the TFTP server

The TFTP server will run as inetd service. Therefor we have to edit /etc/inetd.conf so it looks like this:

tftp            dgram   udp     wait    nobody  /usr/sbin/tcpd  /usr/sbin/in.tftpd /home/tftpboot

How to setup gPXE

Create directory for our files:

/home/tftpboot/gpxe

And create there a text file called menu.gpxe looking as follows:

#!gpxe
chain menu.c32 menu.cfg

This file is going to chain load menu.c32 and our menu config file. You can replace menu.c32 with vesamenu.c32 for a more fancy boot window.

As mentioned above, to be able to create a boot menu for gPXE we will need either menu.c32 or vesamenu.c32 file which are distributed with SysLinux.
To obtain one of the files download tarball of SysLinux: http://www.kernel.org/pub/linux/utils/boot/syslinux/syslinux-3.75.tar.gz
Unpack it and go to the menu directory:

syslinux-3.75/com32/menu/

There you will find two files, menu.c32 and vesamenu.c32. The first one can be used to create simple CLI menus and the last one alows to create more “fancy” graphical menus.
The menu.c32 works well over serial cable and we will use it in this HowTo.

Copy syslinux-3.75/com32/menu/menu.c32 and gpxe-0.9.7/src/bin/undionly.kpx to /home/tftpboot/gpxe

Now create a config file for our boot menu and call it menu.cfg (still in /home/tftpboot/gpxe directory). It will look like this:

PROMPT 0

ALLOWOPTIONS 0
MENU ROWS 6
 
MENU TITLE PLEASE CHOSE A SYSTEM TO BOOT
  
LABEL -
      MENU LABEL NETBOOT
      MENU DISABLE
LABEL SuSe
  MENU LABEL ^1 SUSE
  MENU INDENT 1
  KERNEL vmlinuz-suse
  APPEND ro root=/dev/hda1 initrd=initrd-suse.img
 
MENU SEPARATOR
   
LABEL -
        MENU LABEL DEBIAN
        MENU DISABLE
LABEL DEBIAN
  MENU LABEL ^1 DEBIAN
  MENU INDENT 1
  KERNEL vmlinuz-debian
  APPEND ro root=/dev/hda1 initrd=initrd-debian.img
  
LABEL UBUNTU
  MENU LABEL ^2 UBUNTU
  MENU INDENT 1
  KERNEL vmlinuz-ubuntu
  APPEND ro root=/dev/hda1 initrd=initrd-ubuntu.img

The options are described here: http://syslinux.zytor.com/wiki/index.php/SYSLINUX
How to create bootable Linux images is out of scope of this HowTo.

Starting services

Now we need to start the TFTP and DHCP services

To start the inetd server:

# /etc/init.d/openbsd-inetd start

The DHCP server:

#/etc/init.d/dhcp3-server start

Testing

Boot your computer using PXE network booting.
If all went you should be able to see message about DHCP address and then gPXE will get downloaded and show a menu on your screen.