462 lines
16 KiB
Plaintext
462 lines
16 KiB
Plaintext
= pxelinux(1) =
|
|
:doctype: manpage
|
|
:revdate: 2013-06-12
|
|
:author: H. Peter Anvin
|
|
:author-email: hpa@zytor.com
|
|
:editor1: Gene Cumm
|
|
:editor1-email: gene.cumm@gmail.com
|
|
:editor1-revlast: 2013-06-12
|
|
|
|
|
|
== NAME ==
|
|
pxelinux - The Syslinux derivative PXELINUX for PXE network booting
|
|
|
|
|
|
== SYNOPSIS ==
|
|
[verse]
|
|
pxelinux.0
|
|
|
|
|
|
== DESCRIPTION ==
|
|
*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 Etherboot (http://www.etherboot.org/).
|
|
Etherboot 5.4 or later can also be used to create a PXE-compliant boot
|
|
PROM for many network cards.
|
|
//FIXME: Needs gPXE/iPXE note
|
|
|
|
PXELINUX generally requires that full file pathnames are 127 characters or shorter in length.
|
|
//FIXME: why? many tftpds limiting to 127+null? outdated?
|
|
|
|
|
|
== CURRENT DIRECTORY ==
|
|
The initial current working directory is either as supplied by DHCP
|
|
option 210 (pxelinux.pathprefix), the hardcoded path-prefix or the
|
|
parent directory of the PXELINUX file, as indicated by DHCP fields
|
|
'sname' and 'file' (sname="192.168.2.3" and file="boot/pxelinux.0"
|
|
results in "tftp://192.168.2.3/boot/", "192.168.2.3::boot/" in older
|
|
PXELINUX format) with precedence specified under *OPTIONS*.
|
|
|
|
All unqualified filenames are relative to the current directory.
|
|
|
|
|
|
== CONFIGURATION ==
|
|
See *syslinux.cfg*(5) for the format of the contents.
|
|
|
|
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. After attempting the file as specified in the DHCP or
|
|
hardcoded options, PXELINUX will probe the following paths, prefixed
|
|
with "pxelinux.cfg/", under the initial current working directory:
|
|
|
|
- The client UUID if provided by the PXE stack (note, some BIOSes don't
|
|
have a valid UUID, and you might end up with something like all 1's.)
|
|
This is in the standard UUID format using lower case hexadecimal digits,
|
|
e.g. b8945908-d6a6-41a9-611d-74a6ab80b83d.
|
|
|
|
- The hardware type (using its ARP type code) and address, all in lower
|
|
case 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.
|
|
|
|
- The client's IPv4 address in upper-case hexidecimal (ie 192.168.2.91
|
|
-> C0A8025B; you can use the included progam "gethostip" to compute the
|
|
hexadecimal IP address for any host.) followed by removing characters,
|
|
one at a time, from the end.
|
|
|
|
- "default"
|
|
|
|
Starting in release 3.20, if PXELINUX can not find a configuration file,
|
|
it will reboot after the timeout interval has expired. This keeps a
|
|
machine from getting stuck indefinitely due to a boot server failure.
|
|
|
|
|
|
== OPTIONS ==
|
|
*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*. See RFC
|
|
5071 for some additional information about these options. Options for
|
|
*PXELINUX* can be specified by DHCP options or hardcoded into the
|
|
binary.
|
|
|
|
=== Option Priority ===
|
|
Hardcoded after-options are applied after DHCP options (and overrride)
|
|
while hardcoded before-options are applied prior to DHCP options and
|
|
default behavior takes the lowest priority.
|
|
|
|
=== DHCP options ===
|
|
*Option 208* (pxelinux.magic)::
|
|
Earlier versions of *PXELINUX* required this to be set to F1:00:74:7E
|
|
(241.0.116.126) for *PXELINUX* to recognize any special DHCP options
|
|
whatsoever. As of *PXELINUX* 3.55, this option is deprecated and is no
|
|
longer required.
|
|
|
|
*Option 209* (pxelinux.configfile)::
|
|
Specifies the initial *PXELINUX* configuration file name which may be
|
|
qualified or unqualified.
|
|
|
|
*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.)
|
|
|
|
=== Hardcoded options ===
|
|
Since version 3.83, the program "pxelinux-options" can be used to
|
|
hard-code DHCP options into the pxelinux.0 image file; this is
|
|
sometimes useful when the DHCP server is under different
|
|
administrative control. Hardcoded options
|
|
|
|
6 => 'domain-name-servers',
|
|
15 => 'domain-name',
|
|
54 => 'next-server',
|
|
209 => 'config-file',
|
|
210 => 'path-prefix',
|
|
211 => 'reboottime'
|
|
|
|
|
|
== HTTP/FTP ==
|
|
Since version 5.10, a special PXELINUX binary, lpxelinux.0, natively
|
|
supports HTTP and FTP transfers, greatly increasing load speed and
|
|
allowing for standard HTTP scripts to present PXELINUX's configuration
|
|
file. To use http or ftp, use standard URL syntax as filename; use the
|
|
DHCP options below to transmit a suitable URL prefix to the client, or
|
|
use the "pxelinux-options" tool provided in the utils directory to
|
|
program it directly into the lpxelinux.0 file.
|
|
|
|
|
|
== FILENAME SYNTAX ==
|
|
//FIXME
|
|
PXELINUX supports the following special pathname conventions:
|
|
|
|
*::filename*::
|
|
Suppresses the common filename prefix, i.e. passes the string "filename"
|
|
unmodified to the server.
|
|
|
|
*IP address::filename* (e.g. 192.168.2.3::filename)::
|
|
Suppresses the common filename prefix, *and* sends a request to an alternate TFTP server. Instead of an IP address, a DNS name can be used. It will be assumed to be fully qualified if it contains dots; otherwise the local domain as reported by the DHCP server (option 15) will be added.
|
|
|
|
:: was chosen because it is unlikely to conflict with operating system
|
|
usage. However, if you happen to have an environment for which the
|
|
special treatment of :: is a problem, please contact the Syslinux
|
|
mailing list.
|
|
|
|
Since version 4.00, PXELINUX also supports standard URL syntax.
|
|
|
|
|
|
== KEEPPXE ==
|
|
Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
|
|
the kernel. In special circumstances (for example, when using MEMDISK
|
|
to boot an operating system with an UNDI network driver) it might be
|
|
desirable to keep the PXE stack in memory. If the option "keeppxe"
|
|
is given on the kernel command line, PXELINUX will keep the PXE and
|
|
UNDI stacks in memory. (If you don't know what this means, you
|
|
probably don't need it.)
|
|
|
|
|
|
== EXAMPLES ==
|
|
|
|
=== Configuration filename ===
|
|
For DHCP siaddr 192.168.2.3, file 'mybootdir/pxelinux.0', client UUID
|
|
b8945908-d6a6-41a9-611d-74a6ab80b83d, Ethernet MAC address
|
|
88:99:AA:BB:CC:DD and IPv4 address 192.168.2.91, the following files in
|
|
this order will be attempted (after config-file options):
|
|
|
|
mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d
|
|
mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
|
|
mybootdir/pxelinux.cfg/C0A8025B
|
|
mybootdir/pxelinux.cfg/C0A8025
|
|
mybootdir/pxelinux.cfg/C0A802
|
|
mybootdir/pxelinux.cfg/C0A80
|
|
mybootdir/pxelinux.cfg/C0A8
|
|
mybootdir/pxelinux.cfg/C0A
|
|
mybootdir/pxelinux.cfg/C0
|
|
mybootdir/pxelinux.cfg/C
|
|
mybootdir/pxelinux.cfg/default
|
|
|
|
|
|
=== TFTP servers ===
|
|
For best results, use a TFTP server which supports the "tsize" TFTP
|
|
option (RFC 1784/RFC 2349). The "tftp-hpa" TFTP server, which support
|
|
options, 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/
|
|
|
|
If your boot server is running Windows (and you can't fix that), try
|
|
tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
|
|
versions had a bug which made it incompatible with PXELINUX):
|
|
|
|
http://tftpd32.jounin.net/
|
|
|
|
|
|
=== DHCP config: Simple ===
|
|
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.
|
|
|
|
|
|
=== DHCP Config: PXE-1 ===
|
|
If the simple config does not work for your environment, 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 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.
|
|
|
|
|
|
=== DHCP Config: Encapsulated ===
|
|
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.
|
|
|
|
|
|
=== DHCP Config: ISC dhcpd options ===
|
|
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;
|
|
----
|
|
NOTE: In earlier versions of PXELINUX, this would only work as a
|
|
"site-option-space". Since PXELINUX 2.07, this will work both as a
|
|
"site-option-space" (unencapsulated) and as a "vendor-option-space"
|
|
(type 43 encapsulated.) This may avoid messing with the
|
|
dhcp-parameter-request-list, as detailed below.
|
|
|
|
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 (specified in hexadecimal)
|
|
option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
|
|
}
|
|
# 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 "option dhcp-parameter-request-list" statement forces the DHCP
|
|
server to send the PXELINUX-specific options, even though they are not
|
|
explicitly requested. Since the DHCP request is done before PXELINUX
|
|
is loaded, the PXE client won't know to request them.
|
|
|
|
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 (specified in hexadecimal)
|
|
option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
|
|
}
|
|
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".
|
|
|
|
|
|
== KNOWN ISSUES ==
|
|
The following problems are known with PXELINUX, so far:
|
|
|
|
- The error recovery routine doesn't work quite right. For right now,
|
|
it just does a hard reset - seems good enough.
|
|
- We should probably call the UDP receive function in the keyboard
|
|
entry loop, so that we answer ARP requests.
|
|
- Boot sectors/disk images are not supported yet.
|
|
|
|
If you have additional problems, please contact the Syslinux mailing
|
|
list (see syslinux.txt for the address.)
|
|
|
|
=== Broken PXE stacks ===
|
|
Lots of PXE stacks, especially old ones, have various problems of
|
|
varying degrees of severity. Please see:
|
|
|
|
http://syslinux.zytor.com/hardware.php
|
|
|
|
... for a list of currently known hardware problems, with workarounds
|
|
if known.
|
|
|
|
There are a number of extremely broken PXE stacks in the field. The
|
|
gPXE project (formerly known as Etherboot) provides an open-source PXE
|
|
stack that works with a number of cards, and which can be loaded from
|
|
a CD-ROM, USB key, or floppy if desired.
|
|
|
|
Information on gPXE is available from:
|
|
|
|
http://www.etherboot.org/
|
|
|
|
... and ready-to-use ROM or disk images from:
|
|
|
|
http://www.rom-o-matic.net/
|
|
|
|
Some cards, like may systems with the SiS 900, has a PXE stack which
|
|
works just barely well enough to load a single file, but doesn't
|
|
handle the more advanced items required by PXELINUX. If so, it is
|
|
possible to use the built-in PXE stack to load gPXE, which can then
|
|
load PXELINUX. See:
|
|
|
|
http://www.etherboot.org/wiki/pxechaining
|
|
|
|
|
|
== NOTES ==
|
|
=== MTFTP ===
|
|
PXELINUX does not support MTFTP, and there are no plans of doing so, as
|
|
MTFTP is inherently broken for files more than 65535 packets (about 92
|
|
MB) in size. 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.
|
|
|
|
=== Error Recovery ===
|
|
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.
|
|
|
|
|
|
== SEE ALSO ==
|
|
*syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8),
|
|
*fdisk*(8), *mkfs*(8), *superformat*(1).
|
|
|
|
|
|
== AUTHOR ==
|
|
This AsciiDoc derived document is a modified version of the original
|
|
*SYSLINUX* documentation by {author} <{author-email}>. The conversion
|
|
to an AsciiDoc was made by {editor1} <{editor1-email}>
|