1.\" Copyright (c) 2006-2021 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 December 27, 2020 26.Dt DHCPCD-RUN-HOOKS 8 27.Os 28.Sh NAME 29.Nm dhcpcd-run-hooks 30.Nd DHCP client configuration script 31.Sh DESCRIPTION 32.Nm 33is used by 34.Xr dhcpcd 8 35to run any system and user defined hook scripts. 36System hook scripts are found in 37.Pa /usr/libexec/dhcpcd-hooks 38and the user defined hooks are 39.Pa /etc/dhcpcd.enter-hook . 40and 41.Pa /etc/dhcpcd.exit-hook . 42The default install supplies hook scripts for configuring 43.Pa /etc/resolv.conf 44and the hostname. 45Your distribution may have included other hook scripts to say configure 46ntp or ypbind. 47A test hook is also supplied that simply echos the dhcp variables to the 48console from DISCOVER message. 49.Pp 50The hooks scripts are loaded into the current shell rather than executed 51in their own process. 52This allows each hook script, such as 53.Pa /etc/dhcpcd.enter-hook 54to customise environment variables or provide alternative functions to hooks 55further down the chain. 56As such, using the shell builtins 57.Ic exit , 58.Ic exec 59or similar will cause 60.Nm 61to exit at that point. 62.Pp 63Each time 64.Nm 65is invoked, 66.Ev $interface 67is set to the interface that 68.Nm dhcpcd 69is run on and 70.Ev $reason 71is to the reason why 72q 73.Nm 74was invoked. 75DHCP information to be configured is held in variables starting with the word 76new_ and old DHCP information to be removed is held in variables starting with 77the word old_. 78.Nm dhcpcd 79can display the full list of variables it knows how about by using the 80.Fl V , -variables 81argument. 82.Pp 83Here's a list of reasons why 84.Nm 85could be invoked: 86.Bl -tag -width EXPIREXXXEXPIRE6 87.It Dv PREINIT 88dhcpcd is starting up and any pre-initialisation should be done. 89.It Dv CARRIER 90dhcpcd has detected the carrier is up. 91This is generally just a notification and no action need be taken. 92.It Dv NOCARRIER 93dhcpcd lost the carrier. 94The cable may have been unplugged or association to the wireless point lost. 95.It Dv NOCARRIER_ROAMING 96dhcpcd lost the carrier but the interface configuration is persisted. 97The OS has to support wireless roaming or IP Persistance for this to happen. 98.It Dv INFORM | Dv INFORM6 99dhcpcd informed a DHCP server about its address and obtained other 100configuration details. 101.It Dv BOUND | Dv BOUND6 102dhcpcd obtained a new lease from a DHCP server. 103.It Dv RENEW | Dv RENEW6 104dhcpcd renewed it's lease. 105.It Dv REBIND | Dv REBIND6 106dhcpcd has rebound to a new DHCP server. 107.It Dv REBOOT | Dv REBOOT6 108dhcpcd successfully requested a lease from a DHCP server. 109.It Dv DELEGATED6 110dhcpcd assigned a delegated prefix to the interface. 111.It Dv IPV4LL 112dhcpcd obtained an IPV4LL address, or one was removed. 113.It Dv STATIC 114dhcpcd has been configured with a static configuration which has not been 115obtained from a DHCP server. 116.It Dv 3RDPARTY 117dhcpcd is monitoring the interface for a 3rd party to give it an IP address. 118.It Dv TIMEOUT 119dhcpcd failed to contact any DHCP servers but was able to use an old lease. 120.It Dv EXPIRE | EXPIRE6 121dhcpcd's lease or state expired and it failed to obtain a new one. 122.It Dv NAK 123dhcpcd received a NAK from the DHCP server. 124This should be treated as EXPIRE. 125.It Dv RECONFIGURE 126dhcpcd has been instructed to reconfigure an interface. 127.It Dv ROUTERADVERT 128dhcpcd has received an IPv6 Router Advertisement, or one has expired. 129.It Dv STOP | Dv STOP6 130dhcpcd stopped running on the interface. 131.It Dv STOPPED 132dhcpcd has stopped entirely. 133.It Dv DEPARTED 134The interface has been removed. 135.It Dv FAIL 136dhcpcd failed to operate on the interface. 137This normally happens when dhcpcd does not support the raw interface, which 138means it cannot work as a DHCP or ZeroConf client. 139Static configuration and DHCP INFORM is still allowed. 140.It Dv TEST 141dhcpcd received an OFFER from a DHCP server but will not configure the 142interface. 143This is primarily used to test the variables are filled correctly for the 144script to process them. 145.El 146.Sh ENVIRONMENT 147.Nm dhcpcd 148will clear the environment variables aside from 149.Ev $PATH . 150The following variables will then be set, along with any protocol supplied 151ones. 152.Bl -tag -width xnew_delegated_dhcp6_prefix 153.It Ev $interface 154the name of the interface. 155.It Ev $protocol 156the protocol that triggered the event. 157.It Ev $reason 158as described above. 159.It Ev $pid 160the pid of 161.Nm dhcpcd . 162.It Ev $ifcarrier 163the link status of 164.Ev $interface : 165.Dv unknown , 166.Dv up 167or 168.Dv down . 169.It Ev $ifmetric 170.Ev $interface 171preference, lower is better. 172.It Ev $ifwireless 173.Dv 1 if 174.Ev $interface 175is wireless, otherwise 176.Dv 0 . 177.It Ev $ifflags 178.Ev $interface 179flags. 180.It Ev $ifmtu 181.Ev $interface 182MTU. 183.It Ev $ifssid 184the name of the SSID the 185.Ev interface 186is connected to. 187.It Ev $interface_order 188A list of interfaces, in order of preference. 189.It Ev $if_up 190.Dv true 191if the 192.Ev interface 193is up, otherwise 194.Dv false . 195This is more than IFF_UP and may not be equal. 196.It Ev $if_down 197.Dv true 198if the 199.Ev interface 200is down, otherwise 201.Dv false . 202This is more than IFF_UP and may not be equal. 203.It Ev $af_waiting 204Address family waiting for, as defined in 205.Xr dhcpcd.conf 5 . 206.It Ev $profile 207the name of the profile selected from 208.Xr dhcpcd.conf 5 . 209.It Ev $new_delegated_dhcp6_prefix 210space separated list of delegated prefixes. 211.El 212.Sh FILES 213When 214.Nm 215runs, it loads 216.Pa /etc/dhcpcd.enter-hook 217and any scripts found in 218.Pa /usr/libexec/dhcpcd-hooks 219in a lexical order and then finally 220.Pa /etc/dhcpcd.exit-hook 221.Sh SEE ALSO 222.Xr dhcpcd 8 223.Sh AUTHORS 224.An Roy Marples Aq Mt roy@marples.name 225.Sh BUGS 226Please report them to 227.Lk http://roy.marples.name/projects/dhcpcd 228.Sh SECURITY CONSIDERATIONS 229.Nm dhcpcd 230will validate the content of each option against its encoding. 231For string, ascii, raw or binhex encoding it's up to the user to validate it 232for the intended purpose. 233.Pp 234When used in a shell script, each variable must be quoted correctly. 235