3b9e0e
.\"	dhclient.8
3b9e0e
.\"
3b9e0e
.\" Copyright (c) 2004,2007 by Internet Systems Consortium, Inc. ("ISC")
3b9e0e
.\" Copyright (c) 1996-2003 by Internet Software Consortium
3b9e0e
.\"
3b9e0e
.\" Permission to use, copy, modify, and distribute this software for any
3b9e0e
.\" purpose with or without fee is hereby granted, provided that the above
3b9e0e
.\" copyright notice and this permission notice appear in all copies.
3b9e0e
.\"
3b9e0e
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
3b9e0e
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
3b9e0e
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
3b9e0e
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
3b9e0e
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
3b9e0e
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
3b9e0e
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
3b9e0e
.\"
3b9e0e
.\"   Internet Systems Consortium, Inc.
3b9e0e
.\"   950 Charter Street
3b9e0e
.\"   Redwood City, CA 94063
3b9e0e
.\"   <info@isc.org>
3b9e0e
.\"   http://www.isc.org/
3b9e0e
.\"
3b9e0e
.\" Support and other services are available for ISC products - see
3b9e0e
.\" http://www.isc.org for more information.
3b9e0e
.\"
3b9e0e
.\" $Id: dhclient.8,v 1.18.116.4 2007/05/23 23:30:32 each Exp $
3b9e0e
.\"
3b9e0e
.TH dhclient 8
3b9e0e
.SH NAME
3b9e0e
dhclient - Dynamic Host Configuration Protocol Client
3b9e0e
.SH SYNOPSIS
3b9e0e
.B dhclient
3b9e0e
[
3b9e0e
.B -p
3b9e0e
.I port
3b9e0e
]
3b9e0e
[
3b9e0e
.B -d
3b9e0e
]
3b9e0e
[
3b9e0e
.B -e
3b9e0e
.I VAR=value
3b9e0e
]
3b9e0e
[
3b9e0e
.B -q
3b9e0e
]
3b9e0e
[
3b9e0e
.B -1
3b9e0e
]
3b9e0e
[
3b9e0e
.B -r
3b9e0e
]
3b9e0e
[
3b9e0e
.B -x
3b9e0e
]
3b9e0e
[
3b9e0e
.B -lf
3b9e0e
.I lease-file
3b9e0e
]
3b9e0e
[
3b9e0e
.B -pf
3b9e0e
.I pid-file
3b9e0e
]
3b9e0e
[
3b9e0e
.B -cf
3b9e0e
.I config-file
3b9e0e
]
3b9e0e
[
3b9e0e
.B -sf
3b9e0e
.I script-file
3b9e0e
]
3b9e0e
[
3b9e0e
.B -s
3b9e0e
server
3b9e0e
]
3b9e0e
[
3b9e0e
.B -g
3b9e0e
relay
3b9e0e
]
3b9e0e
[
3b9e0e
.B -n
3b9e0e
]
3b9e0e
[
3b9e0e
.B -nw
3b9e0e
]
3b9e0e
[
3b9e0e
.B -w
3b9e0e
]
3b9e0e
[
3b9e0e
.B -B
3b9e0e
]
3b9e0e
[
3b9e0e
.B -I
3b9e0e
.I dhcp-client-identifier
3b9e0e
]
3b9e0e
[
3b9e0e
.B -H
3b9e0e
.I host-name
3b9e0e
.R |
3b9e0e
.B -F fqdn.fqdn
3b9e0e
]
3b9e0e
[
3b9e0e
.B -V
3b9e0e
.I vendor-class-identifier
3b9e0e
]
3b9e0e
[
3b9e0e
.B -R
3b9e0e
.I request option list
3b9e0e
]
3b9e0e
[
3b9e0e
.B -T
3b9e0e
.I timeout
3b9e0e
]
3b9e0e
[
3b9e0e
.I if0
3b9e0e
[
3b9e0e
.I ...ifN
3b9e0e
]
3b9e0e
]
3b9e0e
.SH DESCRIPTION
3b9e0e
The Internet Systems Consortium DHCP Client, dhclient, provides a
3b9e0e
means for configuring one or more network interfaces using the Dynamic
3b9e0e
Host Configuration Protocol, BOOTP protocol, or if these protocols
3b9e0e
fail, by statically assigning an address.
3b9e0e
.SH OPERATION
3b9e0e
.PP
3b9e0e
The DHCP protocol allows a host to contact a central server which
3b9e0e
maintains a list of IP addresses which may be assigned on one or more
3b9e0e
subnets.   A DHCP client may request an address from this pool, and
3b9e0e
then use it on a temporary basis for communication on network.   The
3b9e0e
DHCP protocol also provides a mechanism whereby a client can learn
3b9e0e
important details about the network to which it is attached, such as
3b9e0e
the location of a default router, the location of a name server, and
3b9e0e
so on.
3b9e0e
.PP
3b9e0e
On startup, dhclient reads the
3b9e0e
.IR dhclient.conf
3b9e0e
for configuration instructions.   It then gets a list of all the
3b9e0e
network interfaces that are configured in the current system.   For
3b9e0e
each interface, it attempts to configure the interface using the DHCP
3b9e0e
protocol.
3b9e0e
.PP
3b9e0e
In order to keep track of leases across system reboots and server
3b9e0e
restarts, dhclient keeps a list of leases it has been assigned in the
3b9e0e
dhclient.leases(5) file.   On startup, after reading the dhclient.conf
3b9e0e
file, dhclient reads the dhclient.leases file to refresh its memory
3b9e0e
about what leases it has been assigned.
3b9e0e
.PP
3b9e0e
When a new lease is acquired, it is appended to the end of the
3b9e0e
dhclient.leases file.   In order to prevent the file from becoming
3b9e0e
arbitrarily large, from time to time dhclient creates a new
3b9e0e
dhclient.leases file from its in-core lease database.  The old version
3b9e0e
of the dhclient.leases file is retained under the name
3b9e0e
.IR dhclient.leases~
3b9e0e
until the next time dhclient rewrites the database.
3b9e0e
.PP
3b9e0e
Old leases are kept around in case the DHCP server is unavailable when
3b9e0e
dhclient is first invoked (generally during the initial system boot
3b9e0e
process).   In that event, old leases from the dhclient.leases file
3b9e0e
which have not yet expired are tested, and if they are determined to
3b9e0e
be valid, they are used until either they expire or the DHCP server
3b9e0e
becomes available.
3b9e0e
.PP
3b9e0e
A mobile host which may sometimes need to access a network on which no
3b9e0e
DHCP server exists may be preloaded with a lease for a fixed
3b9e0e
address on that network.   When all attempts to contact a DHCP server
3b9e0e
have failed, dhclient will try to validate the static lease, and if it
3b9e0e
succeeds, will use that lease until it is restarted.
3b9e0e
.PP
3b9e0e
A mobile host may also travel to some networks on which DHCP is not
3b9e0e
available but BOOTP is.   In that case, it may be advantageous to
3b9e0e
arrange with the network administrator for an entry on the BOOTP
3b9e0e
database, so that the host can boot quickly on that network rather
3b9e0e
than cycling through the list of old leases.
3b9e0e
.PP
3b9e0e
The names of the network interfaces that dhclient should attempt to
3b9e0e
configure may be specified on the command line.  If no interface names
3b9e0e
are specified on the command line dhclient will normally identify all
3b9e0e
network interfaces, eliminating non-broadcast interfaces if
3b9e0e
possible, and attempt to configure each interface.
3b9e0e
.PP
3b9e0e
It is also possible to specify interfaces by name in the
3b9e0e
.B dhclient.conf(5)
3b9e0e
file.   If interfaces are specified in this way, then the client will
3b9e0e
only configure interfaces that are either specified in the
3b9e0e
configuration file or on the command line, and will ignore all other
3b9e0e
interfaces.
3b9e0e
.SH OPTIONS
3b9e0e
.TP
3b9e0e
.BI \-p\ <port\ number="">
3b9e0e
The UDP port number the DHCP client should listen and transmit on.  If
3b9e0e
unspecified,
3b9e0e
.B dhclient
3b9e0e
uses the default port 68.  This option is mostly useful for debugging
3b9e0e
purposes.  If a different port is specified for the client to listen and
3b9e0e
transmit on, the client will also use a different destination port - one
3b9e0e
greater than the specified destination port.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-d
3b9e0e
Force
3b9e0e
.B dhclient
3b9e0e
to run as a foreground process.  This is useful when running the client
3b9e0e
under a debugger, or when running it out of inittab on System V systems.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-e\ VAR=value
3b9e0e
Define additional environment variables for the environment where
3b9e0e
dhclient-script executes.  You may specify multiple
3b9e0e
.B \-e
3b9e0e
options on the command line.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-q
3b9e0e
Suppress all terminal and log output except error messages.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-1
3b9e0e
Try one to get a lease.  On failure, exit with code 2.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-r
3b9e0e
Tell
3b9e0e
.B dhclient
3b9e0e
to release the current lease it has from the server.  This is not required
3b9e0e
by the DHCP protocol, but some ISPs require their clients to notify the
3b9e0e
server if they wish to release an assigned IP address.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-lf\ <lease-file>
3b9e0e
Path to the lease database file.  If unspecified, the default
3b9e0e
.B DBDIR/dhclient.leases
3b9e0e
is used.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-pf\ <pid-file>
3b9e0e
Path to the process ID file.  If unspecified, the default
3b9e0e
.B RUNDIR/dhclient.pid
3b9e0e
is used.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-cf\ <config-file>
3b9e0e
Path to the client configuration file.  If unspecified, the default
3b9e0e
.B ETCDIR/dhclient.conf
3b9e0e
is used.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-sf\ <script-file>
3b9e0e
Path to the network configuration script invoked by
3b9e0e
.B dhclient
3b9e0e
when it gets a lease.  If unspecified, the default
3b9e0e
.B CLIENTBINDIR/dhclient-script
3b9e0e
is used.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-s\ <server>
3b9e0e
Specifiy the server IP address or fully qualified domain name to transmit
3b9e0e
DHCP protocol messages to.  Normally,
3b9e0e
.B dhclient
3b9e0e
transmits these messages to 255.255.255.255 (the IP limited broadcast
3b9e0e
address).  Overriding this is mostly useful for debugging purposes.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-g\ <relay>
3b9e0e
Only for debugging.  Set the giaddr field of all packets the client
3b9e0e
sends to the IP address specified.  This should not be expected to work
3b9e0e
in any consistent or useful way.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-n
3b9e0e
Do not configure any interfaces.  Most useful combined with the
3b9e0e
.B -w
3b9e0e
option.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-nw
3b9e0e
Become a daemon process immediately (nowait) rather than waiting until an IP
3b9e0e
address has been acquired.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-w
3b9e0e
Keep running even if no network interfaces are found.  The
3b9e0e
.B omshell
3b9e0e
program can be used to notify the client when a network interface has been
3b9e0e
added or removed so it can attempt to configure an IP address on that
3b9e0e
interface.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-B
3b9e0e
Set the BOOTP broadcast flag in request packets so servers will always
3b9e0e
broadcast replies.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-I\ <dhcp-client-identifier>
3b9e0e
Specify the dhcp-client-identifier option to send to the DHCP server.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-H\ <host-name>
3b9e0e
Specify the host-name option to send to the DHCP server.  The host-name
3b9e0e
string only contains the client's hostname prefix, to which the server will
3b9e0e
append the ddns-domainname or domain-name options, if any, to derive the
3b9e0e
fully qualified domain name of the client.  The
3b9e0e
.B -H
3b9e0e
option cannot be used with the
3b9e0e
.B -F
3b9e0e
option.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-F\ <fqdn.fqdn>
3b9e0e
Specify the fqdn.fqdn option to send to the DHCP server.  This option cannot
3b9e0e
be used with the
3b9e0e
.B -H
3b9e0e
option.  The fqdn.fqdn option must specify the complete domain name of the
3b9e0e
client host, which the server may use for dynamic DNS updates.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-V\ <vendor-class-identifier>
3b9e0e
Specify the vendor-class-identifier option to send to the DHCP server.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-R\ <option>[,<option>...]
3b9e0e
Specify the list of options the client is to request from the server.  The
3b9e0e
option list must be a single string consisting of option names separated
3b9e0e
by at least one command and optional space characters.  The default option
3b9e0e
list is:
3b9e0e
3b9e0e
.BR
3b9e0e
    subnet-mask, broadcast-address, time-offset, routers,
