1 | .\" Copyright (c) 2006-2013 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 June 6, 2013 |
---|
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 |
---|
33 | is used by |
---|
34 | .Xr dhcpcd 8 |
---|
35 | to run any system and user defined hook scripts. |
---|
36 | System hook scripts are found in |
---|
37 | .Pa @HOOKDIR@ |
---|
38 | and the user defined hooks are |
---|
39 | .Pa @SYSCONFDIR@/dhcpcd.enter-hook . |
---|
40 | and |
---|
41 | .Pa @SYSCONFDIR@/dhcpcd.exit-hook . |
---|
42 | The default install supplies hook scripts for configuring |
---|
43 | .Pa /etc/resolv.conf |
---|
44 | and the hostname. |
---|
45 | Your distribution may have included other hook scripts to say configure |
---|
46 | ntp or ypbind. |
---|
47 | A test hook is also supplied that simply echos the dhcp variables to the |
---|
48 | console from DISCOVER message. |
---|
49 | .Pp |
---|
50 | Each time |
---|
51 | .Nm |
---|
52 | is invoked, |
---|
53 | .Ev $interface |
---|
54 | is set to the interface that |
---|
55 | .Nm dhcpcd |
---|
56 | is run on and |
---|
57 | .Ev $reason |
---|
58 | is to the reason why |
---|
59 | .Nm |
---|
60 | was invoked. |
---|
61 | DHCP information to be configured is held in variables starting with the word |
---|
62 | new_ and old DHCP information to be removed is held in variables starting with |
---|
63 | the word old_. |
---|
64 | .Nm dhcpcd |
---|
65 | can display the full list of variables it knows how about by using the |
---|
66 | .Fl V , -variables |
---|
67 | argument. |
---|
68 | .Pp |
---|
69 | Here's a list of reasons why |
---|
70 | .Nm |
---|
71 | could be invoked: |
---|
72 | .Bl -tag -width ROUTERADVERT |
---|
73 | .It Dv PREINIT |
---|
74 | dhcpcd is starting up and any pre-initialisation should be done. |
---|
75 | .It Dv CARRIER |
---|
76 | dhcpcd has detected the carrier is up. |
---|
77 | This is generally just a notification and no action need be taken. |
---|
78 | .It Dv INFORM | Dv INFORM6 |
---|
79 | dhcpcd informed a DHCP server about it's address and obtained other |
---|
80 | configuration details. |
---|
81 | .It Dv BOUND | Dv BOUND6 |
---|
82 | dhcpcd obtained a new lease from a DHCP server. |
---|
83 | .It Dv RENEW | Dv RENEW6 |
---|
84 | dhcpcd renewed it's lease. |
---|
85 | .It Dv REBIND | Dv REBIND6 |
---|
86 | dhcpcd has rebound to a new DHCP server. |
---|
87 | .It Dv REBOOT | Dv REBOOT6 |
---|
88 | dhcpcd successfully requested a lease from a DHCP server. |
---|
89 | .It Dv IPV4LL |
---|
90 | dhcpcd failed to contact any DHCP servers but did obtain an IPV4LL address. |
---|
91 | .It Dv STATIC |
---|
92 | dhcpcd has been configured with a static configuration which has not been |
---|
93 | obtained from a DHCP server. |
---|
94 | .It Dv 3RDPARTY |
---|
95 | dhcpcd is monitoring the interface for a 3rd party to give it an IP address. |
---|
96 | .It Dv TIMEOUT |
---|
97 | dhcpcd failed to contact any DHCP servers but was able to use an old lease. |
---|
98 | .It Dv EXPIRE | EXPIRE6 |
---|
99 | dhcpcd's lease or state expired and it failed to obtain a new one. |
---|
100 | .It Dv NAK |
---|
101 | dhcpcd received a NAK from the DHCP server. |
---|
102 | This should be treated as EXPIRE. |
---|
103 | .It Dv RECONFIGURE |
---|
104 | dhcpcd has been instructed to reconfigure an interface. |
---|
105 | .It Dv NOCARRIER |
---|
106 | dhcpcd lost the carrier. |
---|
107 | The cable may have been unplugged or association to the wireless point lost. |
---|
108 | .It Dv FAIL |
---|
109 | dhcpcd failed to operate on the interface. |
---|
110 | This normally happens when dhcpcd does not support the raw interface, which |
---|
111 | means it cannot work as a DHCP or ZeroConf client. |
---|
112 | Static configuration and DHCP INFORM is still allowed. |
---|
113 | .It Dv STOP | Dv STOP6 |
---|
114 | dhcpcd stopped running on the interface. |
---|
115 | .It Dv DEPARTED |
---|
116 | The interface has been removed. |
---|
117 | .It Dv DUMP |
---|
118 | dhcpcd has been asked to dump the last lease for the interface. |
---|
119 | .It Dv TEST |
---|
120 | dhcpcd received an OFFER from a DHCP server but will not configure the |
---|
121 | interface. |
---|
122 | This is primarily used to test the variables are filled correctly for the |
---|
123 | script to process them. |
---|
124 | .It Dv ROUTERADVERT |
---|
125 | dhcpcd has received an IPv6 Router Advertisment, or one has expired. |
---|
126 | .El |
---|
127 | .Sh FILES |
---|
128 | When |
---|
129 | .Nm |
---|
130 | runs, it loads |
---|
131 | .Pa @SYSCONFDIR@/dhcpcd.enter-hook |
---|
132 | and any scripts found in |
---|
133 | .Pa @HOOKDIR@ |
---|
134 | in a lexical order and then finally |
---|
135 | .Pa @SYSCONFDIR@/dhcpcd.exit-hook |
---|
136 | .Sh SEE ALSO |
---|
137 | .Xr dhcpcd 8 |
---|
138 | .Sh AUTHORS |
---|
139 | .An Roy Marples Aq Mt roy@marples.name |
---|
140 | .Sh BUGS |
---|
141 | Please report them to |
---|
142 | .Lk http://roy.marples.name/projects/dhcpcd |
---|
143 | .Sh SECURITY CONSIDERATIONS |
---|
144 | Little validation of DHCP options is done in dhcpcd itself. |
---|
145 | Instead, it is up to the hooks to handle any validation needed. |
---|
146 | To this end, some helper functions are provided, such as valid_domainname as |
---|
147 | used by the |
---|
148 | .Pa 20-resolv.conf |
---|
149 | hook to ensure that the hostname is not set to an invalid value. |
---|
150 | valid_path is also provided, but is currently unused by a stock hook script. |
---|