1 = pxelinux(1) = 2 :doctype: manpage 3 :revdate: 2013-06-12 4 :author: H. Peter Anvin 5 :author-email: hpa (a] zytor.com 6 :editor1: Gene Cumm 7 :editor1-email: gene.cumm (a] gmail.com 8 :editor1-revlast: 2013-06-12 9 10 11 == NAME == 12 pxelinux - The Syslinux derivative PXELINUX for PXE network booting 13 14 15 == SYNOPSIS == 16 [verse] 17 pxelinux.0 18 19 20 == DESCRIPTION == 21 *PXELINUX* is a Syslinux derivative, for booting Linux off a network 22 server, using a network ROM conforming to the Intel PXE (Pre-Execution 23 Environment) specification. *PXELINUX* is _*not*_ a program that is 24 intended to be flashed or burned into a PROM on the network card; if 25 you want that, check out Etherboot (http://www.etherboot.org/). 26 Etherboot 5.4 or later can also be used to create a PXE-compliant boot 27 PROM for many network cards. 28 //FIXME: Needs gPXE/iPXE note 29 30 PXELINUX 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 == 35 The initial current working directory is either as supplied by DHCP 36 option 210 (pxelinux.pathprefix), the hardcoded path-prefix or the 37 parent directory of the PXELINUX file, as indicated by DHCP fields 38 'sname' and 'file' (sname="192.168.2.3" and file="boot/pxelinux.0" 39 results in "tftp://192.168.2.3/boot/", "192.168.2.3::boot/" in older 40 PXELINUX format) with precedence specified under *OPTIONS*. 41 42 All unqualified filenames are relative to the current directory. 43 44 45 == CONFIGURATION == 46 See *syslinux.cfg*(5) for the format of the contents. 47 48 Because more than one system may be booted from the same server, the 49 configuration file name depends on the IP address of the booting 50 machine. After attempting the file as specified in the DHCP or 51 hardcoded options, PXELINUX will probe the following paths, prefixed 52 with "pxelinux.cfg/", under the initial current working directory: 53 54 - The client UUID if provided by the PXE stack (note, some BIOSes don't 55 have a valid UUID, and you might end up with something like all 1's.) 56 This is in the standard UUID format using lower case hexadecimal digits, 57 e.g. b8945908-d6a6-41a9-611d-74a6ab80b83d. 58 59 - The hardware type (using its ARP type code) and address, all in lower 60 case hexadecimal with dash separators; for example, for an Ethernet (ARP 61 type 1) with address 88:99:AA:BB:CC:DD it would search for the filename 62 01-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 66 hexadecimal IP address for any host.) followed by removing characters, 67 one at a time, from the end. 68 69 - "default" 70 71 Starting in release 3.20, if PXELINUX can not find a configuration file, 72 it will reboot after the timeout interval has expired. This keeps a 73 machine from getting stuck indefinitely due to a boot server failure. 74 75 76 == OPTIONS == 77 *PXELINUX* (starting with version 1.62) supports the following 78 nonstandard DHCP options, which depending on your DHCP server you may be 79 able to use to customize the specific behaviour of *PXELINUX*. See RFC 80 5071 for some additional information about these options. Options for 81 *PXELINUX* can be specified by DHCP options or hardcoded into the 82 binary. 83 84 === Option Priority === 85 Hardcoded after-options are applied after DHCP options (and overrride) 86 while hardcoded before-options are applied prior to DHCP options and 87 default behavior takes the lowest priority. 88 89 === DHCP options === 90 *Option 208* (pxelinux.magic):: 91 Earlier 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 93 whatsoever. As of *PXELINUX* 3.55, this option is deprecated and is no 94 longer required. 95 96 *Option 209* (pxelinux.configfile):: 97 Specifies the initial *PXELINUX* configuration file name which may be 98 qualified or unqualified. 99 100 *Option 210* (pxelinux.pathprefix):: 101 Specifies the *PXELINUX* common path prefix, instead of deriving it from 102 the boot file name. This almost certainly needs to end in whatever 103 character the TFTP server OS uses as a pathname separator, e.g. slash 104 (/) for Unix. 105 106 *Option 211* (pxelinux.reboottime):: 107 Specifies, in seconds, the time to wait before reboot in the event of 108 TFTP failure. 0 means wait "forever" (in reality, it waits 109 approximately 136 years.) 110 111 === Hardcoded options === 112 Since version 3.83, the program "pxelinux-options" can be used to 113 hard-code DHCP options into the pxelinux.0 image file; this is 114 sometimes useful when the DHCP server is under different 115 administrative 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 == 126 Since version 5.10, a special PXELINUX binary, lpxelinux.0, natively 127 supports HTTP and FTP transfers, greatly increasing load speed and 128 allowing for standard HTTP scripts to present PXELINUX's configuration 129 file. To use http or ftp, use standard URL syntax as filename; use the 130 DHCP options below to transmit a suitable URL prefix to the client, or 131 use the "pxelinux-options" tool provided in the utils directory to 132 program it directly into the lpxelinux.0 file. 133 134 135 == FILENAME SYNTAX == 136 //FIXME 137 PXELINUX supports the following special pathname conventions: 138 139 *::filename*:: 140 Suppresses the common filename prefix, i.e. passes the string "filename" 141 unmodified to the server. 142 143 *IP address::filename* (e.g. 192.168.2.3::filename):: 144 Suppresses 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 147 usage. However, if you happen to have an environment for which the 148 special treatment of :: is a problem, please contact the Syslinux 149 mailing list. 150 151 Since version 4.00, PXELINUX also supports standard URL syntax. 152 153 154 == KEEPPXE == 155 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking 156 the kernel. In special circumstances (for example, when using MEMDISK 157 to boot an operating system with an UNDI network driver) it might be 158 desirable to keep the PXE stack in memory. If the option "keeppxe" 159 is given on the kernel command line, PXELINUX will keep the PXE and 160 UNDI stacks in memory. (If you don't know what this means, you 161 probably don't need it.) 162 163 164 == EXAMPLES == 165 166 === Configuration filename === 167 For DHCP siaddr 192.168.2.3, file 'mybootdir/pxelinux.0', client UUID 168 b8945908-d6a6-41a9-611d-74a6ab80b83d, Ethernet MAC address 169 88:99:AA:BB:CC:DD and IPv4 address 192.168.2.91, the following files in 170 this 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 === 186 For best results, use a TFTP server which supports the "tsize" TFTP 187 option (RFC 1784/RFC 2349). The "tftp-hpa" TFTP server, which support 188 options, is available at: 189 190 http://www.kernel.org/pub/software/network/tftp/ 191 ftp://www.kernel.org/pub/software/network/tftp/ 192 193 and on any kernel.org mirror (see http://www.kernel.org/mirrors/). 194 195 Another TFTP server which supports this is atftp by Jean-Pierre 196 Lefebvre: 197 198 ftp://ftp.mamalinux.com/pub/atftp/ 199 200 If your boot server is running Windows (and you can't fix that), try 201 tftpd32 by Philippe Jounin (you need version 2.11 or later; previous 202 versions had a bug which made it incompatible with PXELINUX): 203 204 http://tftpd32.jounin.net/ 205 206 207 === DHCP config: Simple === 208 The PXE protocol uses a very complex set of extensions to DHCP or 209 BOOTP. However, most PXE implementations -- this includes all Intel 210 ones version 0.99n and later -- seem to be able to boot in a 211 "conventional" DHCP/TFTP configuration. Assuming you don't have to 212 support any very old or otherwise severely broken clients, this is 213 probably the best configuration unless you already have a PXE boot 214 server on your network. 215 216 A sample DHCP setup, using the "conventional TFTP" configuration, 217 would look something like the following, using ISC dhcp 2.0 dhcpd.conf 218 syntax: 219 220 ----- 221 allow booting; 222 allow bootp; 223 224 # Standard configuration directives... 225 226 option domain-name "<domain name>"; 227 option subnet-mask <subnet mask>; 228 option broadcast-address <broadcast address>; 229 option domain-name-servers <dns servers>; 230 option routers <default router>; 231 232 # Group the PXE bootable hosts together 233 group { 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 247 Note that if your particular TFTP daemon runs under chroot (tftp-hpa 248 will do this if you specify the -s (secure) option; this is highly 249 recommended), you almost certainly should not include the /tftpboot 250 prefix in the filename statement. 251 252 253 === DHCP Config: PXE-1 === 254 If the simple config does not work for your environment, you probably 255 should set up a "PXE boot server" on port 4011 of your TFTP server; a 256 free PXE boot server is available at: 257 258 http://www.kano.org.uk/projects/pxe/ 259 260 With such a boot server defined, your DHCP configuration should look 261 the same except for an "option dhcp-class-identifier" ("option 262 vendor-class-identifier" if you are using DHCP 3.0): 263 264 ---- 265 allow booting; 266 allow bootp; 267 268 # Standard configuration directives... 269 270 option domain-name "<domain name>"; 271 option subnet-mask <subnet mask>; 272 option broadcast-address <broadcast address>; 273 option domain-name-servers <dns servers>; 274 option routers <default router>; 275 276 # Group the PXE bootable hosts together 277 group { 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 291 Here, the boot file name is obtained from the PXE server. 292 293 294 === DHCP Config: Encapsulated === 295 If the "conventional TFTP" configuration doesn't work on your clients, 296 and setting up a PXE boot server is not an option, you can attempt the 297 following configuration. It has been known to boot some 298 configurations correctly; however, there are no guarantees: 299 ---- 300 allow booting; 301 allow bootp; 302 303 # Standard configuration directives... 304 305 option domain-name "<domain name>"; 306 option subnet-mask <subnet mask>; 307 option broadcast-address <broadcast address>; 308 option domain-name-servers <dns servers>; 309 option routers <default router>; 310 311 # Group the PXE bootable hosts together 312 group { 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 ---- 327 Note that this *will not* boot some clients that *will* boot with the 328 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are 329 known to fall into this category. 330 331 332 === DHCP Config: ISC dhcpd options === 333 ISC dhcp 3.0 supports a rather nice syntax for specifying custom 334 options; you can use the following syntax in dhcpd.conf if you are 335 running this version of dhcpd: 336 ---- 337 option space pxelinux; 338 option pxelinux.magic code 208 = string; 339 option pxelinux.configfile code 209 = text; 340 option pxelinux.pathprefix code 210 = text; 341 option 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 349 Then, inside your PXELINUX-booting group or class (whereever you have 350 the PXELINUX-related options, such as the filename option), you can 351 add, for example: 352 ---- 353 # Always include the following lines for all PXELINUX clients 354 site-option-space "pxelinux"; 355 option pxelinux.magic f1:00:74:7e; 356 if 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 361 option pxelinux.configfile "configs/common"; 362 option pxelinux.pathprefix "/tftpboot/pxelinux/files/"; 363 option pxelinux.reboottime 30; 364 filename "/tftpboot/pxelinux/pxelinux.bin"; 365 ---- 366 Note that the configfile is relative to the pathprefix: this will look 367 for a config file called /tftpboot/pxelinux/files/configs/common on 368 the TFTP server. 369 370 The "option dhcp-parameter-request-list" statement forces the DHCP 371 server to send the PXELINUX-specific options, even though they are not 372 explicitly requested. Since the DHCP request is done before PXELINUX 373 is loaded, the PXE client won't know to request them. 374 375 Using ISC dhcp 3.0 you can create a lot of these strings on the fly. 376 For example, to use the hexadecimal form of the hardware address as 377 the configuration file name, you could do something like: 378 ---- 379 site-option-space "pxelinux"; 380 option pxelinux.magic f1:00:74:7e; 381 if 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 } 385 option pxelinux.configfile = 386 concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware)); 387 filename "/tftpboot/pxelinux.bin"; 388 ---- 389 If you used this from a client whose Ethernet address was 390 58: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 == 395 The 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 403 If you have additional problems, please contact the Syslinux mailing 404 list (see syslinux.txt for the address.) 405 406 === Broken PXE stacks === 407 Lots of PXE stacks, especially old ones, have various problems of 408 varying 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 413 if known. 414 415 There are a number of extremely broken PXE stacks in the field. The 416 gPXE project (formerly known as Etherboot) provides an open-source PXE 417 stack that works with a number of cards, and which can be loaded from 418 a CD-ROM, USB key, or floppy if desired. 419 420 Information 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 428 Some cards, like may systems with the SiS 900, has a PXE stack which 429 works just barely well enough to load a single file, but doesn't 430 handle the more advanced items required by PXELINUX. If so, it is 431 possible to use the built-in PXE stack to load gPXE, which can then 432 load PXELINUX. See: 433 434 http://www.etherboot.org/wiki/pxechaining 435 436 437 == NOTES == 438 === MTFTP === 439 PXELINUX does not support MTFTP, and there are no plans of doing so, as 440 MTFTP is inherently broken for files more than 65535 packets (about 92 441 MB) in size. It is of course possible to use MTFTP for the initial 442 boot, if you have such a setup. MTFTP server setup is beyond the scope 443 of this document. 444 445 === Error Recovery === 446 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever; 447 rather, if it has not received any input for approximately five 448 minutes after displaying an error message, it will reset the machine. 449 This allows an unattended machine to recover in case it had bad enough 450 luck 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 == 459 This AsciiDoc derived document is a modified version of the original 460 *SYSLINUX* documentation by {author} <{author-email}>. The conversion 461 to an AsciiDoc was made by {editor1} <{editor1-email}> 462
