


dhclient(8)                                           dhclient(8)


NAME
       dhclient-script - DHCP client network configuration script

DESCRIPTION
       The DHCP client network configuration  script  is  invoked
       from  time to time by dhclient(8).  This script is used by
       the dhcp client to set each interface's initial configura-
       tion  prior  to requesting an address, to test the address
       once it has been offered, and to set the interface's final
       configuration once a lease has been acquired.  If no lease
       is acquired, the script is used to test predefined leases,
       if  any,  and  also  called  once if no valid lease can be
       identified.

       This script is not meant to be customized by the end user.
       However, the script may not work on particular versions of
       particular operating systems (indeed, no  standard  script
       exists  for  some operating systems), so a pioneering user
       may well need to create a new script or modify an existing
       one.   In general, customizations specific to a particular
       computer should be done in the /etc/dhclient.conf  script.
       If you find that you can't make such a customization with-
       out customizing dhclient.conf, please submit a bug report.

OPERATION
       When  dhclient  needs  to  invoke the client configuration
       script, it writes a shell script into /tmp which defines a
       variety of variables.  In all cases, $reason is set to the
       name of the reason why the script has been invoked.    The
       following  reasons are currently defined: MEDIUM, PREINIT,
       ARPCHECK, ARPSEND, BOUND, RENEW, REBIND,  REBOOT,  EXPIRE,
       FAIL and TIMEOUT.


MEDIUM
       The  DHCP  client  is requesting that an interface's media
       type be set.  The interface name is passed in  $interface,
       and the media type is passed in $medium.

PREINIT
       The DHCP client is requesting that an interface be config-
       ured as required in order to send packets prior to receiv-
       ing  an  actual  address.    For clients which use the BSD
       socket library, this means configuring the interface  with
       an  IP  address  of  0.0.0.0  and  a  broadcast address of
       255.255.255.255.   For other clients, it may  be  possible
       to simply configure the interface up without actually giv-
       ing it an IP address  at  all.    The  interface  name  is
       passed in $interface, and the media type in $medium.

       If  an  IP  alias  has been declared in dhclient.conf, its
       address will be passed in $alias_ip_address, and  that  ip
       alias should be deleted from the interface, along with any
       routes to it.



                                                                1





dhclient(8)                                           dhclient(8)


ARPSEND
       The DHCP client is requesting that  an  address  that  has
       been  offered  to it be checked to see if somebody else is
       using it, by sending an  ARP  request  for  that  address.
       It's not clear how to implement this, so no examples exist
       yet.    The   IP   address   to   check   is   passed   in
       $new_ip_address,  and  the  interface  name  is  passed in
       $interface.

ARPCHECK
       The DHCP client wants to know if a  response  to  the  ARP
       request  send  using  ARPCHECK has been received.   If one
       has, the script should exit with a nonzero  status,  indi-
       cating that the offered address has already been requested
       and should be declined.   $new_ip_address  and  $interface
       are set as with ARPSEND.

BOUND
       The  DHCP  client  has  done  an  initial binding to a new
       address.     The   new   ip   address   is    passed    in
       $new_ip_address,  and  the  interface  name  is  passed in
       $interface.   The media type is passed in  $medium.    Any
       options  acquired  from  the  server  are passed using the
       option name described in dhcp-options, except that  dashes
       ('-')  are  replaced by underscores ('_') in order to make
       valid shell variables, and the variable names  start  with
       new_.    So  for  example,  the  new  subnet mask would be
       passed in $new_subnet_mask.

       When a binding has been completed, a lot of network param-
       eters   are   likely  to  need  to  be  set  up.    A  new
       /etc/resolv.conf needs to be created, using the values  of
       $new_domain_name  and  $new_domain_name_servers (which may
       list more than one  server,  separated  by  spaces).    If
       /etc/resolv.conf.tail exists, it is appended to the newly-
       created /etc/resolv.conf file.  A default route should  be
       set  using  $new_routers, and static routes may need to be
       set up using $new_static_routes.

       If an IP alias has been declared, it must be set up  here.
       The alias IP address will be written as $alias_ip_address,
       and other DHCP options that are set for the  alias  (e.g.,
       subnet   mask)  will  be  passed  in  variables  named  as
       described previously except starting with $alias_  instead
       of $new_.   Care should be taken that the alias IP address
       not be used if it is identical to  the  bound  IP  address
       ($new_ip_address), since the other alias parameters may be
       incorrect in this case.

