Annotation of embedaddon/dhcp/client/dhclient.8, revision 1.1
1.1 ! misho 1: .\" $Id: dhclient.8,v 1.30.8.4.6.1 2011-04-15 22:26:20 sar 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