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>