syslinux/pxelinux.doc

   1                                PXELINUX
   2
   3     A bootloader for Linux using the PXE network booting protocol
   4
   5                 Copyright (C) 1994-2004 H. Peter Anvin
   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 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.
  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.doc 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.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:
  42
  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
  47   01-88-99-aa-bb-cc-dd.
  48
  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.)
  53
  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"
  56   (in lower case).
  57
  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:
  61
  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
  72
  73   ... in that order.
  74
  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.
  78
  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
  82 this document.
  83
  84
  85     ++++ SETTING UP THE TFTP SERVER ++++
  86
  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:
  90
  91         http://www.kernel.org/pub/software/network/tftp/
  92         ftp://www.kernel.org/pub/software/network/tftp/
  93
  94 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
  95
  96 Another TFTP server which supports this is atftp by Jean-Pierre
  97 Lefebvre:
  98
  99         ftp://ftp.mamalinux.com/pub/atftp/
 100
 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):
 104
 105         http://tftpd32.jounin.net/
 106
 107
 108     ++++ SETTING UP THE DHCP SERVER ++++
 109
 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.
 117
 118 A sample DHCP setup, using the "conventional TFTP" configuration,
 119 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
 120 syntax:
 121
 122         allow booting;
 123         allow bootp;
 124
 125         # Standard configuration directives...
 126
 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>;
 132
 133         # Group the PXE bootable hosts together
 134         group {
 135                 # PXE-specific configuration directives...
 136                 next-server <TFTP server address>;
 137                 filename "/tftpboot/pxelinux.0";
 138
 139                 # You need an entry like this for every host
 140                 # unless you're using dynamic addresses
 141                 host <hostname> {
 142                         hardware ethernet <ethernet address>;
 143                         fixed-address <hostname>;
 144                 }
 145         }
 146
 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.
 151
 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:
 155
 156         http://www.kano.org.uk/projects/pxe/
 157
 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):
 161
 162         allow booting;
 163         allow bootp;
 164
 165         # Standard configuration directives...
 166
 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>;
 172
 173         # Group the PXE bootable hosts together
 174         group {
 175                 # PXE-specific configuration directives...
 176                 option dhcp-class-identifier "PXEClient";
 177                 next-server <pxe boot server address>;
 178
 179                 # You need an entry like this for every host
 180                 # unless you're using dynamic addresses
 181                 host <hostname> {
 182                         hardware ethernet <ethernet address>;
 183                         fixed-address <hostname>;
 184                 }
 185         }
 186
 187 Here, the boot file name is obtained from the PXE server.
 188
 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:
 193
 194         allow booting;
 195         allow bootp;
 196
 197         # Standard configuration directives...
 198
 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>;
 204
 205         # Group the PXE bootable hosts together
 206         group {
 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";
 212
 213                 # You need an entry like this for every host
 214                 # unless you're using dynamic addresses
 215                 host <hostname> {
 216                         hardware ethernet <ethernet address>;
 217                         fixed-address <hostname>;
 218                 }
 219         }
 220
 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.
 224
 225
 226     ++++ SPECIAL DHCP OPTIONS ++++
 227
 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:
 231
 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.
 235
 236 Option 209      pxelinux.configfile
 237         - Specifies the PXELINUX configuration file name.
 238
 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.
 244
 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.)
 249
 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:
 253
 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;
 259
 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.
 265
 266 Then, inside your PXELINUX-booting group or class (whereever you have
 267 the PXELINUX-related options, such as the filename option), you can
 268 add, for example:
 269
 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);
 276         }
 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";
 282
 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
 285 the TFTP server.
 286
 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.
 291
 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:
 295
 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);
 301         }
 302         option pxelinux.configfile =
 303                 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
 304         filename "/tftpboot/pxelinux.bin";
 305
 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".
 309
 310
 311     ++++ ALTERNATE TFTP SERVERS ++++
 312
 313 PXELINUX supports the following special pathname conventions:
 314
 315 ::filename
 316
 317         Suppresses the common filename prefix, i.e. passes the string
 318         "filename" unmodified to the server.
 319
 320 IP address::filename            (e.g. 192.0.2.1::filename)
 321
 322         Suppresses the common filename prefix, *and* sends a request
 323         to an alternate TFTP server.  Instead of an IP address, a
 324         DNS name can be used.  It will be assumed to be fully
 325         qualified if it contains dots; otherwise the local domain as
 326         reported by the DHCP server (option 15) will be added.
 327
 328 :: was chosen because it is unlikely to conflict with operating system
 329 usage.  However, if you happen to have an environment for which the
 330 special treatment of :: is a problem, please contact the SYSLINUX
 331 mailing list.
 332
 333
 334     ++++ SOME NOTES ++++
 335
 336 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
 337 rather, if it has not received any input for approximately five
 338 minutes after displaying an error message, it will reset the machine.
 339 This allows an unattended machine to recover in case it had bad enough
 340 luck of trying to boot at the same time the TFTP server goes down.
 341
 342 Lots of PXE stacks, especially old ones, have various problems of
 343 varying degrees of severity.  Please see:
 344
 345         http://syslinux.zytor.com/hardware.php
 346
 347 ... for a list of currently known hardware problems, with workarounds
 348 if known.
 349
 350
 351     ++++ KEEPING THE PXE STACK AROUND ++++
 352
 353 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
 354 the kernel.  In special circumstances (for example, when using MEMDISK
 355 to boot an operating system with an UNDI network driver) it might be
 356 desirable to keep the PXE stack in memory.  If the option "keeppxe"
 357 is given on the kernel command line, PXELINUX will keep the PXE and
 358 UNDI stacks in memory.  (If you don't know what this means, you
 359 probably don't need it.)
 360
 361
 362     ++++ CURRENTLY KNOWN PROBLEMS ++++
 363
 364 The following problems are known with PXELINUX, so far:
 365
 366 + Requires a TFTP server which supports the "tsize" option.
 367 + The error recovery routine doesn't work quite right.  For right now,
 368   it just does a hard reset - seems good enough.
 369 + We should probably call the UDP receive function in the keyboard
 370   entry loop, so that we answer ARP requests.
 371 + Boot sectors/disk images are not supported yet.
 372
 373 If you have additional problems, please contact the SYSLINUX mailing
 374 list (see syslinux.doc for the address.)