http://syslinux.zytor.com/

{ PXELINUX Questions }

• What is PXELINUX?
• How can I configure PXELINUX?
• How should I setup my tftp server?
• How should I setup my dhcpd server?
• Can I send information to PXELINUX via the dhcp response?
• What if the boot fails?
• What problems exist in PXELINUX?

{ What is PXELINUX? }

PXELINUX is a SYSLINUX derivative, for booting Linux off a network server, using a network ROM conforming to the Intel PXE (Pre-Execution Environment) specification. PXELINUX is *not* a program that is intended to be flashed or burned into a PROM on the network card; if you want that, check out NILO ( http://www.nilo.org/). NILO can also be used to create a PXE-compliant boot PROM for most network cards which have drivers for Linux or FreeBSD.

{ How do I Configure PXELINUX? }

PXELINUX operates in many ways like SYSLINUX. If you are not familiar with SYSLINUX, read the SYSLINUX FAQ first, since this documentation only explains the differences.

On the TFTP server, create the directory "/tftpboot", and copy pxelinux.0 (from the SYSLINUX distribution) and any kernel or initrd images that you want to boot.

Finally, create the directory "/tftpboot/pxelinux.cfg". The configuration file (equivalent of syslinux.cfg -- see the SYSLINUX FAQ for the options here) will live in this directory. Because more than one system may be booted from the same server, the configuration file name depends on the IP address of the booting machine. PXELINUX will search for its config file on the boot server in the following way:

First, it will search for the config file using its own IP address in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B (you can use the included progam gethostip to compute the hexadecimal IP address for any host.)

If that file is not found, it will remove one hex digit and try again. Ultimately, it will try looking for a file named default (in lower case).

As an example, for 192.0.2.91, it will try C000025B, C000025, C00002, C0000, C000, C00, C0, C, and default, in that order.

(See also the section on special DHCP options.)

It should be noted that all filename references are relative to the directory pxelinux.0 lives in (usually /tftpboot). PXELINUX generally requires that filenames (including any relative path) are 63 characters or shorter in length.

PXELINUX does not support MTFTP, and I have no immediate plans of doing so. It is of course possible to use MTFTP for the initial boot, if you have such a setup. MTFTP server setup is beyond the scope of this document.

{ How Should I Setup my TFTP server? }

PXELINUX currently requires that the boot server has a TFTP server which supports the "tsize" TFTP option (RFC 1784/RFC 2349).

Also, please do check out the problematic hardware reference page to see if your PXE stacks need any special workarounds.

Some TFTP servers which have been successfully used with PXELINUX include:

The "tftp-hpa" TFTP server, a highly portable update and port of the BSD TFTP server code is available at:

· http://www.kernel.org/pub/software/network/tftp/

· ftp://www.kernel.org/pub/software/network/tftp/

... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).

Another TFTP server which supports this is atftp by Jean-Pierre Lefebvre:

ftp://ftp.mamalinux.com/pub/atftp/

atftp is likely going to perform better than tftp-hpa on a large boot server, but may not be quite as widely portable.

