Tribblix: manual page: dhcpagent.8

DHCPAGENT(8) Maintenance Commands and Procedures DHCPAGENT(8)

NAME

dhcpagent - Dynamic Host Configuration Protocol (DHCP) client daemon

SYNOPSIS

dhcpagent [-a] [ -d n] [-f] [-v]

DESCRIPTION

dhcpagent implements the client half of the Dynamic Host
Configuration Protocol (DHCP) for machines running illumos software.

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(8),
nwamcfg(8), or ifconfig(8) in much the same way that the init(8)
daemon is controlled by telinit(8). dhcpagent can be invoked as a
user process, albeit one requiring root privileges, but this is not
necessary, as ipadm(8), nwamcfg(8), or ifconfig(8) will start
dhcpagent automatically.

For IPv6, the dhcpagent daemon is invoked automatically by
in.ndpd(8). It can also be controlled through ifconfig(8), if
necessary.

When invoked, dhcpagent enters a passive state while it awaits
instructions from ipadm(8), nwamcfg(8), ifconfig(8), or in.ndpd(8).
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(8) 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(8) 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:

o Any commas in the platform name are changed to periods.

o If the name does not start with a stock symbol and a
comma, it is automatically prefixed with SUNW.

Messages

The dhcpagent daemon writes information and error messages in five
categories:

critical

Critical messages indicate severe conditions that prevent proper
operation.

errors

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.

warnings

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.

informational

Informational messages provide key pieces of information that can
be useful to debugging a DHCP configuration at a site.
Informational messages are generally controlled by the -v option.
However, certain critical pieces of information, such as the IP
address obtained, are always provided.

debug

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

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.

DHCP Events and User-Defined Actions
If an executable (binary or script) is placed at /etc/dhcp/eventhook,
the dhcpagent daemon will automatically run that program when any of
the following events occur:

BOUND and BOUND6

These events occur during interface configuration. The event
program is invoked when dhcpagent 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 INFORM and INFORM6 events, which occur
when configuration parameters are obtained without address
leases.)

EXTEND and EXTEND6

These events occur during lease extension. The event program is
invoked just after dhcpagent receives the DHCPv4 ACK or DHCPv6
Reply from the DHCP server for the DHCPv4 REQUEST (renew) message
or the DHCPv6 Renew or Rebind message.

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

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.

DROP and DROP6

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.

INFORM and INFORM6

These events occur when an interface acquires new or updated
configuration information from a DHCP server by means of the
DHCPv4 INFORM or the DHCPv6 Information-Request message. These
messages are sent using an ifconfig(8) dhcp inform command or
when the DHCPv6 Router Advertisement O (letter 0) bit is set and
the M 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.

LOSS6

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

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

This event occurs during the period when a leased address is
released. The event program is invoked just before dhcpagent
relinquishes the address on an interface and sends the DHCPv4
RELEASE or DHCPv6 Release packet to the DHCP server.

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.

OPTIONS

The following options are supported:

-a

Adopt a configured IPv4 interface. This option is for use with
diskless DHCP clients. In the case of diskless DHCP, DHCP has
already been performed on the network interface providing the
operating system image prior to running dhcpagent. This option
instructs the agent to take over control of the interface. It is
intended primarily for use in boot scripts.

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

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:

http://www.ietf.org

-d n

Set debug level to n. Two levels of debugging are currently
available, 1 and 2; the latter is more verbose.

-f

Run in the foreground instead of as a daemon process. When this
option is used, messages are sent to standard error instead of to
syslog(3C).

-v

Provide verbose output useful for debugging site configuration
problems.

EXAMPLES

Example 1: Example Event Program

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.

FILES

/etc/dhcp/if.dhc
/etc/dhcp/if.dh6

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, dhcpagent confirms the
validity of the address using REQUEST (for DHCPv4) or Confirm
(DHCPv6).

/etc/dhcp/duid
/etc/dhcp/iaid

