Subject: Re: [dhcwg] Etherboot Project use of DHCP options

From: Richard Johnson <[email-masked]>
Date: Tue, 4 Dec 2007 13:28:35 -0800

Can we get some documentation about the format of your option 150?   
I'm wondering if your use of the number can be easily distinguished  
from Cisco's use of it as a simple list of IPv4 addresses.

/raj

On Nov 30, 2007, at 3:12 PM, Marty Connor wrote:

> Hello,
>
> First let me apologize for the lateness of this message.  We have been
> uncertain how to proceed regarding the DHCP options that our project
> ( Etherboot Project, http://etherboot.org/ ) is using.
>
> At the strong suggestion of a colleague I am writing to give status of
> our current and planned usage of tentatively assigned DHCP options,  
> and
> to ask for guidance from members of this list on how we should proceed
> to properly document our use of them.
>
> For those that might not be familiar with our project please allow  
> me to
> give  a brief introduction.  The Etherboot Project has existed since
> about 1993.  Our primary purpose has been to create and support Open
> Source network booting.  Our most well-known network booting  
> software is
> known as Etherboot.
>
> In the 14 year history of the project there have been three Project
> Leaders:  Markus Gutschke, Ken Yap, and myself (Marty Connor).   
> Each of
> us has worked to expand the capabilities of Etherboot, and in the last
> few years we have created a new network bootloader called gPXE.  gPXE
> blends features of Etherboot with features of PXE, and adds some
> extensions not present in either specification.
>
> Etherboot's method of network booting predates the PXE  
> specification and
> differs from it significantly. From using pre-wrapped binaries in NBI
> (Network Boot Image) format to handling of DHCP options.  There is a
> large installed base of systems which use Etherboot BIOS Expansion  
> ROMs
> or other media to network boot various operating systems.
>
> In 1999 we created the website:
>
>     http://rom-o-matic.net/
>
> To distribute free, on-demand, custom Etherboot ROM images.  To date
> approximately 2,000,000 Etherboot images have been downloaded.  This
> total does not include ROMs created by downloading Etherboot from
> SourceForge.net or by simply copying an existing image.
>
> In 2002 we began an effort to add PXE compatibility to Etherboot.   
> This
> involved adding the PXE API to Etherboot, while maintaining support  
> for
> legacy features.  The current release of Etherboot (5.4.3) is  
> capable of
> functioning as PXE boot ROM, with certain limitations.  Etherboot is
> capable of loading PXELINUX, running RIS and other PXE NBPs and has
> proven useful for many applications, from network booting  
> supercomputer
> clusters to enabling thin-client computing using economical hardware.
>
> In 2005 we began work on a rewrite of Etherboot called gPXE.  Our aim
> was to create a bootloader that stronger compliance with the PXE
> specification with extensions that make sense for contemporary  
> networking.
>
> Since 2005 (which is is when I became Project Leader), we have  
> focussed
> most of our development energy on gPXE, and have made significant
> progress.  gPXE is capable of both traditional PXE operation (DHCP 
> +TFTP)
> plus a number of modern network booting methods, such as:
>
>    * HTTP(S) booting
>    * iSCSI booting
>    * AoE booting
>
> Some of these network protocols required the addition of custom TCP
> stack for transport.  We also added DNS support and URL parsing to
> support multiple protocols.
>
> That's a long preamble, but hopefully will give a sense of the  
> level of
> effort we have invested in our software, and how many people have come
> to rely on it.
>
> Referring to the following document:
>
>    http://www.iana.org/assignments/bootp-dhcp-parameters
>
> I note that Etherboot is mentioned in four places:
>
>    128     Etherboot signature. 6 bytes: E4:45:74:68:00:00	
>    150     Etherboot	
>    175     Etherboot (Tentatively Assigned - 23 Jun 2005)
>    177     Etherboot (Tentatively Assigned - 23 Jun 2005)
>
> The first two (128 and 150) are in wide use.  Option 150 is where
> options for our Etherboot bootloader have long been encapsulated.  We
> also use 129 for passing kernel options in Etherboot.
>
> I note that former Project Leader Ken Yap and former developer Timothy
> Legge had begun work on securing options 175 and 177:
>
>    http://www3.ietf.org/proceedings/05aug/slides/dhc-7.pdf
>
> As early as 2002 when work on incorporating PXE into Etherboot we  
> began
> using Option 175 for encapsulation as this message from our Lead
> Developer, Michael Brown explains:
>
>    http://osdir.com/ml/network.etherboot.devel/2002-05/msg00032.html
>
> Our usage of Option 175 continues in gPXE.
>
> Our use of Option 177 is less clear.  We need to do further  
> research to
> understand our motivation for requesting that option and how we are
> currently using it.
>
> So, in summary:
>
>   * We are doing research into our use of DHCP options
>   * We will work on an RFC draft for our usage
>   * Any pointers would be appreciated.
>
> Thank you for any and all feedback regarding our situation. I once  
> more
> apologize for the lateness of this communication, and thank you in
> advance for your thoughts.
>
> Regards,
>
> Marty
>
>
>
>
> _______________________________________________
> dhcwg mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/dhcwg

_______________________________________________
dhcwg mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/dhcwg

---

From: "Bernie Volz (volz)" <[email-masked]>
Date: Tue, 4 Dec 2007 17:12:33 -0500

It would be nice to get more details on the format of all of the
options. Also, it is important to learn about which direction these
options are used in (client -> server, server->client). Does the client
only include them in the Parameter Request List OR does the client send
data in these options that is used by the server?

We already have a conflict with 128 and 129 with the PXE options.
Perhaps Etherboot's usage is compatible with the PXE options and then
there is no conflict. Perhaps there is an easy way for clients and
servers to distinguish the usage (PXE or Etherboot).

For option 150, we are planning on letting Richard's draft use that
option number. Thus, it is important to understand whether the existing
Etherboot usage would conflict with that. We might be able to update the
I-D to document how to tell the options apart and then clients and/or
servers supporting these options might want to add some conflict
detection logic.

- Bernie

-----Original Message-----
From: Richard Johnson (raj) 
Sent: Tuesday, December 04, 2007 4:29 PM
To: Marty Connor
Cc: DHC WG
Subject: Re: [dhcwg] Etherboot Project use of DHCP options

/raj

---

From: Marty Connor <[email-masked]>
Date: Thu, 06 Dec 2007 23:23:36 -0500

I have done some research into the Etherboot Project's use of DHCP
options, and hopefully this message will clarify things a bit.

First, let me explain some terms:

. "Etherboot Project" is the name of our organization. We primarily
  produce network booting software.

. "Etherboot" and "gPXE" refer to software packages produced by our
  organization.

Etherboot is our older and most widely known network booting software.
Documentation for options that Etherboot has used over the years can be
found here:

  http://www.etherboot.org/doc/html/userman/a838.html

Though all of the options mentioned in this document are not being used
in current versions of Etherboot, there are BIOS expansion ROM images
which have versions of Etherboot which may use these options,
in particular options 128, 129 have been used to pass kernel options
during network booting.

In later versions of Etherboot option 150 was used to encapsulate
Etherboot-specific options.

We did not use option 43 for encapsulating Etherboot options because a
number of the options specified there have PXE defined uses which would
conflict with Etherboot's usage.  We felt the use of a single
encapsulated option was a better (and more responsible) way to go.

Starting about 3 years ago we decided to rewrite Etherboot and call it
gPXE.  Major design goals for gPXE are closer compatibility with the
PXE, with additions to allow more flexible booting methods.

While we were at it, we decided to clean up our use of DHCP option
space.

gPXE uses option 175 exclusively to encapsulate gPXE-specific options.

. Option 43 is not used because PXE defines sub-options for that space
  that would conflict with our usage and could create potential future
  conflicts with other vendors.

. An implementation using Options 124+125 was considered but rejected
  based on two objections:

  . Code size for implementation would be significantly increased by
    adding code to manage the additional level of encapsulation.

  . Storage of options in the very limited NVS (non-volatile storage)
    on NICs would be unacceptably increased.

Of the options tentatively assigned to Etherboot Project, Option 175 was
chosen for gPXE because we knew of no other conflicts with that
particular option.

For those who might be interested below are some of the options defined
in gPXE as sub-options of option 175, I have included an excerpt from
current gPXE code, Please note that development is on-going, and thus
the definitions of these  sub-options should not be relied upon.  Also,
references to "Etherboot" and "_EB_" should be understood to be
referring to gPXE.

====== excerpt of gpxe.git/src/include/gpxe/dhcp.h ======

/** Etherboot-specific encapsulated options
 *
 * This encapsulated options field is used to contain all options
 * specific to Etherboot (i.e. not assigned by IANA or other standards
 * bodies).
 */
#define DHCP_EB_ENCAP 175

/** Priority of this options block
 *
 * This is a signed 8-bit integer field indicating the priority of
 * this block of options.  It can be used to specify the relative
 * priority of multiple option blocks (e.g. options from non-volatile
 * storage versus options from a DHCP server).
 */
#define DHCP_EB_PRIORITY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 1 )

/** "Your" IP address
 *
 * This option is used internally to contain the value of the "yiaddr"
 * field, in order to provide a consistent approach to storing and
 * processing options.  It should never be present in a DHCP packet.
 */
#define DHCP_EB_YIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 2 )

/** "Server" IP address
 *
 * This option is used internally to contain the value of the "siaddr"
 * field, in order to provide a consistent approach to storing and
 * processing options.  It should never be present in a DHCP packet.
 */
#define DHCP_EB_SIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 3 )

/*
 * Tags in the range 0x10-0x7f are reserved for feature markers
 *
 */

/** Network device descriptor
 *
 * Byte 0 is the bus type ID; remaining bytes depend on the bus type.
 *
 * PCI devices:
 * Byte 0 : 1 (PCI)
 * Byte 1 : PCI vendor ID MSB
 * Byte 2 : PCI vendor ID LSB
 * Byte 3 : PCI device ID MSB
 * Byte 4 : PCI device ID LSB
 */
#define DHCP_EB_BUS_ID DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb1 )

/** BIOS drive number
 *
 * This is the drive number for a drive emulated via INT 13.  0x80 is
 * the first hard disk, 0x81 is the second hard disk, etc.
 */
#define DHCP_EB_BIOS_DRIVE DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbd )

/** Username
 *
 * This will be used as the username for any required authentication.
 * It is expected that this option's value will be held in
 * non-volatile storage, rather than transmitted as part of a DHCP
 * packet.
 */
#define DHCP_EB_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbe )

/** Password
 *
 * This will be used as the password for any required authentication.
 * It is expected that this option's value will be held in
 * non-volatile storage, rather than transmitted as part of a DHCP
 * packet.
 */
#define DHCP_EB_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbf )

====== end excerpt ======

Source code for gPXE and Etherboot is available at:

  http://git.etherboot.org/?p=gpxe.git;a=summary

and

  http://git.etherboot.org/?p=etherboot.git;a=summary

I hope that this message helps to explain our past, current,and
planned use of DHCP options for Etherboot and gPXE. We welcome and
questions or suggestions you may have.

What would you suggest as next steps to formalize our use of
option 175?

Marty

---

From: "Bernie Volz (volz)" <[email-masked]>
Date: Fri, 7 Dec 2007 02:40:33 -0500

Marty:

Thanks for the details. I haven't followed the links you provided "for
more information" yet.

I'd just like to make sure I understand ...

Today (gPXE) only requires option 175? No other option is used?

The other options (128, 129, 150) were used in previous versions but are
not being used in the current (new) version? They may still be used in
the field, but that usage hasn't been an issue and it is likely that use
of these options will decrease over time (as equipment is
replaced/upgraded to the newer version)?

---

>What would you suggest as next steps to formalize our use of

As to my knowledge, Etherboot was the only user of option 175, it may be
possible to consider allowing Etherboot to keep that option assignment.
However, for that to happen, an informational Internet-Draft would need
to be submitted to document the Etherboot current usage. This would need
to advance through the DHC WG to be published as an RFC. These are the
steps outlined in RFC 3942.

- Bernie

-----Original Message-----
From: Marty Connor [mailto:[email-masked]] 
Sent: Thursday, December 06, 2007 11:24 PM
To: Bernie Volz (volz)
Cc: Richard Johnson (raj); DHC WG
Subject: Re: [dhcwg] Etherboot Project use of DHCP options

/** "Your" IP address
 *

/** "Server" IP address
 *

/*

/** BIOS drive number
 *

/** Username
 *

/** Password
 *

and

Marty

---

From: Marty Connor <[email-masked]>
Date: Fri, 07 Dec 2007 14:31:16 -0500

Bernie, thanks for your reply.  I have responded inline below.

> Today (gPXE) only requires option 175? No other option is used?

We certainly use a variety of other DHCP options (most notably PXE 
options) in a way that is compliant with relevant RFCs.

Option 175 is where we place options that are not currently RFC-based 
but are needed for features particular to gPXE.

> replaced/upgraded to the newer version)?

That's a fair statement.  To clarify: Many people currently use 
Etherboot versions which use options 128, 129, and 150, and we still 
distribute Etherboot versions via source code and pre-compiled binary 
image ( http://rom-o-matic.net/ ) that use options 128, 129, 150, and to 
a lesser extent, others.

In releasing gPXE we expect the usage of Etherboot to decrease, as we 
will be:

   * Providing what we believe will be compelling new network  booting
     functionality, (iSCSI, AoE, HTTP(S))

   * Improving compliance with the PXE specification.

   * Providing a migration path for Etherboot users through support of
     .nbi loading.

It is our expectation that gPXE will replace Etherboot in many 
instances, and Etherboot usage (and thus use of conflicting/unassigned 
options) will decrease.  How much, how soon, we'll have to wait and see.

> steps outlined in RFC 3942.

We are interested in creating an informational Internet-Draft for option 
175.  I have read RFC 3942 and see that we are past the deadline 
outlined in the document, so I hope we may be allowed an extension in 
order to participate in the process.

I have a few questions about the Internet-Draft process that I am hoping 
  you (or others) might answer:

   * As or use of option 175 is for gPXE-specific encapsulated options,
     and as the encapsulated content may change as we continue
     development, is it permissible to document our current usage with
     the caution that the encapsulated contents may change?

     We expect to add additional values to the encapsulated option over
     time, and may wish to redefine the format or function of
     sub-options.

     As we are an Open Source project, the format and usage of the
     encapsulated options will be documented in our code, so the opacity
     of the the option is to avoid errata as extend network booting in
     various ways.

   * Might someone point me toward a Internet-Draft that deals with
     encapsulated options which I might use as a reference.

That's all I can think of at the moment.  Thank you very much for your 
assistance with this process.  We will do our best to return the favor.

Marty

---

From: Richard Johnson <[email-masked]>
Date: Wed, 19 Dec 2007 15:40:55 -0800

Responses inline...

>   http://www.etherboot.org/doc/html/userman/a838.html

However, option 150 is not mentioned on this web page.

<snip>

> Etherboot-specific options.

Can we get some documentation about the exact format of this option?   
We're still trying to figure out if we can document how to  
distinguish between this use of "150" and Cisco's TFTP Server Address  
use of the same option number.

/raj

---

From: Marty Connor <[email-masked]>
Date: Fri, 21 Dec 2007 19:29:53 -0500

Hello Richard,

I asked our lead developer Michael Brown to look into how option 150 is 
used by our Etherboot network bootloader.  I have inserted his response 
below.

Please let me know if I can provide more information.

Best Regards,

Marty

-------- Original Message --------
Subject: Re: [Fwd: Re: [dhcwg] Etherboot Project use of DHCP options]
Date: Sat, 22 Dec 2007 00:06:26 +0000 (GMT)
From: Michael Brown <[email-masked]>
To: Marty Connor <[email-masked]>
References: <[email-masked]>

 > Can we get some documentation about the exact format of this option?

It's an encapsulated-option field; the following ISC dhcpd.conf extract
should provide enough information:

   option space etherboot;
   option etherboot-encap-opts code 150 = encapsulate etherboot;
   option etherboot.nic-dev-id code 175 = string;
   option etherboot.cpu-arch code 177 = unsigned integer 16;
   option etherboot.magic code 128 = string;

The DHCPDISCOVER will not contain an option 150; the DHCPREQUEST will
always contain an option 150, and Etherboot will respond to options
encapsulated within option 150 only if the option etherboot.magic starts
with the string e4:45:74:68.

(This is deduced from observation of the source code; I haven't tested
these observations but they agree with my memory from several years ago.)

Michael

Richard Johnson wrote:
> We're still trying to figure out if we can document how to distinguish 
> between this use of "150" and Cisco's TFTP Server Address use of the 
> same option number.
> 
> /raj

---

From: "Bernie Volz (volz)" <[email-masked]>
Date: Fri, 28 Dec 2007 15:07:06 -0500

Marty/Richard:

It seems to me that there shouldn't really be a conflict as for
Etherboot to use option 150, requires the magic value to be in option
128. Also, for Etherboot this option 150 is client to server; not server
to client. Whereas the VoIP Configuration Server Address option is
server to client (client requests in PRL).

Thus, only if a device that needed the VoIP Configuration Server Address
Option *AND* used Etherboot would there be an issue; and even then there
may not be an issue.

- Bernie

-----Original Message-----
From: Marty Connor [mailto:[email-masked]] 
Sent: Friday, December 21, 2007 7:30 PM
To: Richard Johnson (raj)
Cc: Marty Connor; Bernie Volz (volz); DHC WG
Subject: Re: [dhcwg] Etherboot Project use of DHCP options

Hello Richard,

Best Regards,

Marty

-------- Original Message --------
Subject: Re: [Fwd: Re: [dhcwg] Etherboot Project use of DHCP options]
Date: Sat, 22 Dec 2007 00:06:26 +0000 (GMT)
From: Michael Brown <[email-masked]>
To: Marty Connor <[email-masked]>
References: <[email-masked]>

   option space etherboot;

(This is deduced from observation of the source code; I haven't tested
these observations but they agree with my memory from several years
ago.)

Michael