1: .\" $Id: dhclient.8,v 1.1 2012/02/21 22:30:18 misho Exp $
2: .\"
3: .\" Copyright (c) 2004,2007-2011 by Internet Systems Consortium, Inc. ("ISC")
4: .\" Copyright (c) 1996-2003 by Internet Software Consortium
5: .\"
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.
9: .\"
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: .\" https://www.isc.org/
23: .\"
24: .\" Support and other services are available for ISC products - see
25: .\" https://www.isc.org for more information or to learn more about ISC.
26: .\"
27: .TH dhclient 8
28: .SH NAME
29: dhclient - Dynamic Host Configuration Protocol Client
30: .SH SYNOPSIS
31: .B dhclient
32: [
33: .B -4
34: |
35: .B -6
36: ]
37: [
38: .B -S
39: ]
40: [
41: .B -N
42: [
43: .B -N...
44: ]
45: ]
46: [
47: .B -T
48: [
49: .B -T...
50: ]
51: ]
52: [
53: .B -P
54: [
55: .B -P...
56: ]
57: ]
58: [
59: .B -p
60: .I port
61: ]
62: [
63: .B -d
64: ]
65: [
66: .B -e
67: .I VAR=value
68: ]
69: [
70: .B -q
71: ]
72: [
73: .B -1
74: ]
75: [
76: .B -r
77: |
78: .B -x
79: ]
80: [
81: .B -lf
82: .I lease-file
83: ]
84: [
85: .B -pf
86: .I pid-file
87: ]
88: [
89: .B --no-pid
90: ]
91: [
92: .B -cf
93: .I config-file
94: ]
95: [
96: .B -sf
97: .I script-file
98: ]
99: [
100: .B -s
101: .I server-addr
102: ]
103: [
104: .B -g
105: .I relay
106: ]
107: [
108: .B -n
109: ]
110: [
111: .B -nw
112: ]
113: [
114: .B -w
115: ]
116: [
117: .B -v
118: ]
119: [
120: .B --version
121: ]
122: [
123: .I if0
124: [
125: .I ...ifN
126: ]
127: ]
128: .SH DESCRIPTION
129: The Internet Systems Consortium DHCP Client, \fBdhclient\fR, provides a
130: means for configuring one or more network interfaces using the Dynamic
131: Host Configuration Protocol, BOOTP protocol, or if these protocols
132: fail, by statically assigning an address.
133: .SH OPERATION
134: .PP
135: The DHCP protocol allows a host to contact a central server which
136: maintains a list of IP addresses which may be assigned on one or more
137: subnets. A DHCP client may request an address from this pool, and
138: then use it on a temporary basis for communication on network. The
139: DHCP protocol also provides a mechanism whereby a client can learn
140: important details about the network to which it is attached, such as
141: the location of a default router, the location of a name server, and
142: so on.
143: .PP
144: There are two versions of the DHCP protocol DHCPv4 and DHCPv6. At
145: startup the client may be started for one or the other via the
146: .B -4
147: or
148: .B -6
149: options.
150: .PP
151: On startup, \fBdhclient\fR reads the dhclient.conf
152: .IR dhclient.conf
153: for configuration instructions. It then gets a list of all the
154: network interfaces that are configured in the current system. For
155: each interface, it attempts to configure the interface using the DHCP
156: protocol.
157: .PP
158: In order to keep track of leases across system reboots and server
159: restarts, \fBdhclient\fR keeps a list of leases it has been assigned in the
160: dhclient.leases file. On startup, after reading the dhclient.conf
161: file, \fBdhclient\fR reads the dhclient.leases file to refresh its memory
162: about what leases it has been assigned.
163: .PP
164: When a new lease is acquired, it is appended to the end of the
165: dhclient.leases file. In order to prevent the file from becoming
166: arbitrarily large, from time to time \fBdhclient\fR creates a new
167: dhclient.leases file from its in-core lease database. The old version
168: of the dhclient.leases file is retained under the name
169: .IR dhclient.leases~
170: until the next time \fBdhclient\fR rewrites the database.
171: .PP
172: Old leases are kept around in case the DHCP server is unavailable when
173: \fBdhclient\fR is first invoked (generally during the initial system boot
174: process). In that event, old leases from the dhclient.leases file
175: which have not yet expired are tested, and if they are determined to
176: be valid, they are used until either they expire or the DHCP server
177: becomes available.
178: .PP
179: A mobile host which may sometimes need to access a network on which no
180: DHCP server exists may be preloaded with a lease for a fixed
181: address on that network. When all attempts to contact a DHCP server
182: have failed, \fBdhclient\fR will try to validate the static lease, and if it
183: succeeds, will use that lease until it is restarted.
184: .PP
185: A mobile host may also travel to some networks on which DHCP is not
186: available but BOOTP is. In that case, it may be advantageous to
187: arrange with the network administrator for an entry on the BOOTP
188: database, so that the host can boot quickly on that network rather
189: than cycling through the list of old leases.
190: .SH COMMAND LINE
191: .PP
192: The names of the network interfaces that \fBdhclient\fR should attempt to
193: configure may be specified on the command line. If no interface names
194: are specified on the command line \fBdhclient\fR will normally identify all
195: network interfaces, eliminating non-broadcast interfaces if
196: possible, and attempt to configure each interface.
197: .PP
198: It is also possible to specify interfaces by name in the dhclient.conf
199: file. If interfaces are specified in this way, then the client will
200: only configure interfaces that are either specified in the
201: configuration file or on the command line, and will ignore all other
202: interfaces.
203: .PP
204: The client normally prints no output during its startup sequence. It
205: can be made to emit verbose messages displaying the startup sequence events
206: until it has acquired an address by supplying the
207: .B -v
208: command line argument. In either case, the client logs messages using
209: the
210: .B syslog(3)
211: facility.
212: .SH OPTIONS
213: .TP
214: .BI \-4
215: Use the DHCPv4 protocol to obtain an IPv4 address and configuration
216: parameters. This is the default and cannot be combined with
217: \fB\-6\fR.
218: .TP
219: .BI \-6
220: Use the DHCPv6 protocol to obtain whatever IPv6 addresses are available
221: along with configuration parameters. It cannot be combined with
222: \fB\-4\fR. The \fB\-S -T -P\fR and
223: \fB\-N\fR arguments provide more control over aspects of the DHCPv6
224: processing. Note: it is not recommended to mix queries of different
225: types together or even to share the lease file between them.
226: .TP
227: .BI \-1
228: Try to get a lease once. On failure exit with code 2. In DHCPv6 this
229: sets the maximum duration of the initial exchange to
230: .I timeout
231: (from
232: .IR dhclient.conf(5)
233: with a default of sixty seconds).
234: .TP
235: .BI \-d
236: .\" This is not intuitive.
237: Force
238: .B dhclient
239: to run as a foreground process. Normally the DHCP client will run
240: in the foreground until is has configured an interface at which time
241: it will revert to running in the background. This option is useful
242: when running the client under a debugger, or when running it out of
243: inittab on System V systems. This implies \fB-v\fR.
244: .TP
245: .BI \-nw
246: Become a daemon immediately (nowait) rather than waiting until an
247: an IP address has been acquired.
248: .TP
249: .BI \-q
250: Be quiet at startup, this is the default.
251: .TP
252: .BI \-v
253: Enable verbose log messages.
254: .\" This prints the version, copyright and URL.
255: .TP
256: .BI \-w
257: Continue running even if no broadcast interfaces were found. Normally
258: DHCP client will exit if it isn't able to identify any network interfaces
259: to configure. On laptop computers and other computers with
260: hot-swappable I/O buses, it is possible that a broadcast interface may
261: be added after system startup. This flag can be used to cause the client
262: not to exit when it doesn't find any such interfaces. The
263: .B omshell(1)
264: program can then be used to notify the client when a network interface
265: has been added or removed, so that the client can attempt to configure an IP
266: address on that interface.
267: .TP
268: .BI \-n
269: Do not configure any interfaces. This is most likely to be useful in
270: combination with the
271: .B -w
272: flag.
273: .TP
274: .BI \-e \ VAR=val
275: Define additional environment variables for the environment where
276: .B dhclient-script(8)
277: executes. You may specify multiple
278: .B \-e
279: options on the command line.
280: .TP
281: .BI \-r
282: Release the current lease and stop the running DHCP client as previously
283: recorded in the PID file. When shutdown via this method
284: .B dhclient-script(8)
285: will be executed with the specific reason for calling the script set.
286: The client normally doesn't release the current lease as this is not
287: required by the DHCP protocol but some cable ISPs require their clients
288: to notify the server if they wish to release an assigned IP address.
289: .\" TODO what dhclient-script argument?
290: .\" When released,
291: .TP
292: .BI \-x
293: Stop the running DHCP client without releasing the current lease.
294: Kills existing \fBdhclient\fR process as previously recorded in the
295: PID file. When shutdown via this method
296: .B dhclient-script(8)
297: will be executed with the specific reason for calling the script set.
298: .TP
299: .BI \-p \ port
300: The UDP port number on which the DHCP client should listen and transmit.
301: If unspecified,
302: .B dhclient
303: uses the default port of 68. This is mostly useful for debugging purposes.
304: If a different port is specified on which the client should listen and
305: transmit, the client will also use a different destination port -
306: one less than the specified port.
307: .TP
308: .BI \-s \ server-addr
309: Specify the server IP address or fully qualified domain name to use as
310: a destination for DHCP protocol messages before
311: .B dhclient
312: has acquired an IP address. Normally,
313: .B dhclient
314: transmits these messages to 255.255.255.255 (the IP limited broadcast
315: address). Overriding this is mostly useful for debugging purposes. This
316: feature is not supported in DHCPv6 (\fB-6\fR) mode.
317: .TP
318: .BI \-g \ relay
319: .\" mockup relay
320: Set the giaddr field of all packets to the \fIrelay\fR IP address
321: simulating a relay agent. This is for testing pruposes only and
322: should not be expected to work in any consistent or useful way.
323: .TP
324: .BI \--version
325: Print version number and exit.
326: .PP
327: .I Options available for DHCPv6 mode:
328: .TP
329: .BI \-S
330: .\" TODO: mention DUID?
331: Use Information-request to get only stateless configuration parameters
332: (i.e., without address). This implies \fB\-6\fR. It also doesn't
333: rewrite the lease database.
334: .\" TODO: May not be used with -N -P or -T. ??
335: .TP
336: .BI \-T
337: .\" TODO wanted_ia_ta++
338: Ask for IPv6 temporary addresses, one set per \fB\-T\fR flag. This
339: implies \fB\-6\fR and also disables the normal address query.
340: See \fB\-N\fR to restore it.
341: .TP
342: .BI \-P
343: Enable IPv6 prefix delegation. This implies \fB\-6\fR and also
344: disables the normal address query. See \fB\-N\fR to restore it.
345: Note only one requested interface is allowed.
346: .TP
347: .BI \-N
348: .\" TODO: is this for telling an already running dhclient?
349: Restore normal address query for IPv6. This implies \fB-6\fR.
350: It is used to restore normal operation after using \fB-T\fR or \fB-P\fR.
351: .PP
352: .I Modifying default file locations:
353: The following options can be used to modify the locations a client uses
354: for it's files. They can be particularly useful if, for example,
355: .B DBDIR
356: or
357: .B RUNDIR
358: have not been mounted when the DHCP client is started.
359: .TP
360: .BI \-cf \ config-file
361: Path to the client configuration file. If unspecified, the default
362: .B ETCDIR/dhclient.conf
363: is used. See \fBdhclient.conf(5)\fR for a description of this file.
364: .TP
365: .BI \-lf \ lease-file
366: Path to the lease database file. If unspecified, the default
367: .B DBDIR/dhclient.leases
368: is used. See \fBdhclient.leases(5)\fR for a descriptionof this file.
369: .TP
370: .BI \-pf \ pid-file
371: Path to the process ID file. If unspecified, the default
372: .B RUNDIR/dhclient.pid
373: is used.
374: .TP
375: .BI \--no-pid
376: Option to disable writing pid files. By default the program
377: will write a pid file. If the program is invoked with this
378: option it will not attempt to kill any existing client processes
379: even if invoked with \fB-r\fR or \fB-x\fR.
380: .TP
381: .BI \-sf \ script-file
382: Path to the network configuration script invoked by
383: .B dhclient
384: when it gets a lease. If unspecified, the default
385: .B CLIENTBINDIR/dhclient-script
386: is used. See \fBdhclient-script(8)\fR for a description of this file.
387:
388:
389: .PP
390: .SH CONFIGURATION
391: The syntax of the \fBdhclient.conf(5)\fR file is discussed separately.
392: .SH OMAPI
393: The DHCP client provides some ability to control it while it is
394: running, without stopping it. This capability is provided using OMAPI,
395: an API for manipulating remote objects. OMAPI clients connect to the
396: client using TCP/IP, authenticate, and can then examine the client's
397: current status and make changes to it.
398: .PP
399: Rather than implementing the underlying OMAPI protocol directly, user
400: programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
401: wrapper that handles some of the housekeeping chores that OMAPI does
402: not do automatically. Dhcpctl and OMAPI are documented in
403: \fBdhcpctl(3)\fR
404: and \fBomapi(3)\fR. Most things you'd want to do with the client can
405: be done directly using the \fBomshell(1)\fR command, rather than
406: having to write a special program.
407: .SH THE CONTROL OBJECT
408: The control object allows you to shut the client down, releasing all
409: leases that it holds and deleting any DNS records it may have added.
410: It also allows you to pause the client - this unconfigures any
411: interfaces the client is using. You can then restart it, which
412: causes it to reconfigure those interfaces. You would normally pause
413: the client prior to going into hibernation or sleep on a laptop
414: computer. You would then resume it after the power comes back.
415: This allows PC cards to be shut down while the computer is hibernating
416: or sleeping, and then reinitialized to their previous state once the
417: computer comes out of hibernation or sleep.
418: .PP
419: The control object has one attribute - the state attribute. To shut
420: the client down, set its state attribute to 2. It will automatically
421: do a DHCPRELEASE. To pause it, set its state attribute to 3. To
422: resume it, set its state attribute to 4.
423: .PP
424: .SH ENVIRONMENT VARIABLES
425: .PP
426: The following environment variables may be defined
427: to override the builtin defaults for file locations.
428: Note that use of the related command-line options
429: will ignore the corresponding environment variable settings.
430: .TP
431: .B PATH_DHCLIENT_CONF
432: The dhclient.conf configuration file.
433: .TP
434: .B PATH_DHCLIENT_DB
435: The dhclient.leases database.
436: .TP
437: .B PATH_DHCLIENT_PID
438: The dhclient PID file.
439: .TP
440: .B PATH_DHCLIENT_SCRIPT
441: The dhclient-script file.
442: .PP
443: .SH FILES
444: .B CLIENTBINDIR/dhclient-script,
445: .B ETCDIR/dhclient.conf, DBDIR/dhclient.leases, RUNDIR/dhclient.pid,
446: .B DBDIR/dhclient.leases~.
447: .SH SEE ALSO
448: dhcpd(8), dhcrelay(8), dhclient-script(8), dhclient.conf(5),
449: dhclient.leases(5), dhcp-eval(5).
450: .SH AUTHOR
451: .B dhclient(8)
452: has been written for Internet Systems Consortium
453: by Ted Lemon in cooperation with Vixie
454: Enterprises. To learn more about Internet Systems Consortium,
455: see
456: .B https://www.isc.org
457: To learn more about Vixie
458: Enterprises, see
459: .B http://www.vix.com.
460: .PP
461: This client was substantially modified and enhanced by Elliot Poger
462: for use on Linux while he was working on the MosquitoNet project at
463: Stanford.
464: .PP
465: The current version owes much to Elliot's Linux enhancements, but
466: was substantially reorganized and partially rewritten by Ted Lemon
467: so as to use the same networking framework that the Internet Systems
468: Consortium DHCP server uses. Much system-specific configuration code
469: was moved into a shell script so that as support for more operating
470: systems is added, it will not be necessary to port and maintain
471: system-specific configuration code to these operating systems - instead,
472: the shell script can invoke the native tools to accomplish the same
473: purpose.
474: .PP
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dhclient.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / client