


dhclient-script(8)                             dhclient-script(8)


NNAAMMEE
       dhclient-script - DHCP client network configuration script

DDEESSCCRRIIPPTTIIOONN
       The DHCP client network configuration  script  is  invoked
       from  time to time by ddhhcclliieenntt((88)).  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
       //eettcc//rreessoollvv..ccoonnff 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
       //eettcc//ddhhcclliieenntt..ccoonnff file.   If you find that you can't make
       such      a      customization     without     customizing
       //eettcc//ddhhcclliieenntt..ccoonnff or using  the  enter  and  exit  hooks,
       please submit a bug report.

HHOOOOKKSS
       When  it  starts,  the client script first defines a shell
       function, mmaakkee__rreessoollvv__ccoonnff ,, which is later used to create
       the  //eettcc//rreessoollvv..ccoonnff  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
       //eettcc//ddhhcclliieenntt--eenntteerr--hhooookkss   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
       //uussrr//llooccaall//ssbbiinn//ddhhcclliieenntt--ssccrriipptt will exit with that  error
       code immediately after the client script exits.

       After       all       processing       has      completed,
       //uussrr//llooccaall//ssbbiinn//ddhhcclliieenntt--ssccrriipptt checks for the presence of
       an  executable  //eettcc//ddhhcclliieenntt--eexxiitt--hhooookkss  script, which if
       present is invoked using the '.' command.  The exit status



                                                                1





dhclient-script(8)                             dhclient-script(8)


       of  dhclient-script  will be passed to dhclient-exit-hooks
       in the exit_status shell variable, and will always be zero
       if  the  script  succeeded  at  the  task for which it was
       invoked.   The rest of the environment as described previ-
       ously  for  dhclient-enter-hooks  is  also  present.   The
       //eettcc//ddhhcclliieenntt--eexxiitt--hhooookkss script can modify  the  valid  of
       exit_status  to change the exit status of dhclient-script.

OOPPEERRAATTIIOONN
       When dhclient needs to  invoke  the  client  configuration
       script,  it defines a set of variables in the environment,
       and then invokes //uussrr//llooccaall//ssbbiinn//ddhhcclliieenntt--ssccrriipptt..  In  all
       cases,  $reason  is  set to the name of the reason why the
       script has been invoked.   The following reasons are  cur-
       rently  defined:  MEDIUM,  PREINIT,  BOUND, RENEW, REBIND,
       REBOOT, EXPIRE, FAIL, STOP, RELEASE, NBI and TIMEOUT.


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

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

BBOOUUNNDD
       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 ddhhccpp--ooppttiioonnss, 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.

       Before actually configuring the  address,  dhclient-script
       should  somehow  ARP for it and exit with a nonzero status
       if it receives a reply.   In this case,  the  client  will



                                                                2





dhclient-script(8)                             dhclient-script(8)


       send  a  DHCPDECLINE  message  to the server and acquire a
       different address.   This may also be done in  the  RENEW,
       REBIND,  or REBOOT states, but is not required, and indeed
       may not be desirable.

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

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

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

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

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

FFAAIILL
       The  DHCP  client  has  been  unable  to  contact any DHCP
       servers, and any leases that have  been  tested  have  not



                                                                3





dhclient-script(8)                             dhclient-script(8)


       proved  to  be valid.   The parameters from the last lease
       tested should be deconfigured.   This can  be  handled  in
       the same way as EXPIRE.

SSTTOOPP
       The  dhclient  has  been informed to shut down gracefully,
       the dhclient-script should  unconfigure  or  shutdown  the
       interface as appropriate.

RREELLEEAASSEE
       The dhclient has been executed using the -r flag, indicat-
       ing that  the  administrator  wishes  it  to  release  its
       lease(s).   dhclient-script should unconfigure or shutdown
       the interface.

NNBBII
       No-Broadcast-Interfaces...dhclient was unable to find  any
       interfaces upon which it believed it should commence DHCP.
       What  dhclient-script  should  do  in  this  situation  is
       entirely up to the implementor.

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

FFIILLEESS
       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 Internet Systems Consortium DHCP  distribution
       appear  in the distribution tree under client/scripts, and
       bear the names of the operating systems on which they  are
       intended to work.

BBUUGGSS
       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



                                                                4





dhclient-script(8)                             dhclient-script(8)


       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.

SSEEEE AALLSSOO
       dhclient(8),  dhcpd(8),  dhcrelay(8), dhclient.conf(5) and
       dhclient.leases(5).

AAUUTTHHOORR
       ddhhcclliieenntt--ssccrriipptt((88)) has been written for  Internet  Systems
       Consortium  by  Ted Lemon in cooperation with Vixie Enter-
       prises.  To learn more about Internet Systems  Consortium,
       see hhttttppss::////wwwwww..iisscc..oorrgg..  To learn more about Vixie Enter-
       prises, see hhttttpp::////wwwwww..vviixx..ccoomm..









































                                                                5


