doc/pxelinux.txt

   1                                PXELINUX
   2
   3     A bootloader for Linux using the PXE network booting protocol
   4
   5        Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
   6
   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.
  11
  12 ----------------------------------------------------------------------
  13
  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.
  21
  22
  23     ++++ HOW TO CONFIGURE PXELINUX ++++
  24
  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.
  28
  29 On the TFTP server, create the directory "/tftpboot", and copy the
  30 following files to it:
  31
  32         pxelinux.0              - from the Syslinux distribution
  33
  34         any kernel or initrd images you want to boot
  35
  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:
  42
  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.
  48
  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
  53   01-88-99-aa-bb-cc-dd.
  54
  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.)
  59
  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"
  62   (in lower case).
  63
  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
  67   try:
  68
  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
  80
  81   ... in that order.
  82
  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.
  86
  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.
  91
  92 Starting in release 3.50, PXELINUX displays network information at
  93 the boot prompt pressing <Ctrl-N>.
  94
  95 PXELINUX does not support MTFTP, and I have no plans of doing so, as
  96 MTFTP is inherently broken for files more than 65535 packets (about
  97 92 MB) in size.  It is of course possible to use MTFTP for the initial
  98 boot, if you have such a setup.  MTFTP server setup is beyond the
  99 scope of this document.
 100
 101
 102     ++++ gPXE-ENHANCED VARIANTS ++++
 103
 104 gPXE can be used to enhance PXELINUX's functionality to also include
 105 HTTP transfers, greatly increasing load speed and allowing for standard
 106 HTTP scripts to present PXELINUX's configuration file.  pxelinux.0 is
 107 the plain variant.  gpxelinux.0 (included as of 3.70) is gPXE's
 108 undionly.kkpxe, pxelinux.0 and a script to run pxelinux.0.  gpxelinuxk.0
 109 (included as of 4.04) is gPXE's undionly.kpxe, pxelinux.0 and a script
 110 to run pxelinux.0.  gpxelinuxk.0 should only be used with systems that
 111 are incompatible with gpxelinux.0 as it prevents certain functionality
 112 from working (LOCALBOOT with a type not equal to -1) and is incompatible
 113 with certain hardware, PXE stacks and network setups.
 114
 115
 116     ++++ SETTING UP THE TFTP SERVER ++++
 117
 118 PXELINUX currently requires that the boot server has a TFTP server
 119 which supports the "tsize" TFTP option (RFC 1784/RFC 2349).  The
 120 "tftp-hpa" TFTP server, which support options, is available at:
 121
 122         http://www.kernel.org/pub/software/network/tftp/
 123         ftp://www.kernel.org/pub/software/network/tftp/
 124
 125 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
 126
 127 Another TFTP server which supports this is atftp by Jean-Pierre
 128 Lefebvre:
 129
 130         ftp://ftp.mamalinux.com/pub/atftp/
 131
 132 If your boot server is running Windows (and you can't fix that), try
 133 tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
 134 versions had a bug which made it incompatible with PXELINUX):
 135
 136         http://tftpd32.jounin.net/
 137
 138
 139     ++++ SETTING UP THE DHCP SERVER ++++
 140
 141 The PXE protocol uses a very complex set of extensions to DHCP or
 142 BOOTP.  However, most PXE implementations -- this includes all Intel
 143 ones version 0.99n and later -- seem to be able to boot in a
 144 "conventional" DHCP/TFTP configuration.  Assuming you don't have to
 145 support any very old or otherwise severely broken clients, this is
 146 probably the best configuration unless you already have a PXE boot
 147 server on your network.
 148
 149 A sample DHCP setup, using the "conventional TFTP" configuration,
 150 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
 151 syntax:
 152
 153         allow booting;
 154         allow bootp;
 155
 156         # Standard configuration directives...
 157
 158         option domain-name "<domain name>";
 159         option subnet-mask <subnet mask>;
 160         option broadcast-address <broadcast address>;
 161         option domain-name-servers <dns servers>;
 162         option routers <default router>;
 163
 164         # Group the PXE bootable hosts together
 165         group {
 166                 # PXE-specific configuration directives...
 167                 next-server <TFTP server address>;
 168                 filename "/tftpboot/pxelinux.0";
 169
 170                 # You need an entry like this for every host
 171                 # unless you're using dynamic addresses
 172                 host <hostname> {
 173                         hardware ethernet <ethernet address>;
 174                         fixed-address <hostname>;
 175                 }
 176         }
 177
 178 Note that if your particular TFTP daemon runs under chroot (tftp-hpa
 179 will do this if you specify the -s (secure) option; this is highly
 180 recommended), you almost certainly should not include the /tftpboot
 181 prefix in the filename statement.
 182
 183 If this does not work for your configuration, you probably should set
 184 up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
 185 boot server is available at:
 186
 187         http://www.kano.org.uk/projects/pxe/
 188
 189 With such a boot server defined, your DHCP configuration should look
 190 the same except for an "option dhcp-class-identifier" ("option
 191 vendor-class-identifier" if you are using DHCP 3.0):
 192
 193         allow booting;
 194         allow bootp;
 195
 196         # Standard configuration directives...
 197
 198         option domain-name "<domain name>";
 199         option subnet-mask <subnet mask>;
 200         option broadcast-address <broadcast address>;
 201         option domain-name-servers <dns servers>;
 202         option routers <default router>;
 203
 204         # Group the PXE bootable hosts together
 205         group {
 206                 # PXE-specific configuration directives...
 207                 option dhcp-class-identifier "PXEClient";
 208                 next-server <pxe boot server address>;
 209
 210                 # You need an entry like this for every host
 211                 # unless you're using dynamic addresses
 212                 host <hostname> {
 213                         hardware ethernet <ethernet address>;
 214                         fixed-address <hostname>;
 215                 }
 216         }
 217
 218 Here, the boot file name is obtained from the PXE server.
 219
 220 If the "conventional TFTP" configuration doesn't work on your clients,
 221 and setting up a PXE boot server is not an option, you can attempt the
 222 following configuration.  It has been known to boot some
 223 configurations correctly; however, there are no guarantees:
 224
 225         allow booting;
 226         allow bootp;
 227
 228         # Standard configuration directives...
 229
 230         option domain-name "<domain name>";
 231         option subnet-mask <subnet mask>;
 232         option broadcast-address <broadcast address>;
 233         option domain-name-servers <dns servers>;
 234         option routers <default router>;
 235
 236         # Group the PXE bootable hosts together
 237         group {
 238                 # PXE-specific configuration directives...
 239                 option dhcp-class-identifier "PXEClient";
 240                 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;
 241                 next-server <TFTP server>;
 242                 filename "/tftpboot/pxelinux.0";
 243
 244                 # You need an entry like this for every host
 245                 # unless you're using dynamic addresses
 246                 host <hostname> {
 247                         hardware ethernet <ethernet address>;
 248                         fixed-address <hostname>;
 249                 }
 250         }
 251
 252 Note that this *will not* boot some clients that *will* boot with the
 253 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are
 254 known to fall into this category.
 255
 256
 257     ++++ SPECIAL DHCP OPTIONS ++++
 258
 259 PXELINUX (starting with version 1.62) supports the following
 260 nonstandard DHCP options, which depending on your DHCP server you may
 261 be able to use to customize the specific behaviour of PXELINUX.  See
 262 RFC 5071 for some additional information about these options.
 263
 264 Option 208      pxelinux.magic
 265         - Earlier versions of PXELINUX required this to be set to
 266           F1:00:74:7E (241.0.116.126) for PXELINUX to
 267           recognize any special DHCP options whatsoever.  As of
 268           PXELINUX 3.55, this option is deprecated and is no longer
 269           required.
 270
 271 Option 209      pxelinux.configfile
 272         - Specifies the PXELINUX configuration file name.
 273
 274 Option 210      pxelinux.pathprefix
 275         - Specifies the PXELINUX common path prefix, instead of
 276           deriving it from the boot file name.  This almost certainly
 277           needs to end in whatever character the TFTP server OS uses
 278           as a pathname separator, e.g. slash (/) for Unix.
 279
 280 Option 211      pxelinux.reboottime
 281         - Specifies, in seconds, the time to wait before reboot in the
 282           event of TFTP failure.  0 means wait "forever" (in reality,
 283           it waits approximately 136 years.)
 284
 285 ISC dhcp 3.0 supports a rather nice syntax for specifying custom
 286 options; you can use the following syntax in dhcpd.conf if you are
 287 running this version of dhcpd:
 288
 289         option space pxelinux;
 290         option pxelinux.magic      code 208 = string;
 291         option pxelinux.configfile code 209 = text;
 292         option pxelinux.pathprefix code 210 = text;
 293         option pxelinux.reboottime code 211 = unsigned integer 32;
 294
 295     NOTE: In earlier versions of PXELINUX, this would only work as a
 296     "site-option-space".  Since PXELINUX 2.07, this will work both as a
 297     "site-option-space" (unencapsulated) and as a "vendor-option-space"
 298     (type 43 encapsulated.)  This may avoid messing with the
 299     dhcp-parameter-request-list, as detailed below.
 300
 301 Then, inside your PXELINUX-booting group or class (whereever you have
 302 the PXELINUX-related options, such as the filename option), you can
 303 add, for example:
 304
 305         # Always include the following lines for all PXELINUX clients
 306         site-option-space "pxelinux";
 307         option pxelinux.magic f1:00:74:7e;
 308         if exists dhcp-parameter-request-list {
 309                 # Always send the PXELINUX options (specified in hexadecimal)
 310                 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
 311         }
 312         # These lines should be customized to your setup
 313         option pxelinux.configfile "configs/common";
 314         option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
 315         option pxelinux.reboottime 30;
 316         filename "/tftpboot/pxelinux/pxelinux.bin";
 317
 318 Note that the configfile is relative to the pathprefix: this will look
 319 for a config file called /tftpboot/pxelinux/files/configs/common on
 320 the TFTP server.
 321
 322 The "option dhcp-parameter-request-list" statement forces the DHCP
 323 server to send the PXELINUX-specific options, even though they are not
 324 explicitly requested.  Since the DHCP request is done before PXELINUX
 325 is loaded, the PXE client won't know to request them.
 326
 327 Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
 328 For example, to use the hexadecimal form of the hardware address as
 329 the configuration file name, you could do something like:
 330
 331         site-option-space "pxelinux";
 332         option pxelinux.magic f1:00:74:7e;
 333         if exists dhcp-parameter-request-list {
 334                 # Always send the PXELINUX options (specified in hexadecimal)
 335                 option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
 336         }
 337         option pxelinux.configfile =
 338                 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
 339         filename "/tftpboot/pxelinux.bin";
 340
 341 If you used this from a client whose Ethernet address was
 342 58:FA:84:CF:55:0E, this would look for a configuration file named
 343 "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
 344
 345
 346     ++++ ALTERNATE TFTP SERVERS ++++
 347
 348 PXELINUX supports the following special pathname conventions:
 349
 350 ::filename
 351
 352         Suppresses the common filename prefix, i.e. passes the string
 353         "filename" unmodified to the server.
 354
 355 IP address::filename            (e.g. 192.0.2.1::filename)
 356
 357         Suppresses the common filename prefix, *and* sends a request
 358         to an alternate TFTP server.  Instead of an IP address, a
 359         DNS name can be used.  It will be assumed to be fully
 360         qualified if it contains dots; otherwise the local domain as
 361         reported by the DHCP server (option 15) will be added.
 362
 363 :: was chosen because it is unlikely to conflict with operating system
 364 usage.  However, if you happen to have an environment for which the
 365 special treatment of :: is a problem, please contact the Syslinux
 366 mailing list.
 367
 368
 369     ++++ SOME NOTES ++++
 370
 371 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
 372 rather, if it has not received any input for approximately five
 373 minutes after displaying an error message, it will reset the machine.
 374 This allows an unattended machine to recover in case it had bad enough
 375 luck of trying to boot at the same time the TFTP server goes down.
 376
 377 Lots of PXE stacks, especially old ones, have various problems of
 378 varying degrees of severity.  Please see:
 379
 380         http://syslinux.zytor.com/hardware.php
 381
 382 ... for a list of currently known hardware problems, with workarounds
 383 if known.
 384
 385
 386     ++++ KEEPING THE PXE STACK AROUND ++++
 387
 388 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
 389 the kernel.  In special circumstances (for example, when using MEMDISK
 390 to boot an operating system with an UNDI network driver) it might be
 391 desirable to keep the PXE stack in memory.  If the option "keeppxe"
 392 is given on the kernel command line, PXELINUX will keep the PXE and
 393 UNDI stacks in memory.  (If you don't know what this means, you
 394 probably don't need it.)
 395
 396
 397     ++++ PROBLEMS WITH YOUR PXE STACK ++++
 398
 399 There are a number of extremely broken PXE stacks in the field.  The
 400 gPXE project (formerly known as Etherboot) provides an open-source PXE
 401 stack that works with a number of cards, and which can be loaded from
 402 a CD-ROM, USB key, or floppy if desired.
 403
 404 Information on gPXE is available from:
 405
 406         http://www.etherboot.org/
 407
 408 ... and ready-to-use ROM or disk images from:
 409
 410         http://www.rom-o-matic.net/
 411
 412 Some cards, like may systems with the SiS 900, has a PXE stack which
 413 works just barely well enough to load a single file, but doesn't
 414 handle the more advanced items required by PXELINUX.  If so, it is
 415 possible to use the built-in PXE stack to load gPXE, which can then
 416 load PXELINUX.  See:
 417
 418         http://www.etherboot.org/wiki/pxechaining
 419
 420
 421     ++++ CURRENTLY KNOWN PROBLEMS ++++
 422
 423 The following problems are known with PXELINUX, so far:
 424
 425 + The error recovery routine doesn't work quite right.  For right now,
 426   it just does a hard reset - seems good enough.
 427 + We should probably call the UDP receive function in the keyboard
 428   entry loop, so that we answer ARP requests.
 429 + Boot sectors/disk images are not supported yet.
 430
 431 If you have additional problems, please contact the Syslinux mailing
 432 list (see syslinux.txt for the address.)