Commit | Line | Data |
---|---|---|
5ba6b67a | 1 | .\" $OpenBSD: src/sbin/dhclient/dhclient-script.8,v 1.6 2011/04/04 11:43:20 krw Exp $ |
846204b6 HT |
2 | .\" |
3 | .\" Copyright (c) 1997 The Internet Software Consortium. | |
4 | .\" All rights reserved. | |
5 | .\" | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. Neither the name of The Internet Software Consortium nor the names | |
16 | .\" of its contributors may be used to endorse or promote products derived | |
17 | .\" from this software without specific prior written permission. | |
18 | .\" | |
19 | .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND | |
20 | .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, | |
21 | .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
22 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | |
23 | .\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR | |
24 | .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
25 | .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
26 | .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF | |
27 | .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND | |
28 | .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
29 | .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
30 | .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
32 | .\" | |
33 | .\" This software has been written for the Internet Software Consortium | |
34 | .\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie | |
35 | .\" Enterprises. To learn more about the Internet Software Consortium, | |
36 | .\" see ``http://www.isc.org/isc''. To learn more about Vixie | |
37 | .\" Enterprises, see ``http://www.vix.com''. | |
38 | .\" | |
5ba6b67a | 39 | .Dd August 4, 2012 |
846204b6 HT |
40 | .Dt DHCLIENT-SCRIPT 8 |
41 | .Os | |
42 | .Sh NAME | |
43 | .Nm dhclient-script | |
44 | .Nd DHCP client network configuration script | |
45 | .Sh DESCRIPTION | |
46 | The DHCP client network configuration script is invoked from time to | |
47 | time by | |
48 | .Xr dhclient 8 . | |
846204b6 HT |
49 | .Pp |
50 | .\" No standard client script exists for some operating systems, even though | |
51 | .\" the actual client may work, so a pioneering user may well need to create | |
52 | .\" a new script or modify an existing one. | |
53 | In general, customizations specific to a particular computer should be done | |
54 | in the | |
55 | .Pa /etc/dhclient.conf | |
56 | file. | |
57 | .Sh OPERATION | |
58 | When | |
59 | .Xr dhclient 8 | |
60 | needs to invoke the client configuration script, it sets up a number of | |
61 | environment variables and runs | |
68d52ec8 | 62 | .Nm . |
846204b6 HT |
63 | In all cases, |
64 | .Va $reason | |
65 | is set to the name of the reason why the script has been invoked. | |
66 | The following reasons are currently defined: | |
5ba6b67a | 67 | BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL and TIMEOUT. |
846204b6 | 68 | .Bl -tag -width "ARPCHECK" |
846204b6 HT |
69 | .It BOUND |
70 | The DHCP client has done an initial binding to a new address. | |
71 | The new IP address is passed in | |
72 | .Va $new_ip_address , | |
73 | and the interface name is passed in | |
74 | .Va $interface . | |
846204b6 HT |
75 | Any options acquired from the server are passed using the option name |
76 | described in | |
77 | .Xr dhcp-options 5 , | |
78 | except that dashes | |
79 | .Pq Sq - | |
80 | are replaced by underscores | |
81 | .Pq Sq _ | |
82 | in order to make valid shell variables, and the variable names start with new_. | |
83 | So for example, the new subnet mask would be passed in | |
84 | .Va $new_subnet_mask . | |
85 | .Pp | |
86 | When a binding has been completed, a lot of network parameters are | |
87 | likely to need to be set up. | |
88 | A new | |
89 | .Pa /etc/resolv.conf | |
90 | needs to be created, using the values of | |
91 | .Va $new_domain_name | |
92 | and | |
93 | .Va $new_domain_name_servers | |
94 | (which may list more than one server, separated by spaces). | |
95 | A default route should be set using | |
96 | .Va $new_routers , | |
97 | and static routes may need to be set up using | |
98 | .Va $new_static_routes . | |
99 | .Pp | |
100 | Note: since | |
101 | .Nm | |
102 | effectively overwrites | |
103 | .Pa /etc/resolv.conf , | |
104 | any information contained therein is lost. | |
105 | If options must be passed to the resolver, | |
106 | they may be contained in | |
107 | .Pa /etc/resolv.conf.tail , | |
108 | which is appended to the generated | |
109 | .Pa /etc/resolv.conf | |
110 | by | |
111 | .Nm . | |
5943b4b0 SW |
112 | .\"See |
113 | .\".Xr resolv.conf.tail 5 | |
114 | .\"for further information. | |
846204b6 HT |
115 | .It RENEW |
116 | When a binding has been renewed, the script is called as in BOUND, | |
117 | except that in addition to all the variables starting with $new_, | |
118 | there is another set of variables starting with $old_. | |
119 | Persistent settings that may have changed need to be deleted \- for example, | |
120 | if a local route to the bound address is being configured, the old local | |
121 | route should be deleted. | |
122 | If the default route has changed, the old default route should be deleted. | |
123 | If the static routes have changed, the old ones should be deleted. | |
124 | Otherwise, processing can be done as with BOUND. | |
125 | .It REBIND | |
126 | The DHCP client has rebound to a new DHCP server. | |
127 | This can be handled as with RENEW, except that if the IP address has changed, | |
128 | the ARP table should be cleared. | |
129 | .It REBOOT | |
130 | The DHCP client has successfully reacquired its old address after a reboot. | |
131 | This can be processed as with BOUND. | |
132 | .It EXPIRE | |
133 | The DHCP client has failed to renew its lease or acquire a new one, | |
134 | and the lease has expired. | |
135 | The IP address must be relinquished, and all related parameters should be | |
136 | deleted, as in RENEW and REBIND. | |
137 | .It FAIL | |
138 | The DHCP client has been unable to contact any DHCP servers, and any | |
139 | leases that have been tested have not proved to be valid. | |
140 | The parameters from the last lease tested should be deconfigured. | |
141 | This can be handled in the same way as EXPIRE. | |
142 | .It TIMEOUT | |
143 | The DHCP client has been unable to contact any DHCP servers. | |
144 | However, an old lease has been identified, and its parameters have | |
145 | been passed in as with BOUND. | |
146 | The client configuration script should test these parameters and, | |
147 | if it has reason to believe they are valid, should exit with a value of zero. | |
148 | If not, it should exit with a nonzero value. | |
149 | .El | |
150 | .Pp | |
151 | The usual way to test a lease is to set up the network as with REBIND | |
152 | (since this may be called to test more than one lease) and then ping | |
153 | the first router defined in | |
154 | .Va $routers . | |
155 | If a response is received, the lease must be valid for the network to | |
156 | which the interface is currently connected. | |
157 | It would be more complete to try to ping all of the routers listed in | |
158 | .Va $new_routers , | |
159 | as well as those listed in | |
160 | .Va $new_static_routes , | |
161 | but current scripts do not do this. | |
162 | .\" .Sh FILES | |
163 | .\" Each operating system should generally have its own script file, | |
164 | .\" although the script files for similar operating systems may be similar | |
165 | .\" or even identical. | |
166 | .\" The script files included in the Internet Software Consortium DHCP | |
167 | .\" distribution appear in the distribution tree under client/scripts, | |
168 | .\" and bear the names of the operating systems on which they are intended | |
169 | .\" to work. | |
170 | .Sh SEE ALSO | |
171 | .Xr dhclient.conf 5 , | |
172 | .Xr dhclient.leases 5 , | |
5943b4b0 | 173 | .\".Xr resolv.conf.tail 5 , |
846204b6 | 174 | .Xr dhclient 8 , |
c8e8a2e5 SW |
175 | .Xr dhcpd 8 Pq Pa net/isc-dhcp42-server , |
176 | .Xr dhcrelay 8 Pq Pa net/isc-dhcp42-relay | |
846204b6 HT |
177 | .Sh AUTHORS |
178 | .An -nosplit | |
179 | The original version of | |
180 | .Nm | |
181 | was written for the Internet Software Consortium by | |
1cb631f7 | 182 | .An Ted Lemon Aq Mt mellon@fugue.com |
846204b6 HT |
183 | in cooperation with Vixie Enterprises. |
184 | .Pp | |
185 | The | |
186 | .Ox | |
187 | implementation of | |
188 | .Nm | |
189 | was written by | |
1cb631f7 | 190 | .An Kenneth R. Westerback Aq Mt krw@openbsd.org . |
846204b6 HT |
191 | .Sh BUGS |
192 | If more than one interface is being used, there's no obvious way to | |
193 | avoid clashes between server-supplied configuration parameters \- for | |
194 | example, the stock dhclient-script rewrites | |
195 | .Pa /etc/resolv.conf . | |
196 | If more than one interface is being configured, | |
197 | .Pa /etc/resolv.conf | |
198 | will be repeatedly initialized to the values provided by one server, and then | |
199 | the other. | |
200 | Assuming the information provided by both servers is valid, this shouldn't | |
201 | cause any real problems, but it could be confusing. |