3 A bootloader for Linux using the PXE network booting protocol
5 Copyright (C) 1994-2004 H. Peter Anvin
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 NILO (http://www.nilo.org/). NILO can also
19 be used to create a PXE-compliant boot PROM for most network cards
20 which have drivers for Linux or FreeBSD.
23 ++++ HOW TO CONFIGURE PXELINUX ++++
25 PXELINUX operates in many ways like SYSLINUX. If you are not familiar
26 with SYSLINUX, read syslinux.doc 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.doc 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 hardware type
44 (using its ARP type code) and address, all in lower case hexadecimal
45 with dash separators; for example, for an Ethernet (ARP type 1)
46 with address 88:99:AA:BB:CC:DD it would search for the filename
49 Next, it will search for the config file using its own IP address
50 in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B
51 (you can use the included progam "gethostip" to compute the
52 hexadecimal IP address for any host.)
54 If that file is not found, it will remove one hex digit and try
55 again. Ultimately, it will try looking for a file named "default"
58 As an example, if the boot file name is /mybootdir/pxelinux.0, the
59 Ethernet MAC address is 88:99:AA:BB:CC:DD and the IP address
60 192.0.2.91, it will try:
62 /mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
63 /mybootdir/pxelinux.cfg/C000025B
64 /mybootdir/pxelinux.cfg/C000025
65 /mybootdir/pxelinux.cfg/C00002
66 /mybootdir/pxelinux.cfg/C0000
67 /mybootdir/pxelinux.cfg/C000
68 /mybootdir/pxelinux.cfg/C00
69 /mybootdir/pxelinux.cfg/C0
70 /mybootdir/pxelinux.cfg/C
71 /mybootdir/pxelinux.cfg/default
75 Note that all filename references are relative to the directory
76 pxelinux.0 lives in. PXELINUX generally requires that filenames
77 (including any relative path) are 127 characters or shorter in length.
79 PXELINUX does not support MTFTP, and I have no immediate plans of
80 doing so. It is of course possible to use MTFTP for the initial boot,
81 if you have such a setup. MTFTP server setup is beyond the scope of
85 ++++ SETTING UP THE TFTP SERVER ++++
87 PXELINUX currently requires that the boot server has a TFTP server
88 which supports the "tsize" TFTP option (RFC 1784/RFC 2349). The
89 "tftp-hpa" TFTP server, which support options, is available at:
91 http://www.kernel.org/pub/software/network/tftp/
92 ftp://www.kernel.org/pub/software/network/tftp/
94 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
96 Another TFTP server which supports this is atftp by Jean-Pierre
99 ftp://ftp.mamalinux.com/pub/atftp/
101 If your boot server is running Windows (and you can't fix that), try
102 tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
103 versions had a bug which made it incompatible with PXELINUX):
105 http://tftpd32.jounin.net/
108 ++++ SETTING UP THE DHCP SERVER ++++
110 The PXE protocol uses a very complex set of extensions to DHCP or
111 BOOTP. However, most PXE implementations -- this includes all Intel
112 ones version 0.99n and later -- seem to be able to boot in a
113 "conventional" DHCP/TFTP configuration. Assuming you don't have to
114 support any very old or otherwise severely broken clients, this is
115 probably the best configuration unless you already have a PXE boot
116 server on your network.
118 A sample DHCP setup, using the "conventional TFTP" configuration,
119 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
125 # Standard configuration directives...
127 option domain-name "<domain name>";
128 option subnet-mask <subnet mask>;
129 option broadcast-address <broadcast address>;
130 option domain-name-servers <dns servers>;
131 option routers <default router>;
133 # Group the PXE bootable hosts together
135 # PXE-specific configuration directives...
136 next-server <TFTP server address>;
137 filename "/tftpboot/pxelinux.0";
139 # You need an entry like this for every host
140 # unless you're using dynamic addresses
142 hardware ethernet <ethernet address>;
143 fixed-address <hostname>;
147 Note that if your particular TFTP daemon runs under chroot (tftp-hpa
148 will do this if you specify the -s (secure) option; this is highly
149 recommended), you almost certainly should not include the /tftpboot
150 prefix in the filename statement.
152 If this does not work for your configuration, you probably should set
153 up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
154 boot server is available at:
156 http://www.kano.org.uk/projects/pxe/
158 With such a boot server defined, your DHCP configuration should look
159 the same except for an "option dhcp-class-identifier" ("option
160 vendor-class-identifier" if you are using DHCP 3.0):
165 # Standard configuration directives...
167 option domain-name "<domain name>";
168 option subnet-mask <subnet mask>;
169 option broadcast-address <broadcast address>;
170 option domain-name-servers <dns servers>;
171 option routers <default router>;
173 # Group the PXE bootable hosts together
175 # PXE-specific configuration directives...
176 option dhcp-class-identifier "PXEClient";
177 next-server <pxe boot server address>;
179 # You need an entry like this for every host
180 # unless you're using dynamic addresses
182 hardware ethernet <ethernet address>;
183 fixed-address <hostname>;
187 Here, the boot file name is obtained from the PXE server.
189 If the "conventional TFTP" configuration doesn't work on your clients,
190 and setting up a PXE boot server is not an option, you can attempt the
191 following configuration. It has been known to boot some
192 configurations correctly; however, there are no guarantees:
197 # Standard configuration directives...
199 option domain-name "<domain name>";
200 option subnet-mask <subnet mask>;
201 option broadcast-address <broadcast address>;
202 option domain-name-servers <dns servers>;
203 option routers <default router>;
205 # Group the PXE bootable hosts together
207 # PXE-specific configuration directives...
208 option dhcp-class-identifier "PXEClient";
209 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;
210 next-server <TFTP server>;
211 filename "/tftpboot/pxelinux.0";
213 # You need an entry like this for every host
214 # unless you're using dynamic addresses
216 hardware ethernet <ethernet address>;
217 fixed-address <hostname>;
221 Note that this *will not* boot some clients that *will* boot with the
222 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are
223 known to fall into this category.
226 ++++ SPECIAL DHCP OPTIONS ++++
228 PXELINUX (starting with version 1.62) supports the following
229 nonstandard DHCP options, which depending on your DHCP server you may
230 be able to use to customize the specific behaviour of PXELINUX:
232 Option 208 pxelinux.magic
233 - Must be set to F1:00:74:7E (241.0.116.126) for PXELINUX to
234 recognize any special DHCP options whatsoever.
236 Option 209 pxelinux.configfile
237 - Specifies the PXELINUX configuration file name.
239 Option 210 pxelinux.pathprefix
240 - Specifies the PXELINUX common path prefix, instead of
241 deriving it from the boot file name. This almost certainly
242 needs to end in whatever character the TFTP server OS uses
243 as a pathname separator, e.g. slash (/) for Unix.
245 Option 211 pxelinux.reboottime
246 - Specifies, in seconds, the time to wait before reboot in the
247 event of TFTP failure. 0 means wait "forever" (in reality,
248 it waits approximately 136 years.)
250 ISC dhcp 3.0 supports a rather nice syntax for specifying custom
251 options; you can use the following syntax in dhcpd.conf if you are
252 running this version of dhcpd:
254 option space pxelinux;
255 option pxelinux.magic code 208 = string;
256 option pxelinux.configfile code 209 = text;
257 option pxelinux.pathprefix code 210 = text;
258 option pxelinux.reboottime code 211 = unsigned integer 32;
260 NOTE: In earlier versions of PXELINUX, this would only work as a
261 "site-option-space". Since PXELINUX 2.07, this will work both as a
262 "site-option-space" (unencapsulated) and as a "vendor-option-space"
263 (type 43 encapsulated.) This may avoid messing with the
264 dhcp-parameter-request-list, as detailed below.
266 Then, inside your PXELINUX-booting group or class (whereever you have
267 the PXELINUX-related options, such as the filename option), you can
270 # Always include the following lines for all PXELINUX clients
271 site-option-space "pxelinux";
272 option pxelinux.magic f1:00:74:7e;
273 if exists dhcp-parameter-request-list {
274 # Always send the PXELINUX options (specified in hexadecimal)
275 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
277 # These lines should be customized to your setup
278 option pxelinux.configfile "configs/common";
279 option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
280 option pxelinux.reboottime 30;
281 filename "/tftpboot/pxelinux/pxelinux.bin";
283 Note that the configfile is relative to the pathprefix: this will look
284 for a config file called /tftpboot/pxelinux/files/configs/common on
287 The "option dhcp-parameter-request-list" statement forces the DHCP
288 server to send the PXELINUX-specific options, even though they are not
289 explicitly requested. Since the DHCP request is done before PXELINUX
290 is loaded, the PXE client won't know to request them.
292 Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
293 For example, to use the hexadecimal form of the hardware address as
294 the configuration file name, you could do something like:
296 site-option-space "pxelinux";
297 option pxelinux.magic f1:00:74:7e;
298 if exists dhcp-parameter-request-list {
299 # Always send the PXELINUX options (specified in hexadecimal)
300 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
302 option pxelinux.configfile =
303 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
304 filename "/tftpboot/pxelinux.bin";
306 If you used this from a client whose Ethernet address was
307 58:FA:84:CF:55:0E, this would look for a configuration file named
308 "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
313 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
314 rather, if it has not received any input for approximately five
315 minutes after displaying an error message, it will reset the machine.
316 This allows an unattended machine to recover in case it had bad enough
317 luck of trying to boot at the same time the TFTP server goes down.
319 Lots of PXE stacks, especially old ones, have various problems of
320 varying degrees of severity. Please see:
322 http://syslinux.zytor.com/hardware.php
324 ... for a list of currently known hardware problems, with workarounds
328 ++++ KEEPING THE PXE STACK AROUND ++++
330 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
331 the kernel. In special circumstances (for example, when using MEMDISK
332 to boot an operating system with an UNDI network driver) it might be
333 desirable to keep the PXE stack in memory. If the option "keeppxe"
334 is given on the kernel command line, PXELINUX will keep the PXE and
335 UNDI stacks in memory. (If you don't know what this means, you
336 probably don't need it.)
339 ++++ CURRENTLY KNOWN PROBLEMS ++++
341 The following problems are known with PXELINUX, so far:
343 + Requires a TFTP server which supports the "tsize" option.
344 + The error recovery routine doesn't work quite right. For right now,
345 it just does a hard reset - seems good enough.
346 + We should probably call the UDP receive function in the keyboard
347 entry loop, so that we answer ARP requests.
348 + Boot sectors/disk images are not supported yet.
350 If you have additional problems, please contact the SYSLINUX mailing
351 list (see syslinux.doc for the address.)