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