.\" .\" .\" Copyright (c) 1999-2024 Apple Inc. All rights reserved. .\" .\" @APPLE_LICENSE_HEADER_START@ .\" .\" This file contains Original Code and/or Modifications of Original Code .\" as defined in and that are subject to the Apple Public Source License .\" Version 2.0 (the 'License'). You may not use this file except in .\" compliance with the License. Please obtain a copy of the License at .\" http://www.opensource.apple.com/apsl/ and read it before using this .\" file. .\" .\" The Original Code and all software distributed under the License are .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. .\" Please see the License for the specific language governing rights and .\" limitations under the License. .\" .\" @APPLE_LICENSE_HEADER_END@ .\" .Dd February 2, 2023 .Dt BOOTPD 8 .Os "Mac OS X" .Sh NAME .Nm bootpd .Nd DHCP/BOOTP .Sh SYNOPSIS .Nm \fI[options]\fR .Sh DESCRIPTION .Nm implements a DHCP/BOOTP server as defined in RFC951, RFC1542, RFC2131, and RFC2132, as well as a BOOTP/DHCP relay agent. .Pp .Nm understands and handles requests that arrive via a DHCP/BOOTP relay agent, allowing the server to be centrally located, and serve many remote subnets. .Pp The server is normally invoked by .Xr launchd 8 when a request arrives, but can also be invoked manually. If it is invoked by .Xr launchd 8 , .Nm 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, .Nm continues to run indefinitely. .Pp If .Nm receives a SIGHUP (-1) signal, it will re-read its configuration and client binding files. .Pp When a request from a client arrives, the server logs an entry to \fI/var/log/system.log\fR indicating which client made the request, and logs another entry once a reply is sent. This feature can be turned off using the .Fl q option described below. .Pp .Nm reads its configuration from \fIbootpd.plist\fR, a plist that by default is expected to exist as \fI/etc/bootpd.plist\fR. An alternate path can be specified using the .Fl f option. There are also a number of command-line options to change its behavior on the fly. Note in particular that options \fBDrS\fR can also be controlled via service-control properties. See .Xr "Service Controls and Filters" below. .Sh "OPTIONS" .Bl -tag -width indent .It Fl B Disable BOOTP service. BOOTP is now disabled by default, so specifying this option has no effect. .It Fl b Only respond if the client's bootfile exists: for BOOTP clients only. .It Fl D Enable DHCP service. By default, DHCP service is disabled. .It Fl d Remain in the foreground and produce extra debugging output to stderr. .It Fl f Ar "filename" Specify an alternate \fIbootpd.plist\fR configuration file instead of the default \fI/etc/bootpd.plist\fR. .It Fl I Disable re-initialization on IP address changes. By default, changes to the server's configured IP addresses cause it to re-initialize. .It Fl i Ar "interface" Enable service on the specified interface. This flag may appear multiple times to enable multiple interfaces. For example, .nf bootpd -i en0 -i en1 .fi forces .Nm to respond only to requests received on ethernet ports en0 and en1. By default, all interfaces are enabled. .It Fl o Ar hop_count For relay agent operation, the maximum hop count, default is 4 hops. .It Fl q Be quiet as possible. Only report serious errors to .It Fl r Ar server_ip Relay packets to the specified server_ip, not exceeding the hop count. This option can be specified multiple times, one for each server to relay to. .It Fl S Enable BOOTP service. .It Fl v Be more verbose in messages logged to \fI/var/log/system.log\fR. .El .Sh "CONFIGURING BOOTPD" .Nm reads its configuration from \fIbootpd.plist\fR\fR, an XML property list. The root of the property list is a dictionary. The property list has two main areas: .Bl -tag -width "Root dictionary" .It "Root dictionary" Service Controls and Filters .It "Subnets" Subnet Entries .El .Ss "Service Controls and Filters" The root dictionary in \fIbootpd.plist\fR contains properties to control whether .Nm will respond to a particular request, There are MAC address filters, DHCP controls, as well as controls to enable services. .Bl -tag -width allow .Pp The MAC address filter properties are: .It Sy allow (Array of String) Enables servicing a list of MAC addresses. .It Sy deny (Array of String) Disables servicing a list of MAC addresses. .El .Pp When a packet arrives, .Nm checks whether the client's MAC address is in the \fBdeny\fR list. If it is, the packet is dropped. Otherwise, if the client's MAC address is in the \fBallow\fR list, the packet continues to be processed, otherwise it is dropped. If neither the \fBallow\fR nor the \fBdeny\fR property is specified, the packet continues to be processed. .Pp Allow/deny filtering can be disabled using the \fBignore_allow_deny\fR property: .Bl -tag -width ignore_allow_deny .It Sy 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. .El .Pp The service-control properties are: .Bl -tag -width ignore_allow_deny .It Sy bootp_enabled Enables BOOTP on the specified list of interfaces. .It Sy dhcp_enabled Enables DHCP on the specified list of interfaces. .It Sy relay_enabled Enables the relay agent on the specified list of interfaces. Note that this option also requires the \fBrelay_ip_list\fR property to be specified. .El .Pp 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 \fIboolean\fR value \fItrue\fR or \fIfalse\fR 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. .Pp For example, to enable DHCP on interfaces en0 and en1, disable BOOTP on all interfaces, and enable relay agent on interface en1, \fIbootpd.plist\fR could contain: .nf bootp_enabled dhcp_enabled en0 en1 relay_enabled en1 .fi .Bl -tag -width detect_other_dhcp_server .Pp Some additional properties are: .It Sy relay_ip_list (Array of String) If relay agent functionality is enabled (see \fBrelay_enabled\fR above), this property contains the list of IP addresses to relay the packet to. .It Sy 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 .Nm receives a SIGHUP, or exits. .It Sy reply_threshold_seconds (Integer) .Nm won't respond to the request until the bp_secs field is at least \fIreply_theshold_seconds\fR. The default value is 0 (zero). .It Sy use_open_directory (Boolean) If this property is set to true, .Nm will look for static IP address to ethernet address bindings in \fBOpen Directory\fR. The default value is false. .It Sy 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. .It Sy 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 \fI/etc/bootptab\fR. .It Sy 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. .El .Ss "Subnet Entries" The "Subnets" property in \fIbootpd.plist\fR contains an array of dictionaries, each dictionary corresponds to a single subnet entry. .Pp 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. .Pp 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 \fBsupernet\fR property described below. .Pp Subnet entries may not overlap in the IP ranges the describe, nor specify values that are inconsistent. Specifically, applying the \fBnet_mask\fR value to each of the values in the \fBnet_range\fR must yield the \fBnet_address\fR value. .Pp Errors in configuration are logged to \fI/var/log/system.log\fR. 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. .Pp Each subnet entry is encoded as a dictionary with the following properties: .Bl -tag -width client_types .It Sy name (String) A descriptive name for the subnet, e.g. "17.202.40/22". .It Sy net_mask (String) The network mask, e.g. "255.255.252.0". This property is required. .It Sy net_address (String) The network address, e.g. "17.202.40.0". This property is required. .It Sy net_range (Array of String) The network address range stored as two values: the first IP address and the last IP address. For example: .nf 17.202.40.2 17.202.43.254 .fi This property is required. .It Sy allocate (Boolean) Indicates whether the DHCP service should allocate IP addresses from the range specified by \fBnet_range\fR. A \fItrue\fR value means allocate IP addresses, otherwise, the subnet entry is informational only. .It Sy lease_min (Integer) The minimum allowable lease time (in seconds). This property is ignored unless \fBallocate\fR specifies \fItrue\fR. Default value is 3600 (one hour). .It Sy lease_max (Integer) The maximum allowable lease time (in seconds). This property is ignored unless \fBallocate\fR specifies \fItrue\fR. Default value is 3600 (one hour). .It Sy supernet (String) This property indicates that the subnet is on the same physical broadcast domain as other subnets with the same supernet value. .El .Pp The server can also supply clients with the following DHCP option information: .Bl -tag -width client_types .It Sy 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. .It Sy 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). .It Sy 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). .It Sy 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). .It Sy 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 "\fI\fR/\fI\fR", and the second element gives the gateway as "\fI\fR" is "0.0.0.0", the destination is the interface itself. .Pp For example: .nf dhcp_classless_static_route 192.168.100.0/22 0.0.0.0 44.100.100.100/22 192.168.100.1 129.210.177.132/25 1.1.1.1 .fi .Pp 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. .It Sy dhcp_ldap_url The default LDAP URL (option code 95). .It Sy dhcp_netinfo_server_address The NetInfo parent server IP address(es) (option code 112). .It Sy dhcp_netinfo_server_tag The NetInfo parent domain tag (option code 113). .It Sy dhcp_url The default URL to present in a web browser (option code 114). .It Sy dhcp_time_offset The time offset from GMT in seconds (option code 2). .It Sy dhcp_network_time_protocol_servers The network time protocol (NTP) server IP address(es) (option code 42). .It Sy dhcp_nb_over_tcpip_name_server The NetBIOS over TCP/IP name server IP address(es) (option code 44). .It Sy dhcp_nb_over_tcpip_dgram_dist_server The NetBIOS over TCP/IP datagram distribution server IP address(es) (option code 45). .It Sy dhcp_nb_over_tcpip_node_type The NetBIOS over TCP/IP node type (option code 46). .It Sy dhcp_nb_over_tcpip_scope The NetBIOS over TCP/IP scope string (option code 47). .It Sy dhcp_smtp_server The Simple Mail Transport Protocol (SMTP) server IP address(es) (option code 69). .It Sy dhcp_pop3_server The Post Office Protocol (POP3) server IP address(es) (option code 70). .It Sy dhcp_nntp_server The Network News Transport Protocol (NNTP) server IP address(es) (option code 71). .It Sy dhcp_proxy_auto_discovery_url The default Web Proxy Auto Discovery URL (option code 252). .El .Pp DHCP options may also be specified using the naming convention: .nf dhcp_option_\fIoption_code\fR .fi replacing \fIoption_code\fR with a numeric value in the range of 1 through 254. For example, to specify option code 128, specify a property named \fBdhcp_option_128\fR. .Pp .Nm 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 .Nm 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. .Pp 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. .Pp Regardless of whether .Nm knows the type of the option or not, you can always specify the DHCP option using the \fIdata\fR property list type e.g.: .nf dhcp_option_128 AAqV1Tzo .fi .El .Sh "BOOTP/DHCP STATIC BINDINGS" Static IP address to ethernet address bindings are stored in the \fI/etc/bootptab\fR file and in \fBOpen Directory\fR. Bindings specified in the \fI/etc/bootptab\fR file take precedence over those in \fBOpen Directory\fR. .Pp See .Xr bootptab 5 for more information about the \fI/etc/bootptab\fR file. .Pp For \fBOpen Directory\fR, .Nm looks at the /Computers records for the following properties: .Bl -tag -width IPAddressAndENetAddress .It Sy ENetAddress (String) The ethernet MAC address(es) of the computer. Each address must be of the form xx:xx:xx:xx:xx:xx using only the characters 0123456789abcdef. Leading zeros must be specified. .It Sy IPAddress (String) The IP address(es) of the computer. .It Sy IPAddressAndENetAddress (String) Pairs of IP and Ethernet MAC addresses of the computer. Each address pair consists of an single IP and MAC address separated by a slash character, e.g. "192.168.1.1/01:23:45:67:89:ab". This attribute should be provided when multiple addresses are provided because not all directories return attribute values in a guaranteed order. .It Sy BootFile (String) The bootfile to use for this computer. .El .Sh "DHCP SERVICE" .Pp 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). .Pp 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. .Ss "IP Allocation" The DHCP server first tries to find a static binding for the client (see section .Xr "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. .Pp 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. .Pp 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. .Pp 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. .Pp 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. .Pp 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. .Xr "BOOTP/DHCP STATIC BINDINGS" above), or the server must have an applicable dynamic pool of IP addresses, just as with DHCP. .Sh "SEE ALSO" .Lp .Xr bootptab 5 , .Xr launchd 8 , .Xr tftpd 8 , .Xr exports 5