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