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