dmi: check both the AC and ID flags at the same time
[syslinux.git] / doc / pxelinux.txt
blob4dbb152eba976144e54fa41b0d8bbdd88bfa76d4
1                                PXELINUX
3     A bootloader for Linux using the PXE network booting protocol
5        Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
6        Copyright 2009-2011 Intel Corporation; author: H. Peter Anvin
8 This program is provided under the terms of the GNU General Public
9 License, version 2 or, at your option, any later version.  There is no
10 warranty, neither expressed nor implied, to the function of this
11 program.  Please see the included file COPYING for details.
13 This documentation file is slightly out of date; please check the NEWS
14 file for changes.
16 ----------------------------------------------------------------------
18 PXELINUX is a Syslinux derivative, for booting Linux off a network
19 server, using a network ROM conforming to the Intel PXE (Pre-Execution
20 Environment) specification.  PXELINUX is *not* a program that is
21 intended to be flashed or burned into a PROM on the network card; if
22 you want that, check out Etherboot (http://www.etherboot.org/).
23 Etherboot 5.4 or later can also be used to create a PXE-compliant boot
24 PROM for many network cards.
27     ++++ HOW TO CONFIGURE PXELINUX ++++
29 PXELINUX operates in many ways like SYSLINUX.  If you are not familiar
30 with SYSLINUX, read syslinux.txt first, since this documentation only
31 explains the differences.
33 On the TFTP server, create the directory "/tftpboot", and copy the
34 following files to it:
36         pxelinux.0              - from the Syslinux distribution
38         any kernel or initrd images you want to boot
40 Finally, create the directory "/tftpboot/pxelinux.cfg".  The
41 configuration file (equivalent of syslinux.cfg -- see syslinux.txt for
42 the options here) will live in this directory.  Because more than one
43 system may be booted from the same server, the configuration file name
44 depends on the IP address of the booting machine.  PXELINUX will
45 search for its config file on the boot server in the following way:
47   First, it will search for the config file using the client UUID, if
48   one is provided by the PXE stack (note, some BIOSes don't have a
49   valid UUID, and you might end up with something like all 1's.)  This is
50   in the standard UUID format using lower case hexadecimal digits, e.g.
51   b8945908-d6a6-41a9-611d-74a6ab80b83d.
53   Next, it will search for the config file using the hardware type
54   (using its ARP type code) and address, all in lower case hexadecimal
55   with dash separators; for example, for an Ethernet (ARP type 1)
56   with address 88:99:AA:BB:CC:DD it would search for the filename
57   01-88-99-aa-bb-cc-dd.
59   Next, it will search for the config file using its own IP address
60   in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B
61   (you can use the included progam "gethostip" to compute the
62   hexadecimal IP address for any host.)
64   If that file is not found, it will remove one hex digit and try
65   again.  Ultimately, it will try looking for a file named "default"
66   (in lower case).
68   As an example, if the boot file name is /mybootdir/pxelinux.0, the
69   UUID is b8945908-d6a6-41a9-611d-74a6ab80b83d, the Ethernet MAC
70   address is 88:99:AA:BB:CC:DD and the IP address 192.0.2.91, it will
71   try:
73         /mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d
74         /mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
75         /mybootdir/pxelinux.cfg/C000025B
76         /mybootdir/pxelinux.cfg/C000025
77         /mybootdir/pxelinux.cfg/C00002
78         /mybootdir/pxelinux.cfg/C0000
79         /mybootdir/pxelinux.cfg/C000
80         /mybootdir/pxelinux.cfg/C00
81         /mybootdir/pxelinux.cfg/C0
82         /mybootdir/pxelinux.cfg/C
83         /mybootdir/pxelinux.cfg/default
85   ... in that order.
87 Note that all filename references are relative to the directory
88 pxelinux.0 lives in.  PXELINUX generally requires that filenames
89 (including any relative path) are 127 characters or shorter in length.
91 Starting in release 3.20, PXELINUX will no longer apply a built-in
92 default if it cannot find any configuration file at all; instead it
93 will reboot after the timeout interval has expired.  This keeps a
94 machine from getting stuck indefinitely due to a boot server failure.
96 Starting in release 3.50, PXELINUX displays network information at
97 the boot prompt pressing <Ctrl-N>.
99 PXELINUX does not support MTFTP, and I have no plans of doing so, as
100 MTFTP is inherently broken for files more than 65535 packets (about
101 92 MB) in size.  It is of course possible to use MTFTP for the initial
102 boot, if you have such a setup.  MTFTP server setup is beyond the
103 scope of this document.
106     ++++ HTTP AND FTP DOWNLOADS ++++
108 Since version 5.10, native pxelinux.0 can support HTTP and FTP
109 transfers, greatly increasing load speed and allowing for standard
110 HTTP scripts to present PXELINUX's configuration file.  To use http or
111 ftp, use standard URL syntax as filename; use the DHCP options below
112 to transmit a suitable URL prefix to the client, or use the
113 "pxelinux-options" tool provided in the utils directory to program it
114 directly into the pxelinux.0 file.
117     ++++ SETTING UP THE TFTP SERVER ++++
119 For best results, use a TFTP server which supports the "tsize" TFTP
120 option (RFC 1784/RFC 2349).  The "tftp-hpa" TFTP server, which support
121 options, is available at:
123         http://www.kernel.org/pub/software/network/tftp/
124         ftp://www.kernel.org/pub/software/network/tftp/
126 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
128 Another TFTP server which supports this is atftp by Jean-Pierre
129 Lefebvre:
131         ftp://ftp.mamalinux.com/pub/atftp/
133 If your boot server is running Windows (and you can't fix that), try
134 tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
135 versions had a bug which made it incompatible with PXELINUX):
137         http://tftpd32.jounin.net/
140     ++++ SETTING UP THE DHCP SERVER ++++
142 The PXE protocol uses a very complex set of extensions to DHCP or
143 BOOTP.  However, most PXE implementations -- this includes all Intel
144 ones version 0.99n and later -- seem to be able to boot in a
145 "conventional" DHCP/TFTP configuration.  Assuming you don't have to
146 support any very old or otherwise severely broken clients, this is
147 probably the best configuration unless you already have a PXE boot
148 server on your network.
150 A sample DHCP setup, using the "conventional TFTP" configuration,
151 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
152 syntax:
154         allow booting;
155         allow bootp;
157         # Standard configuration directives...
159         option domain-name "<domain name>";
160         option subnet-mask <subnet mask>;
161         option broadcast-address <broadcast address>;
162         option domain-name-servers <dns servers>;
163         option routers <default router>;
165         # Group the PXE bootable hosts together
166         group {
167                 # PXE-specific configuration directives...
168                 next-server <TFTP server address>;
169                 filename "/tftpboot/pxelinux.0";
171                 # You need an entry like this for every host
172                 # unless you're using dynamic addresses
173                 host <hostname> {
174                         hardware ethernet <ethernet address>;
175                         fixed-address <hostname>;
176                 }
177         }
179 Note that if your particular TFTP daemon runs under chroot (tftp-hpa
180 will do this if you specify the -s (secure) option; this is highly
181 recommended), you almost certainly should not include the /tftpboot
182 prefix in the filename statement.
184 If this does not work for your configuration, you probably should set
185 up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
186 boot server is available at:
188         http://www.kano.org.uk/projects/pxe/
190 With such a boot server defined, your DHCP configuration should look
191 the same except for an "option dhcp-class-identifier" ("option
192 vendor-class-identifier" if you are using DHCP 3.0):
194         allow booting;
195         allow bootp;
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
206         group {
207                 # PXE-specific configuration directives...
208                 option dhcp-class-identifier "PXEClient";
209                 next-server <pxe boot server address>;
211                 # You need an entry like this for every host
212                 # unless you're using dynamic addresses
213                 host <hostname> {
214                         hardware ethernet <ethernet address>;
215                         fixed-address <hostname>;
216                 }
217         }
219 Here, the boot file name is obtained from the PXE server.
221 If the "conventional TFTP" configuration doesn't work on your clients,
222 and setting up a PXE boot server is not an option, you can attempt the
223 following configuration.  It has been known to boot some
224 configurations correctly; however, there are no guarantees:
226         allow booting;
227         allow bootp;
229         # Standard configuration directives...
231         option domain-name "<domain name>";
232         option subnet-mask <subnet mask>;
233         option broadcast-address <broadcast address>;
234         option domain-name-servers <dns servers>;
235         option routers <default router>;
237         # Group the PXE bootable hosts together
238         group {
239                 # PXE-specific configuration directives...
240                 option dhcp-class-identifier "PXEClient";
241                 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;
242                 next-server <TFTP server>;
243                 filename "/tftpboot/pxelinux.0";
245                 # You need an entry like this for every host
246                 # unless you're using dynamic addresses
247                 host <hostname> {
248                         hardware ethernet <ethernet address>;
249                         fixed-address <hostname>;
250                 }
251         }
253 Note that this *will not* boot some clients that *will* boot with the
254 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are
255 known to fall into this category.
258     ++++ SPECIAL DHCP OPTIONS ++++
260 PXELINUX (starting with version 1.62) supports the following
261 nonstandard DHCP options, which depending on your DHCP server you may
262 be able to use to customize the specific behaviour of PXELINUX.  See
263 RFC 5071 for some additional information about these options.
265 Option 208      pxelinux.magic
266         - Earlier versions of PXELINUX required this to be set to
267           F1:00:74:7E (241.0.116.126) for PXELINUX to
268           recognize any special DHCP options whatsoever.  As of
269           PXELINUX 3.55, this option is deprecated and is no longer
270           required.
272 Option 209      pxelinux.configfile
273         - Specifies the PXELINUX configuration file name.
275 Option 210      pxelinux.pathprefix
276         - Specifies the PXELINUX common path prefix, instead of
277           deriving it from the boot file name.  This almost certainly
278           needs to end in whatever character the TFTP server OS uses
279           as a pathname separator, e.g. slash (/) for Unix.
281 Option 211      pxelinux.reboottime
282         - Specifies, in seconds, the time to wait before reboot in the
283           event of TFTP failure.  0 means wait "forever" (in reality,
284           it waits approximately 136 years.)
286 ISC dhcp 3.0 supports a rather nice syntax for specifying custom
287 options; you can use the following syntax in dhcpd.conf if you are
288 running this version of dhcpd:
290         option space pxelinux;
291         option pxelinux.magic      code 208 = string;
292         option pxelinux.configfile code 209 = text;
293         option pxelinux.pathprefix code 210 = text;
294         option pxelinux.reboottime code 211 = unsigned integer 32;
296     NOTE: In earlier versions of PXELINUX, this would only work as a
297     "site-option-space".  Since PXELINUX 2.07, this will work both as a
298     "site-option-space" (unencapsulated) and as a "vendor-option-space"
299     (type 43 encapsulated.)  This may avoid messing with the
300     dhcp-parameter-request-list, as detailed below.
302 Then, inside your PXELINUX-booting group or class (whereever you have
303 the PXELINUX-related options, such as the filename option), you can
304 add, for example:
306         # Always include the following lines for all PXELINUX clients
307         site-option-space "pxelinux";
308         option pxelinux.magic f1:00:74:7e;
309         if exists dhcp-parameter-request-list {
310                 # Always send the PXELINUX options (specified in hexadecimal)
311                 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
312         }
313         # These lines should be customized to your setup
314         option pxelinux.configfile "configs/common";
315         option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
316         option pxelinux.reboottime 30;
317         filename "/tftpboot/pxelinux/pxelinux.bin";
319 Note that the configfile is relative to the pathprefix: this will look
320 for a config file called /tftpboot/pxelinux/files/configs/common on
321 the TFTP server.
323 The "option dhcp-parameter-request-list" statement forces the DHCP
324 server to send the PXELINUX-specific options, even though they are not
325 explicitly requested.  Since the DHCP request is done before PXELINUX
326 is loaded, the PXE client won't know to request them.
328 Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
329 For example, to use the hexadecimal form of the hardware address as
330 the configuration file name, you could do something like:
332         site-option-space "pxelinux";
333         option pxelinux.magic f1:00:74:7e;
334         if exists dhcp-parameter-request-list {
335                 # Always send the PXELINUX options (specified in hexadecimal)
336                 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
337         }
338         option pxelinux.configfile =
339                 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
340         filename "/tftpboot/pxelinux.bin";
342 If you used this from a client whose Ethernet address was
343 58:FA:84:CF:55:0E, this would look for a configuration file named
344 "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
347     ++++ HARDCODED OPTIONS ++++
349 Since version 3.83, the program "pxelinux-options" can be used to
350 hard-code DHCP options into the pxelinux.0 image file; this is
351 sometimes useful when the DHCP server is under different
352 administrative control.
355     ++++ ALTERNATE TFTP SERVERS AND URL SYNTAX ++++
357 PXELINUX supports the following special pathname conventions:
359 ::filename
361         Suppresses the common filename prefix, i.e. passes the string
362         "filename" unmodified to the server.
364 IP address::filename            (e.g. 192.0.2.1::filename)
366         Suppresses the common filename prefix, *and* sends a request
367         to an alternate TFTP server.  Instead of an IP address, a
368         DNS name can be used.  It will be assumed to be fully
369         qualified if it contains dots; otherwise the local domain as
370         reported by the DHCP server (option 15) will be added.
372 :: was chosen because it is unlikely to conflict with operating system
373 usage.  However, if you happen to have an environment for which the
374 special treatment of :: is a problem, please contact the Syslinux
375 mailing list.
377 Since version 4.00, PXELINUX also supports standard URL syntax.
380     ++++ SOME NOTES ++++
382 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
383 rather, if it has not received any input for approximately five
384 minutes after displaying an error message, it will reset the machine.
385 This allows an unattended machine to recover in case it had bad enough
386 luck of trying to boot at the same time the TFTP server goes down.
388 Lots of PXE stacks, especially old ones, have various problems of
389 varying degrees of severity.  Please see:
391         http://syslinux.zytor.com/hardware.php
393 ... for a list of currently known hardware problems, with workarounds
394 if known.
397     ++++ KEEPING THE PXE STACK AROUND ++++
399 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
400 the kernel.  In special circumstances (for example, when using MEMDISK
401 to boot an operating system with an UNDI network driver) it might be
402 desirable to keep the PXE stack in memory.  If the option "keeppxe"
403 is given on the kernel command line, PXELINUX will keep the PXE and
404 UNDI stacks in memory.  (If you don't know what this means, you
405 probably don't need it.)
408     ++++ PROBLEMS WITH YOUR PXE STACK ++++
410 There are a number of extremely broken PXE stacks in the field.  The
411 gPXE project (formerly known as Etherboot) provides an open-source PXE
412 stack that works with a number of cards, and which can be loaded from
413 a CD-ROM, USB key, or floppy if desired.
415 Information on gPXE is available from:
417         http://www.etherboot.org/
419 ... and ready-to-use ROM or disk images from:
421         http://www.rom-o-matic.net/
423 Some cards, like may systems with the SiS 900, has a PXE stack which
424 works just barely well enough to load a single file, but doesn't
425 handle the more advanced items required by PXELINUX.  If so, it is
426 possible to use the built-in PXE stack to load gPXE, which can then
427 load PXELINUX.  See:
429         http://www.etherboot.org/wiki/pxechaining
432     ++++ CURRENTLY KNOWN PROBLEMS ++++
434 The following problems are known with PXELINUX, so far:
436 + The error recovery routine doesn't work quite right.  For right now,
437   it just does a hard reset - seems good enough.
438 + We should probably call the UDP receive function in the keyboard
439   entry loop, so that we answer ARP requests.
440 + Boot sectors/disk images are not supported yet.
442 If you have additional problems, please contact the Syslinux mailing
443 list (see syslinux.txt for the address.)