Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages

OpenDarwin 7.2.1 - man page for bootpd (opendarwin section 8)

BOOTPD(8)			   BSD System Manager's Manual				BOOTPD(8)

     bootpd -- DHCP/BOOTP/NetBoot server

     bootpd [options]

     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-format packets with a special vendor-class identifier and vendor-specific

     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 continues 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 configuration and client bind-
     ing files.

     When a request from a client arrives, the server logs an entry to /var/log/system.log indi-
     cating 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.

     -a      Enable NetInfo anonymous binding for BOOTP clients by supplying NetInfo host infor-
	     mation 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.

     -I      Disable re-initialization on IP address changes.  By default, changes to the
	     server's configured IP addresses cause it to re-initialize.

     -i interface
	     Enable service on the specified interface.  This flag may appear multiple times to
	     enable multiple interfaces.   For example,
		 bootpd -i en0 -i en1
	     forces bootpd to respond only to requests received on ethernet ports en0 and en1.
	     By default, all interfaces are enabled.

     -m      Enable NetBoot 1.0 (BOOTP-based) service.

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

     bootpd reads its configuration from NetInfo (see netinfo(5)).  The directories that it scans

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

     The service-control properties are:

     bootp_enabled	  Enables BOOTP on the specified list of interfaces.

     dhcp_enabled	  Enables DHCP on the specified list of interfaces.

     netboot_enabled	  Enables NetBoot 2.0 (BSDP/DHCP-based) NetBoot on the specified list of

     old_netboot_enabled  Enables NetBoot 1.0 (BOOTP-based) NetBoot on the specified list of

     For each of the above properties dhcp_enabled, bootp_enabled, old_netboot_enabled, and net-
     boot_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 information, 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 fulfill 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 subnet.  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. "".

     net_address   The network address, e.g. "".

     net_range	   The network address range stored as two values: the first IP address and the
		   last IP address.  For example, ( "", "" ).

     client_types  Indicates whether the range is a DHCP address pool, or just informational.
		   Must contain "dhcp" for a DHCP address pool, and "bootp" for an informational

     The following properties are optional:

     lease_min	   The minimum allowable lease time (in seconds).  This is only required/used if
		   the client_types property is set to "dhcp".

     lease_max	   The maximum allowable lease time (in seconds).  This is only required/used if
		   the client_types property is set to "dhcp".

     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 information:

     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.

		   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

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

		   The default LDAP URL (option code 95).

		   The NetInfo parent server IP address(es) (option code 112).

		   The NetInfo parent domain tag (option code 113).

     dhcp_url	   The default URL to present in a web browser (option code 114).

		   The time offset from GMT in seconds (option code 2).

		   The network time protocol (NTP) server IP address(es) (option code 42).

		   The NetBIOS over TCP/IP name server IP address(es) (option code 44).

		   The NetBIOS over TCP/IP datagram distribution server IP address(es) (option
		   code 45).

		   The NetBIOS over TCP/IP node type (option code 46).

		   The NetBIOS over TCP/IP scope string (option code 47).

		   The Simple Mail Transport Protocol (SMTP) server IP address(es) (option code

		   The Post Office Protocol (POP3) server IP address(es) (option code 70).

		   The Network News Transport Protocol (NNTP) server IP address(es) (option code

		   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 create.  The default is
			  50.  Note: the server will never remove a user once it is created, so
			  decreasing this value once the server has read it will have no effect.

     age_time_seconds	  The number of seconds since the client last netbooted 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 "NetBoot%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 testing the string before using it.  The only con-
			  version 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.

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

     bootfile	 Executable image file to be downloaded by the client via TFTP (not required).

     A client is identified by its unique hardware (MAC) address, and is stored in the en_address

     The server searches for a host entry containing both its hardware address and a relevant IP
     address.  A relevant IP address is one which is useful for the subnet on which the client is
     attempting to boot.  If the request is a BOOTP request, and no static binding exists, the
     server does not respond.  If the request is DHCP, and no static binding exists, the server
     tries to find an approprate address pool.	If none exists, it does not respond.

     The server supports having more than one IP address associated with a single client: a sin-
     gle BOOTP/DHCP client can connect to multiple subnets at different times (e.g. a laptop that
     is frequently moved from one location 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 properties 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" = ( "", "" );

     Host "orange" has two IP addresses associated with its name.  The interface with ethernet
     address "0:5:2:f:a:b" has IP address "", and interface "0:5:2:1c:9e:d6" has IP
     address "".

     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 spec-
     ified, 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 (dotted decimal) to have the server supply those options.

     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 database, 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, oth-
     erwise the packet is discarded.

     After a suitable IP address is found for the client, the server attempts to insert as many
     of the requested DHCP options from the client's request as it can into the reply.

     When the server allocates an address dynamically, it automatically excludes addresses that
     appear in static host entries under NetInfo.  For example, if the address range goes from through, but there is a NetInfo host entry in /machines like this:

	 "name" = ( "test" );
	 "ip_address" = ( "" );

     the IP address is automatically excluded from the pool.

     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 hand-
     ing out the same in-use IP address over and over.

     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

     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

     Apple NetBoot uses a technique called "shadowing", whereby an otherwise read-only disk image
     appears to the client as a read/write image by "mapping" 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 manages
     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

     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 these two types of NetBoot are controlled individually using
     command-line options m and N, or using the service configuration properties old_net-
     boot_enabled and netboot_enabled (described above).

     The NetBoot 1.0 server supplies the client with its IP address in addition to its boot
     resources.  The server must be able to find a static binding for the client (see BOOTP/DHCP
     STATIC BINDINGS above), or the server must have an applicable dynamic pool of IP addresses,
     just as with DHCP.  If the server does not also have DHCP service enabled, the pools are
     only used for NetBoot 1.0 clients.  In this case, the server also acts as a DHCP server but
     only services those clients for which it has an existing binding.

     There can only be one NetBoot 1.0 server per subnet because the protocol 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 con-
     tains a valid set of files (described below).  If no images are found, NetBoot is temporar-
     ily disabled.  If it receives a SIGHUP signal, the server again attempts to initialize

     The NetBoot server looks for a symbolic link named:


     at the root of each HFS+ 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 convention, the directory is named:


     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 contains 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 relative to .nbi directory of the first bootfile.

     IsEnabled	       (Boolean) A flag to mark the image as enabled or not.  An image that is
		       disabled will not be offered as a selection by the NetBoot server.
		       Optional, default value is true.

     IsDefault	       (Boolean) A flag to mark the image as a default image.  Setting this key
		       to true for more than one image can be useful if the
		       EnabledSystemIdentifiers property is also defined (see below).  Optional,
		       default value is false.

     IsInstall	       (Boolean) A flag to indicate that the image describes an installation
		       image.  Optional, default value is false.

     Type	       (String) The type of the image.	The value "Classic" implies that the Kind
		       is Mac OS 9 NetBoot, "NFS" implies the Kind is Mac OS X NetBoot.

     Kind	       (Integer) The image kind:
		       0 =  Mac OS 9
		       1 =  Mac OS X
		       2 =  Mac OS X Server
		       Optional, the default value depends on the Type.

     Index	       (Integer) The index of the image.  This is a 16-bit value used to differ-
		       entiate 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 multiple servers, used
				      for load-balancing.

		       The Index forms the lower 16-bits of the unique 32-bit Image ID.  IsIn-
		       stall and Kind make up the remaining bits (with 8 bits reserved).

     RootPath	       (String) If Type is "NFS", this is the path of the "root" disk image rela-
		       tive to the .nbi directory.  The NetBoot server assumes that the path up
		       to and including the NetBootSPx directory is exported via NFS.  Indirect
		       NFS paths are also supported using the syntax:

			   <path> = <host>:<mount_path>[:<image_path>]
			   <host> = <IP address> | <host_name>

		       For example, in the path:


		       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:


		       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>



     SharedImage       (String) If Type is "Classic", this is the path of the system, or
		       read/write, disk image used for Mac OS 9.

     PrivateImage      (String) If Type is "Classic", this is the path of the private, or read-
		       only, disk image used 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.

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

		       Due to limitations in the NetBoot 1.0 protocol, there is no way for the
		       NetBoot server to differentiate between older clients such as the original
		       bondi-blue iMac or B&W G3 (Yosemite).  To enable an image for all NetBoot
		       1.0 clients, include the pseudo system identifier "/NetBoot1".

   NBImageInfo.plist: Mac OS 9 Example
     The path to the image directory in this example is:
	 /Library/NetBoot/NetBootSP0/Mac OS 9.nbi

     This directory contains the following files:
	 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">
	     <string>Mac OS ROM</string>
	     <string>Mac OS 9.2</string>
	     <string>NetBoot HD.img</string>
	     <string>Applications HD.img</string>

     The Type is Classic, which means this is a Mac OS 9 NetBoot image, so the implied Kind value
     is 0 (Mac OS 9).  The BootFile property points to "Mac OS ROM".  The system image is "Net-
     Boot HD.img".  The read-only applications 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.

   NBImageInfo.plist Example: Mac OS X
     The path to this example is:

     This directory contains:

     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">
	     <string>Mac OS X (Jaguar)</string>

     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 boot-
     files, 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 mul-
     tiple 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.

   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 directories to store the
     "shadow" files.  The server creates these directories on each HFS+ volume that contains a
     symbolic link named:


     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.   It also assumes that the directory is
     a valid AFP sharepoint of the same name.  By convention, the directory is named:


     where Y is a unique number starting at zero (0).

     The server "round-robins" client images across each such directory to distribute load
     amongst multiple disk drives to improve overall performance.

     When the server responds to the client's NetBoot request, it ensures that the "shadow" file
     is preallocated to shadow_size_meg megabytes.  Setting that property high enough avoids hav-
     ing every client fail if the server runs out of disk space.   The only clients that fail if
     the server runs out of disk space are those that run of of space in their own pre-allocated
     "shadow" files.

     xinetd(8), tftpd(8), netinfo(5), exports(5)

Mac OS X				  April 16, 2003				 Mac OS X

All times are GMT -4. The time now is 12:59 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password