]>
Commit | Line | Data |
---|---|---|
08fe7cdb TL |
1 | .\" dhcpd.8 |
2 | .\" | |
3 | .\" Copyright (c) 1995, 1996 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''. | |
ee0cda4d TL |
38 | .TH dhcpd 8 |
39 | .SH NAME | |
5e6b52dc | 40 | dhcpd - Dynamic Host Configuration Protocol Server |
ee0cda4d TL |
41 | .SH SYNOPSIS |
42 | .B dhcpd | |
43 | [ | |
44 | .B -p | |
45 | .I port | |
46 | ] | |
d27562c7 TL |
47 | [ |
48 | .B -f | |
49 | ] | |
50 | [ | |
5e6b52dc TL |
51 | .B -d |
52 | ] | |
53 | [ | |
e2ac5814 TL |
54 | .B -cf |
55 | .I config-file | |
56 | ] | |
57 | [ | |
58 | .B -lf | |
59 | .I lease-file | |
60 | ] | |
61 | [ | |
d27562c7 TL |
62 | .I if0 |
63 | [ | |
64 | .I ...ifN | |
65 | ] | |
66 | ] | |
ee0cda4d | 67 | .SH DESCRIPTION |
5e6b52dc TL |
68 | The Internet Software Consortium DHCP Server, dhcpd, implements the |
69 | Dynamic Host Configuration Protocol (DHCP) and the Internet Bootstrap | |
70 | Protocol (BOOTP). DHCP allows hosts on a TCP/IP network to request | |
71 | and be assigned IP addresses, and also to discover information about | |
72 | the network to which they are attached. BOOTP provides similar | |
73 | functionality, with certain restrictions. | |
ee0cda4d TL |
74 | .SH OPERATION |
75 | .PP | |
08fe7cdb TL |
76 | The DHCP protocol allows a host which is unknown to the network |
77 | administrator to be automatically assigned a new IP address out of a | |
78 | pool of IP addresses for its network. In order for this to work, the | |
79 | network administrator allocates address pools in each subnet and | |
ee0cda4d TL |
80 | enters them into the dhcpd.conf(5) file. |
81 | .PP | |
08fe7cdb | 82 | On startup, dhcpd reads the |
ee0cda4d | 83 | .IR dhcpd.conf |
5e6b52dc TL |
84 | file and stores a list of available addresses on each subnet in |
85 | memory. When a client requests an address using the DHCP protocol, | |
86 | dhcpd allocates an address for it. Each client is assigned a lease, | |
87 | which expires after an amount of time chosen by the administrator (by | |
88 | default, one day). Before leases expire, the clients to which leases | |
89 | are assigned are expected to renew them in order to continue to use | |
90 | the addresses. Once a lease has expired, the client to which that | |
91 | lease was assigned is no longer permitted to use the leased IP | |
92 | address. | |
ee0cda4d | 93 | .PP |
08fe7cdb | 94 | In order to keep track of leases across system reboots and server |
ee0cda4d TL |
95 | restarts, dhcpd keeps a list of leases it has assigned in the |
96 | dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it | |
97 | records the lease in this file and makes sure that the contents of the | |
98 | file are flushed to disk. This ensures that even in the event of a | |
99 | system crash, dhcpd will not forget about a lease that it has | |
100 | assigned. On startup, after reading the dhcpd.conf file, dhcpd | |
101 | reads the dhcpd.leases file to refresh its memory about what leases | |
102 | have been assigned. | |
103 | .PP | |
104 | New leases are appended to the end of the dhcpd.leases | |
08fe7cdb | 105 | file. In order to prevent the file from becoming arbitrarily large, |
ee0cda4d TL |
106 | from time to time dhcpd creates a new dhcpd.leases file from its |
107 | in-core lease database. Once this file has been written to disk, the | |
108 | old file is renamed | |
109 | .IR dhcpd.leases~ , | |
110 | and the new file is renamed dhcpd.leases. If the system crashes in | |
111 | the middle of this process, whichever dhcpd.leases file remains will | |
112 | contain all the lease information, so there is no need for a special | |
113 | crash recovery process. | |
114 | .PP | |
5e6b52dc TL |
115 | BOOTP support is also provided by this server. Unlike DHCP, the BOOTP |
116 | protocol does not provide a protocol for recovering | |
117 | dynamically-assigned addresses once they are no longer needed. It is | |
118 | still possible to dynamically assign addresses to BOOTP clients, but | |
119 | some administrative process for reclaiming addresses is required. By | |
120 | default, leases are granted to BOOTP clients in perpetuity, although | |
121 | the network administrator may set an earlier cutoff date or a shorter | |
122 | lease length for BOOTP leases if that makes sense. | |
123 | .PP | |
124 | BOOTP clients may also be served in the old standard way, which is to | |
125 | simply provide a declaration in the dhcpd.conf file for each | |
126 | BOOTP client, permanently assigning an address to each client. | |
ee0cda4d TL |
127 | .PP |
128 | Whenever changes are made to the dhcpd.conf file, dhcpd must be | |
129 | restarted. To restart dhcpd, send a SIGTERM (signal 15) to the | |
130 | process ID contained in | |
5e6b52dc TL |
131 | .IR RUNDIR/dhcpd.pid , |
132 | and then re-invoke dhcpd. Because the DHCP server database is not as | |
133 | lightweight as a BOOTP database, dhcpd does not automatically restart | |
134 | itself when it sees a change to the dhcpd.conf file. | |
4e19a6df TL |
135 | .PP |
136 | Note: We get a lot of complaints about this. We realize that it would | |
137 | be nice if one could send a SIGHUP to the server and have it reload | |
138 | the database. This is not technically impossible, but it would | |
139 | require a great deal of work, our resources are extremely limited, and | |
140 | they can be better spent elsewhere. So please don't complain about | |
141 | this on the mailing list unless you're prepared to fund a project to | |
142 | implement this feature, or prepared to do it yourself. | |
d27562c7 TL |
143 | .SH COMMAND LINE |
144 | .PP | |
5e6b52dc TL |
145 | The names of the network interfaces on which dhcpd should listen for |
146 | broadcasts may be specified on the command line. This should be done | |
147 | on systems where dhcpd is unable to identify non-broadcast interfaces, | |
148 | but should not be required on other systems. If no interface names | |
149 | are specified on the command line dhcpd will identify all network | |
150 | interfaces which are up, elimininating non-broadcast interfaces if | |
151 | possible, and listen for DHCP broadcasts on each interface. | |
d27562c7 | 152 | .PP |
5e6b52dc TL |
153 | If dhcpd should listen on a port other than the standard (port 67), |
154 | the | |
d27562c7 | 155 | .B -p |
5e6b52dc TL |
156 | flag may used. It should be followed by the udp port number on which |
157 | dhcpd should listen. This is mostly useful for debugging purposes. | |
d27562c7 | 158 | .PP |
5e6b52dc TL |
159 | To run dhcpd as a foreground process, rather than allowing it to run |
160 | as a daemon in the background, the | |
d27562c7 | 161 | .B -f |
5e6b52dc TL |
162 | flag should be specified. This is useful when running dhcpd under a |
163 | debugger, or when running it out of inittab on System V systems. | |
164 | .PP | |
165 | To have dhcpd log to the standard error descriptor, specify the | |
166 | .B -d | |
167 | flag. This can be useful for debugging, and also at sites where a | |
168 | complete log of all dhcp activity must be kept but syslogd is not | |
169 | reliable or otherwise cannot be used. Normally, dhcpd will log all | |
170 | output using the syslog(3) function with the log facility set to | |
171 | LOG_DAEMON. | |
e2ac5814 TL |
172 | .PP |
173 | Dhcpd can be made to use an alternate configuration file with the | |
174 | .B -cf | |
175 | flag, or an alternate lease file with the | |
176 | .B -lf | |
177 | flag. Because of the importance of using the same lease database at | |
178 | all times when running dhcpd in production, these options should be | |
179 | used \fBonly\fR for testing lease files or database files in a | |
180 | non-production environment. | |
ee0cda4d | 181 | .SH CONFIGURATION |
ba7ed239 | 182 | The syntax of the dhcpd.conf(5) file is discussed seperately. This |
ee0cda4d | 183 | section should be used as an overview of the configuration process, |
ba7ed239 | 184 | and the dhcpd.conf(5) documentation should be consulted for detailed |
ee0cda4d TL |
185 | reference information. |
186 | .PP | |
187 | .SH Subnets | |
188 | dhcpd needs to know the subnet numbers and netmasks of all subnets for | |
189 | which it will be providing service. In addition, in order to | |
190 | dynamically allocate addresses, it must be assigned one or more ranges | |
191 | of addresses on each subnet which it can in turn assign to client | |
192 | hosts as they boot. Thus, a very simple configuration providing DHCP | |
08fe7cdb TL |
193 | support might look like this: |
194 | .nf | |
195 | .sp 1 | |
5e6b52dc | 196 | subnet 239.252.197.0 netmask 255.255.255.0 { |
08fe7cdb | 197 | range 239.252.197.10 239.252.197.250; |
5e6b52dc | 198 | } |
08fe7cdb | 199 | .fi |
ee0cda4d | 200 | .PP |
08fe7cdb TL |
201 | Multiple address ranges may be specified like this: |
202 | .nf | |
203 | .sp 1 | |
5e6b52dc TL |
204 | subnet 239.252.197.0 netmask 255.255.255.0 { |
205 | range 239.252.197.10 239.252.197.107; | |
08fe7cdb | 206 | range 239.252.197.113 239.252.197.250; |
5e6b52dc | 207 | } |
08fe7cdb | 208 | .fi |
ee0cda4d | 209 | .PP |
08fe7cdb TL |
210 | If a subnet will only be provided with BOOTP service and no dynamic |
211 | address assignment, the range clause can be left out entirely, but the | |
212 | subnet statement must appear. | |
ee0cda4d TL |
213 | .PP |
214 | .SH Lease Lengths | |
08fe7cdb TL |
215 | DHCP leases can be assigned almost any length from zero seconds to |
216 | infinity. What lease length makes sense for any given subnet, or for | |
217 | any given installation, will vary depending on the kinds of hosts | |
218 | being served. | |
ee0cda4d | 219 | .PP |
08fe7cdb TL |
220 | For example, in an office environment where systems are added from |
221 | time to time and removed from time to time, but move relatively | |
222 | infrequently, it might make sense to allow lease times of a month of | |
223 | more. In a final test environment on a manufacturing floor, it may | |
224 | make more sense to assign a maximum lease length of 30 minutes - | |
225 | enough time to go through a simple test procedure on a network | |
226 | appliance before packaging it up for delivery. | |
ee0cda4d | 227 | .PP |
08fe7cdb TL |
228 | It is possible to specify two lease lengths: the default length that |
229 | will be assigned if a client doesn't ask for any particular lease | |
230 | length, and a maximum lease length. These are specified as clauses | |
231 | to the subnet command: | |
232 | .nf | |
233 | .sp 1 | |
5e6b52dc TL |
234 | subnet 239.252.197.0 netmask 255.255.255.0 { |
235 | range 239.252.197.10 239.252.197.107; | |
236 | default-lease-time 600; | |
08fe7cdb | 237 | max-lease-time 7200; |
5e6b52dc | 238 | | |
08fe7cdb | 239 | .fi |
ee0cda4d | 240 | .PP |
08fe7cdb TL |
241 | This particular subnet declaration specifies a default lease time of |
242 | 600 seconds (ten minutes), and a maximum lease time of 7200 seconds | |
243 | (two hours). Other common values would be 86400 (one day), 604800 | |
244 | (one week) and 2592000 (30 days). | |
ee0cda4d | 245 | .PP |
08fe7cdb TL |
246 | Each subnet need not have the same lease\(emin the case of an office |
247 | environment and a manufacturing environment served by the same DHCP | |
248 | server, it might make sense to have widely disparate values for | |
249 | default and maximum lease times on each subnet. | |
ee0cda4d TL |
250 | .SH BOOTP Support |
251 | Each BOOTP client must be explicitly declared in the dhcpd.conf | |
08fe7cdb TL |
252 | file. A very basic client declaration will specify the client |
253 | network interface's hardware address and the IP address to assign to | |
254 | that client. If the client needs to be able to load a boot file from | |
255 | the server, that file's name must be specified. A simple bootp | |
256 | client declaration might look like this: | |
257 | .nf | |
258 | .sp 1 | |
fc5aedc9 TL |
259 | host haagen { |
260 | hardware ethernet 08:00:2b:4c:59:23; | |
5e6b52dc | 261 | fixed-address 239.252.197.9; |
08fe7cdb | 262 | filename "/tftpboot/haagen.boot"; |
5e6b52dc | 263 | } |
08fe7cdb | 264 | .fi |
ee0cda4d | 265 | .SH Options |
08fe7cdb TL |
266 | DHCP (and also BOOTP with Vendor Extensions) provide a mechanism |
267 | whereby the server can provide the client with information about how | |
268 | to configure its network interface (e.g., subnet mask), and also how | |
269 | the client can access various network services (e.g., DNS, IP routers, | |
270 | and so on). | |
ee0cda4d | 271 | .PP |
08fe7cdb TL |
272 | These options can be specified on a per-subnet basis, and, for BOOTP |
273 | clients, also on a per-client basis. In the event that a BOOTP | |
274 | client declaration specifies options that are also specified in its | |
275 | subnet declaration, the options specified in the client declaration | |
276 | take precedence. An reasonably complete DHCP configuration might | |
277 | look something like this: | |
278 | .nf | |
279 | .sp 1 | |
5e6b52dc TL |
280 | subnet 239.252.197.0 netmask 255.255.255.0 { |
281 | range 239.252.197.10 239.252.197.250; | |
282 | default-lease-time 600 max-lease-time 7200; | |
283 | option subnet-mask 255.255.255.0; | |
284 | option broadcast-address 239.252.197.255; | |
285 | option routers 239.252.197.1; | |
286 | option domain-name-servers 239.252.197.2, 239.252.197.3; | |
08fe7cdb | 287 | option domain-name "isc.org"; |
5e6b52dc | 288 | } |
08fe7cdb | 289 | .fi |
ee0cda4d | 290 | .PP |
08fe7cdb TL |
291 | A bootp host on that subnet that needs to be in a different domain and |
292 | use a different name server might be declared as follows: | |
293 | .nf | |
294 | .sp 1 | |
ba7ed239 TL |
295 | host haagen { |
296 | hardware ethernet 08:00:2b:4c:59:23; | |
5e6b52dc TL |
297 | fixed-address 239.252.197.9; |
298 | filename "/tftpboot/haagen.boot"; | |
299 | option domain-name-servers 192.5.5.1; | |
08fe7cdb | 300 | option domain-name "vix.com"; |
5e6b52dc | 301 | } |
08fe7cdb | 302 | .fi |
ee0cda4d | 303 | .PP |
5e6b52dc TL |
304 | A more complete description of the dhcpd.conf file syntax is provided |
305 | in dhcpd.conf(5). | |
ee0cda4d TL |
306 | .SH FILES |
307 | .B ETCDIR/dhcpd.conf, DBDIR/dhcpd.leases, RUNDIR/dhcpd.pid, | |
308 | .B DBDIR/dhcpd.leases~. | |
309 | .SH SEE ALSO | |
66b01364 | 310 | dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5) |
ee0cda4d TL |
311 | .SH AUTHOR |
312 | .B dhcpd(8) | |
313 | was written by Ted Lemon <mellon@vix.com> | |
08fe7cdb TL |
314 | under a contract with Vixie Labs. Funding |
315 | for this project was provided by the Internet Software Corporation. | |
316 | Information about the Internet Software Consortium can be found at | |
ee0cda4d | 317 | .B http://www.isc.org/isc. |