3 A bootloader for Linux using the PXE network booting protocol
5 Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
7 This program is provided under the terms of the GNU General Public
8 License, version 2 or, at your option, any later version. There is no
9 warranty, neither expressed nor implied, to the function of this
10 program. Please see the included file COPYING for details.
12 ----------------------------------------------------------------------
14 PXELINUX is a Syslinux derivative, for booting Linux off a network
15 server, using a network ROM conforming to the Intel PXE (Pre-Execution
16 Environment) specification. PXELINUX is *not* a program that is
17 intended to be flashed or burned into a PROM on the network card; if
18 you want that, check out Etherboot (http://www.etherboot.org/).
19 Etherboot 5.4 or later can also be used to create a PXE-compliant boot
20 PROM for many network cards.
23 ++++ HOW TO CONFIGURE PXELINUX ++++
25 PXELINUX operates in many ways like SYSLINUX. If you are not familiar
26 with SYSLINUX, read syslinux.txt first, since this documentation only
27 explains the differences.
29 On the TFTP server, create the directory "/tftpboot", and copy the
30 following files to it:
32 pxelinux.0 - from the Syslinux distribution
34 any kernel or initrd images you want to boot
36 Finally, create the directory "/tftpboot/pxelinux.cfg". The
37 configuration file (equivalent of syslinux.cfg -- see syslinux.txt for
38 the options here) will live in this directory. Because more than one
39 system may be booted from the same server, the configuration file name
40 depends on the IP address of the booting machine. PXELINUX will
41 search for its config file on the boot server in the following way:
43 First, it will search for the config file using the client UUID, if
44 one is provided by the PXE stack (note, some BIOSes don't have a
45 valid UUID, and you might end up with something like all 1's.) This is
46 in the standard UUID format using lower case hexadecimal digits, e.g.
47 b8945908-d6a6-41a9-611d-74a6ab80b83d.
49 Next, it will search for the config file using the hardware type
50 (using its ARP type code) and address, all in lower case hexadecimal
51 with dash separators; for example, for an Ethernet (ARP type 1)
52 with address 88:99:AA:BB:CC:DD it would search for the filename
55 Next, it will search for the config file using its own IP address
56 in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B
57 (you can use the included progam "gethostip" to compute the
58 hexadecimal IP address for any host.)
60 If that file is not found, it will remove one hex digit and try
61 again. Ultimately, it will try looking for a file named "default"
64 As an example, if the boot file name is /mybootdir/pxelinux.0, the
65 UUID is b8945908-d6a6-41a9-611d-74a6ab80b83d, the Ethernet MAC
66 address is 88:99:AA:BB:CC:DD and the IP address 192.0.2.91, it will
69 /mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d
70 /mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
71 /mybootdir/pxelinux.cfg/C000025B
72 /mybootdir/pxelinux.cfg/C000025
73 /mybootdir/pxelinux.cfg/C00002
74 /mybootdir/pxelinux.cfg/C0000
75 /mybootdir/pxelinux.cfg/C000
76 /mybootdir/pxelinux.cfg/C00
77 /mybootdir/pxelinux.cfg/C0
78 /mybootdir/pxelinux.cfg/C
79 /mybootdir/pxelinux.cfg/default
83 Note that all filename references are relative to the directory
84 pxelinux.0 lives in. PXELINUX generally requires that filenames
85 (including any relative path) are 127 characters or shorter in length.
87 Starting in release 3.20, PXELINUX will no longer apply a built-in
88 default if it cannot find any configuration file at all; instead it
89 will reboot after the timeout interval has expired. This keeps a
90 machine from getting stuck indefinitely due to a boot server failure.
92 PXELINUX does not support MTFTP, and I have no plans of doing so, as
93 MTFTP is inherently broken for files more than 65535 packets (about
94 92 MB) in size. It is of course possible to use MTFTP for the initial
95 boot, if you have such a setup. MTFTP server setup is beyond the
96 scope of this document.
99 ++++ SETTING UP THE TFTP SERVER ++++
101 PXELINUX currently requires that the boot server has a TFTP server
102 which supports the "tsize" TFTP option (RFC 1784/RFC 2349). The
103 "tftp-hpa" TFTP server, which support options, is available at:
105 http://www.kernel.org/pub/software/network/tftp/
106 ftp://www.kernel.org/pub/software/network/tftp/
108 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
110 Another TFTP server which supports this is atftp by Jean-Pierre
113 ftp://ftp.mamalinux.com/pub/atftp/
115 If your boot server is running Windows (and you can't fix that), try
116 tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
117 versions had a bug which made it incompatible with PXELINUX):
119 http://tftpd32.jounin.net/
122 ++++ SETTING UP THE DHCP SERVER ++++
124 The PXE protocol uses a very complex set of extensions to DHCP or
125 BOOTP. However, most PXE implementations -- this includes all Intel
126 ones version 0.99n and later -- seem to be able to boot in a
127 "conventional" DHCP/TFTP configuration. Assuming you don't have to
128 support any very old or otherwise severely broken clients, this is
129 probably the best configuration unless you already have a PXE boot
130 server on your network.
132 A sample DHCP setup, using the "conventional TFTP" configuration,
133 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
139 # Standard configuration directives...
141 option domain-name "<domain name>";
142 option subnet-mask <subnet mask>;
143 option broadcast-address <broadcast address>;
144 option domain-name-servers <dns servers>;
145 option routers <default router>;
147 # Group the PXE bootable hosts together
149 # PXE-specific configuration directives...
150 next-server <TFTP server address>;
151 filename "/tftpboot/pxelinux.0";
153 # You need an entry like this for every host
154 # unless you're using dynamic addresses
156 hardware ethernet <ethernet address>;
157 fixed-address <hostname>;
161 Note that if your particular TFTP daemon runs under chroot (tftp-hpa
162 will do this if you specify the -s (secure) option; this is highly
163 recommended), you almost certainly should not include the /tftpboot
164 prefix in the filename statement.
166 If this does not work for your configuration, you probably should set
167 up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
168 boot server is available at:
170 http://www.kano.org.uk/projects/pxe/
172 With such a boot server defined, your DHCP configuration should look
173 the same except for an "option dhcp-class-identifier" ("option
174 vendor-class-identifier" if you are using DHCP 3.0):
179 # Standard configuration directives...
181 option domain-name "<domain name>";
182 option subnet-mask <subnet mask>;
183 option broadcast-address <broadcast address>;
184 option domain-name-servers <dns servers>;
185 option routers <default router>;
187 # Group the PXE bootable hosts together
189 # PXE-specific configuration directives...
190 option dhcp-class-identifier "PXEClient";
191 next-server <pxe boot server address>;
193 # You need an entry like this for every host
194 # unless you're using dynamic addresses
196 hardware ethernet <ethernet address>;
197 fixed-address <hostname>;
201 Here, the boot file name is obtained from the PXE server.
203 If the "conventional TFTP" configuration doesn't work on your clients,
204 and setting up a PXE boot server is not an option, you can attempt the
205 following configuration. It has been known to boot some
206 configurations correctly; however, there are no guarantees:
211 # Standard configuration directives...
213 option domain-name "<domain name>";
214 option subnet-mask <subnet mask>;
215 option broadcast-address <broadcast address>;
216 option domain-name-servers <dns servers>;
217 option routers <default router>;
219 # Group the PXE bootable hosts together
221 # PXE-specific configuration directives...
222 option dhcp-class-identifier "PXEClient";
223 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;
224 next-server <TFTP server>;
225 filename "/tftpboot/pxelinux.0";
227 # You need an entry like this for every host
228 # unless you're using dynamic addresses
230 hardware ethernet <ethernet address>;
231 fixed-address <hostname>;
235 Note that this *will not* boot some clients that *will* boot with the
236 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are
237 known to fall into this category.
240 ++++ SPECIAL DHCP OPTIONS ++++
242 PXELINUX (starting with version 1.62) supports the following
243 nonstandard DHCP options, which depending on your DHCP server you may
244 be able to use to customize the specific behaviour of PXELINUX. See
245 RFC 5071 for some additional information about these options.
247 Option 208 pxelinux.magic
248 - Earlier versions of PXELINUX required this to be set to
249 F1:00:74:7E (241.0.116.126) for PXELINUX to
250 recognize any special DHCP options whatsoever. As of
251 PXELINUX 3.55, this option is deprecated and is no longer
254 Option 209 pxelinux.configfile
255 - Specifies the PXELINUX configuration file name.
257 Option 210 pxelinux.pathprefix
258 - Specifies the PXELINUX common path prefix, instead of
259 deriving it from the boot file name. This almost certainly
260 needs to end in whatever character the TFTP server OS uses
261 as a pathname separator, e.g. slash (/) for Unix.
263 Option 211 pxelinux.reboottime
264 - Specifies, in seconds, the time to wait before reboot in the
265 event of TFTP failure. 0 means wait "forever" (in reality,
266 it waits approximately 136 years.)
268 ISC dhcp 3.0 supports a rather nice syntax for specifying custom
269 options; you can use the following syntax in dhcpd.conf if you are
270 running this version of dhcpd:
272 option space pxelinux;
273 option pxelinux.magic code 208 = string;
274 option pxelinux.configfile code 209 = text;
275 option pxelinux.pathprefix code 210 = text;
276 option pxelinux.reboottime code 211 = unsigned integer 32;
278 NOTE: In earlier versions of PXELINUX, this would only work as a
279 "site-option-space". Since PXELINUX 2.07, this will work both as a
280 "site-option-space" (unencapsulated) and as a "vendor-option-space"
281 (type 43 encapsulated.) This may avoid messing with the
282 dhcp-parameter-request-list, as detailed below.
284 Then, inside your PXELINUX-booting group or class (whereever you have
285 the PXELINUX-related options, such as the filename option), you can
288 # Always include the following lines for all PXELINUX clients
289 site-option-space "pxelinux";
290 option pxelinux.magic f1:00:74:7e;
291 if exists dhcp-parameter-request-list {
292 # Always send the PXELINUX options (specified in hexadecimal)
293 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
295 # These lines should be customized to your setup
296 option pxelinux.configfile "configs/common";
297 option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
298 option pxelinux.reboottime 30;
299 filename "/tftpboot/pxelinux/pxelinux.bin";
301 Note that the configfile is relative to the pathprefix: this will look
302 for a config file called /tftpboot/pxelinux/files/configs/common on
305 The "option dhcp-parameter-request-list" statement forces the DHCP
306 server to send the PXELINUX-specific options, even though they are not
307 explicitly requested. Since the DHCP request is done before PXELINUX
308 is loaded, the PXE client won't know to request them.
310 Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
311 For example, to use the hexadecimal form of the hardware address as
312 the configuration file name, you could do something like:
314 site-option-space "pxelinux";
315 option pxelinux.magic f1:00:74:7e;
316 if exists dhcp-parameter-request-list {
317 # Always send the PXELINUX options (specified in hexadecimal)
318 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
320 option pxelinux.configfile =
321 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
322 filename "/tftpboot/pxelinux.bin";
324 If you used this from a client whose Ethernet address was
325 58:FA:84:CF:55:0E, this would look for a configuration file named
326 "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
329 ++++ ALTERNATE TFTP SERVERS ++++
331 PXELINUX supports the following special pathname conventions:
335 Suppresses the common filename prefix, i.e. passes the string
336 "filename" unmodified to the server.
338 IP address::filename (e.g. 192.0.2.1::filename)
340 Suppresses the common filename prefix, *and* sends a request
341 to an alternate TFTP server. Instead of an IP address, a
342 DNS name can be used. It will be assumed to be fully
343 qualified if it contains dots; otherwise the local domain as
344 reported by the DHCP server (option 15) will be added.
346 :: was chosen because it is unlikely to conflict with operating system
347 usage. However, if you happen to have an environment for which the
348 special treatment of :: is a problem, please contact the Syslinux
354 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
355 rather, if it has not received any input for approximately five
356 minutes after displaying an error message, it will reset the machine.
357 This allows an unattended machine to recover in case it had bad enough
358 luck of trying to boot at the same time the TFTP server goes down.
360 Lots of PXE stacks, especially old ones, have various problems of
361 varying degrees of severity. Please see:
363 http://syslinux.zytor.com/hardware.php
365 ... for a list of currently known hardware problems, with workarounds
369 ++++ KEEPING THE PXE STACK AROUND ++++
371 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
372 the kernel. In special circumstances (for example, when using MEMDISK
373 to boot an operating system with an UNDI network driver) it might be
374 desirable to keep the PXE stack in memory. If the option "keeppxe"
375 is given on the kernel command line, PXELINUX will keep the PXE and
376 UNDI stacks in memory. (If you don't know what this means, you
377 probably don't need it.)
380 ++++ PROBLEMS WITH YOUR PXE STACK ++++
382 There are a number of extremely broken PXE stacks in the field. The
383 gPXE project (formerly known as Etherboot) provides an open-source PXE
384 stack that works with a number of cards, and which can be loaded from
385 a CD-ROM, USB key, or floppy if desired.
387 Information on gPXE is available from:
389 http://www.etherboot.org/
391 ... and ready-to-use ROM or disk images from:
393 http://www.rom-o-matic.net/
395 Some cards, like may systems with the SiS 900, has a PXE stack which
396 works just barely well enough to load a single file, but doesn't
397 handle the more advanced items required by PXELINUX. If so, it is
398 possible to use the built-in PXE stack to load gPXE, which can then
401 http://www.etherboot.org/wiki/pxechaining
404 ++++ CURRENTLY KNOWN PROBLEMS ++++
406 The following problems are known with PXELINUX, so far:
408 + Requires a TFTP server which supports the "tsize" option.
409 + The error recovery routine doesn't work quite right. For right now,
410 it just does a hard reset - seems good enough.
411 + We should probably call the UDP receive function in the keyboard
412 entry loop, so that we answer ARP requests.
413 + Boot sectors/disk images are not supported yet.
415 If you have additional problems, please contact the Syslinux mailing
416 list (see syslinux.txt for the address.)