RFC 5071

Dynamic Host Configuration Protocol Options Used by PXELINUX

📅 published December 2007, from ietf

RFC 5071 🎀 Dynamic Host Configuration Protocol Options Used by PXELINUX

Okay bestie, this is RFC 5071 💖 and it's called Dynamic Host Configuration Protocol Options Used by PXELINUX. It came from the Network Working Group and was written by D. Hankins at ISC 👑. It's Category: Informational 📚 and it's dated December 2007 🌸. The header doesn't list anything it obsoletes or updates, so it isn't replacing or changing any other RFC 🙈.

Status of This Memo ✨

This memo provides information for the Internet community. It does not specify an Internet standard of any kind, and distribution of this memo is unlimited 🦋.

Abstract 💜

Basically, this document is about how PXELINUX uses some DHCP Option Codes numbering from 208-211 🧚.

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

1. Introduction ✨

Okay so, PXE (the Preboot eXecution Environment) is a first-stage network bootstrap agent 🦋. It's loaded out of the firmware on the client host, and it does DHCP [3] queries to get an IP address.

Once it's on the network, it loads a second-stage bootstrap agent, based on what the DHCP header and option contents tell it to do 🍓.

PXELINUX is one of those second-stage bootstrap agents 💅. Once PXE hands execution over to it, PXELINUX looks for its configuration in a cache of DHCP options that were supplied to the PXE first-stage agent, and then takes action based on those options.

Most often, this means loading one or more images over Trivial File Transfer Protocol (TFTP) [6]. Those images get decompressed into memory and then run, which passes execution to the final Host Operating System 🔥.

PXELINUX uses DHCP options 208-211 to control parts of this bootstrap process 🫶. These options aren't requested by the PXE DHCP client when it acquires its lease, though. At that point the PXE bootloader has no clue PXELINUX is going to be in use, and even if it did, it wouldn't know which option(s) PXELINUX might digest 🙈. Local installations that serve this PXELINUX image to their clients have to configure their DHCP servers to provide these options anyway, even though they aren't on the DHCP Parameter Request List [4] 💀.

These options are:

"MAGIC" - 208 - An option whose presence and content lets the PXELINUX bootloader verify that options 209-211 are meant for the purpose described here 🔮.
"ConfigFile" - 209 - Sets the path/filename part of the configuration file's location, which this bootloader should use to configure itself 🎀.
"PathPrefix" - 210 - Sets a value that gets prepended to the ConfigFile to work out the directory location of the file 🗺️.
"RebootTime" - 211 - Sets a timeout after which the bootstrap program reboots the system (most likely sending it back to PXE) ⏰.

Historically, these option codes numbering from 208-211 were designated 'Site Local' 🕰️. After RFC3942 [8] came out, though, they were made available for allocation as new standard DHCP options 🌈.

This document marks these codes as assigned ✅.

Now, this direct assignment of option code values in the option definitions below is pretty unusual 🤔. It isn't mentioned in the 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 📖

"first-stage bootloader" - A boot order can have lots of stages, like a BIOS booting a DOS Boot Disk that then loads a PXE executable. In that example, only the PXE executable is what this document calls the "first-stage bootloader". It's basically the first stage of booting where DHCP is involved 🌸.
"second-stage bootloader" - A program that the first-stage bootloader loads at the behest of the DHCP server 🧚.
"bootloader" and "network bootstrap agent" - These are synonyms, except that "bootloader" is intentionally vague, since its next form of bootstrapping may not actually involve network resources 🫶.

Ok so 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 PXELINUX checks that the value matches the octet string f1:00:74:7e 🔍. If it matches, PXELINUX bootloaders will also consume options 209-211, as described below. Otherwise, they get ignored 🙅.

This measure was intended to make sure that, since the 'Site Local' option space isn't allocated from a central authority, no conflict would make a PXELINUX bootloader improperly digest options meant for some other purpose 🛡️.

3.2. Packet Format