If your boot server runs Windows (and you can't fix that), try tftpd32 by Philippe Jounin:

http://tftpd32.jounin.net/

Eric Cook of Intel also reports that the TFTPD server from Win2000 Server RIS can be used:

The trick is to install RIS, but DON'T configure it with the GUI. Instead, do the following:

· In the registry, add the folder \HKLM\System\CurrentControlSet\Services\TFTPD\Parameters.

· In the Parameters folder, add a key called Directory, with a value of the TFTP root directory path.

· With the Services GUI, configure the TFTPD service for Automatic start and start it.

If you DO configure the RIS in Win2k, you end up with the MS PXE stuff, which is ugly to get rid of.

{ How Should I Setup My DHCP server? }

The PXE protocol uses a very complex set of extensions to DHCP or BOOTP. However, most PXE implementations -- this includes all Intel ones version 0.99n and later -- seem to be able to boot in a "conventional" DHCP/TFTP configuration. Assuming you don't have to support any very old or otherwise severely broken clients, this is probably the best configuration unless you already have a PXE boot server on your network.

A sample DHCP setup, using the "conventional TFTP" configuration, would look something like the following, using ISC dhcp 2.0 dhcpd.conf syntax:

 
 allow booting;
 allow bootp;
 
 # Standard configuration directives...
 
 option domain-name "domain_name";
 option subnet-mask subnet_mask;
 option broadcast-address broadcast_address;
 option domain-name-servers dns_servers;
 option routers default_router;
 
 # Group the PXE bootable hosts together
 group {
  # PXE-specific configuration directives...
  next-server TFTP_server_address;
  filename "/tftpboot/pxelinux.0";
 
  # You need an entry like this for every host
  # unless you're using dynamic addresses
  host hostname {
   hardware ethernet ethernet_address;
   fixed-address hostname;
  }
 }

Note that if your particular TFTP daemon runs under chroot (tftp-hpa will do this if you specify the -s (secure) option; this is highly recommended), you almost certainly should not include the /tftpboot prefix in the filename statement.

If this does not work for your configuration, you probably should set up a "PXE boot server" on port 4011 of your TFTP server; a free PXE boot server is available at:

http://www.kano.org.uk/projects/pxe/

With such a boot server defined, your DHCP configuration should look the same except for an "option dhcp-class-identifier" ("option vendor-class-identifier" if you are using ISC dhcp 3.0):

 allow booting;
 allow bootp;
 
 # Standard configuration directives...
 
 option domain-name "domain_name";
 option subnet-mask subnet_mask;
 option broadcast-address broadcast_address;
 option domain-name-servers dns_servers;
 option routers default_router;
 
 # Group the PXE bootable hosts together
 group {
  # PXE-specific configuration directives...
  option dhcp-class-identifier "PXEClient";
  next-server pxe_boot_server_address;
 
  # You need an entry like this for every host
  # unless you're using dynamic addresses
  host hostname {
   hardware ethernet ethernet_address;
   fixed-address hostname;
  }
 }

Here, the boot file name is obtained from the PXE server.

If the "conventional TFTP" configuration doesn't work on your clients, and setting up a PXE boot server is not an option, you can attempt the following configuration. It has been known to boot some configurations correctly; however, there are no guarantees:

 
 allow booting;
 allow bootp;
 
 # Standard configuration directives...
 
 option domain-name "domain_name";
 option subnet-mask subnet_mask;
 option broadcast-address broadcast_address;
  option domain-name-servers dns_servers;
 option routers default_router;
 
 # Group the PXE bootable hosts together
 group {
  # PXE-specific configuration directives...
  option dhcp-class-identifier "PXEClient";
  option vendor-encapsulated-options 09:0f:80:00:0c:4e:65:74:77:6f:72:6b:20:62:6f:6f:74:0a:07:00:50:72:6f:6d:70:74:06:01:02:08:03:80:00:00:47:04:80:00:00:00:ff;
  next-server TFTP_server;
  filename "/tftpboot/pxelinux.0";
 
  # You need an entry like this for every host
  # unless you're using dynamic addresses
  host hostname {
   hardware ethernet ethernet_address;
   fixed-address hostname;
  }
 }

Note that this will not boot some clients that will boot with the "conventional TFTP" configuration; Intel Boot Client 3.0 and later are known to fall into this category.

{ Can I send information to PXELINUX via special options in the DHCP response? }

PXELINUX (starting with version 1.62) supports the following nonstandard DHCP options, which depending on your DHCP server you may be able to use to customize the specific behaviour of PXELINUX:

Option 208: pxelinux.magic
Must be set to F1:00:74:7E (241.0.116.126) for PXELINUX to recognize any special DHCP options whatsoever.

Option 209: pxelinux.configfile
Specifies the PXELINUX configuration file name.

Option 210: pxelinux.pathprefix
Specifies the PXELINUX common path prefix, instead of deriving it from the boot file name. This almost certainly needs to end in whatever character the TFTP server OS uses as a pathname separator, e.g. slash (/) for Unix.

Option 211: pxelinux.reboottime
Specifies, in seconds, the time to wait before reboot in the event of TFTP failure. 0 means wait "forever" (in reality, it waits approximately 136 years.)

ISC dhcp 3.0 supports a rather nice syntax for specifying custom options; you can use the following syntax in dhcpd.conf if you are running this version of dhcpd:

 option space pxelinux;
 option pxelinux.magic code 208 = string;
 option pxelinux.configfile code 209 = text;
 option pxelinux.pathprefix code 210 = text;
 option pxelinux.reboottime code 211 = unsigned integer 32;

Then, inside your PXELINUX-booting group or class (whereever you have the PXELINUX-related options, such as the filename option), you can add, for example:

 # Always include the following lines for all PXELINUX clients
 site-option-space "pxelinux";
 option pxelinux.magic f1:00:74:7e;
 if exists dhcp-parameter-request-list {
  # Always send the PXELINUX options
  append dhcp-parameter-request-list 208, 209, 210, 211;
 }
 # These lines should be customized to your setup
 option pxelinux.configfile "configs/common";
 option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
 option pxelinux.reboottime 30;
 filename "/tftpboot/pxelinux/pxelinux.bin";

Note that the configfile is relative to the pathprefix: this will look for a config file called /tftpboot/pxelinux/files/configs/common on the TFTP server.

The "append dhcp-parameter-request-list" is an undocumented (as of DHCP 3.0rc2pl1) option which forces the DHCP server to send the PXELINUX-specific options, even though they are not explicitly requested.

Using ISC dhcp 3.0 you can create a lot of these strings on the fly. For example, to use the hexadecimal form of the hardware address as the configuration file name, you could do something like:

 site-option-space "pxelinux";
 option pxelinux.magic f1:00:74:7e;
 if exists dhcp-parameter-request-list {
  # Always send the PXELINUX options
  append dhcp-parameter-request-list 208, 209, 210, 211;
 }
 option pxelinux.configfile =
  concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
 filename "/tftpboot/pxelinux.bin";

If you used this from a client whose Ethernet address was 58:FA:84:CF:55:0E, this would look for a configuration file named "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".

{ What Happens When a Boot Fails? }

If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever; rather, if it has not received any input for approximately five minutes after displaying an error message, it will reset the machine. This allows an unattended machine to recover in case it had bad enough luck of trying to boot at the same time the TFTP server goes down.

{ What Problems Are There Currently With PXELINUX? }

· Requires a TFTP server which supports the "tsize" option.

· The error recovery routine doesn't work quite right. For right now, it just does a hard reset - seems good enough.

· There may be funnies with memory management. The PXE spec has no decent way of telling it to free up all memory and unchain any interrupts; it allows the base stack to be unloaded, but not the UNDI driver.

· We should probably call the UDP receive function in the keyboard entry loop, so that we answer ARP requests.

· Boot sectors don't work yet... they probably need auxilliary information (such as device) to work at all.

{ MEMDISK documentation }

• What is MEMDISK?
• How can I use MEMDISK?
• How should the image be constructed?

{ What is MEMDISK? }

MEMDISK is meant to allow booting legacy operating systems via PXE, and as a workaround for BIOSes where ISOLINUX image support doesn't work.

MEMDISK simulates a disk by claiming a chunk of high memory for the disk and a (very small - 2K typical) chunk of low (DOS) memory for the driver itself, then hooking the INT 13h (disk driver) and INT 15h (memory query) BIOS interrupts.

{ How can I use MEMDISK? }

MEMDISK is an auxillary module used in conjunction with one of the SYSLINUX bootloaders, usually PXELINUX or ISOLINUX. You need a disk image as well as the memdisk file itself. As far as the bootloader is concerned, memdisk is the "kernel" and disk image is the initial ramdisk (initrd).

You can use MEMDISK straight off the boot loader command line like the following:

memdisk initrd=diskimg.img

... where, of course, diskimg.img is the name of the disk image file. The memdisk file and the disk image need to be present in the appropriate location (for PXELINUX, on your TFTP server, for ISOLINUX, in the /isolinux directory on your CD, etc.)

Normally, however, you would put something like following in the configuration file:

label dos
 kernel memdisk
 append initrd=dosboot.img

{ How should the image be constructed? }

The image file should contain a disk image, either a floppy disk or hard disk image. The disk image should not be compressed.

If the disk image is one of the following sizes, it's assumed to be a floppy image:

368,640 bytes	360K floppy (old 5.25")
737,280 bytes	720K floppy (old 3.5")
1,222,800 bytes	1200K floppy (standard 5.25")
1,474,560 bytes	1440K floppy (standard 3.5")
2,949,120 bytes	2880K floppy (enhanced 3.5")

For any other size, the image is assumed to be a hard disk image, and should have an MBR and a partition table. The C/H/S geometry is determined by examining the partition table, so the image does need to contain a valid partition table which convers the entirety of the image for proper operation.

It is also possible to specify the geometry manually, overriding the autodetect feature, by specifying the following command-line options:

c=number	Specify the number of cylinders (max 1024[*])
h=number	Specify the number of heads (max 256[*])
s=number	Specify the number of sectors (max 63)
floppy	The image is a floppy disk image
harddisk	The image is a hard disk image

[*] MS-DOS only allows max 255 heads, and only allows 255 cylinders on floppy disks.

{ Additional notes }

To recompile MEMDISK from sources, you will need to make sure that you have a fairly recent binutils installed. I have been using binutils-2.11.90.0.8 in the form of the binutils-2.11.90.0.8-9 RPM from RedHat 7.2.

{ SYSLINUX Questions }

• What is SYSLINUX?
• What is SYSLINUX not?
• How do I create a bootable floppy?
• How can I configure SYSLINUX?
• Can SYSLINUX handle large (>500K) bzInage kernels?
• What is the DISPLAY file format?
• Can SYSLINUX boot other operating systems?
• What are COMBOOT files?
• What protections exist in SYSLINUX?
• Does SYSLINUX support bootable CDs?
• Can I use SYSLINUX on a hard drive?
• What Bugs are Outstanding in SYSLINUX?
• How can I Give Feedback on SYSLINUX?

{ What is SYSLINUX? }

SYSLINUX is a boot loader for the Linux operating system which operates off an MS-DOS/Windows FAT filesystem. It is intended to simplify first-time installation of Linux, and for creation of rescue- and other special-purpose boot disks.

SYSLINUX can be used, when properly set up, to completely eliminate the need for distribution of raw diskette images for boot floppies. A SYSLINUX floppy can be manipulated using standard MS-DOS (or any other OS that can access an MS-DOS filesystem) tools once it has been created.

{ What SYSLINUX is Not... }

SYSLINUX is probably not suitable as a general purpose boot loader. It can only boot Linux from a FAT filesystem, and not, for example, ext2. Since a native Linux implementation will typically use ext2, another boot loader (e.g. LILO) is probably more suitable. In a system which actually contains DOS or Windows, LOADLIN may be simpler to use.

However, SYSLINUX has shown itself to be quite useful in a number of special-purpose applications.

{ How do I Create a Bootable Floppy? }

In order to create a bootable Linux floppy using SYSLINUX, prepare a normal MS-DOS formatted floppy. Copy one or more Linux kernel files to it, then execute the DOS command:

syslinux [-s] a:

(or whichever drive letter is appropriate; the [] meaning -s is optional)

If you're running in a Win95/98/ME DOS box, you should execute the command lock a: first. If you're running in a WinNT/2K DOS box, you will probably get a dialog box about not getting exclusive access and with Abort/Retry/Ignore buttons; people have reported that selecting "Ignore" makes the command complete correctly.

Under Linux, execute the command:

syslinux [-s] [-o offset] /dev/fd0

(or, again, whichever device is the correct one.)

This will alter the boot sector on the disk and copy a file named LDLINUX.SYS into its root directory.

The -s option, if given, will install a "safe, slow and stupid" version of SYSLINUX. This version may work on some very buggy BIOSes on which SYSLINUX would otherwise fail. If you find a machine on which the -soption is required to make it boot reliably, please send as much info about your machine as you can, and include the failure mode.

The -o option is used with a disk image file and specifies the byte offset of the filesystem image in the file.

On boot time, by default, the kernel will be loaded from the image named LINUX on the boot floppy. This default can be changed, see the section on the SYSLINUX config file.

If the Shift or Alt keys are held down during boot, or the Caps or Scroll locks are set, SYSLINUX will display a LILO-style "boot:" prompt. The user can then type a kernel file name followed by any kernel parameters. The SYSLINUX loader does not need to know about the kernel file in advance; all that is required is that it is a file located in the root directory on the disk.

{ How do I Configure SYSLINUX? }

All the configurable defaults in SYSLINUX can be changed by putting a file called SYSLINUX.CFG in the root directory of the boot floppy. This is a text file in either UNIX or DOS format, containing one or more of the following items (case is insensitive for keywords; upper case is used here to indicate that a word should be typed verbatim):

All options here applies to PXELINUX as well as SYSLINUX unless otherwise noted. See pxelinux.doc for additional information on PXELINUX.

DEFAULT kernel options...

Sets the default command line. If SYSLINUX boots automatically, it will act just as if the entries after DEFAULT had been typed in at the "boot:" prompt, except that the option "auto" is automatically added, indicating an automatic boot.

If no configuration file is present, or no DEFAULT entry is present in the config file, the default is kernel name "linux", with no options.

APPEND options...

Add one or more options to the kernel command line. These are added both for automatic and manual boots. The options are added at the very beginning of the kernel command line, usually permitting explicitly entered kernel options to override them. This is the equivalent of the LILO "append" option.

IPAPPEND flag_val [PXELINUX only]

The IPAPPEND option is available only on PXELINUX, and indicates (if the flag value is 1) that an option of the following format should be generated and added:

ip=<client-ip>:<boot-server-ip>:<gw-ip>:<netmask>

... based on the input from the DHCP/BOOTP or PXE boot server.

LABEL label

KERNEL image
APPEND options...
IPAPPEND flag_val [PXELINUX only]