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 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.
  97
  98
  99     ++++ SETTING UP THE TFTP SERVER ++++
 100
 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:
 104
 105         http://www.kernel.org/pub/software/network/tftp/
 106         ftp://www.kernel.org/pub/software/network/tftp/
 107
 108 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
 109
 110 Another TFTP server which supports this is atftp by Jean-Pierre
 111 Lefebvre:
 112
 113         ftp://ftp.mamalinux.com/pub/atftp/
 114
 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):
 118
 119         http://tftpd32.jounin.net/
 120
 121
 122     ++++ SETTING UP THE DHCP SERVER ++++
 123
 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.
 131
 132 A sample DHCP setup, using the "conventional TFTP" configuration,
 133 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
 134 syntax:
 135
 136         allow booting;
 137         allow bootp;
 138
 139         # Standard configuration directives...
 140
 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>;
 146
 147         # Group the PXE bootable hosts together
 148         group {
 149                 # PXE-specific configuration directives...
 150                 next-server <TFTP server address>;
 151                 filename "/tftpboot/pxelinux.0";
 152
 153                 # You need an entry like this for every host
 154                 # unless you're using dynamic addresses
 155                 host <hostname> {
 156                         hardware ethernet <ethernet address>;
 157                         fixed-address <hostname>;
 158                 }
 159         }
 160
 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.
 165
 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:
 169
 170         http://www.kano.org.uk/projects/pxe/
 171
 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):
 175
 176         allow booting;
 177         allow bootp;
 178
 179         # Standard configuration directives...
 180
 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>;
 186
 187         # Group the PXE bootable hosts together
 188         group {
 189                 # PXE-specific configuration directives...
 190                 option dhcp-class-identifier "PXEClient";
 191                 next-server <pxe boot server address>;
 192
 193                 # You need an entry like this for every host
 194                 # unless you're using dynamic addresses
 195                 host <hostname> {
 196                         hardware ethernet <ethernet address>;
 197                         fixed-address <hostname>;
 198                 }
 199         }
 200
 201 Here, the boot file name is obtained from the PXE server.
 202
 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:
 207
 208         allow booting;
 209         allow bootp;
 210
 211         # Standard configuration directives...
 212
 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>;
 218
 219         # Group the PXE bootable hosts together
 220         group {
 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";
 226
 227                 # You need an entry like this for every host
 228                 # unless you're using dynamic addresses
 229                 host <hostname> {
 230                         hardware ethernet <ethernet address>;
 231                         fixed-address <hostname>;
 232                 }
 233         }
 234
 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.
 238
 239
 240     ++++ SPECIAL DHCP OPTIONS ++++
 241
 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.
 246
 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
 252           required.
 253
 254 Option 209      pxelinux.configfile
 255         - Specifies the PXELINUX configuration file name.
 256
 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.
 262
 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.)
 267
 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:
 271
 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;
 277
 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.
 283
 284 Then, inside your PXELINUX-booting group or class (whereever you have
 285 the PXELINUX-related options, such as the filename option), you can
 286 add, for example:
 287
 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);
 294         }
 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";
 300
 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
 303 the TFTP server.
 304
 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.
 309
 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:
 313
 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);
 319         }
 320         option pxelinux.configfile =
 321                 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
 322         filename "/tftpboot/pxelinux.bin";
 323
 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".
 327
 328
 329     ++++ ALTERNATE TFTP SERVERS ++++
 330
 331 PXELINUX supports the following special pathname conventions:
 332
 333 ::filename
 334
 335         Suppresses the common filename prefix, i.e. passes the string
 336         "filename" unmodified to the server.
 337
 338 IP address::filename            (e.g. 192.0.2.1::filename)
 339
 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.
 345
 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
 349 mailing list.
 350
 351
 352     ++++ SOME NOTES ++++
 353
 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.
 359
 360 Lots of PXE stacks, especially old ones, have various problems of
 361 varying degrees of severity.  Please see:
 362
 363         http://syslinux.zytor.com/hardware.php
 364
 365 ... for a list of currently known hardware problems, with workarounds
 366 if known.
 367
 368
 369     ++++ KEEPING THE PXE STACK AROUND ++++
 370
 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.)
 378
 379
 380     ++++ PROBLEMS WITH YOUR PXE STACK ++++
 381
 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.
 386
 387 Information on gPXE is available from:
 388
 389         http://www.etherboot.org/
 390
 391 ... and ready-to-use ROM or disk images from:
 392
 393         http://www.rom-o-matic.net/
 394
 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
 399 load PXELINUX.  See:
 400
 401         http://www.etherboot.org/wiki/pxechaining
 402
 403
 404     ++++ CURRENTLY KNOWN PROBLEMS ++++
 405
 406 The following problems are known with PXELINUX, so far:
 407
 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.
 414
 415 If you have additional problems, please contact the SYSLINUX mailing
 416 list (see syslinux.txt for the address.)