RENEW
       When a binding has been renewed, the script is  called  as
       in  BOUND,  except  that  in addition to all the variables
       starting with $new_, there is  another  set  of  variables
       starting  with  $old_.   Persistent settings that may have



                                                                2





dhclient(8)                                           dhclient(8)


       changed need to be deleted - for example, if a local route
       to  the  bound  address is being configured, the old local
       route  should  be  deleted.   If  the  default  route  has
       changed,  the old default route should be deleted.  If the
       static  routes  have  changed,  the  old  ones  should  be
       deleted.  Otherwise, processing can be done as with BOUND.

REBIND
       The DHCP client has rebound to a new  DHCP  server.   This
       can  be  handled  as  with  RENEW,  except  that if the IP
       address has changed, the ARP table should be cleared.

REBOOT
       The  DHCP  client  has  successfully  reacquired  its  old
       address  after  a  reboot.   This can be processed as with
       BOUND.

EXPIRE
       The DHCP client has failed to renew its lease or acquire a
       new  one, and the lease has expired.   The IP address must
       be relinquished, and  all  related  parameters  should  be
       deleted, as in RENEW and REBIND.

FAIL
       The  DHCP  client  has  been  unable  to  contact any DHCP
       servers, and any leases that have  been  tested  have  not
       proved  to  be valid.   The parameters from the last lease
       tested should be deconfigured.   This can  be  handled  in
       the same way as EXPIRE.

TIMEOUT
       The  DHCP  client  has  been  unable  to  contact any DHCP
       servers.  However, an old lease has been  identified,  and
       its  parameters  have  been passed in as with BOUND.   The
       client configuration script should test  these  parameters
       and,  if  it  has reason to believe they are valid, should
       exit with a value of zero.   If not, it should exit with a
       nonzero value.

       The  usual way to test a lease is to set up the network as
       with REBIND (since this may be called to  test  more  than
       one  lease)  and  then  ping  the  first router defined in
       $routers.  If a response is received, the  lease  must  be
       valid  for the network to which the interface is currently
       connected.   It would be more complete to try to ping  all
       of  the  routers  listed in $new_routers, as well as those
       listed in $new_static_routes, but current scripts  do  not
       do this.

FILES
       Each operating system should generally have its own script
       file, although the script files for similar operating sys-
       tems  may be similar or even identical.   The script files
       included  in  the  Internet   Software   Consortium   DHCP



                                                                3





dhclient(8)                                           dhclient(8)


       distribution   appear   in  the  distribution  tree  under
       client/scripts, and bear the names of the  operating  sys-
       tems on which they are intended to work.

BUGS
       If more than one interface is being used, there's no obvi-
       ous way to avoid clashes between server-supplied  configu-
       ration parameters - for example, the stock dhclient-script
       rewrites /etc/resolv.conf.   If more than one interface is
       being configured, /etc/resolv.conf will be repeatedly ini-
       tialized to the values provided by one  server,  and  then
       the  other.    Assuming  the  information provided by both
       servers is valid, this shouldn't cause any real  problems,
       but it could be confusing.

SEE ALSO
       dhclient(8),  dhcpd(8),  dhcrelay(8), dhclient.conf(5) and
       dhclient.leases(5).

AUTHOR
       dhclient-script(8) has been written for the Internet Soft-
       ware Consortium by Ted Lemon <mellon@fugue.com> in cooper-
       ation with Vixie Enterprises.  To  learn  more  about  the
       Internet  Software Consortium, see http://www.vix.com/isc.
       To   learn   more    about    Vixie    Enterprises,    see
       http://www.vix.com.































                                                                4


