dhcpagent [-a] [ -d n] [-f] [-v]
The dhcpagent daemon obtains configuration parameters for the client (local) machine's network interfaces from a DHCP server. These parameters may include a lease on an IP address, which gives the client machine use of the address for the period of the lease, which may be infinite. If the client wishes to use the IP address for a period longer than the lease, it must negotiate an extension using DHCP. For this reason, dhcpagent must run as a daemon, terminating only when the client machine powers down.
For IPv4, the dhcpagent daemon is controlled through ipadm(1M), nwamcfg(1M), or ifconfig(1M) in much the same way that the init(1M) daemon is controlled by telinit(1M). dhcpagent can be invoked as a user process, albeit one requiring root privileges, but this is not necessary, as ipadm(1M), nwamcfg(1M), or ifconfig(1M) will start dhcpagent automatically.
For IPv6, the dhcpagent daemon is invoked automatically by in.ndpd(1M). It can also be controlled through ifconfig(1M), if necessary.
When invoked, dhcpagent enters a passive state while it awaits instructions from ipadm(1M), nwamcfg(1M), ifconfig(1M), or in.ndpd(1M). When dhcpagent receives a command to configure an interface, dhcpagent brings up the interface (if necessary) and starts DHCP. Once DHCP is complete, dhcpagent can be queried for the values of the various network parameters. In addition, if DHCP was used to obtain a lease on an address for an interface, dhcpagent configures the address for use. When a lease is obtained, it is automatically renewed as necessary. If the lease cannot be renewed, dhcpagent will unconfigure the address, but the interface will be left up, and dhcpagent will attempt to acquire a new address lease.
dhcpagent monitors system suspend/resume events and will validate any non-permanent leases with the DHCP server upon resume. Similarly, dhcpagent monitors link up/down events and will validate any non-permanent leases with the DHCP server when the downed link is brought back up. The lease validation mechanism will restart DHCP if the server indicates that the existing lease is no longer valid. If the server cannot be contacted, then the existing lease will continue. This behavior can be modified with the VERIFIED_LEASE_ONLY parameter in the /etc/default/dhcpagent file. See the description of this parameter below.
For IPv4, if the configured interface is found to be unplumbed, or to have a different IP address, subnet mask, or broadcast address from those obtained from DHCP, the interface is abandoned from DHCP control.
For IPv6, dhcpagent automatically plumbs and unplumbs logical interfaces as necessary for the IPv6 addresses supplied by the server. The IPv6 prefix length (netmask) is not set by the DHCPv6 protocol, but is instead set by in.ndpd(1M) using prefix information obtained by Router Advertisements. If any of the logical interfaces created by dhcpagent is unplumbed, or configured with a different IP address, it will be abandoned from DHCP control. If the link-local interface is unplumbed, then all addresses configured by DHCP on that physical interface will be removed.
In addition to DHCP, dhcpagent also supports BOOTP (IPv4 only). See RFC 951, Bootstrap Protocol. Configuration parameters obtained from a BOOTP server are treated identically to those received from a DHCP server, except that the IP address received from a BOOTP server always has an infinite lease.
DHCP also acts as a mechanism to configure other information needed by the client, for example, the domain name and addresses of routers. Aside from the IP address, and for IPv4 alone, the netmask, broadcast address, and default router, the agent does not directly configure the workstation, but instead acts as a database which may be interrogated by other programs, and in particular by dhcpinfo(1).
On clients with a single interface, this is quite straightforward. Clients with multiple interfaces may present difficulties, as it is possible that some information arriving on different interfaces may need to be merged, or may be inconsistent. Furthermore, the configuration of the interfaces is asynchronous, so requests may arrive while some or all of the interfaces are still unconfigured. To handle these cases, one interface may be designated as primary, which makes it the authoritative source for the values of DHCP parameters in the case where no specific interface is requested. See dhcpinfo(1) and ifconfig(1M) for details.
For IPv4, the dhcpagent daemon can be configured to request a particular Fully Qualified Domain Name (FQDN) or host name. See the REQUEST_FQDN or REQUEST_HOSTNAME description in the FILES section. When first configuring a client to request an FQDN or host name, you must perform the following steps as root to ensure that the full DHCP negotiation takes place:
# pkill dhcpagent # rm /etc/dhcp/interface.dhc # reboot
All DHCP packets sent by dhcpagent include a vendor class identifier (RFC 2132, option code 60; RFC 3315, option code 16). This identifier is the same as the platform name returned by the uname -i command, except:
When dhcpagent is run without the -f option, all messages are sent to the system logger syslog(3C) at the appropriate matching priority and with a facility identifier LOG_DAEMON. When dhcpagent is run with the -f option, all messages are directed to standard error.
BOUND and BOUND6
EXTEND and EXTEND6
Note that with DHCPv6, the server might choose to remove some addresses, add new address leases, and ignore (allow to expire) still other addresses in a given Reply message. The EXTEND6 event occurs when a Reply is received that leaves one or more address leases still valid, even if the Reply message does not extend the lease for any address. The event program is invoked just before any addresses are removed, but just after any new addresses are added. Those to be removed will be marked with the IFF_DEPRECATED flag.
EXPIRE and EXPIRE6
DROP and DROP6
INFORM and INFORM6
Note that this event is not associated with the receipt of the Reply message, which occurs only when one or more valid leases remain, and occurs only with DHCPv6. If all leases have expired, then the EXPIRE6 event occurs instead.
RELEASE and RELEASE6
The system does not provide a default event program. The file /etc/dhcp/eventhook is expected to be owned by root and have a mode of 755.
The event program will be passed two arguments, the interface name and the event name, respectively. For DHCPv6, the interface name is the name of the physical interface.
The event program can use the dhcpinfo(1) utility to fetch additional information about the interface. While the event program is invoked on every event defined above, it can ignore those events in which it is not interested. The event program runs with the same privileges and environment as dhcpagent itself, except that stdin, stdout, and stderr are redirected to /dev/null. Note that this means that the event program runs with root privileges.
If an invocation of the event program does not exit after 55 seconds, it is sent a SIGTERM signal. If does not exit within the next three seconds, it is terminated by a SIGKILL signal.
See EXAMPLES for an example event program.
The effect of this option depends on whether the interface is being adopted.
If the interface is being adopted, the following conditions apply:
dhcpagent uses the client id specified in /chosen:<client_id>, as published by the PROM or as specified on a boot(1M) command line. If this value is not present, the client id is undefined. The DHCP server then determines what to use as a client id. It is an error condition if the interface is an Infiniband interface and the PROM value is not present.
If the interface is not being adopted:
dhcpagent uses the value stored in /etc/default/dhcpagent. If this value is not present, the client id is undefined. If the interface is Infiniband and there is no value in /etc/default/dhcpagent, a client id is generated as described by the draft document on DHCP over Infiniband, available at:
The following script is stored in the file /etc/dhcp/eventhook, owned by root with a mode of 755. It is invoked upon the occurrence of the events listed in the file.
#!/bin/sh ( echo "Interface name: " $1 echo "Event: " $2 case $2 in "BOUND") echo "Address acquired from server "\ `/sbin/dhcpinfo -i $1 ServerID` ;; "BOUND6") echo "Addresses acquired from server " \ `/sbin/dhcpinfo -v6 -i $1 ServerID` ;; "EXTEND") echo "Lease extended for " \ `/sbin/dhcpinfo -i $1 LeaseTim`" seconds" ;; "EXTEND6") echo "New lease information obtained on $i" ;; "EXPIRE" | "DROP" | "RELEASE") ;; esac ) >/var/run/dhcp_eventhook_output 2>&1
Note the redirection of stdout and stderr to a file.
To configure IPv6 parameters, place the string .v6 between the interface name (if any) and the parameter name. For example, to set the global IPv6 parameter request list, use .v6.PARAM_REQUEST_LIST. To set the CLIENT_ID (DUID) on hme0, use hme0.v6.CLIENT_ID.
The parameters include:
Enabling this option is often desirable on mobile systems, such as laptops, to allow the system to recover quickly from moves.
Default value of this option is no.
Default value of this option is 3.
decimal,data... 0xHHHHH... "string...."
The first form is an RFC 3315 DUID. This is legal for both IPv4 DHCP and DHCPv6. For IPv4, an RFC 4361 Client ID is constructed from this value. In this first form, the format of data... depends on the decimal value. The following formats are defined for this first form:
The second and third forms of CLIENT_ID are legal for IPv4 only. These both represent raw Client ID (without RFC 4361), in hex, or NVT ASCII string format. Thus, "Sun" and 0x53756E are equivalent.
An IPv4 interface that is not in an IP network multipathing (IPMP) group, that is not IP over InfiniBand (IPoIB), and that is not a logical interface does not normally get a default binding identifier.
Default value of this option is no.
The hostname in the FQDN is determined from the following possible configurations:
1. ipadm(1M): include the -1,--primary flag when creating an address that uses DHCP so that nodename(4) is used as the hostname.
2. ipadm(1M): include the -h,--reqhost hostname switch when executing the create-addr -T dhcp subcommand, or use the set-addrprop -p reqhost=hostname subcommand for any existing DHCP address.
3. nwamcfg(1M): set a property, ip-primary=on, for an ncu ip that uses DHCP so that nodename(4) is used as the hostname.
4. nwamcfg(1M): set a property, ip-reqhost=hostname, for an ncu ip that uses DHCP.
The hostname value is either a Partially Qualified Domain Name (PQDN) or an FQDN (i.e., a "rooted" domain name ending with a '.' or one inferred to be an FQDN if it contains at least three DNS labels such as srv.example.com). If a PQDN is specified, then an FQDN is constructed if DNS_DOMAINNAME is defined or if ADOPT_DOMAINNAME is set to yes and an eligible domain name (as described below) is available.
If an FQDN is sent, REQUEST_HOSTNAME processing will not be done, per RFC 4702 (3.1): "clients that send the Client FQDN option in their messages MUST NOT also send the Host Name."
Default value of this option is yes.
Default value of this option is no.
where hostname is the host name requested.
This option works with DHCPv4 only.
Default value of this option is yes.
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|
Croft, B. and Gilmore, J. RFC 951, Bootstrap Protocol (BOOTP), Network Working Group, September 1985.
Droms, R. RFC 2131, Dynamic Host Configuration Protocol, Network Working Group, March 1997.
Lemon, T. and B. Sommerfeld. RFC 4361, Node-specific Client Identifiers for Dynamic Host Configuration Protocol Version Four (DHCPv4). Nominum and Sun Microsystems. February 2006.
Droms, R. RFC 3315, Dynamic Host Configuration Protocol for IPv6 (DHCPv6). Cisco Systems. July 2003.
As with physical IPv4 interfaces, the /etc/hostname.hme0:1 and /etc/dhcp.hme0:1 files must also be created in order for hme0:1 to be automatically plumbed and configured at boot. In addition, unlike physical IPv4 interfaces, dhcpagent does not add or remove default routes associated with logical interfaces.
DHCP can be performed on IPMP IP interfaces to acquire and maintain IPMP data addresses. Because an IPMP IP interface has no hardware address, the daemon automatically constructs a Client ID using the same approach described above for IPv4 logical interfaces. In addition, the lack of a hardware address means the daemon must set the "broadcast" flag in all DISCOVER and REQUEST messages on IPMP IP interfaces. Some DHCP servers may refuse such requests.
DHCP can be performed on IP interfaces that are part of an IPMP group (to acquire and maintain test addresses). The daemon will automatically set the NOFAILOVER and DEPRECATED flags on each test address. Additionally, the daemon will not add or remove default routes in this case. Note that the actual DHCP packet exchange may be performed over any active IP interface in the IPMP group. It is strongly recommended that test addresses have infinite leases. Otherwise, an extended network outage detectable only by probes may cause test address leases to expire, causing in.mpathd(1M) to revert to link-based failure detection and trigger an erroneous repair.
With DHCPv6, the link-local interface must be configured using /etc/hostname6.hme0 in order for DHCPv6 to run on hme0 at boot time. The logical interfaces for each address are plumbed by dhcpagent automatically.
|February 13, 2020|