diff options
Diffstat (limited to 'client/dhclient.8')
| -rw-r--r-- | client/dhclient.8 | 486 |
1 files changed, 486 insertions, 0 deletions
diff --git a/client/dhclient.8 b/client/dhclient.8 new file mode 100644 index 0000000..6306b08 --- /dev/null +++ b/client/dhclient.8 @@ -0,0 +1,486 @@ +.\" $Id: dhclient.8,v 1.32.24.4 2011-04-15 22:12:50 sar Exp $ +.\" +.\" Copyright (c) 2004,2007-2011 by Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (c) 1996-2003 by Internet Software Consortium +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Internet Systems Consortium, Inc. +.\" 950 Charter Street +.\" Redwood City, CA 94063 +.\" <info@isc.org> +.\" https://www.isc.org/ +.\" +.\" Support and other services are available for ISC products - see +.\" https://www.isc.org for more information or to learn more about ISC. +.\" +.TH dhclient 8 +.SH NAME +dhclient - Dynamic Host Configuration Protocol Client +.SH SYNOPSIS +.B dhclient +[ +.B -4 +| +.B -6 +] +[ +.B -S +] +[ +.B -N +[ +.B -N... +] +] +[ +.B -T +[ +.B -T... +] +] +[ +.B -P +[ +.B -P... +] +] +[ +.B -D +.I LL|LLT +] +[ +.B -p +.I port +] +[ +.B -d +] +[ +.B -e +.I VAR=value +] +[ +.B -q +] +[ +.B -1 +] +[ +.B -r +| +.B -x +] +[ +.B -lf +.I lease-file +] +[ +.B -pf +.I pid-file +] +[ +.B --no-pid +] +[ +.B -cf +.I config-file +] +[ +.B -sf +.I script-file +] +[ +.B -s +.I server-addr +] +[ +.B -g +.I relay +] +[ +.B -n +] +[ +.B -nw +] +[ +.B -w +] +[ +.B -v +] +[ +.B --version +] +[ +.I if0 +[ +.I ...ifN +] +] +.SH DESCRIPTION +The Internet Systems Consortium DHCP Client, \fBdhclient\fR, provides a +means for configuring one or more network interfaces using the Dynamic +Host Configuration Protocol, BOOTP protocol, or if these protocols +fail, by statically assigning an address. +.SH OPERATION +.PP +The DHCP protocol allows a host to contact a central server which +maintains a list of IP addresses which may be assigned on one or more +subnets. A DHCP client may request an address from this pool, and +then use it on a temporary basis for communication on network. The +DHCP protocol also provides a mechanism whereby a client can learn +important details about the network to which it is attached, such as +the location of a default router, the location of a name server, and +so on. +.PP +There are two versions of the DHCP protocol DHCPv4 and DHCPv6. At +startup the client may be started for one or the other via the +.B -4 +or +.B -6 +options. +.PP +On startup, \fBdhclient\fR reads the dhclient.conf +for configuration instructions. It then gets a list of all the +network interfaces that are configured in the current system. For +each interface, it attempts to configure the interface using the DHCP +protocol. +.PP +In order to keep track of leases across system reboots and server +restarts, \fBdhclient\fR keeps a list of leases it has been assigned in the +dhclient.leases file. On startup, after reading the dhclient.conf +file, \fBdhclient\fR reads the dhclient.leases file to refresh its memory +about what leases it has been assigned. +.PP +When a new lease is acquired, it is appended to the end of the +dhclient.leases file. In order to prevent the file from becoming +arbitrarily large, from time to time \fBdhclient\fR creates a new +dhclient.leases file from its in-core lease database. The old version +of the dhclient.leases file is retained under the name +.IR dhclient.leases~ +until the next time \fBdhclient\fR rewrites the database. +.PP +Old leases are kept around in case the DHCP server is unavailable when +\fBdhclient\fR is first invoked (generally during the initial system boot +process). In that event, old leases from the dhclient.leases file +which have not yet expired are tested, and if they are determined to +be valid, they are used until either they expire or the DHCP server +becomes available. +.PP +A mobile host which may sometimes need to access a network on which no +DHCP server exists may be preloaded with a lease for a fixed +address on that network. When all attempts to contact a DHCP server +have failed, \fBdhclient\fR will try to validate the static lease, and if it +succeeds, will use that lease until it is restarted. +.PP +A mobile host may also travel to some networks on which DHCP is not +available but BOOTP is. In that case, it may be advantageous to +arrange with the network administrator for an entry on the BOOTP +database, so that the host can boot quickly on that network rather +than cycling through the list of old leases. +.SH COMMAND LINE +.PP +The names of the network interfaces that \fBdhclient\fR should attempt to +configure may be specified on the command line. If no interface names +are specified on the command line \fBdhclient\fR will normally identify all +network interfaces, eliminating non-broadcast interfaces if +possible, and attempt to configure each interface. +.PP +It is also possible to specify interfaces by name in the dhclient.conf +file. If interfaces are specified in this way, then the client will +only configure interfaces that are either specified in the +configuration file or on the command line, and will ignore all other +interfaces. +.PP +The client normally prints no output during its startup sequence. It +can be made to emit verbose messages displaying the startup sequence events +until it has acquired an address by supplying the +.B -v +command line argument. In either case, the client logs messages using +the +.B syslog(3) +facility. +.SH OPTIONS +.TP +.BI \-4 +Use the DHCPv4 protocol to obtain an IPv4 address and configuration +parameters. This is the default and cannot be combined with +\fB\-6\fR. +.TP +.BI \-6 +Use the DHCPv6 protocol to obtain whatever IPv6 addresses are available +along with configuration parameters. It cannot be combined with +\fB\-4\fR. The \fB\-S -T -P -N\fR and +\fB\-D\fR arguments provide more control over aspects of the DHCPv6 +processing. Note: it is not recommended to mix queries of different +types together or even to share the lease file between them. +.TP +.BI \-1 +Try to get a lease once. On failure exit with code 2. In DHCPv6 this +sets the maximum duration of the initial exchange to +.I timeout +(from +.IR dhclient.conf(5) +with a default of sixty seconds). +.TP +.BI \-d +.\" This is not intuitive. +Force +.B dhclient +to run as a foreground process. Normally the DHCP client will run +in the foreground until is has configured an interface at which time +it will revert to running in the background. This option is useful +when running the client under a debugger, or when running it out of +inittab on System V systems. This implies \fB-v\fR. +.TP +.BI \-nw +Become a daemon immediately (nowait) rather than waiting until an +an IP address has been acquired. +.TP +.BI \-q +Be quiet at startup, this is the default. +.TP +.BI \-v +Enable verbose log messages. +.\" This prints the version, copyright and URL. +.TP +.BI \-w +Continue running even if no broadcast interfaces were found. Normally +DHCP client will exit if it isn't able to identify any network interfaces +to configure. On laptop computers and other computers with +hot-swappable I/O buses, it is possible that a broadcast interface may +be added after system startup. This flag can be used to cause the client +not to exit when it doesn't find any such interfaces. The +.B omshell(1) +program can then be used to notify the client when a network interface +has been added or removed, so that the client can attempt to configure an IP +address on that interface. +.TP +.BI \-n +Do not configure any interfaces. This is most likely to be useful in +combination with the +.B -w +flag. +.TP +.BI \-e \ VAR=val +Define additional environment variables for the environment where +.B dhclient-script(8) +executes. You may specify multiple +.B \-e +options on the command line. +.TP +.BI \-r +Release the current lease and stop the running DHCP client as previously +recorded in the PID file. When shutdown via this method +.B dhclient-script(8) +will be executed with the specific reason for calling the script set. +The client normally doesn't release the current lease as this is not +required by the DHCP protocol but some cable ISPs require their clients +to notify the server if they wish to release an assigned IP address. +.\" TODO what dhclient-script argument? +.\" When released, +.TP +.BI \-x +Stop the running DHCP client without releasing the current lease. +Kills existing \fBdhclient\fR process as previously recorded in the +PID file. When shutdown via this method +.B dhclient-script(8) +will be executed with the specific reason for calling the script set. +.TP +.BI \-p \ port +The UDP port number on which the DHCP client should listen and transmit. +If unspecified, +.B dhclient +uses the default port of 68. This is mostly useful for debugging purposes. +If a different port is specified on which the client should listen and +transmit, the client will also use a different destination port - +one less than the specified port. +.TP +.BI \-s \ server-addr +Specify the server IP address or fully qualified domain name to use as +a destination for DHCP protocol messages before +.B dhclient +has acquired an IP address. Normally, +.B dhclient +transmits these messages to 255.255.255.255 (the IP limited broadcast +address). Overriding this is mostly useful for debugging purposes. This +feature is not supported in DHCPv6 (\fB-6\fR) mode. +.TP +.BI \-g \ relay +.\" mockup relay +Set the giaddr field of all packets to the \fIrelay\fR IP address +simulating a relay agent. This is for testing pruposes only and +should not be expected to work in any consistent or useful way. +.TP +.BI \--version +Print version number and exit. +.PP +.I Options available for DHCPv6 mode: +.TP +.BI \-S +.\" TODO: mention DUID? +Use Information-request to get only stateless configuration parameters +(i.e., without address). This implies \fB\-6\fR. It also doesn't +rewrite the lease database. +.\" TODO: May not be used with -N -P or -T. ?? +.TP +.BI \-T +.\" TODO wanted_ia_ta++ +Ask for IPv6 temporary addresses, one set per \fB\-T\fR flag. This +implies \fB\-6\fR and also disables the normal address query. +See \fB\-N\fR to restore it. +.TP +.BI \-P +Enable IPv6 prefix delegation. This implies \fB\-6\fR and also +disables the normal address query. See \fB\-N\fR to restore it. +Note only one requested interface is allowed. +.TP +.BI \-D \ LL\ or\ LLT +Override the default when selecting the type of DUID to use. By default, +DHCPv6 \fBdhclient\fR creates an identifier based on the link-layer address +(DUID-LL) if it is running in stateless mode (with \fB\-S\fR, not +requesting an address), or it creates an identifier based on the +link-layer address plus a timestamp (DUID-LLT) if it is running in +stateful mode (without \fB\-S\fR, requesting an address). \fB\-D\fR +overrides this default, with a value of either \fILL\fR or \fILLT\fR. +.TP +.BI \-N +.\" TODO: is this for telling an already running dhclient? +Restore normal address query for IPv6. This implies \fB-6\fR. +It is used to restore normal operation after using \fB-T\fR or \fB-P\fR. +.PP +.I Modifying default file locations: +The following options can be used to modify the locations a client uses +for it's files. They can be particularly useful if, for example, +.B DBDIR +or +.B RUNDIR +have not been mounted when the DHCP client is started. +.TP +.BI \-cf \ config-file +Path to the client configuration file. If unspecified, the default +.B ETCDIR/dhclient.conf +is used. See \fBdhclient.conf(5)\fR for a description of this file. +.TP +.BI \-lf \ lease-file +Path to the lease database file. If unspecified, the default +.B DBDIR/dhclient.leases +is used. See \fBdhclient.leases(5)\fR for a descriptionof this file. +.TP +.BI \-pf \ pid-file +Path to the process ID file. If unspecified, the default +.B RUNDIR/dhclient.pid +is used. +.TP +.BI \--no-pid +Option to disable writing pid files. By default the program +will write a pid file. If the program is invoked with this +option it will not attempt to kill any existing client processes +even if invoked with \fB-r\fR or \fB-x\fR. +.TP +.BI \-sf \ script-file +Path to the network configuration script invoked by +.B dhclient +when it gets a lease. If unspecified, the default +.B CLIENTBINDIR/dhclient-script +is used. See \fBdhclient-script(8)\fR for a description of this file. + + +.PP +.SH CONFIGURATION +The syntax of the \fBdhclient.conf(5)\fR file is discussed separately. +.SH OMAPI +The DHCP client provides some ability to control it while it is +running, without stopping it. This capability is provided using OMAPI, +an API for manipulating remote objects. OMAPI clients connect to the +client using TCP/IP, authenticate, and can then examine the client's +current status and make changes to it. +.PP +Rather than implementing the underlying OMAPI protocol directly, user +programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a +wrapper that handles some of the housekeeping chores that OMAPI does +not do automatically. Dhcpctl and OMAPI are documented in +\fBdhcpctl(3)\fR +and \fBomapi(3)\fR. Most things you'd want to do with the client can +be done directly using the \fBomshell(1)\fR command, rather than +having to write a special program. +.SH THE CONTROL OBJECT +The control object allows you to shut the client down, releasing all +leases that it holds and deleting any DNS records it may have added. +It also allows you to pause the client - this unconfigures any +interfaces the client is using. You can then restart it, which +causes it to reconfigure those interfaces. You would normally pause +the client prior to going into hibernation or sleep on a laptop +computer. You would then resume it after the power comes back. +This allows PC cards to be shut down while the computer is hibernating +or sleeping, and then reinitialized to their previous state once the +computer comes out of hibernation or sleep. +.PP +The control object has one attribute - the state attribute. To shut +the client down, set its state attribute to 2. It will automatically +do a DHCPRELEASE. To pause it, set its state attribute to 3. To +resume it, set its state attribute to 4. +.PP +.SH ENVIRONMENT VARIABLES +.PP +The following environment variables may be defined +to override the builtin defaults for file locations. +Note that use of the related command-line options +will ignore the corresponding environment variable settings. +.TP +.B PATH_DHCLIENT_CONF +The dhclient.conf configuration file. +.TP +.B PATH_DHCLIENT_DB +The dhclient.leases database. +.TP +.B PATH_DHCLIENT_PID +The dhclient PID file. +.TP +.B PATH_DHCLIENT_SCRIPT +The dhclient-script file. +.PP +.SH FILES +.B CLIENTBINDIR/dhclient-script, +.B ETCDIR/dhclient.conf, DBDIR/dhclient.leases, RUNDIR/dhclient.pid, +.B DBDIR/dhclient.leases~. +.SH SEE ALSO +dhcpd(8), dhcrelay(8), dhclient-script(8), dhclient.conf(5), +dhclient.leases(5), dhcp-eval(5). +.SH AUTHOR +.B dhclient(8) +has been written for Internet Systems Consortium +by Ted Lemon in cooperation with Vixie +Enterprises. To learn more about Internet Systems Consortium, +see +.B https://www.isc.org +To learn more about Vixie +Enterprises, see +.B http://www.vix.com. +.PP +This client was substantially modified and enhanced by Elliot Poger +for use on Linux while he was working on the MosquitoNet project at +Stanford. +.PP +The current version owes much to Elliot's Linux enhancements, but +was substantially reorganized and partially rewritten by Ted Lemon +so as to use the same networking framework that the Internet Systems +Consortium DHCP server uses. Much system-specific configuration code +was moved into a shell script so that as support for more operating +systems is added, it will not be necessary to port and maintain +system-specific configuration code to these operating systems - instead, +the shell script can invoke the native tools to accomplish the same +purpose. +.PP |