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