dhcpagent - Dynamic Host Configuration Protocol (DHCP) client daemon
dhcpagent [-a] [ -d n] [-f] [-v]
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 parame-
ters 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.
The dhcpagent daemon is controlled through ifconfig(1M) in much the same way that the init(1M) daemon is controlled by telinit(1M). dhcpa-
gent can be invoked as a user process, albeit one requiring root privileges, but this is not necessary, as ifconfig(1M) will start it auto-
When invoked, dhcpagent enters a passive state while it awaits instructions fromifconfig(1M). When it receives a command to configure an
interface, it starts DHCP. Once DHCP is complete, dhcpagent may 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, the interface is configured and brought up. When a lease is obtained, it
is automatically renewed as necessary. If the lease cannot be renewed, dhcpagent will take the interface down at the end of the lease. If
the configured interface is found to be unplumbed, marked down, or to have a different IP address, subnet mask, or broadcast address from
those obtained from DHCP, the interface is abandoned by DHCP control.
In addition to DHCP, dhcpagent also supports BOOTP. 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 infi-
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, 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 pos-
sible 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.
The dhcpagent daemon can be configured to request a particular host name. See the REQUEST_HOSTNAME 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
# pkill dhcpagent
# rm /etc/dhcp/interface.dhc
All DHCP packets sent by dhcpagent include a vendor class identifier (RFC 2132, option code 60). This identifier is the same as the plat-
form 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.
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 fail-
ure 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 infor-
mation, 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. Debug-
ging 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 deamon will automatically run that program when any of
the following events occur:
This event occurs during interface configuration. The event program is invoked when dhcpagent receives the ACK reply from the DHCP
server for the lease request of an address, indicating successful configuration.
This event occurs during lease extension. The event program is invoked just after dhcpagent receives the ACK reply from the DHCP server
for the renew request.
This event occurs during lease expiration. The event program is invoked just before the leased address is removed from an interface and
the interface is marked as "down".
This event occurs during the period when an interface is dropped. The event program is invoked just before the interface is removed
from DHCP control.
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 RELEASE packet to the DHCP server.
The system does not provide a default event program. The file /etc/dhcp/eventhook is owned by the root and its mode must be 755.
The event program will be passed two arguments, the interface name and the event name, respectively.
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 for an example event program.
The following options are supported:
-a Adopt a configured 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:
o 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:
o 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:
-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
-v Provide verbose output useful for debugging site configuration problems.
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.
echo "Interface name: " $1
echo "Event: " $2
case $2 in
echo "Address acquired from server " `/sbin/dhcpinfo -i $1 ServerID`
echo "Lease extended for " `'sbin/dhcpinfo -i $1 LeaseTim`" seconds"
"EXPIRE" | "DROP" | "RELEASE")
) >/var/run/dhcp_eventhook_output 2>&1
Note the redirection of stdout and stderr to a file.
Contains the configuration for interface. The mere existence of this file does not imply that the configuration is correct, since the
lease may have expired.
Contains default values for tunable parameters. All values may be qualified with the interface they apply to by prepending the inter-
face name and a period (".") to the interface parameter name. The parameters include:
Indicates that a RELEASE rather than a DROP should be performed on managed interfaces when the agent terminates.
Indicates how long to wait between checking for valid OFFERs after sending a DISCOVER.
Indicates how long to wait for clients to respond to an ARP request before concluding the address in the ARP request is unused.
Specifies whether or not the agent should assume an address is available, in the unlikely event that ARP cannot be performed on
Indicates the value that should be used to uniquely identify the client to the server.
Specifies a list of comma-separated integer values of options for which the client would like values.
Indicates the client requests the DHCP server to map the client's leased IP 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
where hostname is the host name requested.
Location of a DHCP event program.
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|Availability |SUNWcsr |
|Interface Stability |Evolving |
dhcpinfo(1), ifconfig(1M), init(1M), syslog(3C), attributes(5), dhcp(5)
Croft, B. and Gilmore, J.,Bootstrap Protocol (BOOTP)RFC 951, Network Working Group, September 1985.
Droms, R., Dynamic Host Configuration Protocol, RFC 2131, Network Working Group, March 1997.
The dhcpagent daemon can be used on logical interfaces just as with physical interfaces. However, each logical interface must first be con-
figured with a unique client id by setting the /etc/default/dhcpagent CLIENT_ID parameter (see description above).
For example, inserting the entry:
...in /etc/default/dhcpagent will cause dhcpagent to use the client id orangutan when managing the lease for hme0:1. As with physical
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 interfaces, dhcpagent does not add or remove default routes associated with logical interfaces.
4 Feb 2005 dhcpagent(1M)