System Administration Commands dhcpagent(1M)
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 Solaris
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
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 ifconfig(1M) will start it automati-
cally.
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 ifconfig(1M) or in.ndpd(1M). When
it receives a command to configure an interface, it 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, it 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,
SunOS 5.11 Last change: 20 Jan 2009 1
System Administration Commands dhcpagent(1M)
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.
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 logi-
cal 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 BOTP (IPv4
only). See RFC 951, Bootstrap Protocol. Configuration param-
eters obtained from a BOTP server are treated identically
to those received from a DHCP server, except that the IP
address received from a BOTP 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 worksta-
tion, but instead acts as a database which may be interro-
gated by other programs, and in particular by dhcpinfo(1).
On clients with a single interface, this is quite straight-
forward. Clients with multiple interfaces may present diffi-
culties, as it is possible that some information arriving on
different interfaces may need to be merged, or may be incon-
sistent. 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.
SunOS 5.11 Last change: 20 Jan 2009 2
System Administration Commands dhcpagent(1M)
For IPv4, the dhcpagent daemon can be configured to request
a particular host name. See the REQUESTHOSTNAME description
in the FILES section. When first configuring a client to
request a 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
SunOS 5.11 Last change: 20 Jan 2009 3
System Administration Commands dhcpagent(1M)
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 dif-
ferent 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 prob-
lems. 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 LOGDAEMON.
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 deamon 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 success-
ful initial configuration of the interface. (See also
the INFORM and INFORM6 events, which occur when confi-
guration 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
SunOS 5.11 Last change: 20 Jan 2009 4
System Administration Commands dhcpagent(1M)
(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 IFDEPRECATED 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 inter-
face, 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(1M) 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 parame-
ters.
LOS6
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 IFDEPRECATED
flag.
Note that this event is not associated with the receipt
SunOS 5.11 Last change: 20 Jan 2009 5
System Administration Commands dhcpagent(1M)
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 inter-
face 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 inter-
face 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 SIGKIL
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
SunOS 5.11 Last change: 20 Jan 2009 6
System Administration Commands dhcpagent(1M)
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 pri-
marily for use in boot scripts.
The effect of this option depends on whether the inter-
face is being adopted.
If the interface is being adopted, the following condi-
tions apply:
dhcpagent uses the client id specified in
/chosen:, 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 inter-
face 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 Infini-
band and there is no value in /etc/default/dhcpagent, a
client id is generated as described by the draft docu-
ment 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 ver-
bose.
-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 confi-
guration problems.
SunOS 5.11 Last change: 20 Jan 2009 7
System Administration Commands dhcpagent(1M)
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/dhcpeventhookoutput 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 confi-
guration is correct, since the lease might have expired.
On start-up, dhcpagent confirms the validity of the
SunOS 5.11 Last change: 20 Jan 2009 8
System Administration Commands dhcpagent(1M)
address using REQUEST (for DHCPv4) or Confirm (DHCPv6).
/etc/dhcp/duid
/etc/dhcp/iaid
Contains persistent storage for DUID (DHCP Unique Iden-
tifier) and IAID (Identity Association Identifier)
values. The format of these files is undocumented, and
applications should not read from or write to them.
/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.PARAMREQUESTLIST. To set the
CLIENTID (DUID) on hme0, use hme0.v6.CLIENTID.
The parameters include:
RELEASEONSIGTERM
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.
OFERWAIT
Indicates how long to wait between checking for
valid OFERs after sending a DISCOVER. For DHCPv6,
sets the time to wait between checking for valid
Advertisements after sending a Solicit.
CLIENTID
Indicates the value that should be used to uniquely
identify the client to the server. This value can
take one of three basic forms:
SunOS 5.11 Last change: 20 Jan 2009 9
System Administration Commands dhcpagent(1M)
decimal,data...
0xH...
"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-LT. 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-L. This is the same as DUID-LT
(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 CLIENTID are legal
for IPv4 only. These both represent raw Client ID
(without RFC 4361), in hex, or NVT ASCI string for-
mat. Thus, Sun and 0x53756E are equivalent.
SunOS 5.11 Last change: 20 Jan 2009 10
System Administration Commands dhcpagent(1M)
PARAMREQUESTLIST
Specifies a list of comma-separated integer values
of options for which the client would like values.
REQUESTHOSTNAME
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
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.
/etc/dhcp/eventhook
Location of a DHCP event program.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsr
Interface Stability Committed
SEE ALSO
dhcpinfo(1), ifconfig(1M), init(1M), in.mpathd(1M),
in.ndpd(1M), syslog(3C), attributes(5), dhcp(5)
Croft, B. and Gilmore, J.,Bootstrap Protocol (BOTP)RFC 951,
Network Working Group, September 1985.
SunOS 5.11 Last change: 20 Jan 2009 11
System Administration Commands dhcpagent(1M)
Droms, R., Dynamic Host Configuration Protocol, RFC 2131,
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.
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 CLIENTID 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(1M) to
revert to link-based failure detection and trigger an
erroneous repair.
SunOS 5.11 Last change: 20 Jan 2009 12
System Administration Commands dhcpagent(1M)
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.
SunOS 5.11 Last change: 20 Jan 2009 13
|
