Fix residual use of DX:AX in the KEYMAP command
[syslinux.git] / doc / rfc5071.txt
blob68f6f5a84e4db1a36c39595b65df3939c0807849
7 Network Working Group                                         D. Hankins
8 Request for Comments: 5071                                           ISC
9 Category: Informational                                    December 2007
12       Dynamic Host Configuration Protocol Options Used by PXELINUX
14 Status of This Memo
16    This memo provides information for the Internet community.  It does
17    not specify an Internet standard of any kind.  Distribution of this
18    memo is unlimited.
20 Abstract
22    This document describes the use by PXELINUX of some DHCP Option Codes
23    numbering from 208-211.
58 Hankins                      Informational                      [Page 1]
60 RFC 5071                    PXELINUX Options               December 2007
63 Table of Contents
65    1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
66    2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
67    3.  MAGIC Option . . . . . . . . . . . . . . . . . . . . . . . . .  4
68      3.1.  Description  . . . . . . . . . . . . . . . . . . . . . . .  4
69      3.2.  Packet Format  . . . . . . . . . . . . . . . . . . . . . .  5
70      3.3.  Applicability  . . . . . . . . . . . . . . . . . . . . . .  5
71      3.4.  Response to RFC 3942 . . . . . . . . . . . . . . . . . . .  5
72    4.  Configuration File Option  . . . . . . . . . . . . . . . . . .  5
73      4.1.  Description  . . . . . . . . . . . . . . . . . . . . . . .  5
74      4.2.  Packet Format  . . . . . . . . . . . . . . . . . . . . . .  6
75      4.3.  Applicability  . . . . . . . . . . . . . . . . . . . . . .  6
76      4.4.  Response to RFC 3942 . . . . . . . . . . . . . . . . . . .  6
77      4.5.  Client and Server Behaviour  . . . . . . . . . . . . . . .  6
78    5.  Path Prefix Option . . . . . . . . . . . . . . . . . . . . . .  7
79      5.1.  Description  . . . . . . . . . . . . . . . . . . . . . . .  7
80      5.2.  Packet Format  . . . . . . . . . . . . . . . . . . . . . .  7
81      5.3.  Applicability  . . . . . . . . . . . . . . . . . . . . . .  7
82      5.4.  Response to RFC 3942 . . . . . . . . . . . . . . . . . . .  8
83      5.5.  Client and Server Behaviour  . . . . . . . . . . . . . . .  8
84    6.  Reboot Time Option . . . . . . . . . . . . . . . . . . . . . .  9
85      6.1.  Description  . . . . . . . . . . . . . . . . . . . . . . .  9
86      6.2.  Packet Format  . . . . . . . . . . . . . . . . . . . . . .  9
87      6.3.  Applicability  . . . . . . . . . . . . . . . . . . . . . . 10
88      6.4.  Response to RFC 3942 . . . . . . . . . . . . . . . . . . . 10
89      6.5.  Client and Server Behaviour  . . . . . . . . . . . . . . . 10
90    7.  Specification Conformance  . . . . . . . . . . . . . . . . . . 11
91    8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 11
92    9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
93    10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
94    11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
95      11.1. Normative References . . . . . . . . . . . . . . . . . . . 12
96      11.2. Informative References . . . . . . . . . . . . . . . . . . 12
114 Hankins                      Informational                      [Page 2]
116 RFC 5071                    PXELINUX Options               December 2007
119 1.  Introduction
121    PXE, the Preboot eXecution Environment, is a first-stage network
122    bootstrap agent.  PXE is loaded out of firmware on the client host,
123    and performs DHCP [3] queries to obtain an IP address.
125    Once on the network, it loads a second-stage bootstrap agent as
126    configured by DHCP header and option contents.
128    PXELINUX is one such second-stage bootstrap agent.  Once PXE has
129    passed execution to it, PXELINUX seeks its configuration from a cache
130    of DHCP options supplied to the PXE first-stage agent, and then takes
131    action based upon those options.
133    Most frequently, this implies loading via Trivial File Transfer
134    Protocol (TFTP) [6] one or more images that are decompressed into
135    memory, then executed to pass execution to the final Host Operating
136    System.
138    PXELINUX uses DHCP options 208-211 to govern parts of this bootstrap
139    process, but these options are not requested by the PXE DHCP client
140    at the time it acquires its lease.  At that time, the PXE bootloader
141    has no knowledge that PXELINUX is going to be in use, and even so,
142    would have no way to know what option(s) PXELINUX might digest.
143    Local installations that serve this PXELINUX image to its clients
144    must also configure their DHCP servers to provide these options even
145    though they are not on the DHCP Parameter Request List [4].
147    These options are:
149    o  "MAGIC" - 208 - An option whose presence and content verifies to
150       the PXELINUX bootloader that the options numbered 209-211 are for
151       the purpose as described herein.
153    o  "ConfigFile" - 209 - Configures the path/filename component of the
154       configuration file's location, which this bootloader should use to
155       configure itself.
157    o  "PathPrefix" - 210 - Configures a value to be prepended to the
158       ConfigFile to discern the directory location of the file.
160    o  "RebootTime" - 211 - Configures a timeout after which the
161       bootstrap program will reboot the system (most likely returning it
162       to PXE).
164    Historically, these option codes numbering from 208-211 were
165    designated 'Site Local', but after publication of RFC3942 [8], they
166    were made available for allocation as new standard DHCP options.
170 Hankins                      Informational                      [Page 3]
172 RFC 5071                    PXELINUX Options               December 2007
175    This document marks these codes as assigned.
177    This direct assignment of option code values in the option
178    definitions below is unusual as it is not mentioned in DHCP Option
179    Code assignment guidelines [5].  This document's Option Code
180    assignments are done within RFC 3942's provisions for documenting
181    prior use of option codes within the new range (128-223 inclusive).
183 2.  Terminology
185    o  "first-stage bootloader" - Although a given bootloading order may
186       have many stages, such as where a BIOS boots a DOS Boot Disk,
187       which then loads a PXE executable, it is, in this example, only
188       the PXE executable that this document describes as the "first-
189       stage bootloader" -- in essence, this is the first stage of
190       booting at which DHCP is involved.
192    o  "second-stage bootloader" - This describes a program loaded by the
193       first-stage bootloader at the behest of the DHCP server.
195    o  "bootloader" and "network bootstrap agent" - These are synonyms,
196       excepting that "bootloader" is intentionally vague in that its
197       next form of bootstrapping may not in fact involve network
198       resources.
200    The key words "MAY", "MUST", "MUST NOT", "SHOULD", and "SHOULD NOT"
201    in this document are to be interpreted as described in RFC 2119 [2].
203 3.  MAGIC Option
205 3.1.  Description
207    If this option is provided to the PXE bootloader, then the value is
208    checked by PXELINUX to match the octet string f1:00:74:7e.  If this
209    matches, then PXELINUX bootloaders will also consume options 209-211,
210    as described below.  Otherwise, they are ignored.
212    This measure was intended to ensure that, as the 'Site Local' option
213    space is not allocated from a central authority, no conflict would
214    result in a PXELINUX bootloader improperly digesting options intended
215    for another purpose.
226 Hankins                      Informational                      [Page 4]
228 RFC 5071                    PXELINUX Options               December 2007
231 3.2.  Packet Format
233    The MAGIC Option format is as follows:
235               Code    Length     m1       m2       m3       m4
236            +--------+--------+--------+--------+--------+--------+
237            |   208  |    4   |  0xF1  |  0x00  |  0x74  |  0x7E  |
238            +--------+--------+--------+--------+--------+--------+
240    The code for this option is 208.  The length is always four.
242 3.3.  Applicability
244    This option is absolutely inapplicable to any other purpose.
246 3.4.  Response to RFC 3942
248    The option code 208 will be adopted for this purpose and immediately
249    deprecated.  Future standards action may return this option to an
250    available status should it be necessary.
252    A collision of the use of this option is harmless (at least from
253    PXELINUX' point of view) by design: if it does not match the
254    aforementioned magic value, the PXELINUX bootloader will take no
255    special action.
257    The PXELINUX project will deprecate the use of this option; future
258    versions of the software will not evaluate its contents.
260    It is reasonable to utilize this option code for another purpose, but
261    it is recommended to do this at a later time, given the desire to
262    avoid potential collisions in legacy user bases.
264 4.  Configuration File Option
266 4.1.  Description
268    Once the PXELINUX executable has been entered from the PXE
269    bootloader, it evaluates this option and loads a file of that name
270    via TFTP.  The contents of this file serve to configure PXELINUX in
271    its next stage of bootloading (specifying boot image names,
272    locations, boot-time flags, text to present the user in menu
273    selections, etc).
275    In the absence of this option, the PXELINUX agent will search the
276    TFTP server (as determined by PXE prior to this stage) for a config
277    file of several default names.
282 Hankins                      Informational                      [Page 5]
284 RFC 5071                    PXELINUX Options               December 2007
287 4.2.  Packet Format
289    The Configuration File Option format is as follows:
291               Code    Length    Config-file...
292            +--------+--------+--------+--------+--------+--------+
293            |   209  |    n   |   c1   |   c2   |   ...  |   c(n) |
294            +--------+--------+--------+--------+--------+--------+
296    The code for this option is 209.  The Config-file (c1..c(n)) is an
297    NVT-ASCII [1] printable string; it is not terminated by a zero or any
298    other value.
300 4.3.  Applicability
302    Any bootloader, PXE or otherwise, that makes use of a separate
303    configuration file rather than containing all configurations within
304    DHCP options (which may be impossible due to the limited space
305    available for DHCP options) may conceivably make use of this option.
307 4.4.  Response to RFC 3942
309    The code 209 will be adopted for this purpose.
311 4.5.  Client and Server Behaviour
313    The Config File Option MUST be supplied by the DHCP server if it
314    appears on the Parameter Request List, but MUST also be supplied if
315    the server administrator believed it would later be useful to the
316    client (such as because the server is configured to offer a second-
317    stage boot image, which they know will make use of it).  The option
318    MUST NOT be supplied if no value has been configured for it, or if a
319    value of zero length has been configured.
321    The DHCP client MUST only cache this option in a location the second-
322    stage bootloader may access.
324    The second-stage bootloader MUST, in concert with other DHCP options
325    and fields, use this option's value as a filename to be loaded via
326    TFTP and read for further second-stage-loader-specific configuration
327    parameters.  The format and content of such a file is specific to the
328    second-stage bootloader, and as such, is out of scope of this
329    document.
338 Hankins                      Informational                      [Page 6]
340 RFC 5071                    PXELINUX Options               December 2007
343 5.  Path Prefix Option
345 5.1.  Description
347    In PXELINUX' case, it is often the case that several different
348    environments would have the same TFTP path prefix, but would have
349    different filenames (for example: hosts' bootloader images and config
350    files may be kept in a directory structure derived from their Media
351    Access Control (MAC) address).  Consequently, it was deemed
352    worthwhile to deliver a TFTP path prefix configuration option, so
353    that these two things could be configured separately in a DHCP Server
354    configuration: the prefix and the possibly host-specific file
355    location.
357    The actual filename that PXELINUX requests from its TFTP server is
358    derived by prepending this value to the Config File Option above.
359    Once this config file is loaded and during processing, any TFTP file
360    paths specified within it are similarly processed -- prepending the
361    contents of this option.
363 5.2.  Packet Format
365    The Path Prefix Option format is as follows:
367               Code    Length   Path-Prefix...
368            +--------+--------+--------+--------+--------+--------+
369            |   210  |    n   |   p1   |   p2   |   ...  |   p(n) |
370            +--------+--------+--------+--------+--------+--------+
372    The code for this option is 210.  The Path Prefix is an NVT-ASCII
373    printable string; it is not terminated by zero or any other value.
375 5.3.  Applicability
377    This option came into existence because server administrators found
378    it useful to configure the prefix and suffix of the config file path
379    separately.  A group of different PXE booting clients may use the
380    same path prefix, but different filenames, or vice versa.
382    The 'shortcut' this represents is worthwhile, but it is questionable
383    whether that needs to manifest itself on the protocol wire.
394 Hankins                      Informational                      [Page 7]
396 RFC 5071                    PXELINUX Options               December 2007
399    It only becomes interesting from a protocol standpoint if other
400    options are adopted that prefix this value as well -- performing a
401    kind of string compression is highly beneficial to the limited
402    available DHCP option space.
404    But it's clearly inapplicable to any current use of, e.g., the
405    FILENAME header contents or the DHCP Boot File Name option (#67).
406    Use of these fields is encoded on firmware of thousands of devices
407    that can't or are not likely to be upgraded.  Altering any behaviour
408    here is likely to cause severe compatibility problems.
410    Although compression of the TFTP-loaded configuration file contents
411    is not a compelling factor, contrived configurations using these
412    values may also exist: where each of a large variety of different
413    clients load the same configuration file, with the same contents, but
414    due to a differently configured path prefix actually load different
415    images.  Whether this sort of use is truly needed remains unproven.
417 5.4.  Response to RFC 3942
419    The code 210 will be adopted for this purpose.
421 5.5.  Client and Server Behaviour
423    The Path Prefix option MUST be supplied by the DHCP server if it
424    appears on the Parameter Request List, but MUST also be supplied if
425    the server administrator believed it would later be useful to the
426    client (such as because the server is configured to offer a second-
427    stage boot image that they know will make use of it).  The option
428    MUST NOT be supplied if no value has been configured for it, or if a
429    value of zero length has been configured.
431    The DHCP client MUST only cache this option in a location where the
432    second-stage bootloader may access it.
434    The second-stage bootloader MUST prepend this option's value, if any,
435    to the contents of the ConfigFile option prior to obtaining the
436    resulting value via TFTP, or the default 'Config File Search Path',
437    which the second-stage bootloader iterates in the absence of a Config
438    File Option.  The client MAY prepend the value to other configuration
439    directives within that file once it has been loaded.  The client MUST
440    NOT prepend this option's value to any other DHCP option contents or
441    field, unless explicitly stated in a document describing that option
442    or field.
450 Hankins                      Informational                      [Page 8]
452 RFC 5071                    PXELINUX Options               December 2007
455 6.  Reboot Time Option
457 6.1.  Description
459    Should PXELINUX be executed, and then for some reason, be unable to
460    reach its TFTP server to continue bootstrapping, the client will, by
461    default, reboot itself after 300 seconds have passed.  This may be
462    too long, too short, or inappropriate behaviour entirely, depending
463    on the environment.
465    By configuring a non-zero value in this option, admins can inform
466    PXELINUX of which specific timeout is desired.  The client will
467    reboot itself if it fails to achieve its configured network resources
468    within the specified number of seconds.
470    This reboot will run through the system's normal boot-time execution
471    path, most likely leading it back to PXE and therefore PXELINUX.  So,
472    in the general case, this is akin to returning the client to the DHCP
473    INIT state.
475    By configuring zero, the feature is disabled, and instead the client
476    chooses to remove itself from the network and wait indefinitely for
477    operator intervention.
479    It should be stressed that this is in no way related to configuring a
480    lease time.  The perceived transition to INIT state is due to client
481    running state -- reinitializing itself -- not due to lease timer
482    activity.  That is, it is not safe to assume that a PXELINUX client
483    will abandon its lease when this timer expires.
485 6.2.  Packet Format
487    The Reboot Time Option format is as follows:
489               Code    Length
490            +--------+--------+--------+--------+--------+--------+
491            |   211  |    4   |            Reboot Time            |
492            +--------+--------+--------+--------+--------+--------+
494    The code for this option is 211.  The length is always four.  The
495    Reboot Time is a 32-bit (4 byte) integer in network byte order.
506 Hankins                      Informational                      [Page 9]
508 RFC 5071                    PXELINUX Options               December 2007
511 6.3.  Applicability
513    Any network bootstrap program in any sufficiently complex networking
514    environment could conceivably enter into such a similar condition,
515    either due to having its IP address stolen out from under it by a
516    rogue client on the network, by being moved between networks where
517    its PXE-derived DHCP lease is no longer valid, or any similar means.
519    It seems desirable for any network bootstrap agent to implement an
520    ultimate timeout for it to start over.
522    The client may, for example, get different working configuration
523    parameters from a different DHCP server upon restarting.
525 6.4.  Response to RFC 3942
527    The code 211 will be adopted for this purpose.
529 6.5.  Client and Server Behaviour
531    The Reboot Time Option MUST be supplied by the DHCP server if it
532    appears on the Parameter Request List, but MUST also be supplied if
533    the server administrator believed it would later be useful to the
534    client (such as because the server is configured to offer a second-
535    stage boot image that they know will make use of it).  The option
536    MUST NOT be supplied if no value has been configured for it, or if it
537    contains a value of zero length.
539    The DHCP client MUST only cache this option in a location the second-
540    stage bootloader may access.
542    If the value of this option is nonzero, the second-stage bootloader
543    MUST schedule a timeout: after a number of seconds equal to this
544    option's value have passed, the second-stage bootloader MUST reboot
545    the system, ultimately returning the path of execution back to the
546    first-stage bootloader.  It MUST NOT reboot the system once the
547    thread of execution has been passed to the host operating system (at
548    which point, this timeout is effectively obviated).
550    If the value of this option is zero, the second-stage bootloader MUST
551    NOT schedule such a timeout at all.  Any second-stage bootloader that
552    finds it has encountered excessive timeouts attempting to obtain its
553    host operating system SHOULD disconnect itself from the network to
554    wait for operator intervention, but MAY continue to attempt to
555    acquire the host operating system indefinitely.
562 Hankins                      Informational                     [Page 10]
564 RFC 5071                    PXELINUX Options               December 2007
567 7.  Specification Conformance
569    To conform to this specification, clients and servers MUST implement
570    the Configuration File, Path Prefix, and Reboot Time options as
571    directed.
573    The MAGIC option MAY NOT be implemented, as it has been deprecated.
575 8.  Security Considerations
577    PXE and PXELINUX allow any entity acting as a DHCP server to execute
578    arbitrary code upon a system.  At present, no PXE implementation is
579    known to implement authentication mechanisms [7] so that PXE clients
580    can be sure they are receiving configuration information from the
581    correct, authoritative DHCP server.
583    The use of TFTP by PXE and PXELINUX also lacks any form of
584    cryptographic signature -- so a 'Man in the Middle' attack may lead
585    to an attacker's code being executed on the client system.  Since
586    this is not an encrypted channel, any of the TFTP loaded data may
587    also be exposed (such as in loading a "RAMDISK" image, which contains
588    /etc/passwd or similar information).
590    The use of the Ethernet MAC Address as the client's unique identity
591    may allow an attacker who takes on that identity to gain
592    inappropriate access to a client system's network resources by being
593    given by the DHCP server whatever 'keys' are required, in fact, to be
594    the target system (to boot up as though it were the target).
596    Great care should be taken to secure PXE and PXELINUX installations,
597    such as by using IP firewalls, to reduce or eliminate these concerns.
599    A nearby attacker might feed a "Reboot Time" option value of 1 second
600    to a mass of unsuspecting clients, to effect a Denial Of Service
601    (DoS) upon the DHCP server, but then again it may just as easily
602    supply these clients with rogue second-stage bootloaders that simply
603    transmit a flood of packets.
605    This document in and by itself provides no security, nor does it
606    impact existing DCHP security as described in RFC 2131 [3].
608 9.  IANA Considerations
610    IANA has done the following:
612    1.  Moved DHCPv4 Option code 208 from 'Tentatively Assigned' to
613        'Assigned', referencing this document.  IANA has marked this same
614        option code, 208, as Deprecated.
618 Hankins                      Informational                     [Page 11]
620 RFC 5071                    PXELINUX Options               December 2007
623    2.  Moved DHCPv4 Option code 209 from 'Tentatively Assigned' to
624        'Assigned', referencing this document.
626    3.  Moved DHCPv4 Option code 210 from 'Tentatively Assigned' to
627        'Assigned', referencing this document.
629    4.  Moved DHCPv4 Option code 211 from 'Tentatively Assigned' to
630        'Assigned', referencing this document.
632 10.  Acknowledgements
634    These options were designed and implemented for the PXELINUX project
635    by H. Peter Anvin, and he was instrumental in producing this
636    document.  Shane Kerr has also provided feedback that has improved
637    this document.
639 11.  References
641 11.1.  Normative References
643    [1]  Postel, J. and J. Reynolds, "Telnet Protocol Specification",
644         STD 8, RFC 854, May 1983.
646    [2]  Bradner, S., "Key words for use in RFCs to Indicate Requirement
647         Levels", BCP 14, RFC 2119, March 1997.
649    [3]  Droms, R., "Dynamic Host Configuration Protocol", RFC 2131,
650         March 1997.
652    [4]  Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor
653         Extensions", RFC 2132, March 1997.
655    [5]  Droms, R., "Procedures and IANA Guidelines for Definition of New
656         DHCP Options and Message Types", BCP 43, RFC 2939,
657         September 2000.
659 11.2.  Informative References
661    [6]  Sollins, K., "The TFTP Protocol (Revision 2)", STD 33, RFC 1350,
662         July 1992.
664    [7]  Droms, R. and W. Arbaugh, "Authentication for DHCP Messages",
665         RFC 3118, June 2001.
667    [8]  Volz, B., "Reclassifying Dynamic Host Configuration Protocol
668         version 4 (DHCPv4) Options", RFC 3942, November 2004.
674 Hankins                      Informational                     [Page 12]
676 RFC 5071                    PXELINUX Options               December 2007
679 Author's Address
681    David W. Hankins
682    Internet Systems Consortium, Inc.
683    950 Charter Street
684    Redwood City, CA  94063
685    US
687    Phone: +1 650 423 1307
688    EMail: David_Hankins@isc.org
730 Hankins                      Informational                     [Page 13]
732 RFC 5071                    PXELINUX Options               December 2007
735 Full Copyright Statement
737    Copyright (C) The IETF Trust (2007).
739    This document is subject to the rights, licenses and restrictions
740    contained in BCP 78, and except as set forth therein, the authors
741    retain all their rights.
743    This document and the information contained herein are provided on an
744    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
745    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
746    THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
747    OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
748    THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
749    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
751 Intellectual Property
753    The IETF takes no position regarding the validity or scope of any
754    Intellectual Property Rights or other rights that might be claimed to
755    pertain to the implementation or use of the technology described in
756    this document or the extent to which any license under such rights
757    might or might not be available; nor does it represent that it has
758    made any independent effort to identify any such rights.  Information
759    on the procedures with respect to rights in RFC documents can be
760    found in BCP 78 and BCP 79.
762    Copies of IPR disclosures made to the IETF Secretariat and any
763    assurances of licenses to be made available, or the result of an
764    attempt made to obtain a general license or permission for the use of
765    such proprietary rights by implementers or users of this
766    specification can be obtained from the IETF on-line IPR repository at
767    http://www.ietf.org/ipr.
769    The IETF invites any interested party to bring to its attention any
770    copyrights, patents or patent applications, or other proprietary
771    rights that may cover technology that may be required to implement
772    this standard.  Please address the information to the IETF at
773    ietf-ipr@ietf.org.
786 Hankins                      Informational                     [Page 14]