dhcpagent(1M)															     dhcpagent(1M)

NAME

       dhcpagent - Dynamic Host Configuration Protocol (DHCP) client daemon

SYNOPSIS

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

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

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

       BOUND

	   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.

       EXTEND

	   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.

       EXPIRE

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

       DROP

	   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.

       RELEASE

	   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:

		     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.

       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`
	    ;;
       "EXTEND")
	    echo "Lease extended for " `'sbin/dhcpinfo -i $1 LeaseTim`" seconds"
	    ;;
       "EXPIRE" | "DROP" | "RELEASE")
	    ;;

       esac
       ) >/var/run/dhcp_eventhook_output 2>&1

       Note the redirection of stdout and stderr to a file.

       /etc/dhcp/if.dhc

	   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.

       /etc/default/dhcpagent

	   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:

	   RELEASE_ON_SIGTERM

	       Indicates that a RELEASE rather than a DROP should be performed on managed interfaces when the agent terminates.

	   OFFER_WAIT

	       Indicates how long to wait between checking for valid OFFERs after sending a DISCOVER.

	   ARP_WAIT

	       Indicates how long to wait for clients to respond to an ARP request before concluding the address in the ARP request is unused.

	   IGNORE_FAILED_ARP

	       Specifies  whether  or  not  the agent should assume an address is available, in the unlikely event that ARP cannot be performed on
	       that address.

	   CLIENT_ID

	       Indicates the value that should be used to uniquely identify the client to the server.

	   PARAM_REQUEST_LIST

	       Specifies a list of comma-separated integer values of options for which the client would like values.

	   REQUEST_HOSTNAME

	       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

	       inet hostname

		where hostname is the host name requested.

       /etc/dhcp/eventhook

	   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:

       hme0:1.CLIENT_ID=orangutan

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