bootpd(8)

Service Controls and Filters

The root dictionary in bootpd.plist contains properties to control whether bootpd will respond to a particular request, There are MAC address filters, DHCP controls, as well as controls to enable services.

allow

(Array of String) Enables servicing a list of MAC addresses.

deny

(Array of String) Disables servicing a list of MAC addresses.

The MAC address filter properties are:

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.

Allow/deny filtering can be disabled using the ignore_allow_deny property:

ignore_allow_deny

(Array of String) Disable allow/deny processing on the specified list of interfaces. When a packet arrives on an interface in this list, processing continues without consulting the allow/deny filters.

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.

relay_enabled

Enables the relay agent on the specified list of interfaces. Note that this option also requires the relay_ip_list property to be specified.

For each of the properties dhcp_enabled, bootp_enabled, and relay_enabled, the corresponding service can be enabled or disabled for all interfaces, or enabled for just a specific set of interfaces. To enable or disable globally, use a boolean value true or false respectively. To enable just for a specific set of interfaces, use either a string, for a single interface, or an array of strings, one element for each interface.

For example, to enable DHCP on interfaces en0 and en1, disable BOOTP on all interfaces, and enable relay agent on interface en1, bootpd.plist could contain:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>bootp_enabled</key>
        <false/>
        <key>dhcp_enabled</key>
        <array>
                <string>en0</string>
                <string>en1</string>
        </array>
        <key>relay_enabled</key>
        <array>
                <string>en1</string>
        </array>
</dict>
</plist>

relay_ip_list

(Array of String) If relay agent functionality is enabled (see relay_enabled above), this property contains the list of IP addresses to relay the packet to.

detect_other_dhcp_server

(Boolean, Array of String) Enables detecting another DHCP server either globally (Boolean), or only on the specified list of interfaces (Array of String). When another DHCP server is detected on an interface, DHCP service is disabled on that interface until the next time bootpd receives a SIGHUP, or exits.

reply_threshold_seconds

(Integer) bootpd won't respond to the request until the bp_secs field is at least reply_theshold_seconds. The default value is 0 (zero).

use_open_directory

(Boolean) If this property is set to true, bootpd will look for static IP address to ethernet address bindings in Open Directory. The default value is false.

dhcp_ignore_client_identifier

(Boolean) If this property is set to true, the DHCP server tries to ignore the DHCP client identifier option (code 61) in the client's DHCP packet. Instead, the DHCP server tries to use the hardware address fields (bp_htype, bp_hlen, bp_chaddr) of the DHCP packet to identify the client. The default value of this property is false.

dhcp_supply_bootfile

(Boolean) If this property is set to true, the DHCP server supplies the bootfile specified in the static binding for a client in /etc/bootptab.

use_server_config_for_dhcp_options

(Boolean) If this property is set to true, the DHCP server tries to use its own configuration to supply the subnet mask, router, DNS server addresses, DNS domain, and DNS domain search options, if those options are missing from the subnet description. If the property is false, the server only uses the information in the subnet description to supply these DHCP options. The default value of this property is true.

Some additional properties are:

Subnet Entries

The "Subnets" property in bootpd.plist contains an array of dictionaries, each dictionary corresponds to a single subnet entry.

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. The informational range is used when the client's IP address binding is static, or the client knows its own IP address and simply wants relevant option information.

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 sub-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 is encoded as a dictionary with the following properties:

name

(String) A descriptive name for the subnet, e.g. "17.202.40/22".

net_mask

(String) The network mask, e.g. "255.255.252.0". This property is required.

net_address

(String) The network address, e.g. "17.202.40.0". This property is required.

net_range

(Array of String) The network address range stored as two values: the first IP address and the last IP address. For example:

	<array>
		<string>17.202.40.2</string>
		<string>17.202.43.254</string>
	</array>

This property is required.

allocate

(Boolean) Indicates whether the DHCP service should allocate IP addresses from the range specified by net_range. A true value means allocate IP addresses, otherwise, the subnet entry is informational only.

lease_min

(Integer) The minimum allowable lease time (in seconds). This property is ignored unless allocate specifies true. Default value is 3600 (one hour).

lease_max

(Integer) The maximum allowable lease time (in seconds). This property is ignored unless allocate specifies true. Default value is 3600 (one hour).

supernet

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

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_domain_search

The domain search list (option code 119). If this property is not present, the server will supply its domain search list (if available).

dhcp_classless_static_route

The classless static route (option code 121). The list of static routes is specified using an array of strings. The array is interpreted as an array of string pairs, the first element of the pair describes the destination network using the notation "<destination_ip>/<prefix_length>", and the second element gives the gateway as "<gateway_ip". If "<gateway_ip>" is "0.0.0.0", the destination is the interface itself.

For example:

	<key>dhcp_classless_static_route</key>
	<array>
		<string>192.168.100.0/22</string>
		<string>0.0.0.0</string>
		<string>44.100.100.100/22</string>
		<string>192.168.100.1</string>
		<string>129.210.177.132/25</string>
		<string>1.1.1.1</string>
	</array>

The first route has destination 192.168.100.0/22 and gateway 0.0.0.0 which means 192.168.100.0/22 is directly reachable on the link. The second route has destination 44.100.100.100/22 and gateway 192.168.100.1. The third route has destination 129.210.177.132/25 and gateway 1.1.1.1.

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_nb_over_tcpip_scope

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

dhcp_smtp_server

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

dhcp_pop3_server

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

dhcp_nntp_server

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

dhcp_proxy_auto_discovery_url

The default Web Proxy Auto Discovery URL (option code 252).

DHCP options may also be specified using the naming convention:

	dhcp_option_option_code

replacing option_code with a numeric value in the range of 1 through 254. For example, to specify option code 128, specify a property named dhcp_option_128.

bootpd has a built-in type conversion table for many more options, mostly those specified in RFC 2132, and will try to convert from whatever type the option appears in the property list to the binary, packet format. For example, if bootpd knows that the type of the option is an IP address or list of IP addresses, it converts from the string form of the IP address to the binary, network byte order numeric value.

If the type of the option is a numeric value, it converts from string, integer, or boolean, to the proper sized, network byte-order numeric value.

Regardless of whether bootpd knows the type of the option or not, you can always specify the DHCP option using the data property list type e.g.:

	<key>dhcp_option_128</key>
	<data>
	AAqV1Tzo
	</data>

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, otherwise 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. For example, if the address range goes from 10.0.0.2 through 10.0.0.10, but there is a static entry that specifies 10.0.0.3, that 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 handing out the same in-use IP address over and over. BOOTP/DHCP STATIC BINDINGS above), or the server must have an applicable dynamic pool of IP addresses, just as with DHCP.