Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎


     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

     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-

     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  starts
     DHCP on the interface.  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,  and  attempt  to  acquire  a new
     address lease on the interface.  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.

     For IPv4,  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.

     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, marked down, or configured with  a  different  IP
     address,  it will be abandoned by 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 param-
     eters 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

     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.

     For IPv4, 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 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

         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  messages  indicate  severe   conditions   that
         prevent proper operation.


         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 indicate less  severe  problems,  and  in  most
         cases,  describe unusual or incorrect datagrams received
         from servers, or requests for  service  that  cannot  be


         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


         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 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:

     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


         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.


         These events occur during lease expiration. For  DHCPv4,
         the  event  program  is  invoked  just before the leased
         address is removed from an interface and  the  interface
         is  marked  as  down.  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.


         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-


         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

         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


         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 SIGKILL

     See EXAMPLES for an example event program.

     The following options are supported:


         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 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:<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 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:


     -d n

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


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


         Provide verbose output useful for debugging site  confi-
         guration 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


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

       case $2 in
           echo "Address acquired from server "\
               `/sbin/dhcpinfo -i $1 ServerID`
           echo "Addresses acquired from server " \
               `/sbin/dhcpinfo -v6 -i $1 ServerID`
          echo "Lease extended for " \
               `sbin/dhcpinfo -i $1 LeaseTim`" seconds"
          echo "New lease information obtained on $i"
       "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 confi-
         guration 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).


         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.


         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:


             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.


             Indicates how long  to  wait  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.


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

             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:


                 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


                 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.


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


                 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 for-
             mat. Thus, Sun and 0x53756E are equivalent.


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


         Location of a DHCP event program.

     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWcsr                     |
    | Interface Stability         | Committed                   |

     dhcpinfo(1),    ifconfig(1M),     init(1M),     in.ndpd(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.

     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.

     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/dhcpclient 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

     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.

Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.