DESCRIPTION
bootpd implements a DHCP/BOOTP server as defined in RFC951, RFC1542,
RFC2131, and RFC2132. It is also a NetBoot server implementing Apple-
proprietary NetBoot 1.0 (BOOTP-based) and NetBoot 2.0 BSDP (Boot Server
Discovery Protocol). BSDP works along with regular DHCP, using DHCP-for-
mat packets with a special vendor-class identifier and vendor-specific
options.
bootpd understands and handles requests that arrive via a DHCP/BOOTP
relay agent, allowing the server to be centrally located, and serve many
remote subnets.
The server is normally invoked by xinetd(8) when a request arrives, but
can also be invoked manually. If it is invoked by xinetd(8), bootpd con-
tinues to service requests until it is idle for a period of 5 minutes,
after which it exits to conserve system resources. If invoked manually,
bootpd continues to run indefinitely.
If bootpd receives a SIGHUP (-1) signal, it will re-read its configura-
tion and client binding files.
When a request from a client arrives, the server logs an entry to
/var/log/system.log indicating which client made the request, and logs
another entry once a reply is sent. This feature can be turned off using
the -q option described below.
bootpd reads its configuration settings from the local NetInfo domain.
There are also a number of command-line options to change its behavior on
the fly. Note in particular that options BDmN can also be controlled via
service-control properties. See /config/dhcp: Global Controls and
Filters below.
OPTIONS
-a Enable NetInfo anonymous binding for BOOTP clients by supplying
NetInfo host information options 112 and 113.
-B Disable BOOTP service. By default, BOOTP service is enabled.
-b Only respond if the client's bootfile exists: for BOOTP clients
only.
-c interval
How often to check that the NetInfo host cache is still valid.
Default interval is 30 seconds. If the NetInfo database has
changed since we last checked, the cache for that database is
discarded.
-D Enable DHCP service. By default, DHCP service is disabled.
-d Remain in the foreground and produce extra debugging output to
stderr.
-N Enable NetBoot 2.0 (BSDP/DHCP-based) service.
-n netinfo_domain
Search for host entries in the given NetInfo domain. This flag
may appear multiple times, the order of lookups is the order in
which the flags appear. The value "..." means search the entire
NetInfo hierarchy (the default). The netinfo_domain value can be
specified as a domain path or as host/tag. For example,
bootpd -n ...
is the same as simply invoking bootpd without any options, and
bootpd -n .. -n localhost/local
forces bootpd to look in the parent domain then in the local
domain.
-o hop_count
For relay agent operation, the maximum hop count, default is 4
hops.
-q Be quiet as possible. Only report serious errors to
-r server_ip
Relay packets to the specified server_ip, not exceeding the hop
count.
-v Be more verbose in messages logged to /var/log/system.log.
CONFIGURING BOOTPD
bootpd reads its configuration from NetInfo (see netinfo(5)). The direc-
tories that it scans are:
/config/dhcp Global controls and filters
/config/dhcp/subnets Subnet entries
/config/NetBootServer NetBoot server configuration
/config/dhcp: Global Controls and Filters
The directory /config/dhcp contains properties to control whether bootpd
will respond to a particular request. There are MAC address filters
(allow/deny) as well as controls to enable services per interface.
The MAC address filter properties are:
allow Enables the specified list of MAC addresses.
deny Disables the specified list of MAC addresses.
When a packet arrives, bootpd checks whether the client's MAC address is
in the deny list. If it is, the packet is dropped. Otherwise, if the
client's MAC address is in the allow list, the packet continues to be
processed, otherwise it is dropped. If neither the allow nor the deny
property is specified, the packet continues to be processed.
boot_enabled, and netboot_enabled, the absence of a value implies that
the service is enabled on all interfaces. To disable a service, specify
a single value of "". For example (using nidump(8) syntax):
"dhcp_enabled" = ( "en2", "en5" );
enables DHCP only on interfaces "en2" and "en5", whereas:
"dhcp_enabled" = ();
enables DHCP on every interface, and:
"dhcp_enabled" = ( "" );
disables DHCP on all interfaces.
/config/dhcp/subnets: Subnet Entries
A subnet entry describes a range of IP addresses, and associated informa-
tion, such as the subnet mask, router, DNS servers, and other option
data. A subnet entry also indicates whether the range is an address pool
from which to allocate vs. simply an informational range in order to ful-
fill requests for option information, i.e. for answering DHCP Inform
requests, and BOOTP requests.
A subnet entry is required to supply the DHCP service with pool(s) of IP
address(es), and to inform the server of subnet-specific options and
parameters. A subnet entry can also be used to convey network topology
information via the supernet property described below.
Subnet entries may not overlap in the IP ranges the describe, nor specify
values that are inconsistent. Specifically, applying the net_mask value
to each of the values in the net_range must yield the net_address value.
Errors in configuration are logged to /var/log/system.log. There may be
multiple entries for a given subnet, allowing different configuration
values to be specified for a given range of IP addresses within the sub-
net. For example, part of the range might be used for statically bound
clients, and another for a dynamic address pool.
Each subnet entry appears as a sub-directory in /config/dhcp/subnets. A
subnet entry must contain the following properties:
name A descriptive name for the subnet, e.g. "17.202.40/22".
net_mask The network mask, e.g. "255.255.252.0".
net_address The network address, e.g. "17.202.40.0".
net_range The network address range stored as two values: the first
IP address and the last IP address. For example, (
"17.202.40.2", "17.202.43.254" ).
supernet This property indicates that the subnet is on the same
physical broadcast domain as other subnets with the same
supernet value.
The server can also supply clients with the following DHCP option infor-
mation:
dhcp_router The IP address of the default router (DHCP option code 3).
If this property is not present, the server will attempt to
provide its own default route for this option, if it is
applicable.
dhcp_domain_name_server
The IP address(es) of the DNS server(s) (option code 6).
If this property is not present, the server will supply its
own DNS server configuration (if available).
dhcp_domain_name
The default DNS domain name (option code 15). if this
property is not present, the server will supply its own
default domain name (if available).
dhcp_ldap_url
The default LDAP URL (option code 95).
dhcp_netinfo_server_address
The NetInfo parent server IP address(es) (option code 112).
dhcp_netinfo_server_tag
The NetInfo parent domain tag (option code 113).
dhcp_url The default URL to present in a web browser (option code
114).
dhcp_time_offset
The time offset from GMT in seconds (option code 2).
dhcp_network_time_protocol_servers
The network time protocol (NTP) server IP address(es)
(option code 42).
dhcp_nb_over_tcpip_name_server
The NetBIOS over TCP/IP name server IP address(es) (option
code 44).
dhcp_nb_over_tcpip_dgram_dist_server
The NetBIOS over TCP/IP datagram distribution server IP
address(es) (option code 45).
dhcp_nb_over_tcpip_node_type
The NetBIOS over TCP/IP node type (option code 46).
dhcp_proxy_auto_discovery_url
The default Web Proxy Auto Discovery URL (option code 252).
/config/NetBootServer: NetBoot server configuration
This directory contains a number of properties that alter the NetBoot
server's default behavior. The properties are:
afp_uid_start The starting uid used when creating AFP machine
users. The default is uid 100.
afp_users_max The number of AFP machine users to automaticaly cre-
ate. The default is 50. Note: the server will
never remove a user once it is created, so decreas-
ing this value once the server has read it will have
no effect.
age_time_seconds The number of seconds since the client last net-
booted before before the client is considered
"aged". A client that has aged becomes available
for resource reclamation. The server will only
reclaim aged client bindings when it runs out of
free resources.
machine_name_format This property is used to generate a unique name to
each NetBoot client. The default value is "Net-
Boot%03d" (without the double quotes). The format
string must be a printf(3) compatible format string
that takes a single integer value as an argument.
The server ensures that the string is valid by test-
ing the string before using it. The only conversion
specifiers that should be used are diouxX.
shadow_size_meg The size (in megabytes) to allocate for the client
shadow file. The default is 48 (megabytes). See
Diskless Resources below.
BOOTP/DHCP STATIC BINDINGS
Static IP address to ethernet address bindings are stored in NetInfo.
The bindings appear in host entries. Each host entry is a subdirectory
of the /machines directory of a NetInfo domain. The server consults the
default NetInfo domain hierarchy unless overridden by -n flags (see
OPTIONS above).
The server recognizes the following properties in the host entry:
name The name of the host (required).
en_address Ethernet address(es) of the host stored in colon hex ie.
"%x:%x:%x:%x:%x:%x" format (required).
ip_address The IP address(es) of the host (required).
The server supports having more than one IP address associated with a
single client: a single BOOTP/DHCP client can connect to multiple subnets
at different times (e.g. a laptop that is frequently moved from one loca-
tion to another). Multiple host entries may include the same hardware
address but should have distinct IP addresses to avoid associating the
same IP with more than one host. If there is more than one relevant IP
address for a client, the server chooses the first one that it finds.
The server also supports multi-homed hosts (host with the same name but
multiple IP addresses) by treating the en_address and ip_address proper-
ties as parallel arrays. For example, consider a host entry with the
following values:
"name" = ( "orange" );
"en_address" = ( "0:5:2:f:a:b", "0:5:2:1c:9e:d6" );
"ip_address" = ( "17.202.42.110", "17.202.21.221" );
Host "orange" has two IP addresses associated with its name. The inter-
face with ethernet address "0:5:2:f:a:b" has IP address "17.202.42.110",
and interface "0:5:2:1c:9e:d6" has IP address "17.202.21.221".
BOOTP SERVICE
The server supplies a BOOTP client with its statically-assigned IP
address, hostname, subnet mask, default router, domain name server(s),
and domain name, and if the -a option was specified, the NetInfo server
address and NetInfo server tag options. It will not exceed the default
BOOTP packet size however, so it's possible that not all of the options
will fit. The client must set the magic number field (first 4 bytes of
the vendor extensions field) to 99.130.83.99 (dotted decimal) to have the
server supply those options.
DHCP SERVICE
If DHCP service is enabled for a client, the server processes the
client's packet. The packet may be a request for an IP address and
option information (DHCP Discover, DHCP Request) or for just option
information (DHCP Inform). The packet might also tell the server that
the address is in use by some other host (DHCP Decline), or that the
client is done with the IP address (DHCP Release).
The server uses the DHCP client identifier (option 61) if it is present
as the unique client identifier, otherwise it uses the htype/hlen/chaddr
fields in the DHCP packet.
IP Allocation
The DHCP server first tries to find a static binding for the client (see
section BOOTP/DHCP STATIC BINDINGS above). If one exists, it uses it.
If not, it tries to find an existing dynamic binding from its lease data-
base, stored in /var/db/dhcpd_leases. If one exists and it is applicable
to the subnet, the server uses it, otherwise, it tries to allocate an
address from one of its address pools. If an address is available, the
server uses it, otherwise the packet is discarded.
The server tries to give the same address back to a client by remembering
the binding even after it has expired. The server removes an expired
lease entry only when it runs out of addresses, and needs to reclaim an
address in order to fulfill a new request.
When the server receives a DHCP Release packet, it sets the expiration
for that lease to now, so that it can immediately reclaim the address if
needed.
When the server receives a DHCP Decline packet, it removes the client
binding from the IP address, and sets the expiration on the "unbound"
lease to 10 minutes from now. That allows the address to return to the
address pool again without manual intervention and avoids handing out the
same in-use IP address over and over.
NETBOOT SERVICE
The NetBoot server enables a client to perform a network boot, that is,
access its operating system image over the network instead of from its
local drive.
The sequence of events that occur when a NetBoot client is powered are:
1. firmware gets IP address and image information (using BOOTP, or
BSDP/DHCP)
2. firmware saves relevant packet(s) in memory to be used by client
operating system (see step 4 below)
3. firmware TFTP's the bootfile image, and begins executing it
3.1. (Mac OS X only) secondary loader TFTP's kernel and drivers, and
begins executing the kernel
4. client operating system initializes its network stack and accesses
its "root" disk using information in packets saved at step 2, uses
AFP, NFS, or HTTP to access the image
Apple NetBoot uses a technique called "shadowing", whereby an otherwise
read-only disk image appears to the client as a read/write image by "map-
ping" writes to the original image file to an auxilliary "shadow" file.
Subsequent reads from portions that have been written also come from the
"shadow" file. The disk image driver in the client operating system man-
ages the shadow mapping and provides the illusion of a writable disk.
The term diskless NetBoot implies that the client receives all of its
necessary booting resources from the network, so that a local disk drive
is not required, though may still be present.
The NetBoot server supplies a NetBoot client with the resources and
information it needs to boot. Two versions of NetBoot are supported:
NetBoot 1.0 (BOOTP-based) and NetBoot 2.0 (BSDP/DHCP-based). Service for
uses BOOTP, and BOOTP does not support multiple servers. However, the
NetBoot 1.0 server will co-exist with an existing DHCP server, assuming
it only serves DHCP.
The NetBoot 2.0 server only supplies the client with boot resources.
Unlike NetBoot 1.0, there is no limit on the number of NetBoot servers
per subnet.
The NetBoot server stores a list of NetBoot client records in the file
/var/db/bsdpd_clients. Each client record contains the client name and
number assigned by the server, the boot image ID selected by the client,
and the client's last boot time.
NetBoot Image Location
When the NetBoot server initializes, it looks for NetBoot images at well-
known locations in the file system. A "NetBoot image" is a directory
that ends in the .nbi extension, and contains a valid set of files
(described below). If no images are found, NetBoot is temporarily dis-
abled. If it receives a SIGHUP signal, the server again attempts to ini-
tialize itself.
The NetBoot server looks for a symbolic link named:
Library/NetBoot/.sharepoint
at the root of each local volume. If the symlink is valid, and points to
a directory, it assumes that the directory contains NetBoot images and
that the contents are accessible via TFTP, AFP, NFS, and HTTP. By con-
vention, the directory is named:
Library/NetBoot/NetBootSPx
where x is a unique number starting at zero (0).
NetBoot Image (.nbi)
A NetBoot Image is stored in a directory whose name ends with .nbi, and
contains a set of files. The directory must contain an NBImageInfo.plist
file, one or more bootfiles, and may contain one or more image files.
The NBImageInfo.plist file is encoded as an XML property list, and con-
tains information about the image.
The properties defined in the NBImageInfo.plist file and their meanings
are:
Name (String) The name of the image that appears in the
Startup Disk UI.
BootFile (String) The path of the first bootfile, relative to
either the .nbi directory (for architecture "ppc"
only), or a sub-directory of the .nbi directory. The
sub-directory names correspond to the Architectures
that the NetBoot Image supports. See also the Archi-
false.
Type (String) The expected image contents and the mechanism
used to supply images to the client. The defined val-
ues are:
Classic After downloading the boot file via TFTP,
the client OS accesses its images via
AFP. The SharedImage and PrivateImage
properties (defined below) specify the
images to use.
NFS After downloading the boot files via
TFTP, the client OS accesses its "root"
filesystem via NFS. The RootPath prop-
erty (detailed below) specifies the path.
HTTP After downloading the boot files via
TFTP, the client accesses its "root"
filesystem via HTTP. The RootPath prop-
erty (detailed below) specifies the path.
BootFileOnly The client downloads the boot file(s),
and does not require any additional boot
image information.
Kind (Integer) The defined image kind values are:
0 = Mac OS 9
1 = Mac OS X
2 = Mac OS X Server
3 = Hardware Diagnostics
The default Kind is determined from the Type:
Type Default Kind
Classic 0 - Mac OS 9
NFS 1 - Mac OS X
HTTP 1 - Mac OS X
BootFileOnly none
The Kind must be specified if the Type is BootFileOnly.
Index (Integer) The index of the image. This is a 16-bit
value used to differentiate between multiple NetBoot
images supplied by a server. There are two value
ranges:
1 .. 4095 Image is local to this server.
4096 .. 65535 Image is global and may appear on multi-
ple servers, used for load-balancing.
The Index forms the lower 16-bits of the unique 32-bit
Image ID. IsInstall and Kind make up the remaining
the image is on a server named "myserver" with NFS
export "/NetBoot" and the image file appears relative
to the mount point as "Images/Jaguar.dmg".
If Type is "HTTP", this is the path of the "root" disk
image relative to the .nbi directory. The NetBoot
server assumes that the .nbi directory under NetBootSPx
is exported via HTTP using the convention:
http://<server_ip>/NetBoot/NetBootSPx/<image_dir>.nbi
Indirect HTTP paths are also supported using the HTTP
URL syntax:
<path> = http://[<user>@]<host>[:<port>]/<image_path>
<user> = <user_name>:<password>
<host> = <IP address> | <host_name>
Examples:
http://myserver:8080/Images/Jaguar.dmg
http://joe:secret@someserver/Jaguar/Jaguar.dmg
SharedImage (String) If Type is "Classic", this is the path of the
read/write system disk image used for Mac OS 9.
PrivateImage (String) If Type is "Classic", this is the path of the
read-only private disk image used to store additional
applications for Mac OS 9. Optional.
SupportsDiskless (Boolean) A flag that indicates that the image supports
diskless clients, and tells the server to allocate
resources. If the Type is "Classic", the value of this
property is ignored since the server always allocates
resources required for diskless clients. See Diskless
Resources below.
EnabledSystemIdentifiers
(Array of String) The list of system identifiers that
are enabled for this image. The system identifier for
Apple hardware is the model property from the Open
Firmware device-tree. Some example model properties
are "PowerMac3,3" and "PowerBook3,1".
If this property is not specified, or the list is
empty, the image is enabled for all clients (the
default).
If the server has no images that apply to the client,
it will not respond.
bootfile = plist.BootFile.string
for i = 0; i < plist.Architectures.array.count; i++
arch = plist.Architectures.array.value[i].string
if $arch/$bootfile exists
use $arch/$bootfile
else if $arch == "ppc" and $bootfile exists
use $bootfile
else
reject this image
That is, for each architecture in the Architectures
list look for a sub-directory of the .nbi directory
named architecture. If the BootFile exists within that
directory, continue with the next architecture. Other-
wise, if the architecture is "ppc", and the BootFile
exists directly within the .nbi directory, continue
with the next architecture. Otherwise, reject the
image. If all Architectures have a valid BootFile,
accept the image.
This logic allows a single-architecture, "ppc"-only
NetBoot Image to work as before. The directory struc-
ture ensures that a NetBoot Image that only supports
non-"ppc" architectures will be rejected by a NetBoot
server that doesn't understand the Architectures prop-
erty. This is important because older NetBoot servers
only serve "ppc" images, and they must not mistakenly
serve a non-"ppc" image to a "ppc" client.
NetBoot Image Example: Mac OS 9
The path to the image directory in this example is:
/Library/NetBoot/NetBootSP0/Mac OS 9.nbi
This directory contains the following files:
NBImageInfo.plist
Mac OS ROM
NetBoot HD.img
Applications HD.img
The NBImageInfo.plist contains:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
<key>BootFile</key>
<string>Mac OS ROM</string>
<key>IsEnabled</key>
<true/>
<key>Index</key>
<integer>4</integer>
<key>IsInstall</key>
OS ROM". The system image is "NetBoot HD.img". The read-only applica-
tions image is "Applications HD.img". The Name of the image is "Mac OS
9.2". IsEnabled is supplied and set to true, so the image is active.
The Index is 4, which means the image is local to this server, and will
always appear as a unique choice in the client image selection UI.
NetBoot Image Example: Mac OS X
The path to this example is:
/Library/NetBoot/NetBootSP0/Jaguar.nbi
This directory contains:
NBImageInfo.plist
booter
mach.macosx
mach.macosx.mkext
Jaguar.dmg
The NBImageInfo.plist contains:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
<key>BootFile</key>
<string>booter</string>
<key>IsEnabled</key>
<true/>
<key>Index</key>
<integer>4096</integer>
<key>IsInstall</key>
<false/>
<key>Name</key>
<string>Mac OS X (Jaguar)</string>
<key>RootPath</key>
<string>Jaguar.dmg</string>
<key>Type</key>
<string>NFS</string>
</dict>
</plist>
The Type is NFS, and no Kind is specified, so the server assumes this is
a Mac OS X image with Kind 1. The BootFile property points to "booter".
Mac OS X uses three separate bootfiles, so the remaining files which must
exist, but are not currently verified to exist by the server, are
"mach.macosx" and "mach.macosx.mkext". Those names are non-negotiable,
since the booter hard-codes those names. The RootPath property indicates
that the image file is "Jaguar.dmg". The Index is 4096, so this is a
global image, that may appear on multiple NetBoot servers. If another
server serves an image of the same Kind, IsInstall, and Index, this image
may appear as a single choice in client image selection UI.
NetBoot Image Example: Mac OS X with Multiple Architectures
The path to this example is:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
<key>Architectures</key>
<array>
<string>i386</string>
<string>ppc</string>
</array>
<key>BootFile</key>
<string>booter</string>
<key>IsInstall</key>
<true/>
<key>IsEnabled</key>
<true/>
<key>Index</key>
<integer>5000</integer>
<key>Name</key>
<string>Mac OS X (Tiger)</string>
<key>RootPath</key>
<string>Tiger.dmg</string>
<key>Type</key>
<string>NFS</string>
</dict>
</plist>
This example shows how a NetBoot Image that supports multiple architec-
tures is configured. The bootfiles for "ppc" reside directly within the
.nbi directory, whereas the bootfiles for "i386" reside within a sub-
directory of the .nbi directory named "i386". This image is a Mac OS X
installation image that is served over NFS.
Diskless Resources
The NetBoot server creates and manages per-client AFP user logins as well
as per-client directories to give each client its own protected
resources. The AFP users are created in the local NetInfo domain, and
are marked with the property and value:
"_creator" = ( "bsdpd" );
When the server initializes, it ensures there are at least afp_users_max
users with this property. If there are not, it allocates new user
entries to make up the difference.
Along with the per-client AFP login, the server creates per-client direc-
tories to store the "shadow" files. The server creates these directories
on each local volume that contains a symbolic link named:
Library/NetBoot/.clients
at the root of the volume. If the symlink is valid, and points to a
directory, it assumes that the directory should be used for client files.
out of disk space are those that run of of space in their own pre-allo-
cated "shadow" files.
Note: the server allocates shadow files for Mac OS 9 NetBoot clients only
on local HFS volumes.
SEE ALSO
xinetd(8), tftpd(8), netinfo(5), exports(5)
Mac OS X September 14, 2005 Mac OS X
Man(1) output converted with
man2html