idnits 2.17.1 draft-dhankins-pxelinux-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 537. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 514. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 521. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 527. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 2006) is 6548 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Dynamic Host Configuration Working D. Hankins 3 Group ISC 4 Internet-Draft May 2006 5 Expires: November 2, 2006 7 PXELINUX Use of 'Site Local' Option Space 8 draft-dhankins-pxelinux-02 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on November 2, 2006. 35 Copyright Notice 37 Copyright (C) The Internet Society (2006). 39 Abstract 41 This document is in response to RFC3942 [1], and describes the use by 42 PXELINUX of some DHCP Option Codes [2] numbering from 208-211. These 43 codes were designated 'Site Local' [3] prior to this action, and are 44 redefined by RFC3942 as available for allocation as standard DHCP 45 Options. 47 Table of Contents 49 1. PXELINUX in a Nutshell . . . . . . . . . . . . . . . . . . . . 3 50 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 3. MAGIC Option . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 3.1. Description . . . . . . . . . . . . . . . . . . . . . . . 4 53 3.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 4 54 3.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 4 55 3.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 5 56 4. Configuration File Option . . . . . . . . . . . . . . . . . . 5 57 4.1. Description . . . . . . . . . . . . . . . . . . . . . . . 5 58 4.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 5 59 4.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 5 60 4.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 6 61 4.5. Client and Server Behaviour . . . . . . . . . . . . . . . 6 62 5. Path Prefix Option . . . . . . . . . . . . . . . . . . . . . . 6 63 5.1. Description . . . . . . . . . . . . . . . . . . . . . . . 6 64 5.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 7 65 5.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7 66 5.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 7 67 5.5. Client and Server Behaviour . . . . . . . . . . . . . . . 8 68 6. Option 211 - Reboot Time . . . . . . . . . . . . . . . . . . . 8 69 6.1. Description . . . . . . . . . . . . . . . . . . . . . . . 8 70 6.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 9 71 6.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 9 72 6.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 9 73 6.5. Client and Server Behaviour . . . . . . . . . . . . . . . 9 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 76 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 Intellectual Property and Copyright Statements . . . . . . . . . . 13 81 1. PXELINUX in a Nutshell 83 PXE, the Preboot eXecution Environment, is a first-stage network 84 bootstrap agent. PXE is loaded out of firmware on the client host, 85 and performs DHCP queries to obtain an IP Address. 87 Once on the network, it loads a second-stage bootstrap agent as 88 configured by DHCP header and option contents. 90 PXELINUX is one such second-stage bootstrap agent. Once PXE has 91 passed execution to it, PXELINUX seeks its configuration from a cache 92 of DHCP Options supplied to the PXE first-stage agent, and then takes 93 action based upon those options. 95 Most frequently, this implies loading via TFTP [4] one or more images 96 which are decompressed into memory and executed to pass execution to 97 the final Host Operating System. 99 PXELINUX uses DHCP Options 208-211 to govern parts of this bootstrap 100 process, but these options are not requested by the PXE DHCP Client 101 at the time it acquires its lease...at that time, the PXE bootloader 102 has no knowledge that PXELINUX is going to be in use, and even so 103 would have no way to know what option(s) PXELINUX might digest. 104 Local installations that serve this PXELINUX image to its clients 105 must also configure their DHCP Servers to provide these options even 106 though they are not on the DHCP Parameter Request List. 108 These options are: 110 o "MAGIC" - 208 - An option whose presence and content verifies to 111 the PXELINUX bootloader that the options numbered 209-211 are for 112 the purpose as described herein. 114 o "ConfigFile" - 209 - Configures the file location of the 115 configuration file this bootloader should use to configure itself. 117 o "Pathprefix" - 210 - Configures a value to be prepended to the 118 ConfigFile, to discern the directory location of the file. 120 o "Reboottime" - 211 - Configures a timeout after which the 121 bootstrap program will reboot the system (most likely returning it 122 to PXE). 124 2. Terminology 126 o "first-stage bootloader" - Although a given boot loading order may 127 have many stages, such as where a BIOS boots a DOS Boot Disk which 128 then loads a PXE executable, it is in this example only the PXE 129 executable that this document describes as the "first-stage 130 bootloader" - in essence, this is the first stage of booting at 131 which DHCP is involved. 133 o "second-stage bootloader" - This describes a program loaded by the 134 first-stage bootloader at the behest of the DHCP Server. 136 o "bootloader" and "network bootstrap agent" - These are synonyms, 137 excepting that "bootloader" is intentionally vague in that its 138 next form of bootstrapping may not in fact involve network 139 resources. 141 The key words "MAY", "MUST", "MUST NOT", "SHOULD", and "SHOULD NOT" 142 in this document are to be interpreted as described in RFC2119 [5]. 144 3. MAGIC Option 146 3.1. Description 148 If this option is provided to the PXE bootloader, then the value is 149 checked to match the octet string f1:00:74:7e. If this matches, then 150 PXELINUX bootloaders will also consume options 209-211, as described 151 below. Otherwise, they are ignored. 153 This measure was intended to ensure that, as the site-local option 154 space is not allocated from a central authority, no conflict would 155 result in a PXELINUX bootloader improperly digesting options intended 156 for another purpose. 158 3.2. Packet Format 160 The MAGIC Option format is as follows: 162 Code Length m1 m2 m3 m4 163 +--------+--------+--------+--------+--------+--------+ 164 | 208 | 4 | 0xF1 | 0x00 | 0x74 | 0x7E | 165 +--------+--------+--------+--------+--------+--------+ 167 The code for this option is 208. The length is always four. 169 3.3. Applicability 171 This option is absolutely inapplicable to any other purpose. 173 3.4. Response to RFC3942 175 No action will be taken. A collision of the use of this option is 176 harmless (at least from PXELINUX' point of view) by design: if it 177 does not match the aforementioned magic value, the PXELINUX 178 bootloader will take no special action. 180 The PXELINUX project will deprecate the use of this option, future 181 versions of the software will not evaluate its contents. 183 It is not only reasonable to utilize this option code for another 184 purpose, it is recommended, except that it is undesirable for any 185 future consumer of this option code to have to suffer potential 186 collisions in legacy userbases. 188 4. Configuration File Option 190 4.1. Description 192 Once the PXELINUX executable has been entered from the PXE 193 bootloader, it evaluates this option and loads a file of that name 194 via TFTP. The contents of this file serve to configure PXELINUX in 195 its next stage of bootloading (specifying boot image names, 196 locations, boot-time flags, text to present the user in menu 197 selections, etc). 199 In the absence of this option, the PXELINUX agent will search the 200 TFTP Server (as determined by PXE prior to this stage) for a config 201 file of several default names. 203 4.2. Packet Format 205 The Configuration File Option format is as follows: 207 Code Length Config-file... 208 +--------+--------+--------+--------+--------+--------+ 209 | 209 | n | c1 | c2 | ... | c(n) | 210 +--------+--------+--------+--------+--------+--------+ 212 The code for this option is 209. The Config-file (c1..c(n)) is an 213 NVT-ASCII printable string, it is not terminated by a zero or any 214 other value. 216 4.3. Applicability 218 Any bootloader, PXE or otherwise, that makes use of a separate 219 configuration file rather than containing all configuration within 220 DHCP options (which may be impossible due to the limited space 221 available for DHCP options) may conceivably make use of this option. 223 4.4. Response to RFC3942 225 The code 209 will be adopted for this purpose. 227 4.5. Client and Server Behaviour 229 The Config File Option MUST be supplied by the DHCP Server if it 230 appears on the Parameter Request List, but MUST also be supplied if 231 the server administrator believed it would later be useful to the 232 client (such as because the server is configured to offer a second- 233 stage boot image which they know will make use of it). The option 234 MUST NOT be supplied if no value has been configured for it, or if a 235 value of zero length has been configured. 237 The DHCP Client MUST only cache this option in a location the second- 238 stage bootloader may access it. 240 The second-stage bootloader MUST, in concert with other DHCP Options 241 and fields, use this option's value as a filename to be loaded via 242 TFTP and read for further second-stage-loader-specific configuration 243 parameters. The format and content of such a file is specific to the 244 second-stage bootloader, and as such is out of scope of this 245 document. 247 5. Path Prefix Option 249 5.1. Description 251 In PXELINUX' case, it is often the case that several different 252 environments would have the same TFTP path prefix, but would have 253 different filenames (for example: hosts' bootloader images and config 254 files may be kept in a directory structure derived from their MAC 255 Address). Consequently, it was deemed worthwhile to deliver a TFTP 256 path prefix configuration option, so that these two things could be 257 configured separately in DHCP Server configuration: the prefix and 258 the possibly-host-specific file location. 260 The actual filename that PXELINUX requests from its TFTP server is 261 derived by prepending this value to the Config File Option above. 262 Once this config file is loaded and during processing, any TFTP file 263 paths specified within it are similarly processed - prepending the 264 contents of this option. 266 The contents of the Path Prefix option are also prepended to all 267 configured filename locations within the PXELINUX configuration file. 269 5.2. Packet Format 271 The Path Prefix Option format is as follows: 273 Code Length Path-Prefix... 274 +--------+--------+--------+--------+--------+--------+ 275 | 210 | n | p1 | p2 | ... | p(n) | 276 +--------+--------+--------+--------+--------+--------+ 278 The code for this option is 210. The Path Prefix is an NVT-ASCII 279 printable string, it is not terminated by zero or any other value. 281 5.3. Applicability 283 This option came into existence because server administrators found 284 it useful to configure the prefix and suffix of the config file path 285 separately. A group of different PXE booting clients may use the 286 same path prefix, but different filenames, or vice versa. 288 The 'shortcut' this represents is worthwhile, but it is questionable 289 wether that needs to manifest itself on the protocol wire. 291 It only becomes interesting from a protocol standpoint if other 292 options are adopted which prefix this value as well - performing a 293 kind of string compression is highly beneficial to the limited 294 available DHCP option space. 296 But it's clearly inapplicable to any current use of eg the FILENAME 297 header contents, or the DHCP Boot File Name option (#67). Use of 298 these fields is encoded on firmware of thousands of devices which 299 can't or are not likely to be upgraded. Altering any behaviour here 300 is likely to cause severe compatibility problems. 302 Although compression of the TFTP-loaded configuration file contents 303 is not a compelling factor, contrived configurations using these 304 values may also exist: Where each of a large variety of different 305 clients load the same configuration file, with the same contents, but 306 due to a differently configured path prefix actually load different 307 images. Wether this sort of use is truly needed remains unproven. 309 5.4. Response to RFC3942 311 The code 210 will be adopted for this purpose. 313 5.5. Client and Server Behaviour 315 The Path Prefix option MUST be supplied by the DHCP Server if it 316 appears on the Parameter Request List, but MUST also be supplied if 317 the server administrator believed it would later be useful to the 318 client (such as because the server is configured to offer a second- 319 stage boot image which they know will make use of it). The option 320 MUST NOT be supplied if no value has been configured for it, or if a 321 value of zero length has been configured. 323 The DHCP Client MUST only cache this option in a location where the 324 second-stage bootloader may access it. 326 The second-stage bootloader MUST prepend this option's value, if any, 327 to the contents of the ConfigFile option prior to obtaining the 328 resulting value via TFTP, or the default 'Config File Search Path' 329 which the second-stage bootloader iterates in the absence of a Config 330 File Option. The client MAY prepend the value to other configuration 331 directives within that file once it has been loaded. The client MUST 332 NOT prepend this option's value to any other DHCP option contents or 333 field, unless explicitly stated in a document describing that option 334 or field. 336 6. Option 211 - Reboot Time 338 6.1. Description 340 Should PXELINUX be executed, and then for some reason be unable to 341 reach its TFTP server to continue bootstrapping, the client will by 342 default reboot itself after 300 seconds have passed. This may be too 343 long, too short, or inappropriate behaviour entirely, depending on 344 the environment. 346 By configuring a non-zero value in this option, admins can inform 347 PXELINUX of what specific timeout is desired. The client will reboot 348 itself if it fails to acheive its configured network resources within 349 the specified number of seconds. 351 This reboot will run through the system's normal boot-time execution 352 path, most likely leading it back to PXE and therefore PXELINUX. So, 353 in the general case, this is akin to returning the client to the DHCP 354 INIT state. 356 By configuring zero, the feature is disabled, and instead the client 357 chooses to remove itself from the network and wait indefinitely for 358 operator intervention. 360 It should be stressed that this is in no way related to configuring a 361 lease-time. The perceived transition to INIT state is due to client 362 running state - reinitializing itself - not due to lease timer 363 activity. That is, it is not safe to assume that a PXELINUX client 364 will abandon its lease when this timer expires. 366 6.2. Packet Format 368 The Reboot Time Option format is as follows: 370 Code Length 371 +--------+--------+--------+--------+--------+--------+ 372 | 211 | 4 | Reboot Time | 373 +--------+--------+--------+--------+--------+--------+ 375 The code for this option is 211. The length is always four. The 376 Reboot Time is a 32-bit (4 byte) integer in network byte order. 378 6.3. Applicability 380 Any network bootstrap program in any sufficiently complex networking 381 environment could conceivably enter into such a similar condition. 382 Either due to having its IP address stolen out from under it by a 383 rogue client on the network, by being moved between networks where 384 its PXE-derived DHCP lease is no longer valid, or any similar means. 386 It seems desirable for any network bootstrap agent to implement an 387 ultimate timeout for it to start over. 389 The client may, for example, get different, working configuration 390 parameters from a different DHCP server upon restarting. 392 6.4. Response to RFC3942 394 The code 211 will be adopted for this purpose. 396 6.5. Client and Server Behaviour 398 The Reboot Time Option MUST be supplied by the DHCP Server if it 399 appears on the Parameter Request List, but MUST also be supplied if 400 the server administrator believed it would later be useful to the 401 client (such as because the server is configured to offer a second- 402 stage boot image which they know will make use of it). The option 403 MUST NOT be supplied if no value has been configured for it, or if it 404 contains a value of zero length. 406 The DHCP Client MUST only cache this option in a location the second- 407 stage bootloader may access it. 409 If the value of this option is nonzero, the second-stage bootloader 410 MUST schedule a timeout: after a number of seconds equal to this 411 option's value have passed, the second-stage bootloader MUST reboot 412 the system, ultimately returning the path of execution back to the 413 first-stage bootloader. It MUST NOT reboot the system once the 414 thread of execution has been passed to the host operating system (at 415 which point this timeout is effectively obviated). 417 If the value of this option is zero, the second-stage bootloader MUST 418 NOT schedule such a timeout at all. Any second-stage bootloader that 419 finds it has encountered excessive timeouts attempting to obtain its 420 host operating system SHOULD disconnect itself from the network to 421 wait for operator intervention, but MAY continue to attempt to 422 acquire the host operating system indefinitely. 424 7. Security Considerations 426 PXE and PXELINUX allow any entity acting as a DHCP server to execute 427 arbitrary code upon a system. At present, no PXE implementation is 428 known to implement Authentication mechanisms so that PXE clients can 429 be sure they are receiving configuration information from the 430 correct, authoritative DHCP Server. 432 The use of TFTP by PXE and PXELINUX also lacks any form of 433 cryptographic signature - so a 'Man in the Middle' attack may lead to 434 an attacker's code being executed on the client system. Since this 435 is not an encrypted channel, any of the TFTP loaded data may also be 436 exposed (such as in loading a "RAMDISK" image, which contains /etc/ 437 passwd or similar information). 439 The use of the Ethernet MAC Address as the client's unique identity 440 may allow an attacker who takes on that identity to gain 441 inappropriate access to a client system's network resources by being 442 given by the DHCP Server whatever 'keys' are required to in fact be 443 the target system (to boot up as though it were the target). 445 Great care should be taken to secure PXE and PXELINUX installations, 446 such as by using IP Firewalls, to reduce or eliminate these concerns. 448 The use of these options present no additional security risk. 450 8. IANA Considerations 452 IANA is requested to: 454 1. Move DHCPv4 Option code 208 from 'Tentatively Assigned' to 455 'Unassigned, Last Resort'. It is hoped that Unassigned DHCP 456 Option Codes (that had never been Tentatively Assigned) SHOULD be 457 allocated prior to assigning this option code, but otherwise 458 SHOULD be allocated before any option code that has been 459 Tentatively Assigned, or Assigned. 461 2. Move DHCPv4 Option code 209 from 'Tentatively Assigned' to 462 'Assigned', referencing this document. 464 3. Move DHCPv4 Option code 210 from 'Tentatively Assigned' to 465 'Assigned', referencing this document. 467 4. Move DHCPv4 Option code 211 from 'Tentatively Assigned' to 468 'Assigned', referencing this document. 470 9. Acknowledgements 472 These options were designed and implemented for the PXELINUX project 473 by H. Peter Anvin, and he was instrumental in producing this 474 document. Shane Kerr has also provided feedback which has improved 475 this document. 477 10. References 479 [1] Volz, B., "Reclassifying Dynamic Host Configuration Protocol 480 version 4 (DHCPv4) Options", RFC 3942, November 2004. 482 [2] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, 483 March 1997. 485 [3] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor 486 Extensions", RFC 2132, March 1997. 488 [4] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, 489 July 1992. 491 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 492 Levels", BCP 14, RFC 2119, March 1997. 494 Author's Address 496 David W. Hankins 497 Internet Systems Consortium, Inc. 498 950 Charter Street 499 Redwood City, CA 94063 500 US 502 Phone: +1 650 423 1307 503 Email: David_Hankins@isc.org 505 Intellectual Property Statement 507 The IETF takes no position regarding the validity or scope of any 508 Intellectual Property Rights or other rights that might be claimed to 509 pertain to the implementation or use of the technology described in 510 this document or the extent to which any license under such rights 511 might or might not be available; nor does it represent that it has 512 made any independent effort to identify any such rights. Information 513 on the procedures with respect to rights in RFC documents can be 514 found in BCP 78 and BCP 79. 516 Copies of IPR disclosures made to the IETF Secretariat and any 517 assurances of licenses to be made available, or the result of an 518 attempt made to obtain a general license or permission for the use of 519 such proprietary rights by implementers or users of this 520 specification can be obtained from the IETF on-line IPR repository at 521 http://www.ietf.org/ipr. 523 The IETF invites any interested party to bring to its attention any 524 copyrights, patents or patent applications, or other proprietary 525 rights that may cover technology that may be required to implement 526 this standard. Please address the information to the IETF at 527 ietf-ipr@ietf.org. 529 Disclaimer of Validity 531 This document and the information contained herein are provided on an 532 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 533 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 534 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 535 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 536 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 537 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 539 Copyright Statement 541 Copyright (C) The Internet Society (2006). This document is subject 542 to the rights, licenses and restrictions contained in BCP 78, and 543 except as set forth therein, the authors retain all their rights. 545 Acknowledgment 547 Funding for the RFC Editor function is currently provided by the 548 Internet Society.