Return to dhclient.8 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / client

dhcp 4.1 r7

    1: .\"	$Id: dhclient.8,v 1.1.1.1 2012/10/09 09:06:54 misho Exp $
    2: .\"
    3: .\" Copyright (c) 2004,2007-2012 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: for configuration instructions.  It then gets a list of all the
  153: network interfaces that are configured in the current system.  For
  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
  159: dhclient.leases file.  On startup, after reading the dhclient.conf
  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
  164: dhclient.leases file.  In order to prevent the file from becoming
  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
  173: process).  In that event, old leases from the dhclient.leases file
  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
  180: address on that network.  When all attempts to contact a DHCP server
  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
  185: available but BOOTP is.  In that case, it may be advantageous to
  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
  198: file.  If interfaces are specified in this way, then the client will
  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
  261: not to exit when it doesn't find any such interfaces.  The
  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
  399: programs should use the dhcpctl API or OMAPI itself.  Dhcpctl is a
  400: wrapper that handles some of the housekeeping chores that OMAPI does
  401: not do automatically.  Dhcpctl and OMAPI are documented in
  402: \fBdhcpctl(3)\fR
  403: and \fBomapi(3)\fR.  Most things you'd want to do with the client can
  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
  410: interfaces the client is using.  You can then restart it, which
  411: causes it to reconfigure those interfaces.  You would normally pause
  412: the client prior to going into hibernation or sleep on a laptop
  413: computer.  You would then resume it after the power comes back.
  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
  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
  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
  467: Consortium DHCP server uses.  Much system-specific configuration code
  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