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