diff options
Diffstat (limited to 'contrib/syslinux/syslinux-4.03/doc/rfc5071.txt')
| -rw-r--r-- | contrib/syslinux/syslinux-4.03/doc/rfc5071.txt | 787 |
1 files changed, 0 insertions, 787 deletions
diff --git a/contrib/syslinux/syslinux-4.03/doc/rfc5071.txt b/contrib/syslinux/syslinux-4.03/doc/rfc5071.txt deleted file mode 100644 index 68f6f5a..0000000 --- a/contrib/syslinux/syslinux-4.03/doc/rfc5071.txt +++ /dev/null @@ -1,787 +0,0 @@ - - - - - - -Network Working Group D. Hankins -Request for Comments: 5071 ISC -Category: Informational December 2007 - - - Dynamic Host Configuration Protocol Options Used by PXELINUX - -Status of This Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Abstract - - This document describes the use by PXELINUX of some DHCP Option Codes - numbering from 208-211. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hankins Informational [Page 1] - -RFC 5071 PXELINUX Options December 2007 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. MAGIC Option . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1. Description . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 5 - 3.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 5 - 3.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 5 - 4. Configuration File Option . . . . . . . . . . . . . . . . . . 5 - 4.1. Description . . . . . . . . . . . . . . . . . . . . . . . 5 - 4.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 6 - 4.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 6 - 4.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 6 - 4.5. Client and Server Behaviour . . . . . . . . . . . . . . . 6 - 5. Path Prefix Option . . . . . . . . . . . . . . . . . . . . . . 7 - 5.1. Description . . . . . . . . . . . . . . . . . . . . . . . 7 - 5.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 7 - 5.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 7 - 5.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 8 - 5.5. Client and Server Behaviour . . . . . . . . . . . . . . . 8 - 6. Reboot Time Option . . . . . . . . . . . . . . . . . . . . . . 9 - 6.1. Description . . . . . . . . . . . . . . . . . . . . . . . 9 - 6.2. Packet Format . . . . . . . . . . . . . . . . . . . . . . 9 - 6.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 10 - 6.4. Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 10 - 6.5. Client and Server Behaviour . . . . . . . . . . . . . . . 10 - 7. Specification Conformance . . . . . . . . . . . . . . . . . . 11 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 - 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 - 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 11.1. Normative References . . . . . . . . . . . . . . . . . . . 12 - 11.2. Informative References . . . . . . . . . . . . . . . . . . 12 - - - - - - - - - - - - - - - - - -Hankins Informational [Page 2] - -RFC 5071 PXELINUX Options December 2007 - - -1. Introduction - - 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 [3] 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 Trivial File Transfer - Protocol (TFTP) [6] one or more images that are decompressed into - memory, then 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. At that time, the PXE bootloader - has no knowledge that PXELINUX is going to be in use, and even so, - would have no way to know what option(s) PXELINUX might digest. - Local installations that serve this PXELINUX image to its clients - must also configure their DHCP servers to provide these options even - though they are not on the DHCP Parameter Request List [4]. - - 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 path/filename component of the - configuration file's location, which 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). - - Historically, these option codes numbering from 208-211 were - designated 'Site Local', but after publication of RFC3942 [8], they - were made available for allocation as new standard DHCP options. - - - -Hankins Informational [Page 3] - -RFC 5071 PXELINUX Options December 2007 - - - This document marks these codes as assigned. - - This direct assignment of option code values in the option - definitions below is unusual as it is not mentioned in DHCP Option - Code assignment guidelines [5]. This document's Option Code - assignments are done within RFC 3942's provisions for documenting - prior use of option codes within the new range (128-223 inclusive). - -2. Terminology - - o "first-stage bootloader" - Although a given bootloading order may - have many stages, such as where a BIOS boots a DOS Boot Disk, - which then loads a PXE executable, it is, in this example, only - the PXE executable that this document describes as the "first- - stage bootloader" -- in essence, this is the first stage of - booting at which DHCP is involved. - - o "second-stage bootloader" - This describes a program loaded by the - first-stage bootloader at the behest of the DHCP server. - - o "bootloader" and "network bootstrap agent" - These are synonyms, - excepting that "bootloader" is intentionally vague in that its - next form of bootstrapping may not in fact involve network - resources. - - The key words "MAY", "MUST", "MUST NOT", "SHOULD", and "SHOULD NOT" - in this document are to be interpreted as described in RFC 2119 [2]. - -3. MAGIC Option - -3.1. Description - - If this option is provided to the PXE bootloader, then the value is - checked by PXELINUX to match the octet string f1:00:74:7e. If this - matches, then PXELINUX bootloaders will also consume options 209-211, - as described 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 options intended - for another purpose. - - - - - - - - - - -Hankins Informational [Page 4] - -RFC 5071 PXELINUX Options December 2007 - - -3.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. - -3.3. Applicability - - This option is absolutely inapplicable to any other purpose. - -3.4. Response to RFC 3942 - - The option code 208 will be adopted for this purpose and immediately - deprecated. Future standards action may return this option to an - available status should it be necessary. - - 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 reasonable to utilize this option code for another purpose, but - it is recommended to do this at a later time, given the desire to - avoid potential collisions in legacy user bases. - -4. Configuration File Option - -4.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). - - 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. - - - - -Hankins Informational [Page 5] - -RFC 5071 PXELINUX Options December 2007 - - -4.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 [1] printable string; it is not terminated by a zero or any - other value. - -4.3. Applicability - - Any bootloader, PXE or otherwise, that makes use of a separate - configuration file rather than containing all configurations within - DHCP options (which may be impossible due to the limited space - available for DHCP options) may conceivably make use of this option. - -4.4. Response to RFC 3942 - - The code 209 will be adopted for this purpose. - -4.5. Client and Server Behaviour - - The Config File Option MUST be supplied by the DHCP server if it - appears on the Parameter Request List, but MUST also be supplied if - the server administrator believed it would later be useful to the - client (such as because the server is configured to offer a second- - stage boot image, which they know will make use of it). The option - MUST NOT be supplied if no value has been configured for it, or if a - value of zero length has been configured. - - The DHCP client MUST only cache this option in a location the second- - stage bootloader may access. - - The second-stage bootloader MUST, in concert with other DHCP options - and fields, use this option's value as a filename to be loaded via - TFTP and read for further second-stage-loader-specific configuration - parameters. The format and content of such a file is specific to the - second-stage bootloader, and as such, is out of scope of this - document. - - - - - - - - -Hankins Informational [Page 6] - -RFC 5071 PXELINUX Options December 2007 - - -5. Path Prefix Option - -5.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 Media - Access Control (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 a 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. - -5.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. - -5.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 - whether that needs to manifest itself on the protocol wire. - - - - - - - - - - -Hankins Informational [Page 7] - -RFC 5071 PXELINUX Options December 2007 - - - It only becomes interesting from a protocol standpoint if other - options are adopted that 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, e.g., the - FILENAME header contents or the DHCP Boot File Name option (#67). - Use of these fields is encoded on firmware of thousands of devices - that 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. Whether this sort of use is truly needed remains unproven. - -5.4. Response to RFC 3942 - - The code 210 will be adopted for this purpose. - -5.5. Client and Server Behaviour - - The Path Prefix option MUST be supplied by the DHCP server if it - appears on the Parameter Request List, but MUST also be supplied if - the server administrator believed it would later be useful to the - client (such as because the server is configured to offer a second- - stage boot image that they know will make use of it). The option - MUST NOT be supplied if no value has been configured for it, or if a - value of zero length has been configured. - - The DHCP client MUST only cache this option in a location where the - second-stage bootloader may access it. - - The second-stage bootloader MUST prepend this option's value, if any, - to the contents of the ConfigFile option prior to obtaining the - resulting value via TFTP, or the default 'Config File Search Path', - which the second-stage bootloader iterates in the absence of a Config - File Option. The client MAY prepend the value to other configuration - directives within that file once it has been loaded. The client MUST - NOT prepend this option's value to any other DHCP option contents or - field, unless explicitly stated in a document describing that option - or field. - - - - - - - -Hankins Informational [Page 8] - -RFC 5071 PXELINUX Options December 2007 - - -6. Reboot Time Option - -6.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 which specific timeout is desired. The client will - reboot itself if it fails to achieve 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. - -6.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. - - - - - - - - - - -Hankins Informational [Page 9] - -RFC 5071 PXELINUX Options December 2007 - - -6.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 - 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. - -6.4. Response to RFC 3942 - - The code 211 will be adopted for this purpose. - -6.5. Client and Server Behaviour - - The Reboot Time Option MUST be supplied by the DHCP server if it - appears on the Parameter Request List, but MUST also be supplied if - the server administrator believed it would later be useful to the - client (such as because the server is configured to offer a second- - stage boot image that they know will make use of it). The option - MUST NOT be supplied if no value has been configured for it, or if it - contains a value of zero length. - - The DHCP client MUST only cache this option in a location the second- - stage bootloader may access. - - If the value of this option is nonzero, the second-stage bootloader - MUST schedule a timeout: after a number of seconds equal to this - option's value have passed, the second-stage bootloader MUST reboot - the system, ultimately returning the path of execution back to the - first-stage bootloader. It MUST NOT reboot the system once the - thread of execution has been passed to the host operating system (at - which point, this timeout is effectively obviated). - - If the value of this option is zero, the second-stage bootloader MUST - NOT schedule such a timeout at all. Any second-stage bootloader that - finds it has encountered excessive timeouts attempting to obtain its - host operating system SHOULD disconnect itself from the network to - wait for operator intervention, but MAY continue to attempt to - acquire the host operating system indefinitely. - - - - - - -Hankins Informational [Page 10] - -RFC 5071 PXELINUX Options December 2007 - - -7. Specification Conformance - - To conform to this specification, clients and servers MUST implement - the Configuration File, Path Prefix, and Reboot Time options as - directed. - - The MAGIC option MAY NOT be implemented, as it has been deprecated. - -8. 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 [7] 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, in fact, to be - the target system (to boot up as though it were the target). - - Great care should be taken to secure PXE and PXELINUX installations, - such as by using IP firewalls, to reduce or eliminate these concerns. - - A nearby attacker might feed a "Reboot Time" option value of 1 second - to a mass of unsuspecting clients, to effect a Denial Of Service - (DoS) upon the DHCP server, but then again it may just as easily - supply these clients with rogue second-stage bootloaders that simply - transmit a flood of packets. - - This document in and by itself provides no security, nor does it - impact existing DCHP security as described in RFC 2131 [3]. - -9. IANA Considerations - - IANA has done the following: - - 1. Moved DHCPv4 Option code 208 from 'Tentatively Assigned' to - 'Assigned', referencing this document. IANA has marked this same - option code, 208, as Deprecated. - - - -Hankins Informational [Page 11] - -RFC 5071 PXELINUX Options December 2007 - - - 2. Moved DHCPv4 Option code 209 from 'Tentatively Assigned' to - 'Assigned', referencing this document. - - 3. Moved DHCPv4 Option code 210 from 'Tentatively Assigned' to - 'Assigned', referencing this document. - - 4. Moved DHCPv4 Option code 211 from 'Tentatively Assigned' to - 'Assigned', referencing this document. - -10. Acknowledgements - - These options were designed and implemented for the PXELINUX project - by H. Peter Anvin, and he was instrumental in producing this - document. Shane Kerr has also provided feedback that has improved - this document. - -11. References - -11.1. Normative References - - [1] Postel, J. and J. Reynolds, "Telnet Protocol Specification", - STD 8, RFC 854, May 1983. - - [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - - [3] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, - March 1997. - - [4] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor - Extensions", RFC 2132, March 1997. - - [5] Droms, R., "Procedures and IANA Guidelines for Definition of New - DHCP Options and Message Types", BCP 43, RFC 2939, - September 2000. - -11.2. Informative References - - [6] Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350, - July 1992. - - [7] Droms, R. and W. Arbaugh, "Authentication for DHCP Messages", - RFC 3118, June 2001. - - [8] Volz, B., "Reclassifying Dynamic Host Configuration Protocol - version 4 (DHCPv4) Options", RFC 3942, November 2004. - - - - - -Hankins Informational [Page 12] - -RFC 5071 PXELINUX Options December 2007 - - -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 Informational [Page 13] - -RFC 5071 PXELINUX Options December 2007 - - -Full Copyright Statement - - Copyright (C) The IETF Trust (2007). - - 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. - - 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, THE IETF TRUST 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. - -Intellectual Property - - 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. - - - - - - - - - - - - -Hankins Informational [Page 14] - |