Merge commit 'c5bab7026b8e0ac44b25ee08507ea360f177d844' into merges

[unleashed.git] / share / man / man8 / dhcpagent.8

'\" te
.\"  Copyright (c) 1992-1996 Competitive Automation, Inc. Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
.\"  Copyright (c) 2016-2017, Chris Fraire <cfraire@me.com>.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DHCPAGENT 8 "Jun 30, 2017"
.SH NAME
dhcpagent \- Dynamic Host Configuration Protocol (DHCP) client daemon
.SH SYNOPSIS
.LP
.nf
\fBdhcpagent\fR [\fB-a\fR] [ \fB-d\fR \fIn\fR] [\fB-f\fR] [\fB-v\fR]
.fi

.SH DESCRIPTION
.LP
\fBdhcpagent\fR implements the client half of the Dynamic Host Configuration
Protocol \fB(DHCP)\fR for machines running illumos software.
.sp
.LP
The \fBdhcpagent\fR daemon obtains configuration parameters for the client
(local) machine's network interfaces from a \fBDHCP\fR server. These parameters
may include a lease on an \fBIP\fR 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 \fBIP\fR address for a period longer than the lease,
it must negotiate an extension using \fBDHCP\fR. For this reason,
\fBdhcpagent\fR must run as a daemon, terminating only when the client machine
powers down.
.sp
.LP
For IPv4, the \fBdhcpagent\fR daemon is controlled through \fBipadm\fR(8),
\fBnwamcfg\fR(8), or \fBifconfig\fR(8) in much the same way that the
\fBinit\fR(8) daemon is controlled by \fBtelinit\fR(8). \fBdhcpagent\fR can
be invoked as a user process, albeit one requiring root privileges, but this is
not necessary, as \fBipadm\fR(8), \fBnwamcfg\fR(8), or \fBifconfig\fR(8)
will start \fBdhcpagent\fR automatically.
.sp
.LP
For IPv6, the \fBdhcpagent\fR daemon is invoked automatically by
\fBin.ndpd\fR(8). It can also be controlled through \fBifconfig\fR(8), if
necessary.
.sp
.LP
When invoked, \fBdhcpagent\fR enters a passive state while it awaits
instructions from \fBipadm\fR(8), \fBnwamcfg\fR(8), \fBifconfig\fR(8), or
\fBin.ndpd\fR(8). When \fBdhcpagent\fR receives a command to configure an
interface, \fBdhcpagent\fR brings up the interface (if necessary) and starts
DHCP. Once DHCP is complete, \fBdhcpagent\fR 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, \fBdhcpagent\fR configures the address for use.
When a lease is obtained, it is automatically renewed as necessary. If the
lease cannot be renewed, \fBdhcpagent\fR will unconfigure the address, but the
interface will be left up, and \fBdhcpagent\fR will attempt to acquire a new
address lease.
.sp
.LP
\fBdhcpagent\fR monitors system suspend/resume events and will validate any
non-permanent leases with the DHCP server upon resume. Similarly,
\fBdhcpagent\fR 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
\fBVERIFIED_LEASE_ONLY\fR parameter in the \fB/etc/default/dhcpagent\fR file.
See the description of this parameter below.
.sp
.LP
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.
.sp
.LP
For IPv6, \fBdhcpagent\fR 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
\fBin.ndpd\fR(8) using prefix information obtained by Router Advertisements.
If any of the logical interfaces created by \fBdhcpagent\fR 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.
.sp
.LP
In addition to \fBDHCP\fR, \fBdhcpagent\fR also supports \fBBOOTP\fR (IPv4
only). See \fIRFC 951, Bootstrap Protocol\fR. Configuration parameters obtained
from a \fBBOOTP\fR server are treated identically to those received from a
\fBDHCP\fR server, except that the \fBIP\fR address received from a \fBBOOTP\fR
server always has an infinite lease.
.sp
.LP
\fBDHCP\fR 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
\fBdhcpinfo\fR(1).
.sp
.LP
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 \fBDHCP\fR
parameters in the case where no specific interface is requested. See
\fBdhcpinfo\fR(1) and \fBifconfig\fR(8) for details.
.sp
.LP
For IPv4, the \fBdhcpagent\fR daemon can be configured to request a particular
Fully Qualified Domain Name (FQDN) or host name. See the \fBREQUEST_FQDN\fR or
\fBREQUEST_HOSTNAME\fR description in the \fBFILES\fR 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:
.sp
.in +2
.nf
# pkill dhcpagent
# rm /etc/dhcp/\fIinterface\fR.dhc
# reboot
.fi
.in -2
.sp

