Logo

Charles Steinkuehler's LEAF/LRP Website


 

dhclient-script.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.
       If  local customizations are needed, they should be possi­
       ble using the enter and exit hooks provided (see HOOKS for
       details).    These  hooks  will allow the user to override
       the  default  behaviour  of  the  client  in  creating   a
       /etc/resolv.conf file.

       No  standard  client script exists for some operating sys­
       tems, even though the actual client may work,  so  a  pio­
       neering  user may well need to create a new script or mod­
       ify an existing one.  In general, customizations  specific
       to   a   particular   computer   should  be  done  in  the
       ETCDIR/dhclient.conf file.   If you find  that  you  can't
       make  such  a  customization without customizing dhclient-
       script or using the enter and exit hooks, please submit  a
       bug report.


HOOKS

       When  it  starts,  the client script first defines a shell
       function, make_resolv_conf , which is later used to create
       the  /etc/resolv.conf  file.    To  override  the  default
       behaviour,  redefine  this  function  in  the  enter  hook
       script.

       On  after  defining  the  make_resolv_conf  function,  the
       client script checks for the  presence  of  an  executable
       ETCDIR/dhclient-enter-hooks  script,  and  if  present, it
       invokes the script inline, using the Bourne shell '.' com­
       mand.    The entire environment documented under OPERATION
       is available to this script, which may modify the environ­
       ment if needed to change the behaviour of the script.   If
       an error occurs during the execution of the script, it can
       set  the  exit_status  variable  to  a  nonzero value, and
       ETCDIR/dhclient-script will  exit  with  that  error  code
       immediately after the client script exits.

       After all processing has completed, ETCDIR/dhclient-script
       checks for the presence of an executable  ETCDIR/dhclient-
       exit-hooks  script,  which if present is invoked using the
       '.'  command.    The  exit  status  is   passed   in   the
       exit_status shell variable, and will always be zero if the
       script succeeded at the task for which it was invoked.


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.


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 ARPSEND 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,  seperated  by spaces).   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
       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 distri­
       bution   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.


Man(1) output converted with man2html