1*80aa9461SRoy Marples.\" Copyright (c) 2006-2023 Roy Marples 20a68f8d2SRoy Marples.\" All rights reserved 30a68f8d2SRoy Marples.\" 40a68f8d2SRoy Marples.\" Redistribution and use in source and binary forms, with or without 50a68f8d2SRoy Marples.\" modification, are permitted provided that the following conditions 60a68f8d2SRoy Marples.\" are met: 70a68f8d2SRoy Marples.\" 1. Redistributions of source code must retain the above copyright 80a68f8d2SRoy Marples.\" notice, this list of conditions and the following disclaimer. 90a68f8d2SRoy Marples.\" 2. Redistributions in binary form must reproduce the above copyright 100a68f8d2SRoy Marples.\" notice, this list of conditions and the following disclaimer in the 110a68f8d2SRoy Marples.\" documentation and/or other materials provided with the distribution. 120a68f8d2SRoy Marples.\" 130a68f8d2SRoy Marples.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 140a68f8d2SRoy Marples.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 150a68f8d2SRoy Marples.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 160a68f8d2SRoy Marples.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 170a68f8d2SRoy Marples.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 180a68f8d2SRoy Marples.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 190a68f8d2SRoy Marples.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 200a68f8d2SRoy Marples.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 210a68f8d2SRoy Marples.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 220a68f8d2SRoy Marples.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 230a68f8d2SRoy Marples.\" SUCH DAMAGE. 240a68f8d2SRoy Marples.\" 25*80aa9461SRoy Marples.Dd August 31, 2022 260a68f8d2SRoy Marples.Dt DHCPCD-RUN-HOOKS 8 270a68f8d2SRoy Marples.Os 280a68f8d2SRoy Marples.Sh NAME 290a68f8d2SRoy Marples.Nm dhcpcd-run-hooks 300a68f8d2SRoy Marples.Nd DHCP client configuration script 310a68f8d2SRoy Marples.Sh DESCRIPTION 320a68f8d2SRoy Marples.Nm 330a68f8d2SRoy Marplesis used by 340a68f8d2SRoy Marples.Xr dhcpcd 8 350a68f8d2SRoy Marplesto run any system and user defined hook scripts. 360a68f8d2SRoy MarplesSystem hook scripts are found in 370a68f8d2SRoy Marples.Pa /usr/libexec/dhcpcd-hooks 380a68f8d2SRoy Marplesand the user defined hooks are 390a68f8d2SRoy Marples.Pa /etc/dhcpcd.enter-hook . 400a68f8d2SRoy Marplesand 410a68f8d2SRoy Marples.Pa /etc/dhcpcd.exit-hook . 420a68f8d2SRoy MarplesThe default install supplies hook scripts for configuring 430a68f8d2SRoy Marples.Pa /etc/resolv.conf 440a68f8d2SRoy Marplesand the hostname. 450a68f8d2SRoy MarplesYour distribution may have included other hook scripts to say configure 460a68f8d2SRoy Marplesntp or ypbind. 470a68f8d2SRoy MarplesA test hook is also supplied that simply echos the dhcp variables to the 480a68f8d2SRoy Marplesconsole from DISCOVER message. 490a68f8d2SRoy Marples.Pp 500a68f8d2SRoy MarplesThe hooks scripts are loaded into the current shell rather than executed 510a68f8d2SRoy Marplesin their own process. 520a68f8d2SRoy MarplesThis allows each hook script, such as 530a68f8d2SRoy Marples.Pa /etc/dhcpcd.enter-hook 540a68f8d2SRoy Marplesto customise environment variables or provide alternative functions to hooks 550a68f8d2SRoy Marplesfurther down the chain. 560a68f8d2SRoy MarplesAs such, using the shell builtins 570a68f8d2SRoy Marples.Ic exit , 580a68f8d2SRoy Marples.Ic exec 590a68f8d2SRoy Marplesor similar will cause 600a68f8d2SRoy Marples.Nm 610a68f8d2SRoy Marplesto exit at that point. 620a68f8d2SRoy Marples.Pp 630a68f8d2SRoy MarplesEach time 640a68f8d2SRoy Marples.Nm 650a68f8d2SRoy Marplesis invoked, 660a68f8d2SRoy Marples.Ev $interface 670a68f8d2SRoy Marplesis set to the interface that 680a68f8d2SRoy Marples.Nm dhcpcd 690a68f8d2SRoy Marplesis run on and 700a68f8d2SRoy Marples.Ev $reason 71*80aa9461SRoy Marplesis set to the reason why 720a68f8d2SRoy Marples.Nm 730a68f8d2SRoy Marpleswas invoked. 740a68f8d2SRoy MarplesDHCP information to be configured is held in variables starting with the word 750a68f8d2SRoy Marplesnew_ and old DHCP information to be removed is held in variables starting with 760a68f8d2SRoy Marplesthe word old_. 770a68f8d2SRoy Marples.Nm dhcpcd 78*80aa9461SRoy Marplescan display the full list of variables it knows about by using the 790a68f8d2SRoy Marples.Fl V , -variables 800a68f8d2SRoy Marplesargument. 810a68f8d2SRoy Marples.Pp 820a68f8d2SRoy MarplesHere's a list of reasons why 830a68f8d2SRoy Marples.Nm 840a68f8d2SRoy Marplescould be invoked: 850a68f8d2SRoy Marples.Bl -tag -width EXPIREXXXEXPIRE6 860a68f8d2SRoy Marples.It Dv PREINIT 87*80aa9461SRoy Marplesdhcpcd is starting up and any pre-initialisation required should be performed now. 880a68f8d2SRoy Marples.It Dv CARRIER 890a68f8d2SRoy Marplesdhcpcd has detected the carrier is up. 900a68f8d2SRoy MarplesThis is generally just a notification and no action need be taken. 910a68f8d2SRoy Marples.It Dv NOCARRIER 920a68f8d2SRoy Marplesdhcpcd lost the carrier. 930a68f8d2SRoy MarplesThe cable may have been unplugged or association to the wireless point lost. 940a68f8d2SRoy Marples.It Dv NOCARRIER_ROAMING 950a68f8d2SRoy Marplesdhcpcd lost the carrier but the interface configuration is persisted. 96*80aa9461SRoy MarplesThe OS has to support wireless roaming or IP Persistence for this to happen. 970a68f8d2SRoy Marples.It Dv INFORM | Dv INFORM6 980a68f8d2SRoy Marplesdhcpcd informed a DHCP server about its address and obtained other 990a68f8d2SRoy Marplesconfiguration details. 1000a68f8d2SRoy Marples.It Dv BOUND | Dv BOUND6 1010a68f8d2SRoy Marplesdhcpcd obtained a new lease from a DHCP server. 1020a68f8d2SRoy Marples.It Dv RENEW | Dv RENEW6 103*80aa9461SRoy Marplesdhcpcd renewed its lease. 1040a68f8d2SRoy Marples.It Dv REBIND | Dv REBIND6 1050a68f8d2SRoy Marplesdhcpcd has rebound to a new DHCP server. 1060a68f8d2SRoy Marples.It Dv REBOOT | Dv REBOOT6 1070a68f8d2SRoy Marplesdhcpcd successfully requested a lease from a DHCP server. 1080a68f8d2SRoy Marples.It Dv DELEGATED6 1090a68f8d2SRoy Marplesdhcpcd assigned a delegated prefix to the interface. 1100a68f8d2SRoy Marples.It Dv IPV4LL 1110a68f8d2SRoy Marplesdhcpcd obtained an IPV4LL address, or one was removed. 1120a68f8d2SRoy Marples.It Dv STATIC 1130a68f8d2SRoy Marplesdhcpcd has been configured with a static configuration which has not been 1140a68f8d2SRoy Marplesobtained from a DHCP server. 1150a68f8d2SRoy Marples.It Dv 3RDPARTY 1160a68f8d2SRoy Marplesdhcpcd is monitoring the interface for a 3rd party to give it an IP address. 1170a68f8d2SRoy Marples.It Dv TIMEOUT 1180a68f8d2SRoy Marplesdhcpcd failed to contact any DHCP servers but was able to use an old lease. 1190a68f8d2SRoy Marples.It Dv EXPIRE | EXPIRE6 1200a68f8d2SRoy Marplesdhcpcd's lease or state expired and it failed to obtain a new one. 1210a68f8d2SRoy Marples.It Dv NAK 1220a68f8d2SRoy Marplesdhcpcd received a NAK from the DHCP server. 1230a68f8d2SRoy MarplesThis should be treated as EXPIRE. 1240a68f8d2SRoy Marples.It Dv RECONFIGURE 1250a68f8d2SRoy Marplesdhcpcd has been instructed to reconfigure an interface. 1260a68f8d2SRoy Marples.It Dv ROUTERADVERT 1270a68f8d2SRoy Marplesdhcpcd has received an IPv6 Router Advertisement, or one has expired. 1280a68f8d2SRoy Marples.It Dv STOP | Dv STOP6 1290a68f8d2SRoy Marplesdhcpcd stopped running on the interface. 1300a68f8d2SRoy Marples.It Dv STOPPED 1310a68f8d2SRoy Marplesdhcpcd has stopped entirely. 1320a68f8d2SRoy Marples.It Dv DEPARTED 1330a68f8d2SRoy MarplesThe interface has been removed. 1340a68f8d2SRoy Marples.It Dv FAIL 1350a68f8d2SRoy Marplesdhcpcd failed to operate on the interface. 1360a68f8d2SRoy MarplesThis normally happens when dhcpcd does not support the raw interface, which 1370a68f8d2SRoy Marplesmeans it cannot work as a DHCP or ZeroConf client. 1380a68f8d2SRoy MarplesStatic configuration and DHCP INFORM is still allowed. 1390a68f8d2SRoy Marples.It Dv TEST 1400a68f8d2SRoy Marplesdhcpcd received an OFFER from a DHCP server but will not configure the 1410a68f8d2SRoy Marplesinterface. 1420a68f8d2SRoy MarplesThis is primarily used to test the variables are filled correctly for the 1430a68f8d2SRoy Marplesscript to process them. 1440a68f8d2SRoy Marples.El 1450a68f8d2SRoy Marples.Sh ENVIRONMENT 1460a68f8d2SRoy Marples.Nm dhcpcd 1470a68f8d2SRoy Marpleswill clear the environment variables aside from 1480a68f8d2SRoy Marples.Ev $PATH . 1490a68f8d2SRoy MarplesThe following variables will then be set, along with any protocol supplied 1500a68f8d2SRoy Marplesones. 1510a68f8d2SRoy Marples.Bl -tag -width xnew_delegated_dhcp6_prefix 1520a68f8d2SRoy Marples.It Ev $interface 1530a68f8d2SRoy Marplesthe name of the interface. 1540a68f8d2SRoy Marples.It Ev $protocol 1550a68f8d2SRoy Marplesthe protocol that triggered the event. 1560a68f8d2SRoy Marples.It Ev $reason 1570a68f8d2SRoy Marplesas described above. 1580a68f8d2SRoy Marples.It Ev $pid 1590a68f8d2SRoy Marplesthe pid of 1600a68f8d2SRoy Marples.Nm dhcpcd . 1610a68f8d2SRoy Marples.It Ev $ifcarrier 1620a68f8d2SRoy Marplesthe link status of 1630a68f8d2SRoy Marples.Ev $interface : 1640a68f8d2SRoy Marples.Dv unknown , 1650a68f8d2SRoy Marples.Dv up 1660a68f8d2SRoy Marplesor 1670a68f8d2SRoy Marples.Dv down . 1680a68f8d2SRoy Marples.It Ev $ifmetric 1690a68f8d2SRoy Marples.Ev $interface 1700a68f8d2SRoy Marplespreference, lower is better. 1710a68f8d2SRoy Marples.It Ev $ifwireless 1720a68f8d2SRoy Marples.Dv 1 if 1730a68f8d2SRoy Marples.Ev $interface 1740a68f8d2SRoy Marplesis wireless, otherwise 1750a68f8d2SRoy Marples.Dv 0 . 1760a68f8d2SRoy Marples.It Ev $ifflags 1770a68f8d2SRoy Marples.Ev $interface 1780a68f8d2SRoy Marplesflags. 1790a68f8d2SRoy Marples.It Ev $ifmtu 1800a68f8d2SRoy Marples.Ev $interface 1810a68f8d2SRoy MarplesMTU. 1820a68f8d2SRoy Marples.It Ev $ifssid 183*80aa9461SRoy Marplesthe SSID the 1840a68f8d2SRoy Marples.Ev interface 1850a68f8d2SRoy Marplesis connected to. 1860a68f8d2SRoy Marples.It Ev $interface_order 1870a68f8d2SRoy MarplesA list of interfaces, in order of preference. 1880a68f8d2SRoy Marples.It Ev $if_up 1890a68f8d2SRoy Marples.Dv true 1900a68f8d2SRoy Marplesif the 1910a68f8d2SRoy Marples.Ev interface 1920a68f8d2SRoy Marplesis up, otherwise 1930a68f8d2SRoy Marples.Dv false . 1940a68f8d2SRoy MarplesThis is more than IFF_UP and may not be equal. 1950a68f8d2SRoy Marples.It Ev $if_down 1960a68f8d2SRoy Marples.Dv true 1970a68f8d2SRoy Marplesif the 1980a68f8d2SRoy Marples.Ev interface 1990a68f8d2SRoy Marplesis down, otherwise 2000a68f8d2SRoy Marples.Dv false . 2010a68f8d2SRoy MarplesThis is more than IFF_UP and may not be equal. 2020a68f8d2SRoy Marples.It Ev $af_waiting 2030a68f8d2SRoy MarplesAddress family waiting for, as defined in 2040a68f8d2SRoy Marples.Xr dhcpcd.conf 5 . 2050a68f8d2SRoy Marples.It Ev $profile 2060a68f8d2SRoy Marplesthe name of the profile selected from 2070a68f8d2SRoy Marples.Xr dhcpcd.conf 5 . 2080a68f8d2SRoy Marples.It Ev $new_delegated_dhcp6_prefix 209*80aa9461SRoy Marplesspace-separated list of delegated prefixes. 2100a68f8d2SRoy Marples.El 2110a68f8d2SRoy Marples.Sh FILES 2120a68f8d2SRoy MarplesWhen 2130a68f8d2SRoy Marples.Nm 2140a68f8d2SRoy Marplesruns, it loads 215*80aa9461SRoy Marples.Pa /etc/dhcpcd.enter-hook , 216*80aa9461SRoy Marplesany scripts found in 2170a68f8d2SRoy Marples.Pa /usr/libexec/dhcpcd-hooks 218*80aa9461SRoy Marplesin lexical order, then finally 219*80aa9461SRoy Marples.Pa /etc/dhcpcd.exit-hook . 2200a68f8d2SRoy Marples.Sh SEE ALSO 2210a68f8d2SRoy Marples.Xr dhcpcd 8 2220a68f8d2SRoy Marples.Sh AUTHORS 2230a68f8d2SRoy Marples.An Roy Marples Aq Mt roy@marples.name 2240a68f8d2SRoy Marples.Sh BUGS 2250a68f8d2SRoy MarplesPlease report them to 226*80aa9461SRoy Marples.Lk https://roy.marples.name/projects/dhcpcd 2270a68f8d2SRoy Marples.Sh SECURITY CONSIDERATIONS 2280a68f8d2SRoy Marples.Nm dhcpcd 2290a68f8d2SRoy Marpleswill validate the content of each option against its encoding. 2300a68f8d2SRoy MarplesFor string, ascii, raw or binhex encoding it's up to the user to validate it 2310a68f8d2SRoy Marplesfor the intended purpose. 2320a68f8d2SRoy Marples.Pp 2330a68f8d2SRoy MarplesWhen used in a shell script, each variable must be quoted correctly. 234