Netboot 2.0: Boot Server Discovery Protocol (BSDP) : Author: Date
Netboot 2.0: Boot Server Discovery Protocol (BSDP) : Author: Date
Netboot 2.0: Boot Server Discovery Protocol (BSDP) : Author: Date
0:
Boot Server Discovery Protocol (BSDP)
Author: Dieter Siegmund, dieter@apple.com
Date: December 8, 2003
Version: 1.0.7
1 Introduction
A NetBoot 2.0 client uses the Boot Server Discovery Protocol (BSDP) to dynamically
acquire resources that enable it to boot a suitable operating system. The client uses DHCP
to acquire its IP address and BSDP to acquire boot image resources. The protocols are
initiated by the client at boot time.
This document describes the protocol and how it interoperates with DHCP. It also
describes specifics of the packet encodings and the client and server logic.
The protocol is implemented in client firmware. At boot time, the client obtains an IP
address via DHCP (RFC 2131) then discovers boot servers using BSDP. Each BSDP
server responds with boot information consisting of:
1. A list of bootable operating system images
2. The default operating system image
3. The client’s currently selected operating system image (if defined)
The client chooses an operating system from the list and sends a message to the server
indicating its selection. The selected boot server responds supplying the boot file and
boot image, and any other information needed to download and execute the selected
operating system. The client receives the message then downloads the boot image using
TFTP and begins executing it.
Once a client has configured a boot image with a particular BSDP server, that server
responds to the client’s subsequent DISCOVER requests supplying boot image
information in the OFFER. This means that the client can skip BSDP on subsequent
reboots.
BSDP uses DHCP INFORM and ACK packets for the communication between the client
and server. The Vendor Class Identifier option is set to a value that identifies it as a
BSDP packet. The Vendor Specific Information option includes a BSDP Message Type
option that specifies one of LIST, SELECT, or FAILED.
The next section gives an overview of the packet exchanges used by a client during its
first boot. Subsequent sections describe the packet exchanges used during subsequent
boots.
Notational note: In the sections that follow, a DHCP packet that contains a BSDP
Message Type option is written as “DHCP message[BSDP message]”. For example, a
DHCP INFORM packet with the BSDP Message Type option set to LIST is written as
INFORM[LIST].
Step 1. Client
DHCP Step 2.
DISCOVER
Server
OFFER
Step 3. Client
REQUEST DHCP Step 4.
ACK Server
Step 5. Client
BSDP
INFORM[LIST] Step 6.
Server
ACK [LIST]
Step 7. Client
INFORM[SELECT] BSDP
Step 8.
Server
ACK [SELECT]
Step 9. Client
TFTP READ
BSDP
file (from Step 10.
Server
ACK[SELECT])
TFTP Data block 0
Steps 9 and onward: Client TFTP’s boot file from BSDP server
The client sends a TFTP Read request to the BSDP server specifying the path file, the
server responds with Data block 0, the client replies with an ack, the server sends the next
data block, and so on until the entire image is downloaded. The client begins executing
the image.
1
Details on client selection criteria are discussed fully in a later section.
OFFER*
Step 3. Client
DHCP
REQUEST Step 4.
Server
ACK
Step 5. Client
BSDP
TFTP READ Step 6.
Server
file (from
ACK[SELECT]) TFTP Data block 0
[ etc. ]
Steps 5 and onward. Client TFTP’s boot file from BSDP server
Options defined in RFC 2132 are denoted as “DHCP option code xxx” in the descriptions
that follow. Options appearing inside the Vendor Specific Information option are
denoted as “BSDP option code xxx”.
The boot_image_id is encoded as two 16-bit values: Attributes and Index. The Attributes
field contains attributes of the image. The Index is the identifier for the image and is
encoded as a uint16.
The boot_image_id value zero (0) is used to denote the null image, and will never appear in
messages from the server.
The Attributes field contains information about the type of image and includes the Install
bit and the Kind field. When Install is set (I=1), the image is an installation image.
When it is not set (I=0), the image is not an installation image. The Kind field indicates
the kind of image. There are four kinds of images defined in the table: Mac OS 9, Mac
OS X, Mac OS X Server, and Hardware Diagnostics (see the table above for the values).
All remaining values are reserved for future use. The remaining bits of the Attributes
field are reserved for future use, and must not be interpreted by the client.
The Index field is broken into two value ranges. One range (0x1..0xfff) is reserved for
server-specific images. The second range (0x1000..0xffff) is reserved for images that are
globally unique and are served by multiple NetBoot servers. An Index value of zero (0)
is not valid in messages from the server (see the discussion above describing
boot_image_id).
The Index allows differentiation between multiple occurrences of one Kind of image and
helps form a unique identifier for the image.
Every packet that is sent by a BSDP client and server contains this option. It is encoded
as an ascii_string containing “AAPLBSDPC” in messages from the server and
“AAPLBSDPC/<arch>/<system_id>” in messages from the client.
<arch> indicates the architecture of the client. The defined values are “ppc” and “i386”.
<system_id> contains a value that identifies the client’s system type and revision.
On Apple hardware, the <arch> contains “ppc” and the <system_id> contains the model
property taken from the Open Firmware device tree root node
“device-tree:/”. Two example values are “PowerMac3,1” and “PowerBook2,1”.
This option may appear more than once in responses from the server.
This length of this option is two. It is encoded as a uint16 with value 0x0101
(corresponding to version 1.1):
Code Length Version
2 2 0x01 0x01
One purpose of this option is to help distribute load amongst several BSDP servers. A
BSDP server lowers its priority as it becomes busier, encouraging clients to select a
server that’s less busy.
This option is a uint16 with a range from 0, the lowest priority, to 65535, the highest
priority. The client favors responses with the highest priority value.
The purpose of this option is to make it easier to write a BSDP client that runs on a
particular operating system. The BOOTP/DHCP client port, UDP port 68, may be in use
by a regular DHCP client, so having the server redirect its response allows the client to
use a generic UDP port.
Note: this port must be a privileged port i.e. it must have a value less than 1024.
3.4.10 BSDP Boot Image List Path option: BSDP option code 6 (NOT USED)
The purpose of this option is to provide the boot image list information in a format that
includes an icon for each image. This format is too large to fit inside the ACK[LIST]
packet itself, so must be retrieved using TFTP.
This option is encoded as a boot_image_id. Its length is 4 and the encoding is:
Code Length Default Boot Image ID
7 4 i1 i2 i3 i4
This option is encoded as a boot_image_id. Its length is 4 and the encoding is:
Code Length Selected Boot Image ID
8 4 i1 i2 i3 i4
This option may appear multiple times, in multiple instances of the Vendor Specific
option. Multiple instances are likely because the Vendor Specific option is limited to 255
bytes, and the server may have many images to vend. Regardless of where the instances
of this option occur, the client must be able to retrieve all of them, and re-construct a
single, concatenated list of images.
Image Description 2
ID 2 Count Name 1
(4) 2 (C2)
(1)
i1 i2 i3 i4 C2 N N … NC2
1 2
Image Description k
ID k Count k Name 1
(4) (1) (Ck)
i1 i2 i3 i4 Ck N N … NCk
1 2
After the Code byte and Length byte come any number of Image Description’s. An Image
Description contains a 4-byte ID, followed by a 1-byte Count, followed by Count-bytes of
Name. ID is encoded as a boot_image_id (see 3.4.2). The Name is encoded as a UTF-8
string. The overall length L of this option is:
L = 5k + SUM(Cj, j = 1, j <= k)
The client should set the Maximum DHCP Message Size option (code 57) to the
maximum value allowed by the physical medium. For Ethernet this should be set to
0x5dc (1500). This ensures that the client will be able to retrieve the maximum number of
boot images possible. Failure to supply this option may result in a truncated list.
3.4.15 BSDP Boot Image Attributes Filter List option: BSDP option code 11
This option allows the client to request that the server filter images and return results that
match the given list of image Attributes. Each Attributes value is 2 bytes long, and
matches the definition described in section 3.4.2. Use of this option is optional.
To receive filtered responses, the client inserts this option in the DHCP DISCOVER,
DHCP REQUEST, and BSDP INFORM[LIST] packets that it sends. A server, upon
receipt of a packet containing this option, eliminates images that do not match the given
list of Attributes. The filtering applies to each of the following returned options:
Default Boot Image ID option (section 3.4.11)
Selected Boot Image ID option (section 3.4.12)
Boot Image List option (section 3.4.13)
If no images match the given image Attributes list, a server that supports this option will
not respond. Note: existing servers that do not support this option will respond as if no
image attributes filter were present. The client needs to verify that any BSDP
ACK[LIST] packet it receives matches the desired image Attributes list. In particular, if
the client supplies a single Attributes value, the client verifies that the Default and
Selected Boot Image ID options values match the desired Attributes. For example, if the
client wants to receive only “Hardware Diagnostics” image (Kind = 3), the client supplies
the option:
Code Length Attributes1
11 2 3 0
and checks that the Default Boot Image ID and Selected Boot Image ID options match:
Code Length Default Boot Image ID
7 4 3 0 x x
The data for this option must be a positive multiple of 2 bytes (N >= 1):
Code Length Attributes1 Attributes2 … AttributesN
11 2*N A11 A12 A21 A22 … AN1 AN2
DHCP_ack = 0;
if (DHCP_offer != 0) {
/* send DHCP REQUEST to DHCP_offer.server_id, wait for ACK */
if (requesting_state(DHCP_offer,&DHCP_ack) == FAILURE) {
t = INITIAL_TIMEOUT;
/* retry or abort */
gathering
} = DHCP_offer = BSDP_offer = BOOTP_reply = 0;
formy_ip
(try = 0; try < MAX_TRIES; try++) {
= DHCP_ack.yiaddr;
transmit(DISCOVER);
options = DHCP_ack.options;
} set_timeout(t); t = t * 2;
while
else { (read_packet(&packet) != TIMEDOUT) {
my_ip =ifBOOTP_reply.yiaddr;
(gathering == 0) {
clear_timeout();
options = BOOTP_reply.options;
} set_timeout(GATHERING_SECS);
gathering = 1;
}
configure_IP(my_ip,options.subnet_mask,options.router);
if (packet.type == BOOTP) {
bootfile = 0; if (BOOTP_reply == 0) {
if (BSDP_offer != 0) {BOOTP_reply = packet;
}
bootfile = BSDP_offer.file; /* (Figure 2) */
} }
else { else if (packet.msgtype != OFFER)
BSDP_ack; = 0;
else if (packet.vendor_class_id==
if (Do_BSDP_Protocol(&BSDP_ack) ==FAILURE)
BSDP) { {
/* BSDP_offer
retry or abort=*/
packet;
} }
bootfile else { /* DHCP packet */
= BSDP_ack.file;
} DHCP_offer = packet;
}
load_and_execute(bootfile);
if (DHCP_offer != 0 && BSDP_offer != 0)
break; /* out of while */
} /* while */
if (DHCP_offer != 0 || BSDP_offer != 0 || BOOTP_reply != 0)
break; /* out of for */
} /* for */
clear_timeout();
After the gathering period ends, the client looks at the responses it saved and decides how
to proceed. If it received no IP address information i.e. no DHCP OFFER or BOOTP
REPLY, it retries DHCP. If the client receives a DHCP OFFER, it moves to the DHCP
REQUEST state to confirm the IP address (discussed in the next section). If the client
receives a BOOTP REPLY, it can simply use the specified IP address.
If no BSDP response is received, the client continues on and tries BSDP (discussed in the
following sections). The following pseudo-code details the post-gathering logic:
If the firmware client received a BSDP OFFER (Table 3), it must save it so that it can be
accessed by the loaded operating system. The client then loads and executes the bootfile.
If the client selected a DHCP OFFER, it sends a DHCP REQUEST (Table 4) packet to
transition to the DHCP REQUEST state. If the client selected a BOOTP REPLY, the
client firmware must save the packet in memory so that the booted operating system can
retrieve it.
If the IP address is not in use, the client configures its IP parameters and continues with
BSDP or downloads the appropriate boot file (see the previous sections).
The client firmware must save the DHCP ACK so that it can be accessed by the loaded
operating system.
Figure 4 below illustrates the BSDP client state transitions. The sections that follow
describe each of the BSDP client states.
INFORM[LIST]
INIT
ACK[LIST]
SELECT ACK[FAILED] BOUND
INFORM[SELECT] REQUEST
ACK[SELECT]
The client retries several times. If no packets arrive, the client aborts network boot, and
sends a DHCP RELEASE packet to the DHCP server indicating that it no longer requires
the IP address (see RFC 2131).
Once the first ACK[LIST] packet arrives (see Table 6), the client transitions to the
BSDP SELECT state.
3
A reasonable length for the gathering time is 2 to 4 seconds.
If the client is able to offer a menu selection, it should gather all the responses it received
and build a single list of boot images. Once the user selects an image, the client records
the boot_image_id value for that image, and remembers which ACK[LIST] the image
appeared in. If the client is unable to offer a menu selection, it selects from the responses
automatically. If an ACK[LIST] contains the BSDP Selected Boot Image ID option, the
client selects that response and records the boot_image_id value from the option.
Otherwise, the client selects the ACK[LIST] with the highest BSDP Server Priority
option value and records the boot_image_id value from the BSDP Default Boot Image ID
option.
Once an image is selected, the client forms an INFORM[SELECT] packet, setting the
BSDP Server Identifier option to the value of the DHCP Server Identifier option from the
selected ACK[LIST], and setting the BSDP Selected Boot Image ID option to the
recorded boot_image_id value. The client broadcasts the INFORM[SELECT] and moves
to the BSDP REQUEST state.
Once the client receives the ACK[SELECT], it saves it in a location accessible by the
loaded operating system, and begins downloading the boot file.
The client may choose to specify an alternate port to use in the reply from the server (see
3.4.9) to avoid conflicts with the DHCP client. The protocol proceeds as described
starting in section 4.3.
The reason this is important only to the non-firmware BSDP client is that unlike the
actual firmware, it can run on any system, regardless of its firmware version. It must
adjust its behavior to match the capabilities of the underlying firmware to avoid
surprising the user the next time the system reboots.
Apple systems developed before the original iMac are not able to NetBoot. The non-
firmware BSDP client must prevent the user from negotiating BSDP on such systems.
Failure to do so means the user is left with a system that will fail to boot.
Apple systems that pre-date BSDP, such as the original iMac and blue and white
PowerMac G3 (Yosemite) have an Open Firmware version predating BSDP. These
systems use an enhanced version of BOOTP now referred to as NetBoot 1.0. Such
systems cannot fully benefit from the features of BSDP, and are limited to being served
by a single NetBoot server.
On NetBoot 1.0 systems, the non-firmware BSDP client must identify itself as a NetBoot
1.0 client in its BSDP messages by supplying the BSDP NetBoot 1.0 Firmware option
(see section 3.4.14 for more information).
On NetBoot-capable machines, read the third long-word (4-byte) quantity. If the value is
less than 0x33000, the client is NetBoot 1.0. Otherwise it is NetBoot 2.0.
info = 0
node = DeviceTreeNodeLookup(“device-tree:/rom/boot-rom”);
if (node != NULL) {
plist = DeviceTreeNodeGetProperties(node, plist);
info = PropertyListGetValue(plist, “info”);
}
if (info == NULL) {
client_type = NETBOOT_VERSION_NONE; /* no NetBoot support */
else {
uint32_t third_longword;