The MAGIC Option format looks like this:

           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 totally, absolutely not for 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 on this option is harmless (at least from PXELINUX' point of view) by design. If it doesn't match the aforementioned magic value, the PXELINUX bootloader takes no special action 😌.

The PXELINUX project will deprecate the use of this option. Future versions of the software won't evaluate its contents 👋.

It's reasonable to use this option code for another purpose, but it's recommended to do that 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 that file configure PXELINUX for its next stage of bootloading. That covers things like boot image names, locations, boot-time flags, and text to show the user in menu selections, etc 🍽️.

Without this option, the PXELINUX agent searches the TFTP server (as determined by PXE prior to this stage) for a config file with several default names 🔎.

4.2. Packet Format

The Configuration File Option format looks like this:

           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 isn't terminated by a zero or any other value 🧵.

4.3. Applicability

Any bootloader, PXE or otherwise, that uses a separate configuration file, rather than putting all of its configuration in DHCP options (which can be impossible because DHCP options only have so much space), might 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 it MUST also be supplied if the server administrator believed it would later be useful to the client. An example would be a server 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 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 are specific to the second-stage bootloader, so they're out of scope for this document 🙌.

5. Path Prefix Option 🛤️

5.1. Description

So in PXELINUX' case, it's often that several different environments share the same TFTP path prefix but have different filenames. For example, hosts' bootloader images and config files might be kept in a directory structure derived from their Media Access Control (MAC) address 💻. That's why it was deemed worthwhile to deliver a TFTP path prefix configuration option. That way the two things can 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 that config file is loaded and during processing, any TFTP file paths specified within it are processed the same way, by prepending the contents of this option 🌟.

5.2. Packet Format 💅

okay so here's what the Path Prefix Option looks like on the wire 👀

              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 🎀, and it is not terminated by zero or any other value (no null terminator, bestie 🙈).

5.3. Applicability 🧚

so this option exists because server admins found it super useful to set the prefix and the suffix of the config file path separately 💖. a bunch of different PXE booting clients might share the same path prefix but use different filenames, or the other way round 🌸.

the 'shortcut' this represents is worth it, but ngl it's questionable whether it actually needs to show up on the protocol wire 🤔.

it only gets interesting from a protocol standpoint if other options get adopted that prefix this value too, bc a kind of string compression is highly beneficial when the DHCP option space is so limited 🫶.

but it's clearly not applicable to any current use of, e.g., the FILENAME header contents or the DHCP Boot File Name option (#67) 🚫. these fields are baked into firmware on thousands of devices that can't or aren't likely to get upgraded 😭, so altering any behaviour here is likely to cause severe compatibility problems 💀.

compression of the TFTP-loaded config file contents isn't a compelling factor, but contrived setups using these values might exist. picture lots of different clients loading the same config file with the same contents, but a differently configured path prefix makes them actually load different images 👑. whether this sort of use is truly needed is still unproven ✨.

5.4. Response to RFC 3942 🎀

the code 210 will be adopted for this purpose 💅.

5.5. Client and Server Behaviour 📜

okay, the rules part, so listen up 👂

the DHCP server MUST supply the Path Prefix option if it shows up on the Parameter Request List 💌. the server MUST also supply it if the server administrator thinks it'll be useful to the client later on (like if the server offers a second-stage boot image that they know will use it) 🧠. the option MUST NOT be supplied if no value has been configured for it, or if a zero-length value has been configured 🙅.

the DHCP client MUST only cache this option somewhere the second-stage bootloader can reach it 🗝️.

the second-stage bootloader MUST prepend this option's value (if there is one) to the contents of the ConfigFile option before it fetches the resulting value via TFTP. it does the same to the default 'Config File Search Path', which the second-stage bootloader works through when there's no Config File Option 🛣️. the client MAY also prepend the value to other configuration directives within that file once it's loaded 📄. the client MUST NOT prepend this option's value to any other DHCP option contents or field, unless a document describing that option or field explicitly says so 🚫.

6. Reboot Time Option ⏰

6.1. Description 🔄

so picture this: PXELINUX runs, and then for some reason it can't reach its TFTP server to keep bootstrapping 😱. by default, the client reboots itself after 300 seconds have passed. that might be too long, too short, or just totally inappropriate behaviour, depending on the environment 🙃.

by configuring a non-zero value in this option, admins can tell PXELINUX exactly which timeout they want 🎯. the client reboots itself if it fails to get its configured network resources within that many seconds ⏱️.

this reboot runs through the system's normal boot-time execution path, which most likely leads it back to PXE and therefore PXELINUX 🔁. so in the general case, it's kinda like sending the client back to the DHCP INIT state 🫠.

by configuring zero, the feature is disabled, and the client instead removes itself from the network and waits indefinitely for operator intervention 🧍.

it's worth stressing that this has nothing to do with configuring a lease time ❗. the perceived move back to INIT state comes from the client's running state (it's reinitializing itself), not from lease timer activity. so it's not safe to assume a PXELINUX client will abandon its lease when this timer expires 🚨.

6.2. Packet Format 📦

the Reboot Time Option format looks like this:

              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 💜.

6.3. Applicability 🌍

any network bootstrap program in any sufficiently complex networking environment could end up in a similar situation 😬. maybe its IP address gets stolen out from under it by a rogue client on the network, maybe it gets moved between networks where its PXE-derived DHCP lease isn't valid anymore, or maybe it's some other similar thing.

it seems desirable for any network bootstrap agent to have an ultimate timeout so it can start over 🔁.

the client might, for example, get different working configuration parameters from a different DHCP server when it restarts 🤷.

6.4. Response to RFC 3942 🎀

the code 211 will be adopted for this purpose 💅.

6.5. Client and Server Behaviour 📜

the DHCP server MUST supply the Reboot Time Option if it shows up on the Parameter Request List 💌. the server MUST also supply it if the server administrator thinks it'll be useful to the client later (like if the server offers a second-stage boot image that they know will use it) 🧠. the option MUST NOT be supplied if no value has been configured for it, or if it contains a zero-length value 🙅.

the DHCP client MUST only cache this option somewhere the second-stage bootloader can access it 🗃️.

if the value of this option is nonzero, the second-stage bootloader MUST schedule a timeout ⏲️. once a number of seconds equal to this option's value has 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 that point the timeout is basically moot 🫥).

if the value of this option is zero, the second-stage bootloader MUST NOT schedule such a timeout at all 0️⃣🚫. any second-stage bootloader that finds it has run into excessive timeouts trying to obtain its host operating system SHOULD disconnect itself from the network to wait for operator intervention 🙋. it MAY continue trying to acquire the host operating system indefinitely ♾️.

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 🚨

⚠️ okay bestie, this section is seriously important, so read it carefully 🫶

PXE and PXELINUX let any entity acting as a DHCP server execute arbitrary code on a system 😱. right now, no PXE implementation is known to implement authentication mechanisms [7], so PXE clients can't be sure they're getting 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 isn't an encrypted channel, any of the TFTP-loaded data may also be exposed (like when loading a "RAMDISK" image, which contains /etc/passwd or similar information) 🫣.

using 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. the DHCP server can hand over whatever 'keys' are required to actually be the target system, so the attacker can boot as though they 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:

Moved DHCPv4 Option code 208 from 'Tentatively Assigned' to 'Assigned', referencing this document. IANA has marked this same option code, 208, as Deprecated.
Moved DHCPv4 Option code 209 from 'Tentatively Assigned' to 'Assigned', referencing this document.
Moved DHCPv4 Option code 210 from 'Tentatively Assigned' to 'Assigned', referencing this document.
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.

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

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 ✨

okay so the IETF is being super clear here 💅 it takes no position on whether any Intellectual Property Rights or other rights that might be claimed to pertain to using or implementing the tech in this document are valid or in scope. it also doesn't say whether any license under those rights might or might not be available 🫠 and it hasn't made any independent effort to go hunting for those rights, so don't assume it did 🙈 if you want the rules on rights in RFC documents, check out BCP 78 and BCP 79 📚

copies of IPR disclosures sent to the IETF Secretariat are a thing, and so are any assurances of licenses that get made available. the same goes for the results of an attempt to get a general license or permission for implementers or users to use those proprietary rights 🎀 you can find all of that in the IETF's online IPR repository at http://www.ietf.org/ipr 🦋

and the IETF invites any interested party to flag its attention to any copyrights, patents or patent applications, or other proprietary rights that might cover tech needed to implement this standard 🫶 send that info to the IETF at ietf-ipr@ietf.org 💌 bestie, it's giving transparency 🌈

📦 where this page comes from

ietf: rfc5071 2007-12
💖 girlified by claude-haiku-5-5 on 2026-10-17: a language model's rewrite of the original, under its terms