xref: /freebsd/sbin/dhclient/dhclient.8 (revision 9341e8dd887b66af8f879981f4acb194ff611372)
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 July 22, 2005
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 dhclient to persist in trying to configure the interface, despite
88an inability to gain carrier.
89This is used to survive switch outages and when dhclient is required as
90soon as the cable is connected.
91.It Fl q
92Forces
93.Nm
94to be less verbose on startup.
95.It Fl u
96Forces
97.Nm
98to reject leases with unknown options in them.
99The default behaviour is to accept such lease offers.
100.El
101.Pp
102The DHCP protocol allows a host to contact a central server which
103maintains a list of IP addresses which may be assigned on one or more
104subnets.
105A DHCP client may request an address from this pool, and
106then use it on a temporary basis for communication on the network.
107The DHCP protocol also provides a mechanism whereby a client can learn
108important details about the network to which it is attached, such as
109the location of a default router, the location of a name server, and
110so on.
111.Pp
112On startup,
113.Nm
114reads
115.Pa /etc/dhclient.conf
116for configuration instructions.
117It then gets a list of all the
118network interfaces that are configured in the current system.
119It then attempts to configure each interface with DHCP.
120.Pp
121In order to keep track of leases across system reboots and server
122restarts,
123.Nm
124keeps a list of leases it has been assigned in the
125.Pa /var/db/dhclient.leases. Ns Ar IFNAME
126file.
127.Ar IFNAME
128represents the network interface of the DHCP client
129(e.g.,
130.Li em0 ) ,
131one for each interface.
132On startup, after reading the
133.Xr dhclient.conf 5
134file,
135.Nm
136reads the leases file to refresh its memory about what leases it has been
137assigned.
138.Pp
139Old leases are kept around in case the DHCP server is unavailable when
140.Nm
141is first invoked (generally during the initial system boot
142process).
143In that event, old leases from the
144.Pa dhclient.leases. Ns Ar IFNAME
145file which have not yet expired are tested, and if they are determined to
146be valid, they are used until either they expire or the DHCP server
147becomes available.
148.Pp
149A mobile host which may sometimes need to access a network on which no
150DHCP server exists may be preloaded with a lease for a fixed
151address on that network.
152When all attempts to contact a DHCP server have failed,
153.Nm
154will try to validate the static lease, and if it
155succeeds, it will use that lease until it is restarted.
156.Pp
157A mobile host may also travel to some networks on which DHCP is not
158available but BOOTP is.
159In that case, it may be advantageous to
160arrange with the network administrator for an entry on the BOOTP
161database, so that the host can boot quickly on that network rather
162than cycling through the list of old leases.
163.Sh NOTES
164You must have the Berkeley Packet Filter (BPF) configured in your kernel.
165The
166.Nm
167utility
168requires at least one
169.Pa /dev/bpf*
170device for each broadcast network interface that is attached to your system.
171See
172.Xr bpf 4
173for more information.
174.Sh FILES
175.Bl -tag -width ".Pa /var/db/dhclient.leases. Ns Ar IFNAME" -compact
176.It Pa /etc/dhclient.conf
177DHCP client configuration file
178.It Pa /var/db/dhclient.leases. Ns Ar IFNAME
179database of acquired leases
180.El
181.Sh SEE ALSO
182.Xr dhclient.conf 5 ,
183.Xr dhclient.leases 5 ,
184.Xr dhclient-script 8 ,
185.Xr dhcp 8 ,
186.Xr dhcpd 8 ,
187.Xr dhcrelay 8
188.Sh AUTHORS
189.An -nosplit
190The
191.Nm
192utility
193was written by
194.An Ted Lemon Aq mellon@fugue.com
195and
196.An Elliot Poger Aq elliot@poger.com .
197.Pp
198The current implementation was reworked by
199.An Henning Brauer Aq henning@openbsd.org .
200