xref: /freebsd/sbin/dhclient/dhclient.8 (revision 4fdeb33466ead68cd25b2afec37f2efc7d1e34fe)
1.\" $OpenBSD: dhclient.8,v 1.3 2004/04/09 18:30:15 jmc Exp $
2.\"
3.\" Copyright (c) 1997 The Internet Software Consortium.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\"
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of The Internet Software Consortium nor the names
16.\"    of its contributors may be used to endorse or promote products derived
17.\"    from this software without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
20.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
21.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
22.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23.\" DISCLAIMED.  IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
24.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
27.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.\" This software has been written for the Internet Software Consortium
34.\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie
35.\" Enterprises.  To learn more about the Internet Software Consortium,
36.\" see ``http://www.isc.org/isc''.  To learn more about Vixie
37.\" Enterprises, see ``http://www.vix.com''.
38.\"
39.\" $FreeBSD$
40.\"
41.Dd August 17, 2006
42.Dt DHCLIENT 8
43.Os
44.Sh NAME
45.Nm dhclient
46.Nd "Dynamic Host Configuration Protocol (DHCP) client"
47.Sh SYNOPSIS
48.Nm
49.Op Fl bdpqu
50.Op Fl c Ar file
51.Op Fl l Ar file
52.Ar interface
53.Sh DESCRIPTION
54The
55.Nm
56utility provides a means for configuring network interfaces using DHCP, BOOTP,
57or if these protocols fail, by statically assigning an address.
58.Pp
59The name of the network interface that
60.Nm
61should attempt to
62configure must be specified on the command line.
63.Pp
64The options are as follows:
65.Bl -tag -width ".Fl c Ar file"
66.It Fl b
67Forces
68.Nm
69to immediately move to the background.
70.It Fl c Ar file
71Specify an alternate location,
72.Ar file ,
73for the configuration file.
74.It Fl d
75Forces
76.Nm
77to always run as a foreground process.
78By default,
79.Nm
80runs in the foreground until it has configured the interface, and then
81will revert to running in the background.
82.It Fl l Ar file
83Specify an alternate location,
84.Ar file ,
85for the leases file.
86.It Fl p
87Tells
88.Nm
89to persist in trying to configure the interface, despite
90an inability to gain carrier.
91This is used to survive switch outages and when
92.Nm
93is required as soon as the cable is connected.
94.It Fl q
95Forces
96.Nm
97to be less verbose on startup.
98.It Fl u
99Forces
100.Nm
101to reject leases with unknown options in them.
102The default behaviour is to accept such lease offers.
103.El
104.Pp
105The DHCP protocol allows a host to contact a central server which
106maintains a list of IP addresses which may be assigned on one or more
107subnets.
108A DHCP client may request an address from this pool, and
109then use it on a temporary basis for communication on the network.
110The DHCP protocol also provides a mechanism whereby a client can learn
111important details about the network to which it is attached, such as
112the location of a default router, the location of a name server, and
113so on.
114.Pp
115On startup,
116.Nm
117reads
118.Pa /etc/dhclient.conf
119for configuration instructions.
120It then gets a list of all the
121network interfaces that are configured in the current system.
122It then attempts to configure each interface with DHCP.
123.Pp
124In order to keep track of leases across system reboots and server
125restarts,
126.Nm
127keeps a list of leases it has been assigned in the
128.Pa /var/db/dhclient.leases. Ns Ar IFNAME
129file.
130.Ar IFNAME
131represents the network interface of the DHCP client
132(e.g.,
133.Li em0 ) ,
134one for each interface.
135On startup, after reading the
136.Xr dhclient.conf 5
137file,
138.Nm
139reads the leases file to refresh its memory about what leases it has been
140assigned.
141.Pp
142Old leases are kept around in case the DHCP server is unavailable when
143.Nm
144is first invoked (generally during the initial system boot
145process).
146In that event, old leases from the
147.Pa dhclient.leases. Ns Ar IFNAME
148file which have not yet expired are tested, and if they are determined to
149be valid, they are used until either they expire or the DHCP server
150becomes available.
151.Pp
152A mobile host which may sometimes need to access a network on which no
153DHCP server exists may be preloaded with a lease for a fixed
154address on that network.
155When all attempts to contact a DHCP server have failed,
156.Nm
157will try to validate the static lease, and if it
158succeeds, it will use that lease until it is restarted.
159.Pp
160A mobile host may also travel to some networks on which DHCP is not
161available but BOOTP is.
162In that case, it may be advantageous to
163arrange with the network administrator for an entry on the BOOTP
164database, so that the host can boot quickly on that network rather
165than cycling through the list of old leases.
166.Sh NOTES
167You must have the Berkeley Packet Filter (BPF) configured in your kernel.
168The
169.Nm
170utility
171requires at least one
172.Pa /dev/bpf*
173device for each broadcast network interface that is attached to your system.
174See
175.Xr bpf 4
176for more information.
177.Sh FILES
178.Bl -tag -width ".Pa /var/db/dhclient.leases. Ns Ar IFNAME" -compact
179.It Pa /etc/dhclient.conf
180DHCP client configuration file
181.It Pa /var/db/dhclient.leases. Ns Ar IFNAME
182database of acquired leases
183.El
184.Sh SEE ALSO
185.Xr dhclient.conf 5 ,
186.Xr dhclient.leases 5 ,
187.Xr dhclient-script 8 ,
188.Xr dhcp 8 ,
189.Xr dhcpd 8 ,
190.Xr dhcrelay 8
191.Sh AUTHORS
192.An -nosplit
193The
194.Nm
195utility
196was written by
197.An Ted Lemon Aq mellon@fugue.com
198and
199.An Elliot Poger Aq elliot@poger.com .
200.Pp
201The current implementation was reworked by
202.An Henning Brauer Aq henning@openbsd.org .
203