syslinux/txt/pxelinux.txt
<<
>>
Prefs
   1= pxelinux(1) =
   2:doctype: manpage
   3:revdate: 2013-06-12
   4:author: H. Peter Anvin
   5:author-email: hpa@zytor.com
   6:editor1: Gene Cumm
   7:editor1-email: gene.cumm@gmail.com
   8:editor1-revlast: 2013-06-12
   9
  10
  11== NAME ==
  12pxelinux - The Syslinux derivative PXELINUX for PXE network booting
  13
  14
  15== SYNOPSIS ==
  16[verse]
  17pxelinux.0
  18
  19
  20== DESCRIPTION ==
  21*PXELINUX* is a Syslinux derivative, for booting Linux off a network
  22server, using a network ROM conforming to the Intel PXE (Pre-Execution
  23Environment) specification.  *PXELINUX* is _*not*_ a program that is
  24intended to be flashed or burned into a PROM on the network card; if
  25you want that, check out Etherboot (http://www.etherboot.org/).
  26Etherboot 5.4 or later can also be used to create a PXE-compliant boot
  27PROM for many network cards.
  28//FIXME: Needs gPXE/iPXE note
  29
  30PXELINUX generally requires that full file pathnames are 127 characters or shorter in length.
  31//FIXME: why?  many tftpds limiting to 127+null?  outdated?
  32
  33
  34== CURRENT DIRECTORY ==
  35The initial current working directory is either as supplied by DHCP
  36option 210 (pxelinux.pathprefix), the hardcoded path-prefix or the
  37parent directory of the PXELINUX file, as indicated by DHCP fields
  38'sname' and 'file' (sname="192.168.2.3" and file="boot/pxelinux.0"
  39results in "tftp://192.168.2.3/boot/", "192.168.2.3::boot/" in older
  40PXELINUX format) with precedence specified under *OPTIONS*.
  41
  42All unqualified filenames are relative to the current directory.
  43
  44
  45== CONFIGURATION ==
  46See *syslinux.cfg*(5) for the format of the contents.
  47
  48Because more than one system may be booted from the same server, the
  49configuration file name depends on the IP address of the booting
  50machine.  After attempting the file as specified in the DHCP or
  51hardcoded options, PXELINUX will probe the following paths, prefixed
  52with "pxelinux.cfg/", under the initial current working directory:
  53
  54- The client UUID if provided by the PXE stack (note, some BIOSes don't
  55have a valid UUID, and you might end up with something like all 1's.) 
  56This is in the standard UUID format using lower case hexadecimal digits,
  57e.g. b8945908-d6a6-41a9-611d-74a6ab80b83d.
  58
  59- The hardware type (using its ARP type code) and address, all in lower
  60case hexadecimal with dash separators; for example, for an Ethernet (ARP
  61type 1) with address 88:99:AA:BB:CC:DD it would search for the filename
  6201-88-99-aa-bb-cc-dd.
  63
  64- The client's IPv4 address in upper-case hexidecimal (ie 192.168.2.91
  65-> C0A8025B; you can use the included progam "gethostip" to compute the
  66hexadecimal IP address for any host.) followed by removing characters,
  67one at a time, from the end.
  68
  69- "default"
  70
  71Starting in release 3.20, if PXELINUX can not find a configuration file,
  72it will reboot after the timeout interval has expired.  This keeps a
  73machine from getting stuck indefinitely due to a boot server failure.
  74
  75
  76== OPTIONS ==
  77*PXELINUX* (starting with version 1.62) supports the following
  78nonstandard DHCP options, which depending on your DHCP server you may be
  79able to use to customize the specific behaviour of *PXELINUX*.  See RFC
  805071 for some additional information about these options. Options for
  81*PXELINUX* can be specified by DHCP options or hardcoded into the
  82binary.
  83
  84=== Option Priority ===
  85Hardcoded after-options are applied after DHCP options (and overrride)
  86while hardcoded before-options are applied prior to DHCP options and
  87default behavior takes the lowest priority.
  88
  89=== DHCP options ===
  90*Option 208* (pxelinux.magic)::
  91Earlier versions of *PXELINUX* required this to be set to F1:00:74:7E
  92(241.0.116.126) for *PXELINUX* to recognize any special DHCP options
  93whatsoever.  As of *PXELINUX* 3.55, this option is deprecated and is no
  94longer required.
  95
  96*Option 209* (pxelinux.configfile)::
  97Specifies the initial *PXELINUX* configuration file name which may be
  98qualified or unqualified.
  99
 100*Option 210* (pxelinux.pathprefix)::
 101Specifies the *PXELINUX* common path prefix, instead of deriving it from
 102the boot file name.  This almost certainly needs to end in whatever
 103character the TFTP server OS uses as a pathname separator, e.g. slash
 104(/) for Unix.
 105
 106*Option 211* (pxelinux.reboottime)::
 107Specifies, in seconds, the time to wait before reboot in the event of
 108TFTP failure.  0 means wait "forever" (in reality, it waits
 109approximately 136 years.)
 110
 111=== Hardcoded options ===
 112Since version 3.83, the program "pxelinux-options" can be used to
 113hard-code DHCP options into the pxelinux.0 image file; this is
 114sometimes useful when the DHCP server is under different
 115administrative control.  Hardcoded options 
 116
 117      6 => 'domain-name-servers',
 118     15 => 'domain-name',
 119     54 => 'next-server',
 120    209 => 'config-file',
 121    210 => 'path-prefix',
 122    211 => 'reboottime'
 123
 124
 125== HTTP/FTP ==
 126Since version 5.10, a special PXELINUX binary, lpxelinux.0, natively
 127supports HTTP and FTP transfers, greatly increasing load speed and
 128allowing for standard HTTP scripts to present PXELINUX's configuration
 129file.  To use http or ftp, use standard URL syntax as filename; use the
 130DHCP options below to transmit a suitable URL prefix to the client, or
 131use the "pxelinux-options" tool provided in the utils directory to
 132program it directly into the lpxelinux.0 file.
 133
 134
 135== FILENAME SYNTAX ==
 136//FIXME
 137PXELINUX supports the following special pathname conventions:
 138
 139*::filename*::
 140Suppresses the common filename prefix, i.e. passes the string "filename"
 141unmodified to the server.
 142
 143*IP address::filename* (e.g. 192.168.2.3::filename)::
 144Suppresses the common filename prefix, *and* sends a request to an alternate TFTP server.  Instead of an IP address, a DNS name can be used.  It will be assumed to be fully qualified if it contains dots; otherwise the local domain as reported by the DHCP server (option 15) will be added.
 145
 146:: was chosen because it is unlikely to conflict with operating system
 147usage.  However, if you happen to have an environment for which the
 148special treatment of :: is a problem, please contact the Syslinux
 149mailing list.
 150
 151Since version 4.00, PXELINUX also supports standard URL syntax.
 152
 153
 154== KEEPPXE ==
 155Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
 156the kernel.  In special circumstances (for example, when using MEMDISK
 157to boot an operating system with an UNDI network driver) it might be
 158desirable to keep the PXE stack in memory.  If the option "keeppxe"
 159is given on the kernel command line, PXELINUX will keep the PXE and
 160UNDI stacks in memory.  (If you don't know what this means, you
 161probably don't need it.)
 162
 163
 164== EXAMPLES ==
 165
 166=== Configuration filename ===
 167For DHCP siaddr 192.168.2.3, file 'mybootdir/pxelinux.0', client UUID
 168b8945908-d6a6-41a9-611d-74a6ab80b83d, Ethernet MAC address
 16988:99:AA:BB:CC:DD and IPv4 address 192.168.2.91, the following files in
 170this order will be attempted (after config-file options):
 171
 172        mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d
 173        mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
 174        mybootdir/pxelinux.cfg/C0A8025B
 175        mybootdir/pxelinux.cfg/C0A8025
 176        mybootdir/pxelinux.cfg/C0A802
 177        mybootdir/pxelinux.cfg/C0A80
 178        mybootdir/pxelinux.cfg/C0A8
 179        mybootdir/pxelinux.cfg/C0A
 180        mybootdir/pxelinux.cfg/C0
 181        mybootdir/pxelinux.cfg/C
 182        mybootdir/pxelinux.cfg/default
 183
 184
 185=== TFTP servers ===
 186For best results, use a TFTP server which supports the "tsize" TFTP
 187option (RFC 1784/RFC 2349).  The "tftp-hpa" TFTP server, which support
 188options, is available at:
 189
 190        http://www.kernel.org/pub/software/network/tftp/
 191        ftp://www.kernel.org/pub/software/network/tftp/
 192
 193and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
 194
 195Another TFTP server which supports this is atftp by Jean-Pierre
 196Lefebvre:
 197
 198        ftp://ftp.mamalinux.com/pub/atftp/
 199
 200If your boot server is running Windows (and you can't fix that), try
 201tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
 202versions had a bug which made it incompatible with PXELINUX):
 203
 204        http://tftpd32.jounin.net/
 205
 206
 207=== DHCP config: Simple ===
 208The PXE protocol uses a very complex set of extensions to DHCP or
 209BOOTP.  However, most PXE implementations -- this includes all Intel
 210ones version 0.99n and later -- seem to be able to boot in a
 211"conventional" DHCP/TFTP configuration.  Assuming you don't have to
 212support any very old or otherwise severely broken clients, this is
 213probably the best configuration unless you already have a PXE boot
 214server on your network.
 215
 216A sample DHCP setup, using the "conventional TFTP" configuration,
 217would look something like the following, using ISC dhcp 2.0 dhcpd.conf
 218syntax:
 219
 220-----
 221allow booting;
 222allow bootp;
 223
 224# Standard configuration directives...
 225
 226option domain-name "<domain name>";
 227option subnet-mask <subnet mask>;
 228option broadcast-address <broadcast address>;
 229option domain-name-servers <dns servers>;
 230option routers <default router>;
 231
 232# Group the PXE bootable hosts together
 233group {
 234        # PXE-specific configuration directives...
 235        next-server <TFTP server address>;
 236        filename "/tftpboot/pxelinux.0";
 237
 238        # You need an entry like this for every host
 239        # unless you're using dynamic addresses
 240        host <hostname> {
 241                hardware ethernet <ethernet address>;
 242                fixed-address <hostname>;
 243        }
 244}
 245-----
 246
 247Note that if your particular TFTP daemon runs under chroot (tftp-hpa
 248will do this if you specify the -s (secure) option; this is highly
 249recommended), you almost certainly should not include the /tftpboot
 250prefix in the filename statement.
 251
 252
 253=== DHCP Config: PXE-1 ===
 254If the simple config does not work for your environment, you probably
 255should set up a "PXE boot server" on port 4011 of your TFTP server; a
 256free PXE boot server is available at:
 257
 258http://www.kano.org.uk/projects/pxe/
 259
 260With such a boot server defined, your DHCP configuration should look
 261the same except for an "option dhcp-class-identifier" ("option
 262vendor-class-identifier" if you are using DHCP 3.0):
 263
 264----
 265allow booting;
 266allow bootp;
 267
 268# Standard configuration directives...
 269
 270option domain-name "<domain name>";
 271option subnet-mask <subnet mask>;
 272option broadcast-address <broadcast address>;
 273option domain-name-servers <dns servers>;
 274option routers <default router>;
 275
 276# Group the PXE bootable hosts together
 277group {
 278        # PXE-specific configuration directives...
 279        option dhcp-class-identifier "PXEClient";
 280        next-server <pxe boot server address>;
 281
 282        # You need an entry like this for every host
 283        # unless you're using dynamic addresses
 284        host <hostname> {
 285                hardware ethernet <ethernet address>;
 286                fixed-address <hostname>;
 287        }
 288}
 289----
 290
 291Here, the boot file name is obtained from the PXE server.
 292
 293
 294=== DHCP Config: Encapsulated ===
 295If the "conventional TFTP" configuration doesn't work on your clients,
 296and setting up a PXE boot server is not an option, you can attempt the
 297following configuration.  It has been known to boot some
 298configurations correctly; however, there are no guarantees:
 299----
 300allow booting;
 301allow bootp;
 302
 303# Standard configuration directives...
 304
 305option domain-name "<domain name>";
 306option subnet-mask <subnet mask>;
 307option broadcast-address <broadcast address>;
 308option domain-name-servers <dns servers>;
 309option routers <default router>;
 310
 311# Group the PXE bootable hosts together
 312group {
 313        # PXE-specific configuration directives...
 314        option dhcp-class-identifier "PXEClient";
 315        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;
 316        next-server <TFTP server>;
 317        filename "/tftpboot/pxelinux.0";
 318
 319        # You need an entry like this for every host
 320        # unless you're using dynamic addresses
 321        host <hostname> {
 322                hardware ethernet <ethernet address>;
 323                fixed-address <hostname>;
 324        }
 325}
 326----
 327Note that this *will not* boot some clients that *will* boot with the
 328"conventional TFTP" configuration; Intel Boot Client 3.0 and later are
 329known to fall into this category.
 330
 331
 332=== DHCP Config: ISC dhcpd options ===
 333ISC dhcp 3.0 supports a rather nice syntax for specifying custom
 334options; you can use the following syntax in dhcpd.conf if you are
 335running this version of dhcpd:
 336----
 337option space pxelinux;
 338option pxelinux.magic      code 208 = string;
 339option pxelinux.configfile code 209 = text;
 340option pxelinux.pathprefix code 210 = text;
 341option pxelinux.reboottime code 211 = unsigned integer 32;
 342----
 343    NOTE: In earlier versions of PXELINUX, this would only work as a
 344    "site-option-space".  Since PXELINUX 2.07, this will work both as a
 345    "site-option-space" (unencapsulated) and as a "vendor-option-space"
 346    (type 43 encapsulated.)  This may avoid messing with the
 347    dhcp-parameter-request-list, as detailed below.
 348
 349Then, inside your PXELINUX-booting group or class (whereever you have
 350the PXELINUX-related options, such as the filename option), you can
 351add, for example:
 352----
 353# Always include the following lines for all PXELINUX clients
 354site-option-space "pxelinux";
 355option pxelinux.magic f1:00:74:7e;
 356if exists dhcp-parameter-request-list {
 357        # Always send the PXELINUX options (specified in hexadecimal)
 358        option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
 359}
 360# These lines should be customized to your setup
 361option pxelinux.configfile "configs/common";
 362option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
 363option pxelinux.reboottime 30;
 364filename "/tftpboot/pxelinux/pxelinux.bin";
 365----
 366Note that the configfile is relative to the pathprefix: this will look
 367for a config file called /tftpboot/pxelinux/files/configs/common on
 368the TFTP server.
 369
 370The "option dhcp-parameter-request-list" statement forces the DHCP
 371server to send the PXELINUX-specific options, even though they are not
 372explicitly requested.  Since the DHCP request is done before PXELINUX
 373is loaded, the PXE client won't know to request them.
 374
 375Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
 376For example, to use the hexadecimal form of the hardware address as
 377the configuration file name, you could do something like:
 378----
 379site-option-space "pxelinux";
 380option pxelinux.magic f1:00:74:7e;
 381if exists dhcp-parameter-request-list {
 382        # Always send the PXELINUX options (specified in hexadecimal)
 383        option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
 384}
 385option pxelinux.configfile =
 386        concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
 387filename "/tftpboot/pxelinux.bin";
 388----
 389If you used this from a client whose Ethernet address was
 39058:FA:84:CF:55:0E, this would look for a configuration file named
 391"/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
 392
 393
 394== KNOWN ISSUES ==
 395The following problems are known with PXELINUX, so far:
 396
 397- The error recovery routine doesn't work quite right.  For right now,
 398  it just does a hard reset - seems good enough.
 399- We should probably call the UDP receive function in the keyboard
 400  entry loop, so that we answer ARP requests.
 401- Boot sectors/disk images are not supported yet.
 402
 403If you have additional problems, please contact the Syslinux mailing
 404list (see syslinux.txt for the address.)
 405
 406=== Broken PXE stacks ===
 407Lots of PXE stacks, especially old ones, have various problems of
 408varying degrees of severity.  Please see:
 409
 410        http://syslinux.zytor.com/hardware.php
 411
 412... for a list of currently known hardware problems, with workarounds
 413if known.
 414
 415There are a number of extremely broken PXE stacks in the field.  The
 416gPXE project (formerly known as Etherboot) provides an open-source PXE
 417stack that works with a number of cards, and which can be loaded from
 418a CD-ROM, USB key, or floppy if desired.
 419
 420Information on gPXE is available from:
 421
 422        http://www.etherboot.org/
 423
 424... and ready-to-use ROM or disk images from:
 425
 426        http://www.rom-o-matic.net/
 427
 428Some cards, like may systems with the SiS 900, has a PXE stack which
 429works just barely well enough to load a single file, but doesn't
 430handle the more advanced items required by PXELINUX.  If so, it is
 431possible to use the built-in PXE stack to load gPXE, which can then
 432load PXELINUX.  See:
 433
 434        http://www.etherboot.org/wiki/pxechaining
 435
 436
 437== NOTES ==
 438=== MTFTP ===
 439PXELINUX does not support MTFTP, and there are no plans of doing so, as
 440MTFTP is inherently broken for files more than 65535 packets (about 92
 441MB) in size.  It is of course possible to use MTFTP for the initial
 442boot, if you have such a setup.  MTFTP server setup is beyond the scope
 443of this document.
 444
 445=== Error Recovery ===
 446If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
 447rather, if it has not received any input for approximately five
 448minutes after displaying an error message, it will reset the machine.
 449This allows an unattended machine to recover in case it had bad enough
 450luck of trying to boot at the same time the TFTP server goes down.
 451
 452
 453== SEE ALSO ==
 454*syslinux.cfg*(5), *syslinux-cli*(1), *lilo*(8), *keytab-lilo.pl*(8),
 455*fdisk*(8), *mkfs*(8), *superformat*(1).
 456
 457
 458== AUTHOR ==
 459This AsciiDoc derived document is a modified version of the original
 460*SYSLINUX* documentation by {author} <{author-email}>.  The conversion
 461to an AsciiDoc was made by {editor1} <{editor1-email}>
 462