external/bsd/dhcpcd/dist/dhcpcd-run-hooks.8.in

   1 .\" Copyright (c) 2006-2009 Roy Marples
   2 .\" All rights reserved
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd March 23, 2009
  26 .Dt DHCPCD-RUN-HOOKS 8 SMM
  27 .Os
  28 .Sh NAME
  29 .Nm dhcpcd-run-hooks
  30 .Nd DHCP client configuration script
  31 .Sh DESCRIPTION
  32 .Nm
  33 is used by
  34 .Xr dhcpcd 8
  35 to run any system and user defined hook scripts.
  36 System hook scripts are found in
  37 .Pa @HOOKDIR@
  38 and the user defined hooks are
  39 .Pa @SYSCONFDIR@/dhcpcd.enter-hook .
  40 and
  41 .Pa @SYSCONFDIR@/dhcpcd.exit-hook .
  42 The default install supplies hook scripts for configuring
  43 .Pa /etc/resolv.conf
  44 and the hostname.
  45 Your distribution may have included other hook scripts to say configure
  46 ntp or ypbind.
  47 A test hook is also supplied that simply echos the dhcp variables to the
  48 console from DISCOVER message.
  49 .Pp
  50 Each time
  51 .Nm
  52 is invoked,
  53 .Ev $interface
  54 is set to the interface that
  55 .Nm dhcpcd
  56 is run on and
  57 .Ev $reason
  58 is to the reason why
  59 .Nm
  60 was invoked.
  61 DHCP information to be configured is held in variables starting with the word
  62 new_ and old DHCP information to be removed is held in variables starting with
  63 the word old_.
  64 .Nm dhcpcd
  65 can display the full list of variables it knows how about by using the
  66 .Fl V , -variables
  67 argument.
  68 .Pp
  69 Here's a list of reasons why
  70 .Nm
  71 could be invoked:
  72 .Bl -tag -width PREINIT
  73 .It Dv PREINIT
  74 dhcpcd is starting up and any pre-initialisation should be done.
  75 .It Dv CARRIER
  76 dhcpcd has detected the carrier is up.
  77 This is generally just a notification and no action need be taken.
  78 .It Dv INFORM
  79 dhcpcd informed a DHCP server about it's address and obtained other
  80 configuration details.
  81 .It Dv BOUND
  82 dhcpcd obtained a new lease from a DHCP server.
  83 .It Dv RENEW
  84 dhcpcd renewed it's lease.
  85 .It Dv REBIND
  86 dhcpcd has rebound to a new DHCP server.
  87 .It Dv REBOOT
  88 dhcpcd successfully requested a lease from a DHCP server.
  89 .It Dv IPV4LL
  90 dhcpcd failed to contact any DHCP servers but did obtain an IPV4LL address.
  91 .It Dv STATIC
  92 dhcpcd has been configured with a static configuration which has not been
  93 obtained from a DHCP server.
  94 .It Dv 3RDPARTY
  95 dhcpcd is monitoring the interface for a 3rd party to give it an IP address.
  96 .It Dv TIMEOUT
  97 dhcpcd failed to contact any DHCP servers but was able to use an old lease.
  98 .It Dv EXPIRE
  99 dhcpcd's lease or state expired and it failed to obtain a new one.
 100 .It Dv NAK
 101 dhcpcd received a NAK from the DHCP server.
 102 This should be treated as EXPIRE.
 103 .It Dv NOCARRIER
 104 dhcpcd lost the carrier.
 105 The cable may have been unplugged or association to the wireless point lost.
 106 .It Dv FAIL
 107 dhcpcd failed to operate on the interface.
 108 This normally happens when dhcpcd does not support the raw interface, which
 109 means it cannot work as a DHCP or ZeroConf client.
 110 Static configuration and DHCP INFORM is still allowed.
 111 .It Dv STOP
 112 dhcpcd stopped running on the interface.
 113 .It Dv TEST
 114 dhcpcd received an OFFER from a DHCP server but will not configure the
 115 interface.
 116 This is primarily used to test the variables are filled correctly for the
 117 script to process them.
 118 .El
 119 .Sh FILES
 120 When
 121 .Nm
 122 runs, it loads
 123 .Pa @SYSCONFDIR@/dhcpcd.enter-hook
 124 and any scripts found in
 125 .Pa @HOOKDIR@
 126 in a lexical order and then finally
 127 .Pa @SYSCONFDIR@/dhcpcd.exit-hook
 128 .Sh SEE ALSO
 129 .Xr dhcpcd 8
 130 .Sh AUTHORS
 131 .An Roy Marples Aq roy@marples.name
 132 .Sh BUGS
 133 Please report them to http://roy.marples.name/projects/dhcpcd