Contains persistent storage for system-generated DUID (DHCP
Unique Identifier) and interface-specific IAID (Identity
Association Identifier) values which are used if no CLIENT_ID is
defined (see below). The format of these files is undocumented,
and applications should not read from or write to them. Instead,
dhcpinfo(1) can be used to query the dhcpagent for ClientID. For
DHCPv6 interfaces, the result will contain the DUID. For DHCPv4
interfaces with V4_DEFAULT_IAID_DUID enabled (see below), the
result will contain the IAID and DUID.

/etc/default/dhcpagent

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.

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:

VERIFIED_LEASE_ONLY

Indicates that a RELEASE rather than a DROP 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 /etc/dhcp/interface.dhc or
/etc/dhcp/interface.dh6 for later use. In addition, when the
link status changes to up 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.

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.

OFFER_WAIT

Indicates how long to wait in seconds between checking for
valid OFFERs after sending a DISCOVER. For DHCPv6, sets the
time to wait between checking for valid Advertisements after
sending a Solicit.

Default value of this option is 3.

CLIENT_ID

Indicates the value that should be used to uniquely identify
the client to the server. This value can take one of three
basic forms:

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:

1,hwtype,time,lla

Type 1, DUID-LLT. The hwtype value is an integer in the
range 0-65535, and indicates the type of hardware. The
time value is the number of seconds since midnight,
January 1st, 2000 UTC, and can be omitted to use the
current system time. The lla value is either a colon-
separated MAC address or the name of a physical
interface. If the name of an interface is used, the
hwtype value can be omitted. For example: 1,,,hme0

2,enterprise,hex...

Type 2, DUID-EN. The enterprise value is an integer in
the range 0-4294967295 and represents the SMI Enterprise
number for an organization. The hex string is an even-
length sequence of hexadecimal digits.

3,hwtype,lla

Type 3, DUID-LL. This is the same as DUID-LLT (type 1),
except that a time stamp is not used.

*,hex

Any other type value (0 or 4-65535) can be used with an
even-length hexadecimal string.

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.

V4_DEFAULT_IAID_DUID

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.

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.

PARAM_REQUEST_LIST

Specifies a list of comma-separated integer values of options
for which the client would like values, or symbolic Site or
Option option names. Symbolic option names for IPv4 are
resolved through /etc/dhcp/inittab. Option names for IPv6
are resolved by means of /etc/dhcp/inittab6.

PARAM_IGNORE_LIST

Specifies a list of options (constructed in the same manner
as PARAM_REQUEST_LIST) 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 dhcpinfo(1) or acted on by the client. This parameter
can be used, for example, to disable an unwanted client name
or default router.

REQUEST_FQDN

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.

The hostname in the FQDN is determined from the following
possible configurations:

1. ipadm(8): include the -1,--primary flag when creating an
address that uses DHCP so that nodename(5) is used as the
hostname.

2. ipadm(8): 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(8): set a property, ip-primary=on, for an ncu ip
that uses DHCP so that nodename(5) is used as the hostname.

4. nwamcfg(8): 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.

DNS_DOMAINNAME

Indicates the value that should be appended to a PQDN
specified by the -h,--reqhost option of ipadm(8), by the ncu
ip-reqhost property of nwamcfg(8), or by nodename(5) to
construct an FQDN for REQUEST_FQDN processing. If the
hostname value is already an FQDN, then the value of this
option is not used.

ADOPT_DOMAINNAME

Indicates that a domain name returned by the DHCP server or
the domain from resolv.conf(5) should be adopted if needed to
construct an FQDN from a PQDN specified by the -h,--reqhost
option of ipadm(8), by the ncu ip-reqhost property of
nwamcfg(8), or by nodename(5). If the hostname value is
already an FQDN, then the value of this option is not
applicable. The eligible DHCP option for domain name is
DHCPv4 DNSdmain.

Default value of this option is no.

REQUEST_HOSTNAME

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
REQUEST_FQDN above or specified in the
/etc/hostname.interface file for the relevant interface on a
line of the form

inet hostname

where hostname is the host name requested.

This option works with DHCPv4 only.

Default value of this option is yes.

/etc/dhcp/eventhook

Location of a DHCP event program.

ATTRIBUTES

NOTES

The dhcpagent 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 /etc/default/dhcpagent
CLIENT_ID value, if any, overrides this automatic identifier.

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(8) 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 DHCPAGENT(8)