Dynamic Host Configuration Working D. Hankins Group ISC Internet-Draft May 24, 2006 Expires: November 25, 2006 PXELinux Use of 'Site Local' Option Space draft-dhankins-pxelinux-01 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on November 25, 2006. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document is in response to RFC3942 [1], and describes the use by PXELinux of some DHCP Option Codes [2] numbering from 208-211. These codes were designated 'Site Local' [3] prior to this action, and are redefined by RFC3942 as available for allocation as standard DHCP Options. Hankins Expires November 25, 2006 [Page 1] Internet-Draft PXELinux DHCP Options May 2006 Table of Contents 1. PXELinux in a Nutshell . . . . . . . . . . . . . . . . . . . . 3 2. MAGIC Option . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Description . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 4 2.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 4 3. Configuration File Option . . . . . . . . . . . . . . . . . . 4 3.1. Description . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 5 3.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 5 3.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 5 4. Path Prefix Option . . . . . . . . . . . . . . . . . . . . . . 5 4.1. Description . . . . . . . . . . . . . . . . . . . . . . . 5 4.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 6 4.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 6 4.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 6 5. Option 211 - Reboot Time . . . . . . . . . . . . . . . . . . . 7 5.1. Description . . . . . . . . . . . . . . . . . . . . . . . 7 5.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 7 5.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7 5.4. Response to RFC3942 . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 Intellectual Property and Copyright Statements . . . . . . . . . . 11 Hankins Expires November 25, 2006 [Page 2] Internet-Draft PXELinux DHCP Options May 2006 1. PXELinux in a Nutshell PXE, the Preboot eXecution Environment, is a first-stage network bootstrap agent. PXE is loaded out of firmware on the client host, and performs DHCP queries to obtain an IP Address. Once on the network, it loads a second-stage bootstrap agent as configured by DHCP header and option contents. PXELinux is one such second-stage bootstrap agent. Once PXE has passed execution to it, PXELinux seeks its configuration from a cache of DHCP Options supplied to the PXE first-stage agent, and then takes action based upon those options Most frequently, this implies loading via TFTP [4] one or more images which are decompressed into memory and executed to pass execution to the final Host Operating System. PXELinux uses DHCP Options 208-211 to govern parts of this bootstrap process, but these options are not requested by the PXE DHCP Client at the time it acquires its lease. Local installations that serve this image to its clients must also configure their DHCP Servers to provide these options even though they are not on the request list. These options are: o "MAGIC" - 208 - An option whose presence and content verifies to the PXELinux bootloader that the options numbered 209-211 are for the purpose as described herein. o "ConfigFile" - 209 - Configures the file location of the configuration file this bootloader should use to configure itself. o "Pathprefix" - 210 - Configures a value to be prepended to the ConfigFile, to discern the directory location of the file. o "Reboottime" - 211 - Configures a timeout after which the bootstrap program will reboot the system (most likely returning it to PXE). 2. MAGIC Option 2.1. Description If this option is provided to the PXE bootloader, then the value is checked to match the octet string f1:00:74:7e. If this matches, then PXELinux bootloaders will also consume options 209-211, as described Hankins Expires November 25, 2006 [Page 3] Internet-Draft PXELinux DHCP Options May 2006 below. Otherwise, they are ignored. This measure was intended to ensure that, as the site-local option space is not allocated from a central authority, no conflict would result in a PXELinux bootloader improperly digesting a options intended for another purpose. 2.2. Packet Format The MAGIC Option format is as follows: Code Length m1 m2 m3 m4 +--------+--------+--------+--------+--------+--------+ | 208 | 4 | 0xF1 | 0x00 | 0x74 | 0x7E | +--------+--------+--------+--------+--------+--------+ The code for this option is 208. The length is always four. 2.3. Applicability This option is absolutely unapplicable to any other purpose. 2.4. Response to RFC3942 No action will be taken. A collision of the use of this option is harmless (at least from PXElinux point of view) by design: if it does not match the aforementioned magic value, the PXELinux bootloader will take no special action. The PXELinux project will deprecate the use of this option, future versions of the software will not evaluate its contents. It is not only reasonable to utilize this option code for another purpose, it is recommended, except that it is undesirable for any future consumer of this option code to have to suffer potential collisions in legacy userbases. 3. Configuration File Option 3.1. Description Once the PXELinux executable has been entered from the PXE bootloader, it evaluates this option and loads a file of that name via TFTP. The contents of this file serve to configure PXELinux in its next stage of bootloading (specifying boot image names, locations, boot-time flags, text to present the user in menu selections, etc). Hankins Expires November 25, 2006 [Page 4] Internet-Draft PXELinux DHCP Options May 2006 In the absence of this option, the PXELinux agent will search the TFTP Server (as determined by PXE prior to this stage) for a config file of several default names. 3.2. Packet Format The Configuration File Option format is as follows: Code Length Config-file... +--------+--------+--------+--------+--------+--------+ | 209 | n | c1 | c2 | ... | c(n) | +--------+--------+--------+--------+--------+--------+ The code for this option is 209. The Config-file (c1..c(n)) is an NVT-ASCII printable string, it is not terminated by a zero or any other value. 3.3. Applicability Any bootloader, PXE or otherwise, that makes use of a separate configuration file rather than containing all configuration within DHCP options (which may be impossible due to the limited space available for DHCP options) may conceivably make use of this option. 3.4. Response to RFC3942 The code 209 will be adopted for this purpose. 4. Path Prefix Option 4.1. Description In PXELinux' case, it is often the case that several different environments would have the same TFTP path prefix, but would have different filenames (for example: hosts' bootloader images and config files may be kept in a directory structure derived from their MAC Address). Consequently, it was deemed worthwhile to deliver a TFTP path prefix configuration option, so that these two things could be configured separately in DHCP Server configuration: the prefix and the possibly-host-specific file location. The actual filename that PXELinux requests from its TFTP server is derived by prepending this value to the Config File Option above. Once this config file is loaded and during processing, any TFTP file paths specified within it are similarly processed - prepending the contents of this option. Hankins Expires November 25, 2006 [Page 5] Internet-Draft PXELinux DHCP Options May 2006 The contents of the Path Prefix option are also prepended to all configured filename locations within the PXELinux configuration file. 4.2. Packet Format The Path Prefix Option format is as follows: Code Length Path-Prefix... +--------+--------+--------+--------+--------+--------+ | 210 | n | p1 | p2 | ... | p(n) | +--------+--------+--------+--------+--------+--------| The code for this option is 210. The Path Prefix is an NVT-ASCII printable string, it is not terminated by zero or any other value. 4.3. Applicability This option came into existence because server administrators found it useful to configure the prefix and suffix of the config file path separately. A group of different PXE booting clients may use the same path prefix, but different filenames, or vice versa. The 'shortcut' this represents is worthwhile, but it is questionable wether that needs to manifest itself on the protocol wire. It only becomes interesting from a protocol standpoint if other options are adopted which prefix this value as well - performing a kind of string compression is highly beneficial to the limited available DHCP option space. But it's clearly inapplicable to any current use of eg the FILENAME header contents, or the DHCP Boot File Name option (#67). Use of these fields is encoded on firmware of thousands of devices which can't or are not likely to be upgraded. Altering any behaviour here is likely to cause severe compatibility problems. Although compression of the TFTP-loaded configuration file contents is not a compelling factor, contrived configurations using these values may also exist: Where each of a large variety of different clients load the same configuration file, with the same contents, but due to a differently configured path prefix actually load different images. Wether this sort of use is truly needed remains unproven. 4.4. Response to RFC3942 The code 210 will be adopted for this purpose. Hankins Expires November 25, 2006 [Page 6] Internet-Draft PXELinux DHCP Options May 2006 5. Option 211 - Reboot Time 5.1. Description Should PXELinux be executed, and then for some reason be unable to reach its TFTP server to continue bootstrapping, the client will by default reboot itself after 300 seconds have passed. This may be too long, too short, or inappropriate behaviour entirely, depending on the environment. By configuring a non-zero value in this option, admins can inform PXELinux of what specific timeout is desired. The client will reboot itself if it fails to acheive its configured network resources within the specified number of seconds. This reboot will run through the system's normal boot-time execution path, most likely leading it back to PXE and therefore PXELinux. So, in the general case, this is akin to returning the client to the DHCP INIT state. By configuring zero, the feature is disabled, and instead the client chooses to remove itself from the network and wait indefinitely for operator intervention. It should be stressed that this is in no way related to configuring a lease-time. The perceived transition to INIT state is due to client running state - reinitializing itself - not due to lease timer activity. That is, it is not safe to assume that a PXELinux client will abandon its lease when this timer expires. 5.2. Packet Format The Reboot Time Option format is as follows: Code Length +--------+--------+--------+--------+--------+--------+ | 211 | 4 | Reboot Time | +--------+--------+--------+--------+--------+--------+ The code for this option is 211. The length is always four. The Reboot Time is a 32-bit (4 byte) integer in network byte order. 5.3. Applicability Any network bootstrap program in any sufficiently complex networking environment could conceivably enter into such a similar condition. Either due to having its IP address stolen out from under it by a rogue client on the network, by being moved between networks where Hankins Expires November 25, 2006 [Page 7] Internet-Draft PXELinux DHCP Options May 2006 its PXE-derived DHCP lease is no longer valid, or any similar means. It seems desirable for any network bootstrap agent to implement an ultimate timeout for it to start over. The client may, for example, get different, working configuration parameters from a different DHCP server upon restarting. 5.4. Response to RFC3942 The code 211 will be adopted for this purpose. 6. Security Considerations PXE and PXELinux allow any entity acting as a DHCP server to execute arbitrary code upon a system. At present, no PXE implementation is known to implement Authentication mechanisms so that PXE clients can be sure they are receiving configuration information from the correct, authoritative DHCP Server. The use of TFTP by PXE and PXELinux also lacks any form of cryptographic signature - so a 'Man in the Middle' attack may lead to an attacker's code being executed on the client system. Since this is not an encrypted channel, any of the TFTP loaded data may also be exposed (such as in loading a "RAMDISK" image, which contains /etc/ passwd or similar information). The use of the Ethernet MAC Address as the client's unique identity may allow an attacker who takes on that identity to gain inappropriate access to a client system's network resources by being given by the DHCP Server whatever 'keys' are required to in fact be the target system (to boot up as though it were the target). Great care should be taken to secure PXE and PXELinux installations, to reduce or eliminate these concerns. The use of these options present no additional security risk. 7. IANA Considerations IANA is requested to: 1. Move DHCPv4 Option code 208 from 'Tentatively Assigned' to 'Unassigned, Last Resort'. It is hoped that Unassigned DHCP Option Codes (that had never been Tentatively Assigned) would be allocated prior to assigning this option code. Hankins Expires November 25, 2006 [Page 8] Internet-Draft PXELinux DHCP Options May 2006 2. Move DHCPv4 Option code 209 from 'Tentatively Assigned' to 'Assigned', referencing this document. 3. Move DHCPv4 Option code 210 from 'Tentatively Assigned' to 'Assigned', referencing this document. 4. Move DHCPv4 Option code 211 from 'Tentatively Assigned' to 'Assigned', referencing this document. 8. Acknowledgements These options were designed and implemented for the PXELinux project by H. Peter Anvin, and he was instrumental in producing this document. 9. References [1] Volz, B., "Reclassifying Dynamic Host Configuration Protocol version 4 (DHCPv4) Options", RFC 3942, November 2004. [2] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, March 1997. [3] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor Extensions", RFC 2132, March 1997. [4] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, July 1992. Hankins Expires November 25, 2006 [Page 9] Internet-Draft PXELinux DHCP Options May 2006 Author's Address David W. Hankins Internet Systems Consortium, Inc. 950 Charter Street Redwood City, CA 94063 US Phone: +1 650 423 1307 Email: David_Hankins@isc.org Hankins Expires November 25, 2006 [Page 10] Internet-Draft PXELinux DHCP Options May 2006 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Hankins Expires November 25, 2006 [Page 11]