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