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

   1 .\"     $NetBSD: dhcpcd-run-hooks.8.in,v 1.15 2015/07/09 10:15:34 roy Exp $
   2 .\" Copyright (c) 2006-2015 Roy Marples
   3 .\" All rights reserved
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd June 29, 2015
  27 .Dt DHCPCD-RUN-HOOKS 8
  28 .Os
  29 .Sh NAME
  30 .Nm dhcpcd-run-hooks
  31 .Nd DHCP client configuration script
  32 .Sh DESCRIPTION
  33 .Nm
  34 is used by
  35 .Xr dhcpcd 8
  36 to run any system and user defined hook scripts.
  37 System hook scripts are found in
  38 .Pa @HOOKDIR@
  39 and the user defined hooks are
  40 .Pa @SYSCONFDIR@/dhcpcd.enter-hook .
  41 and
  42 .Pa @SYSCONFDIR@/dhcpcd.exit-hook .
  43 The default install supplies hook scripts for configuring
  44 .Pa /etc/resolv.conf
  45 and the hostname.
  46 Your distribution may have included other hook scripts to say configure
  47 ntp or ypbind.
  48 A test hook is also supplied that simply echos the dhcp variables to the
  49 console from DISCOVER message.
  50 .Pp
  51 Each time
  52 .Nm
  53 is invoked,
  54 .Ev $interface
  55 is set to the interface that
  56 .Nm dhcpcd
  57 is run on and
  58 .Ev $reason
  59 is to the reason why
  60 .Nm
  61 was invoked.
  62 DHCP information to be configured is held in variables starting with the word
  63 new_ and old DHCP information to be removed is held in variables starting with
  64 the word old_.
  65 .Nm dhcpcd
  66 can display the full list of variables it knows how about by using the
  67 .Fl V , -variables
  68 argument.
  69 .Pp
  70 Here's a list of reasons why
  71 .Nm
  72 could be invoked:
  73 .Bl -tag -width EXPIREXXXEXPIRE6
  74 .It Dv PREINIT
  75 dhcpcd is starting up and any pre-initialisation should be done.
  76 .It Dv CARRIER
  77 dhcpcd has detected the carrier is up.
  78 This is generally just a notification and no action need be taken.
  79 .It Dv NOCARRIER
  80 dhcpcd lost the carrier.
  81 The cable may have been unplugged or association to the wireless point lost.
  82 .It Dv INFORM | Dv INFORM6
  83 dhcpcd informed a DHCP server about it's address and obtained other
  84 configuration details.
  85 .It Dv BOUND | Dv BOUND6
  86 dhcpcd obtained a new lease from a DHCP server.
  87 .It Dv RENEW | Dv RENEW6
  88 dhcpcd renewed it's lease.
  89 .It Dv REBIND | Dv REBIND6
  90 dhcpcd has rebound to a new DHCP server.
  91 .It Dv REBOOT | Dv REBOOT6
  92 dhcpcd successfully requested a lease from a DHCP server.
  93 .It Dv DELEGATED6
  94 dhcpcd assigned a delegated prefix to the interface.
  95 .It Dv IPV4LL
  96 dhcpcd obtaind an IPV4LL address, or one was removed.
  97 .It Dv STATIC
  98 dhcpcd has been configured with a static configuration which has not been
  99 obtained from a DHCP server.
 100 .It Dv 3RDPARTY
 101 dhcpcd is monitoring the interface for a 3rd party to give it an IP address.
 102 .It Dv TIMEOUT
 103 dhcpcd failed to contact any DHCP servers but was able to use an old lease.
 104 .It Dv EXPIRE | EXPIRE6
 105 dhcpcd's lease or state expired and it failed to obtain a new one.
 106 .It Dv NAK
 107 dhcpcd received a NAK from the DHCP server.
 108 This should be treated as EXPIRE.
 109 .It Dv RECONFIGURE
 110 dhcpcd has been instructed to reconfigure an interface.
 111 .It Dv ROUTERADVERT
 112 dhcpcd has received an IPv6 Router Advertisment, or one has expired.
 113 .It Dv STOP | Dv STOP6
 114 dhcpcd stopped running on the interface.
 115 .It Dv STOPPED
 116 dhcpcd has stopped entirely.
 117 .It Dv DEPARTED
 118 The interface has been removed.
 119 .It Dv FAIL
 120 dhcpcd failed to operate on the interface.
 121 This normally happens when dhcpcd does not support the raw interface, which
 122 means it cannot work as a DHCP or ZeroConf client.
 123 Static configuration and DHCP INFORM is still allowed.
 124 .It Dv DUMP
 125 dhcpcd has been asked to dump the last lease for the interface.
 126 .It Dv TEST
 127 dhcpcd received an OFFER from a DHCP server but will not configure the
 128 interface.
 129 This is primarily used to test the variables are filled correctly for the
 130 script to process them.
 131 .El
 132 .Sh ENVIRONMENT
 133 .Nm dhcpcd
 134 will clear the environment variables aside from
 135 .Ev $PATH
 136 and
 137 .Ev $RC_SVCNAME .
 138 The following variables will then be set, along with any protocol supplied
 139 ones.
 140 .Bl -tag -width xnew_delegated_dhcp6_prefix
 141 .It Ev $interface
 142 the name of the interface.
 143 .It Ev $reason
 144 as described above.
 145 .It Ev $pid
 146 the pid of
 147 .Nm dhcpcd .
 148 .It Ev $ifcarrier
 149 the link status of
 150 .Ev $interface :
 151 .Dv unknown ,
 152 .Dv up
 153 or
 154 .Dv down .
 155 .It Ev $ifmetric
 156 .Ev $interface
 157 preference, lower is better.
 158 .It Ev $ifwireless
 159 .Dv 1 if
 160 .Ev $interface
 161 is wireless, otherwise
 162 .Dv 0 .
 163 .It Ev $ifflags
 164 .Ev $interface
 165 flags.
 166 .It Ev $ifmtu
 167 .Ev $interface
 168 MTU.
 169 .It Ev $ifssid
 170 the name of the SSID the
 171 .Ev interface
 172 is connected to.
 173 .It Ev $interface_order
 174 A list of interfaces, in order of preference.
 175 .It Ev $if_up
 176 .Dv true
 177 if the
 178 .Ev interface
 179 is up, otherwise
 180 .Dv false .
 181 .It Ev $if_down
 182 .Dv true
 183 if the
 184 .Ev interface
 185 is down, otherwise
 186 .Dv false .
 187 .It Ev $af_waiting
 188 Address family waiting for, as defined in
 189 .Xr dhcpcd.conf 5 .
 190 .It Ev $profile
 191 the name of the profile selected from
 192 .Xr dhcpcd.conf 5 .
 193 .It Ev $new_delegated_dhcp6_prefix
 194 space separated list of delegated prefixes.
 195 .El
 196 .Sh FILES
 197 When
 198 .Nm
 199 runs, it loads
 200 .Pa @SYSCONFDIR@/dhcpcd.enter-hook
 201 and any scripts found in
 202 .Pa @HOOKDIR@
 203 in a lexical order and then finally
 204 .Pa @SYSCONFDIR@/dhcpcd.exit-hook
 205 .Sh SEE ALSO
 206 .Xr dhcpcd 8
 207 .Sh AUTHORS
 208 .An Roy Marples Aq Mt roy@marples.name
 209 .Sh BUGS
 210 Please report them to
 211 .Lk http://roy.marples.name/projects/dhcpcd
 212 .Sh SECURITY CONSIDERATIONS
 213 .Nm dhcpcd
 214 will validate the content of each option against its encoding.
 215 For string, ascii, raw or binhex encoding it's up to the user to validate it
 216 for the intended purpose.
 217 .Pp
 218 When used in a shell script, each variable must be quoted correctly.