.sp
.LP
All DHCP packets sent by \fBdhcpagent\fR 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 \fBuname\fR \fB-i\fR command, except:
.RS +4
.TP
.ie t \(bu
.el o
Any commas in the platform name are changed to periods.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the name does not start with a stock symbol and a comma, it is automatically
prefixed with \fBSUNW\fR.
.RE
.SS "Messages"
.LP
The \fBdhcpagent\fR daemon writes information and error messages in five
categories:
.sp
.ne 2
.na
\fBcritical\fR
.ad
.sp .6
.RS 4n
Critical messages indicate severe conditions that prevent proper operation.
.RE

.sp
.ne 2
.na
\fBerrors\fR
.ad
.sp .6
.RS 4n
Error messages are important, sometimes unrecoverable events due to resource
exhaustion and other unexpected failure of system calls; ignoring errors may
lead to degraded functionality.
.RE

.sp
.ne 2
.na
\fBwarnings\fR
.ad
.sp .6
.RS 4n
Warnings indicate less severe problems, and in most cases, describe unusual or
incorrect datagrams received from servers, or requests for service that cannot
be provided.
.RE

.sp
.ne 2
.na
\fBinformational\fR
.ad
.sp .6
.RS 4n
Informational messages provide key pieces of information that can be useful to
debugging a \fBDHCP\fR configuration at a site. Informational messages are
generally controlled by the \fB-v\fR option. However, certain critical pieces
of information, such as the IP address obtained, are always provided.
.RE

.sp
.ne 2
.na
\fBdebug\fR
.ad
.sp .6
.RS 4n
Debugging messages, which may be generated at two different levels of
verbosity, are chiefly of benefit to persons having access to source code, but
may be useful as well in debugging difficult DHCP configuration problems.
Debugging messages are only generated when using the \fB-d\fR option.
.RE

.sp
.LP
When \fBdhcpagent\fR is run without the \fB-f\fR option, all messages are sent
to the system logger \fBsyslog\fR(3C) at the appropriate matching priority and
with a facility identifier \fBLOG_DAEMON\fR. When \fBdhcpagent\fR is run with
the \fB-f\fR option, all messages are directed to standard error.
.SS "DHCP Events and User-Defined Actions"
.LP
If an executable (binary or script) is placed at \fB/etc/dhcp/eventhook\fR, the
\fBdhcpagent\fR daemon will automatically run that program when any of the
following events occur:
.sp
.ne 2
.na
\fB\fBBOUND\fR and \fBBOUND6\fR\fR
.ad
.sp .6
.RS 4n
These events occur during interface configuration. The event program is invoked
when \fBdhcpagent\fR receives the DHCPv4 ACK or DHCPv6 Reply message from the
DHCP server for the lease request of an address, indicating successful initial
configuration of the interface. (See also the \fBINFORM\fR and \fBINFORM6\fR
events, which occur when configuration parameters are obtained without address
leases.)
.RE

.sp
.ne 2
.na
\fB\fBEXTEND\fR and \fBEXTEND6\fR\fR
.ad
.sp .6
.RS 4n
These events occur during lease extension. The event program is invoked just
after \fBdhcpagent\fR receives the DHCPv4 ACK or DHCPv6 Reply from the DHCP
server for the DHCPv4 REQUEST (renew) message or the DHCPv6 Renew or Rebind
message.
.sp
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 \fBEXTEND6\fR 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 \fBIFF_DEPRECATED\fR flag.
.RE

.sp
.ne 2
.na
\fB\fBEXPIRE\fR and \fBEXPIRE6\fR\fR
.ad
.sp .6
.RS 4n
These events occur during lease expiration. For DHCPv4, the event program is
invoked just before the leased address is removed from an interface. For
DHCPv6, the event program is invoked just before the last remaining leased
addresses are removed from the interface.
.RE

.sp
.ne 2
.na
\fB\fBDROP\fR and \fBDROP6\fR\fR
.ad
.sp .6
.RS 4n
These events occur during the period when an interface is dropped. The event
program is invoked just before the interface is removed from DHCP control. If
the interface has been abandoned due the user unplumbing the interface, then
this event will occur after the user's action has taken place. The interface
might not be present.
.RE

.sp
.ne 2
.na
\fB\fBINFORM\fR and \fBINFORM6\fR\fR
.ad
.sp .6
.RS 4n
These events occur when an interface acquires new or updated configuration
information from a DHCP server by means of the DHCPv4 \fBINFORM\fR or the
DHCPv6 Information-Request message. These messages are sent using an
\fBifconfig\fR(8) \fBdhcp inform\fR command or when the DHCPv6 Router
Advertisement \fBO\fR (letter 0) bit is set and the \fBM\fR bit is not set.
Thus, these events occur when the DHCP client does not obtain an IP address
lease from the server, and instead obtains only configuration parameters.
.RE

.sp
.ne 2
.na
\fB\fBLOSS6\fR\fR
.ad
.sp .6
.RS 4n
This event occurs during lease expiration when one or more valid leases still
remain. The event program is invoked just before expired addresses are removed.
Those being removed will be marked with the \fBIFF_DEPRECATED\fR flag.
.sp
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.
.RE

.sp
.ne 2
.na
\fB\fBRELEASE\fR and \fBRELEASE6\fR\fR
.ad
.sp .6
.RS 4n
This event occurs during the period when a leased address is released. The
event program is invoked just before \fBdhcpagent\fR relinquishes the address
on an interface and sends the DHCPv4 \fBRELEASE\fR or DHCPv6 Release packet to
the DHCP server.
.RE

.sp
.LP
The system does not provide a default event program. The file
\fB/etc/dhcp/eventhook\fR is expected to be owned by root and have a mode of
755.
.sp
.LP
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.
.sp
.LP
The event program can use the \fBdhcpinfo\fR(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
\fBdhcpagent\fR itself, except that \fBstdin\fR, \fBstdout\fR, and \fBstderr\fR
are redirected to \fB/dev/null\fR. Note that this means that the event program
runs with root privileges.
.sp
.LP
If an invocation of the event program does not exit after 55 seconds, it is
sent a \fBSIGTERM\fR signal. If does not exit within the next three seconds, it
is terminated by a \fBSIGKILL\fR signal.
.sp
.LP
See EXAMPLES for an example event program.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
Adopt a configured IPv4 interface. This option is for use with diskless
\fBDHCP\fR clients. In the case of diskless \fBDHCP\fR, \fBDHCP\fR has already
been performed on the network interface providing the operating system image
prior to running \fBdhcpagent\fR. This option instructs the agent to take over
control of the interface. It is intended primarily for use in boot scripts.
.sp
The effect of this option depends on whether the interface is being adopted.
.sp
If the interface is being adopted, the following conditions apply:
.sp
\fBdhcpagent\fR uses the client id specified in
\fB/chosen\fR:\fI<client_id>\fR, as published by the PROM or as specified on a
\fBboot\fR(8) 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.
.sp
If the interface is not being adopted:
.sp
\fBdhcpagent\fR uses the value stored in \fB/etc/default/dhcpagent\fR. If this
value is not present, the client id is undefined. If the interface is
Infiniband and there is no value in \fB/etc/default/dhcpagent\fR, a client id
is generated as described by the draft document on DHCP over Infiniband,
available at:
.sp
.in +2
.nf
http://www.ietf.org
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIn\fR\fR
.ad
.sp .6
.RS 4n
Set debug level to \fIn\fR. Two levels of debugging are currently available, 1
and 2; the latter is more verbose.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Run in the foreground instead of as a daemon process. When this option is used,
messages are sent to standard error instead of to \fBsyslog\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Provide verbose output useful for debugging site configuration problems.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRExample Event Program
.sp
.LP
The following script is stored in the file \fB/etc/dhcp/eventhook\fR, owned by
root with a mode of 755. It is invoked upon the occurrence of the events listed
in the file.

.sp
.in +2
.nf
#!/bin/sh

(
echo "Interface name: " $1
echo "Event: " $2

case $2 in
"BOUND")
     echo "Address acquired from server "\e
         `/sbin/dhcpinfo -i $1 ServerID`
     ;;
"BOUND6")
     echo "Addresses acquired from server " \e
         `/sbin/dhcpinfo -v6 -i $1 ServerID`
     ;;
"EXTEND")
    echo "Lease extended for " \e
         `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
.fi
.in -2
.sp

.sp
.LP
Note the redirection of stdout and stderr to a file.

.SH FILES
.ne 2
.na
\fB\fB/etc/dhcp/\fIif\fR.dhc\fR\fR
.ad
.br
.na
\fB\fB/etc/dhcp/\fIif\fR.dh6\fR\fR
.ad
.sp .6
.RS 4n
Contains the configuration for interface. The mere existence of this file does
not imply that the configuration is correct, since the lease might have
expired. On start-up, \fBdhcpagent\fR confirms the validity of the address
using REQUEST (for DHCPv4) or Confirm (DHCPv6).
.RE

.sp
.ne 2
.na
\fB\fB/etc/dhcp/duid\fR\fR
.ad
.br
.na
\fB\fB/etc/dhcp/iaid\fR\fR
.ad
.sp .6
.RS 4n
Contains persistent storage for system-generated DUID (DHCP Unique Identifier)
and interface-specific IAID (Identity Association Identifier) values which are
used if no \fBCLIENT_ID\fR is defined (see below). The format of these files is
undocumented, and applications should not read from or write to them.  Instead,
\fBdhcpinfo\fR(1) can be used to query the \fBdhcpagent\fR for \fIClientID\fR.
For DHCPv6 interfaces, the result will contain the DUID. For DHCPv4 interfaces
with \fBV4_DEFAULT_IAID_DUID\fR enabled (see below), the result will contain
the IAID and DUID.
.RE

.sp
.ne 2
.na
\fB\fB/etc/default/dhcpagent\fR\fR
.ad
.sp .6
.RS 4n
Contains default values for tunable parameters. All values may be qualified
with the interface they apply to by prepending the interface name and a period
(".") to the interface parameter name. The parameters include: the interface
parameter name.
.sp
To configure IPv6 parameters, place the string \fB\&.v6\fR between the
interface name (if any) and the parameter name. For example, to set the global
IPv6 parameter request list, use \fB\&.v6.PARAM_REQUEST_LIST\fR. To set the
\fBCLIENT_ID\fR (\fBDUID\fR) on \fBhme0\fR, use \fBhme0.v6.CLIENT_ID\fR.
.sp
The parameters include:
.sp
.ne 2
.na
\fB\fBVERIFIED_LEASE_ONLY\fR\fR
.ad
.sp .6
.RS 4n
Indicates that a \fBRELEASE\fR rather than a \fBDROP\fR should be performed on
managed interfaces when the agent terminates. Release causes the client to
discard the lease, and the server to make the address available again. Drop
causes the client to record the lease in \fB/etc/dhcp/\fIinterface\fR.dhc\fR or
\fB/etc/dhcp/\fIinterface\fR.dh6\fR for later use. In addition, when the link
status changes to \fBup\fR or when the system is resumed after a suspend, the
client will verify the lease with the server. If the server is unreachable for
verification, then the old lease will be discarded (even if it has time
remaining) and a new one obtained.
.sp
Enabling this option is often desirable on mobile systems, such as laptops, to
allow the system to recover quickly from moves.
.sp
Default value of this option is \fIno\fR.
.RE

.sp
.ne 2
.na
\fB\fBOFFER_WAIT\fR\fR
.ad
.sp .6
.RS 4n
Indicates how long to wait in seconds between checking for valid
\fBOFFER\fRs after sending a \fBDISCOVER\fR. For DHCPv6, sets the time to
wait between checking for valid Advertisements after sending a Solicit.
.sp
Default value of this option is \fI3\fR.
.RE

.sp
.ne 2
.na
\fB\fBCLIENT_ID\fR\fR
.ad
.sp .6
.RS 4n
Indicates the value that should be used to uniquely identify the client to the
server. This value can take one of three basic forms:
.sp
.in +2
.nf
\fIdecimal\fR,\fIdata\fR...
0xHHHHH...
"\fIstring\fR...."
.fi
.in -2
.sp

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 \fIdata\fR... depends on the decimal value. The
following formats are defined for this first form:
.sp
.ne 2
.na
\fB1,\fIhwtype\fR,\fItime\fR,\fIlla\fR\fR
.ad
.sp .6
.RS 4n
Type 1, DUID-LLT. The \fIhwtype\fR value is an integer in the range 0-65535,
and indicates the type of hardware. The \fItime\fR value is the number of
seconds since midnight, January 1st, 2000 UTC, and can be omitted to use the
current system time. The \fIlla\fR value is either a colon-separated MAC
address or the name of a physical interface. If the name of an interface is
used, the \fIhwtype\fR value can be omitted. For example: \fB1,,,hme0\fR
.RE

.sp
.ne 2
.na
\fB2,\fIenterprise\fR,\fIhex\fR...\fR
.ad
.sp .6
.RS 4n
Type 2, DUID-EN. The \fIenterprise\fR value is an integer in the range
0-4294967295 and represents the SMI Enterprise number for an organization. The
\fIhex\fR string is an even-length sequence of hexadecimal digits.
.RE

.sp
.ne 2
.na
\fB3,\fIhwtype\fR,\fIlla\fR\fR
.ad
.sp .6
.RS 4n
Type 3, DUID-LL. This is the same as DUID-LLT (type 1), except that a time
stamp is not used.
.RE

.sp
.ne 2
.na
\fB*,\fIhex\fR\fR
.ad
.sp .6
.RS 4n
Any other type value (0 or 4-65535) can be used with an even-length hexadecimal
string.
.RE

The second and third forms of \fBCLIENT_ID\fR are legal for IPv4 only. These
both represent raw Client ID (without RFC 4361), in hex, or NVT ASCII string
format. Thus, "\fBSun\fR" and \fB0x53756E\fR are equivalent.
.RE

.sp
.ne 2
.na
\fB\fBV4_DEFAULT_IAID_DUID\fR\fR
.ad
.sp .6
.RS 4n
Indicates whether to use, when CLIENT_ID is not defined, a system-managed,
RFC 3315-style (i.e., DHCPv6-style) binding identifier as documented in
RFC 4361, "Node-specific Client Identifiers for DHCPv4," for IPv4
interfaces which for purposes of backward compatibility do not normally get
default binding identifiers.
.sp
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.
.sp
Default value of this option is \fIno\fR.
.RE

.sp
.ne 2
.na
\fB\fBPARAM_REQUEST_LIST\fR\fR
.ad
.sp .6
.RS 4n
Specifies a list of comma-separated integer values of options for which the
client would like values, or symbolic \fBSite\fR or \fBOption\fR option names.
Symbolic option names for IPv4 are resolved through \fB/etc/dhcp/inittab\fR.
Option names for IPv6 are resolved by means of \fB/etc/dhcp/inittab6\fR.
.RE

.sp
.ne 2
.na
\fB\fBPARAM_IGNORE_LIST\fR\fR
.ad
.sp .6
.RS 4n
Specifies a list of options (constructed in the same manner as
\fBPARAM_REQUEST_LIST\fR) that the DHCP client will ignore. Ignored options are
treated as though the server did not return the options specified. Ignored
options are not visible using \fBdhcpinfo\fR(1) or acted on by the client. This
parameter can be used, for example, to disable an unwanted client name or
default router.
.RE

.sp
.ne 2
.na
\fB\fBREQUEST_FQDN\fR\fR
.ad
.sp .6
.RS 4n
Indicates the client requests the DHCP server to map the client's leased
IPv4 address to the Fully Qualified Domain Name (FQDN) associated with the
network interface that performs DHCP on the client and to collaborate with
a compatible DNS server to manage A and PTR resource records for the FQDN
for the life of the lease.
.sp .6
The \fIhostname\fR in the FQDN is determined from the following possible
configurations:
.sp
.ne 2
.na
1.  \fBipadm\fR(8): include the \fB-1,--primary\fR flag when creating an
address that uses DHCP so that \fBnodename\fR(4) is used as the
\fIhostname\fR.
.ad
.sp
.ne 2
.na
2.  \fBipadm\fR(8): include the \fB-h,--reqhost\fR \fIhostname\fR switch
when executing the \fBcreate-addr -T dhcp\fR subcommand, or use the
\fBset-addrprop -p reqhost=\fR\fIhostname\fR subcommand for any existing
DHCP address.
.ad
.sp
.ne 2
.na
3.  \fBnwamcfg\fR(8): set a property,
\fBip-primary=\fR\fIon\fR, for an ncu ip that uses DHCP so that
\fBnodename\fR(4) is used as the \fIhostname\fR.
.ad
.sp
.ne 2
.na
4.  \fBnwamcfg\fR(8): set a property,
\fBip-reqhost=\fR\fIhostname\fR, for an ncu ip that uses DHCP.
.ad
.sp
The \fIhostname\fR 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
\fBDNS_DOMAINNAME\fR is defined or if \fBADOPT_DOMAINNAME\fR is set to
\fIyes\fR and an eligible domain name (as described below) is available.
.sp
If an FQDN is sent, \fBREQUEST_HOSTNAME\fR 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."
.sp
Default value of this option is \fIyes\fR.
.RE

.sp
.ne 2
.na
\fB\fBDNS_DOMAINNAME\fR\fR
.ad
.sp .6
.RS 4n
Indicates the value that should be appended to a PQDN specified by the
\fB-h,--reqhost\fR option of \fBipadm\fR(8), by the ncu \fBip-reqhost\fR
property of \fBnwamcfg\fR(8), or by \fBnodename\fR(4) to construct an FQDN
for \fBREQUEST_FQDN\fR processing.
If the \fIhostname\fR value is already an FQDN, then the value of this
option is not used.
.RE

.sp
.ne 2
.na
\fB\fBADOPT_DOMAINNAME\fR\fR
.ad
.sp .6
.RS 4n
Indicates that a domain name returned by the DHCP server or the \fBdomain\fR
from \fBresolv.conf\fR(4) should be adopted if needed to construct an FQDN
from a PQDN specified by the \fB-h,--reqhost\fR option of \fBipadm\fR(8),
by the ncu \fBip-reqhost\fR property of \fBnwamcfg\fR(8), or by
\fBnodename\fR(4).
If the \fIhostname\fR value is already an FQDN, then the value of this
option is not applicable.
The eligible DHCP option for domain name is DHCPv4 \fBDNSdmain\fR.
.sp
Default value of this option is \fIno\fR.
.RE

.sp
.ne 2
.na
\fB\fBREQUEST_HOSTNAME\fR\fR
.ad
.sp .6
.RS 4n
Indicates the client requests the DHCP server to map the client's leased IPv4
address to the host name associated with the network interface that performs
DHCP on the client. The host name must be specified as documented for a
PQDN in \fBREQUEST_FQDN\fR above or specified in the
\fB/etc/hostname.\fIinterface\fR\fR file for the relevant interface on a line
of the form
.sp
.in +2
.nf
inet \fIhostname\fR
.fi
.in -2
.sp

where \fIhostname\fR is the host name requested.
.sp
This option works with DHCPv4 only.
.sp
Default value of this option is \fIyes\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fB/etc/dhcp/eventhook\fR\fR
.ad
.sp .6
.RS 4n
Location of a DHCP event program.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     Committed
.TE

.SH SEE ALSO
.LP
\fBdhcpinfo\fR(1), \fBifconfig\fR(8), \fBinit\fR(8), \fBin.mpathd\fR(8),
\fBin.ndpd\fR(8), \fBipadm\fR(8), \fBnwamcfg\fR(8), \fBsyslog\fR(3C),
\fBnodename\fR(4), \fBresolv.conf\fR(4), \fBattributes\fR(5), \fBdhcp\fR(5)
.sp
.LP
\fI\fR
.sp
.LP
Croft, B. and Gilmore, J. \fIRFC 951, Bootstrap Protocol (BOOTP)\fR, Network
Working Group, September 1985.
.sp
.LP
Droms, R. \fIRFC 2131, Dynamic Host Configuration Protocol\fR, Network Working
Group, March 1997.
.sp
.LP
Lemon, T. and B. Sommerfeld. \fIRFC 4361, Node-specific Client Identifiers for
Dynamic Host Configuration Protocol Version Four (DHCPv4)\fR. Nominum and Sun
Microsystems. February 2006.
.sp
.LP
Droms, R. \fIRFC 3315, Dynamic Host Configuration Protocol for IPv6
(DHCPv6)\fR. Cisco Systems. July 2003.
.SH NOTES
.LP
The \fBdhcpagent\fR daemon can be used on IPv4 logical interfaces, just as with
physical interfaces. When used on a logical interface, the daemon automatically
constructs a Client ID value based on the DUID and IAID values, according to
RFC 4361. The  \fB/etc/default/dhcpagent\fR \fBCLIENT_ID\fR value, if any,
overrides this automatic identifier.
.sp
.LP
As with physical IPv4 interfaces, the \fB/etc/hostname.hme0:1\fR and
\fB/etc/dhcp.hme0:1\fR files must also be created in order for \fBhme0:1\fR to
be automatically plumbed and configured at boot. In addition, unlike physical
IPv4 interfaces, \fBdhcpagent\fR does not add or remove default routes
associated with logical interfaces.
.sp
.LP
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 \fBDISCOVER\fR and
\fBREQUEST\fR messages on IPMP IP interfaces. Some DHCP servers may refuse such
requests.
.sp
.LP
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
\fBNOFAILOVER\fR and \fBDEPRECATED\fR 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 \fBin.mpathd\fR(8) to revert to
link-based failure detection and trigger an erroneous repair.
.sp
.LP
With DHCPv6, the link-local interface must be configured using
\fB/etc/hostname6.hme0\fR in order for DHCPv6 to run on \fBhme0\fR at boot
time. The logical interfaces for each address are plumbed by \fBdhcpagent\fR
automatically.