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