3b9e0e
.BR
3b9e0e
    domain-name, domain-name-servers, host-name, nis-domain,
3b9e0e
.BR
3b9e0e
    nis-servers, ntp-servers
3b9e0e
3b9e0e
The
3b9e0e
.B -R
3b9e0e
option does not append options to the default request, it overrides the
3b9e0e
default request list.  Keep this in mind if you want to request an
3b9e0e
additional option besides the default request list.  You will have to
3b9e0e
specify all option names for the
3b9e0e
.B -R
3b9e0e
parameter.
3b9e0e
3b9e0e
.TP
3b9e0e
.BI \-T\ <timeout>
3b9e0e
Specify the time after which
3b9e0e
.B dhclient
3b9e0e
will decide that no DHCP servers can be contacted when no responses have been
3b9e0e
received.
3b9e0e
3b9e0e
.PP
3b9e0e
If the client is killed by a signal (for example at shutdown or reboot)
3b9e0e
it won't execute the
3b9e0e
.B dhclient-script (8)
3b9e0e
at exit. However if you shut the client down gracefully with
3b9e0e
.B -r
3b9e0e
or
3b9e0e
.B -x
3b9e0e
it will execute
3b9e0e
.B dhclient-script (8)
3b9e0e
at shutdown with the specific reason for calling the script set.
3b9e0e
3b9e0e
.PP
3b9e0e
.SH CONFIGURATION
3b9e0e
The syntax of the dhclient.conf(5) file is discussed separately.
3b9e0e
.SH OMAPI
3b9e0e
The DHCP client provides some ability to control it while it is
3b9e0e
running, without stopping it.  This capability is provided using OMAPI,
3b9e0e
an API for manipulating remote objects.  OMAPI clients connect to the
3b9e0e
client using TCP/IP, authenticate, and can then examine the client's
3b9e0e
current status and make changes to it. 
3b9e0e
.PP
3b9e0e
Rather than implementing the underlying OMAPI protocol directly, user
3b9e0e
programs should use the dhcpctl API or OMAPI itself.   Dhcpctl is a
3b9e0e
wrapper that handles some of the housekeeping chores that OMAPI does
3b9e0e
not do automatically.   Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR
3b9e0e
and \fBomapi(3)\fR.   Most things you'd want to do with the client can
3b9e0e
be done directly using the \fBomshell(1)\fR command, rather than
3b9e0e
having to write a special program.
3b9e0e
.SH THE CONTROL OBJECT
3b9e0e
The control object allows you to shut the client down, releasing all
3b9e0e
leases that it holds and deleting any DNS records it may have added.
3b9e0e
It also allows you to pause the client - this unconfigures any
3b9e0e
interfaces the client is using.   You can then restart it, which
3b9e0e
causes it to reconfigure those interfaces.   You would normally pause
3b9e0e
the client prior to going into hibernation or sleep on a laptop
3b9e0e
computer.   You would then resume it after the power comes back.
3b9e0e
This allows PC cards to be shut down while the computer is hibernating
3b9e0e
or sleeping, and then reinitialized to their previous state once the
3b9e0e
computer comes out of hibernation or sleep.
3b9e0e
.PP
3b9e0e
The control object has one attribute - the state attribute.   To shut
3b9e0e
the client down, set its state attribute to 2.   It will automatically
3b9e0e
do a DHCPRELEASE.   To pause it, set its state attribute to 3.   To
3b9e0e
resume it, set its state attribute to 4.
3b9e0e
.PP
3b9e0e
.SH FILES
3b9e0e
.B CLIENTBINDIR/dhclient-script,
3b9e0e
.B ETCDIR/dhclient.conf, DBDIR/dhclient.leases, RUNDIR/dhclient.pid,
3b9e0e
.B DBDIR/dhclient.leases~.
3b9e0e
.SH SEE ALSO
3b9e0e
dhcpd(8), dhcrelay(8), dhclient-script(8), dhclient.conf(5),
3b9e0e
dhclient.leases(5), dhcp-eval(5).
3b9e0e
.SH AUTHOR
3b9e0e
.B dhclient(8)
3b9e0e
has been written for Internet Systems Consortium
3b9e0e
by Ted Lemon in cooperation with Vixie
3b9e0e
Enterprises.  To learn more about Internet Systems Consortium,
3b9e0e
see
3b9e0e
.B http://www.isc.org
3b9e0e
To learn more about Vixie
3b9e0e
Enterprises, see
3b9e0e
.B http://www.vix.com.
3b9e0e
.PP
3b9e0e
This client was substantially modified and enhanced by Elliot Poger
3b9e0e
for use on Linux while he was working on the MosquitoNet project at
3b9e0e
Stanford.
3b9e0e
.PP
3b9e0e
The current version owes much to Elliot's Linux enhancements, but
3b9e0e
was substantially reorganized and partially rewritten by Ted Lemon
3b9e0e
so as to use the same networking framework that the Internet Systems
3b9e0e
Consortium DHCP server uses.   Much system-specific configuration code
3b9e0e
was moved into a shell script so that as support for more operating
3b9e0e
systems is added, it will not be necessary to port and maintain
3b9e0e
system-specific configuration code to these operating systems - instead,
3b9e0e
the shell script can invoke the native tools to accomplish the same
3b9e0e
purpose.
3b9e0e
.PP