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