]>
Commit | Line | Data |
---|---|---|
0e7affc7 TL |
1 | .\" dhclient.8 |
2 | .\" | |
98311e4b DH |
3 | .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") |
4 | .\" Copyright (c) 1996-2003 by Internet Software Consortium | |
0e7affc7 | 5 | .\" |
98311e4b DH |
6 | .\" Permission to use, copy, modify, and distribute this software for any |
7 | .\" purpose with or without fee is hereby granted, provided that the above | |
8 | .\" copyright notice and this permission notice appear in all copies. | |
0e7affc7 | 9 | .\" |
98311e4b DH |
10 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES |
11 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR | |
13 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT | |
16 | .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
17 | .\" | |
18 | .\" Internet Systems Consortium, Inc. | |
19 | .\" 950 Charter Street | |
20 | .\" Redwood City, CA 94063 | |
21 | .\" <info@isc.org> | |
22 | .\" http://www.isc.org/ | |
0e7affc7 | 23 | .\" |
f39b6e00 TL |
24 | .\" Support and other services are available for ISC products - see |
25 | .\" http://www.isc.org for more information. | |
51aca666 | 26 | .\" |
830ebc4c | 27 | .\" $Id: dhclient.8,v 1.19 2007/04/19 21:18:50 dhankins Exp $ |
51aca666 | 28 | .\" |
0e7affc7 TL |
29 | .TH dhclient 8 |
30 | .SH NAME | |
d73361d0 | 31 | dhclient - Dynamic Host Configuration Protocol Client |
0e7affc7 TL |
32 | .SH SYNOPSIS |
33 | .B dhclient | |
34 | [ | |
35 | .B -p | |
36 | .I port | |
37 | ] | |
38 | [ | |
39 | .B -d | |
40 | ] | |
41 | [ | |
88cd8aca DH |
42 | .B -e |
43 | .I VAR=value | |
44 | ] | |
45 | [ | |
93cd3170 TL |
46 | .B -q |
47 | ] | |
48 | [ | |
4ca9936c | 49 | .B -1 |
93cd3170 | 50 | ] |
4ca9936c | 51 | [ |
e493934d TL |
52 | .B -r |
53 | ] | |
54 | [ | |
93cd3170 TL |
55 | .B -lf |
56 | .I lease-file | |
57 | ] | |
58 | [ | |
59 | .B -pf | |
60 | .I pid-file | |
61 | ] | |
62 | [ | |
63 | .B -cf | |
64 | .I config-file | |
65 | ] | |
66 | [ | |
4ca9936c TL |
67 | .B -sf |
68 | .I script-file | |
69 | ] | |
70 | [ | |
93cd3170 TL |
71 | .B -s |
72 | server | |
73 | ] | |
74 | [ | |
4cefd70b TL |
75 | .B -g |
76 | relay | |
77 | ] | |
78 | [ | |
79 | .B -n | |
80 | ] | |
81 | [ | |
78b044fa TL |
82 | .B -nw |
83 | ] | |
84 | [ | |
36cbbce6 TL |
85 | .B -w |
86 | ] | |
87 | [ | |
0e7affc7 TL |
88 | .I if0 |
89 | [ | |
90 | .I ...ifN | |
91 | ] | |
92 | ] | |
93 | .SH DESCRIPTION | |
98311e4b | 94 | The Internet Systems Consortium DHCP Client, dhclient, provides a |
0e7affc7 TL |
95 | means for configuring one or more network interfaces using the Dynamic |
96 | Host Configuration Protocol, BOOTP protocol, or if these protocols | |
97 | fail, by statically assigning an address. | |
98 | .SH OPERATION | |
99 | .PP | |
100 | The DHCP protocol allows a host to contact a central server which | |
101 | maintains a list of IP addresses which may be assigned on one or more | |
102 | subnets. A DHCP client may request an address from this pool, and | |
103 | then use it on a temporary basis for communication on network. The | |
104 | DHCP protocol also provides a mechanism whereby a client can learn | |
105 | important details about the network to which it is attached, such as | |
106 | the location of a default router, the location of a name server, and | |
107 | so on. | |
108 | .PP | |
109 | On startup, dhclient reads the | |
110 | .IR dhclient.conf | |
111 | for configuration instructions. It then gets a list of all the | |
112 | network interfaces that are configured in the current system. For | |
113 | each interface, it attempts to configure the interface using the DHCP | |
114 | protocol. | |
115 | .PP | |
116 | In order to keep track of leases across system reboots and server | |
117 | restarts, dhclient keeps a list of leases it has been assigned in the | |
118 | dhclient.leases(5) file. On startup, after reading the dhclient.conf | |
119 | file, dhclient reads the dhclient.leases file to refresh its memory | |
120 | about what leases it has been assigned. | |
121 | .PP | |
122 | When a new lease is acquired, it is appended to the end of the | |
123 | dhclient.leases file. In order to prevent the file from becoming | |
124 | arbitrarily large, from time to time dhclient creates a new | |
125 | dhclient.leases file from its in-core lease database. The old version | |
126 | of the dhclient.leases file is retained under the name | |
4bd8800e | 127 | .IR dhclient.leases~ |
0e7affc7 TL |
128 | until the next time dhclient rewrites the database. |
129 | .PP | |
130 | Old leases are kept around in case the DHCP server is unavailable when | |
131 | dhclient is first invoked (generally during the initial system boot | |
132 | process). In that event, old leases from the dhclient.leases file | |
133 | which have not yet expired are tested, and if they are determined to | |
134 | be valid, they are used until either they expire or the DHCP server | |
135 | becomes available. | |
136 | .PP | |
137 | A mobile host which may sometimes need to access a network on which no | |
138 | DHCP server exists may be preloaded with a lease for a fixed | |
139 | address on that network. When all attempts to contact a DHCP server | |
140 | have failed, dhclient will try to validate the static lease, and if it | |
141 | succeeds, will use that lease until it is restarted. | |
142 | .PP | |
143 | A mobile host may also travel to some networks on which DHCP is not | |
144 | available but BOOTP is. In that case, it may be advantageous to | |
145 | arrange with the network administrator for an entry on the BOOTP | |
146 | database, so that the host can boot quickly on that network rather | |
147 | than cycling through the list of old leases. | |
148 | .SH COMMAND LINE | |
149 | .PP | |
150 | The names of the network interfaces that dhclient should attempt to | |
151 | configure may be specified on the command line. If no interface names | |
93cd3170 | 152 | are specified on the command line dhclient will normally identify all |
15766849 | 153 | network interfaces, eliminating non-broadcast interfaces if |
93cd3170 | 154 | possible, and attempt to configure each interface. |
0e7affc7 | 155 | .PP |
93cd3170 TL |
156 | It is also possible to specify interfaces by name in the |
157 | .B dhclient.conf(5) | |
158 | file. If interfaces are specified in this way, then the client will | |
159 | only configure interfaces that are either specified in the | |
160 | configuration file or on the command line, and will ignore all other | |
161 | interfaces. | |
162 | .PP | |
163 | If the DHCP client should listen and transmit on a port other than the | |
0e7affc7 TL |
164 | standard (port 68), the |
165 | .B -p | |
166 | flag may used. It should be followed by the udp port number that | |
167 | dhclient should use. This is mostly useful for debugging purposes. | |
93cd3170 TL |
168 | If a different port is specified for the client to listen on and |
169 | transmit on, the client will also use a different destination port - | |
170 | one greater than the specified destination port. | |
171 | .PP | |
172 | The DHCP client normally transmits any protocol messages it sends | |
173 | before acquiring an IP address to, 255.255.255.255, the IP limited | |
174 | broadcast address. For debugging purposes, it may be useful to have | |
175 | the server transmit these messages to some other address. This can | |
176 | be specified with the | |
177 | .B -s | |
178 | flag, followed by the IP address or domain name of the destination. | |
0e7affc7 | 179 | .PP |
4cefd70b TL |
180 | For testing purposes, the giaddr field of all packets that the client |
181 | sends can be set using the | |
182 | .B -g | |
183 | flag, followed by the IP address to send. This is only useful for testing, | |
184 | and should not be expected to work in any consistent or useful way. | |
185 | .PP | |
93cd3170 TL |
186 | The DHCP client will normally run in the foreground until it has |
187 | configured an interface, and then will revert to running in the | |
188 | background. To run force dhclient to always run as a foreground | |
189 | process, the | |
0e7affc7 | 190 | .B -d |
93cd3170 TL |
191 | flag should be specified. This is useful when running the client |
192 | under a debugger, or when running it out of inittab on System V | |
193 | systems. | |
194 | .PP | |
88cd8aca DH |
195 | The dhclient daemon creates its own environment when executing the |
196 | dhclient-script to do the grunt work of interface configuration. | |
197 | To define extra environment variables and their values, use the | |
198 | .B -e | |
199 | flag, followed by the environment variable name and value assignment, | |
200 | just as one would assign a variable in a shell. Eg: | |
201 | .B -e | |
202 | .I IF_METRIC=1 | |
203 | .PP | |
93cd3170 TL |
204 | The client normally prints a startup message and displays the |
205 | protocol sequence to the standard error descriptor until it has | |
206 | acquired an address, and then only logs messages using the | |
207 | .B syslog (3) | |
208 | facility. The | |
209 | .B -q | |
210 | flag prevents any messages other than errors from being printed to the | |
211 | standard error descriptor. | |
0e7affc7 | 212 | .PP |
e493934d TL |
213 | The client normally doesn't release the current lease as it is not |
214 | required by the DHCP protocol. Some cable ISPs require their clients | |
215 | to notify the server if they wish to release an assigned IP address. | |
216 | The | |
217 | .B -r | |
f1d453af TL |
218 | flag explicitly releases the current lease, and once the lease has been |
219 | released, the client exits. | |
e493934d | 220 | .PP |
4ca9936c TL |
221 | The |
222 | .B -1 | |
830ebc4c DH |
223 | flag will cause dhclient to try once to get a lease. If it fails, dhclient |
224 | exits with exit code two. | |
4ca9936c | 225 | .PP |
93cd3170 TL |
226 | The DHCP client normally gets its configuration information from |
227 | .B ETCDIR/dhclient.conf, | |
228 | its lease database from | |
4ca9936c TL |
229 | .B DBDIR/dhclient.leases, |
230 | stores its process ID in a file called | |
231 | .B RUNDIR/dhclient.pid, | |
232 | and configures the network interface using | |
233 | .B CLIENTBINDIR/dhclient-script | |
93cd3170 TL |
234 | To specify different names and/or locations for these files, use the |
235 | .B -cf, | |
4ca9936c | 236 | .B -lf, |
93cd3170 | 237 | .B -pf |
4ca9936c TL |
238 | and |
239 | .B -sf | |
93cd3170 TL |
240 | flags, respectively, followed by the name of the file. This can be |
241 | particularly useful if, for example, | |
242 | .B DBDIR | |
243 | or | |
244 | .B RUNDIR | |
245 | has not yet been mounted when the DHCP client is started. | |
36cbbce6 TL |
246 | .PP |
247 | The DHCP client normally exits if it isn't able to identify any | |
248 | network interfaces to configure. On laptop computers and other | |
249 | computers with hot-swappable I/O buses, it is possible that a | |
250 | broadcast interface may be added after system startup. The | |
251 | .B -w | |
252 | flag can be used to cause the client not to exit when it doesn't find | |
253 | any such interfaces. The | |
88cd8aca | 254 | .B omshell (1) |
36cbbce6 | 255 | program can then be used to notify the client when a network interface |
4cefd70b | 256 | has been added or removed, so that the client can attempt to configure an IP |
36cbbce6 | 257 | address on that interface. |
4cefd70b TL |
258 | .PP |
259 | The DHCP client can be directed not to attempt to configure any interfaces | |
260 | using the | |
261 | .B -n | |
262 | flag. This is most likely to be useful in combination with the | |
263 | .B -w | |
264 | flag. | |
78b044fa TL |
265 | .PP |
266 | The client can also be instructed to become a daemon immediately, rather | |
267 | than waiting until it has acquired an IP address. This can be done by | |
268 | supplying the | |
269 | .B -nw | |
270 | flag. | |
0e7affc7 | 271 | .SH CONFIGURATION |
f953078e | 272 | The syntax of the dhclient.conf(5) file is discussed separately. |
d758ad8c TL |
273 | .SH OMAPI |
274 | The DHCP client provides some ability to control it while it is | |
275 | running, without stopping it. This capability is provided using OMAPI, | |
276 | an API for manipulating remote objects. OMAPI clients connect to the | |
277 | client using TCP/IP, authenticate, and can then examine the client's | |
278 | current status and make changes to it. | |
279 | .PP | |
280 | Rather than implementing the underlying OMAPI protocol directly, user | |
281 | programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a | |
282 | wrapper that handles some of the housekeeping chores that OMAPI does | |
283 | not do automatically. Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR | |
284 | and \fBomapi(3)\fR. Most things you'd want to do with the client can | |
285 | be done directly using the \fBomshell(1)\fR command, rather than | |
286 | having to write a special program. | |
287 | .SH THE CONTROL OBJECT | |
288 | The control object allows you to shut the client down, releasing all | |
289 | leases that it holds and deleting any DNS records it may have added. | |
290 | It also allows you to pause the client - this unconfigures any | |
291 | interfaces the client is using. You can then restart it, which | |
292 | causes it to reconfigure those interfaces. You would normally pause | |
293 | the client prior to going into hibernation or sleep on a laptop | |
294 | computer. You would then resume it after the power comes back. | |
295 | This allows PC cards to be shut down while the computer is hibernating | |
296 | or sleeping, and then reinitialized to their previous state once the | |
297 | computer comes out of hibernation or sleep. | |
298 | .PP | |
299 | The control object has one attribute - the state attribute. To shut | |
300 | the client down, set its state attribute to 2. It will automatically | |
301 | do a DHCPRELEASE. To pause it, set its state attribute to 3. To | |
302 | resume it, set its state attribute to 4. | |
303 | .PP | |
0e7affc7 | 304 | .SH FILES |
4ca9936c | 305 | .B CLIENTBINDIR/dhclient-script, |
0e7affc7 TL |
306 | .B ETCDIR/dhclient.conf, DBDIR/dhclient.leases, RUNDIR/dhclient.pid, |
307 | .B DBDIR/dhclient.leases~. | |
308 | .SH SEE ALSO | |
98311e4b | 309 | dhcpd(8), dhcrelay(8), dhclient-script(8), dhclient.conf(5), |
4ca9936c | 310 | dhclient.leases(5). |
0e7affc7 TL |
311 | .SH AUTHOR |
312 | .B dhclient(8) | |
98311e4b | 313 | has been written for Internet Systems Consortium |
f953078e | 314 | by Ted Lemon in cooperation with Vixie |
98311e4b | 315 | Enterprises. To learn more about Internet Systems Consortium, |
0e7affc7 | 316 | see |
f953078e | 317 | .B http://www.isc.org |
0e7affc7 TL |
318 | To learn more about Vixie |
319 | Enterprises, see | |
320 | .B http://www.vix.com. | |
321 | .PP | |
322 | This client was substantially modified and enhanced by Elliot Poger | |
323 | for use on Linux while he was working on the MosquitoNet project at | |
324 | Stanford. | |
325 | .PP | |
326 | The current version owes much to Elliot's Linux enhancements, but | |
327 | was substantially reorganized and partially rewritten by Ted Lemon | |
98311e4b | 328 | so as to use the same networking framework that the Internet Systems |
0e7affc7 TL |
329 | Consortium DHCP server uses. Much system-specific configuration code |
330 | was moved into a shell script so that as support for more operating | |
331 | systems is added, it will not be necessary to port and maintain | |
332 | system-specific configuration code to these operating systems - instead, | |
333 | the shell script can invoke the native tools to accomplish the same | |
334 | purpose. | |
335 | .PP |