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