| blob | da9e5ebe3a59a212691dba2dfb8ba4421c9554b7 |
1 .TH DHCP.CONF 5
2 .SH NAME
3 dhcp.conf \- dynamic host configuration protocol configuration
4 .SH SYNOPSIS
5 .B /etc/dhcp.conf
6 .SH DESCRIPTION
7 .de SP
8 .if t .sp 0.4
9 .if n .sp
10 ..
11 The file
12 .B /etc/dhcp.conf
13 contains the configuration for the DHCP client/server program
14 .BR dhcpd .
15 This text is a long summation of all the elements that can be found in this
16 configuration file. For a more "just tell me what to do" approach see
17 .BR boot (8).
18 .PP
19 The syntax used is that of the common configuration file described in
20 .BR configfile (5).
21 .PP
22 To find information for a client we first need its IP address. Occasionally
23 this IP address is already known (the special "INFORM" query), but normally
24 we have to make a first pass through the configuration file for a
25 .B client
26 entry. If that fails then we use an IP address from the pool file. If we
27 now have an IP address then the real information gathering can begin.
28 .PP
29 The DHCP daemon reads the configuration file from beginning to end and
30 gathers all information that matches, and information from all macros that
31 are mentioned within the elements that match. If we end up with DHCP
32 information that includes at least a netmask definition, and is good for the
33 network the request came in from, then it is returned to the client. If a
34 DHCP tag is specified twice then the last one wins.
35 .PP
36 In the description below we use [ and ] to denote optional things, and | to
37 show a choice between two things.
38 .PP
39 Client IDs can be either ordinary Ethernet addresses, that are treated as a
40 seven octet string (01 followed by the Ethernet address), or any random
41 octet string in hexadecimal.
42 .PP
43 IP addresses can be simply that, or host names. These host names are
44 searched in
45 .B /etc/hosts
46 by
47 .B dhcpd
48 itself using a domain based prefix match, i.e. you can use "flotsam" for
49 "flotsam.example.com", but not "alpha" for "alphabeta". Once the program
50 decides to be a server it will also look up names normally in the DNS.
51 If a host has more than one IP address then the address on the network the
52 query was seen on is used.
53 .PP
54 Case isn't important in the configuration file, "client", "CLIENT" and
55 "ClIeNt" are all treated the same.
56 .PP
57 Some elements may optionally name a macro or a curly braces enclosed
58 parameter list of more elements. If the element matches then the data
59 in the macro body or parameter list is gathered.
60 .PP
61 The following elements can be used:
62 .PP
63 .B client
64 .I client-ID
65 .RB [ ip #]
66 .I host
67 .RI [ macro |{ params }];
68 .PP
69 .RS
70 Defines a client with a given client ID that is to have the IP address
71 denoted by
72 .I host .
73 On the first pass only the client ID is matched looking for an IP address
74 that lies on the network the request came in on. On the
75 information gathering pass both client ID and IP address must match. If
76 a machine has the same Ethernet address on two or more interfaces then the
77 IP address given out is the one on the same network as the request came in
78 on. The optional interface name
79 .RB ( ip #)
80 must be used if the DHCP daemon is gathering data for itself at boot time
81 to differentiate interfaces with the same ethernet addresses. This is
82 only necessary under Minix-vmd when ethernets on different VLANs share
83 the same physical ethernet. The interface name is only used for a machine's
84 own networks, it ignored on entries for other hosts.
85 .RE
86 .PP
87 .B class
88 .IR class-name " ..."
89 .IR macro |{ params };
90 .PP
91 .RS
92 Includes the macro or parameters if one of the class names is matched. A
93 host normally includes a class ID in its request. MINIX 3 and Minix-vmd
94 use "Minix" as the class name. For Windows the class ID starts with
95 "MSFT", and Solaris' starts with "SUNW".
96 (Use
97 .B dhcpd \-d3
98 to find out what the full IDs are exactly.) The class names are matched if a
99 .I class-name
100 is a prefix of the class ID sent by the client.
101 .RE
102 .PP
103 .B host
104 .I host-spec
105 .IR macro |{ params };
106 .PP
107 .RS
108 Includes the macro or parameters if the IP address of the client matches the
109 host specification. This can either be an ordinary hostname, or a netblock
110 in CIDR notation, e.g. 172.35.0.0/16. The example includes all IP addresses
111 whose top 16 bits are the same as the top 16 bits of 172.35.0.0. Such a
112 netblock automatically defines a netmask (255.255.0.0 in the example) if no
113 netmask has been specified yet.
114 .RE
115 .PP
116 .B interface
117 .BR ip #
118 .I host
119 .RI [ macro |{ params }];
120 .PP
121 .RS
122 Makes
123 .B dhcpd
124 set the IP address of interface
125 .BR ip #
126 (where # is a number) to the IP address denoted by
127 .IR host .
128 This element should only be used for interfaces that are not true Ethernets,
129 and so do not have a unique Ethernet address that can be used for a client
130 element. If the machine has at least one true Ethernet then all interface
131 elements should be added to the parameter list of a host or client element
132 for that Ethernet interface. This binds them to that machine and allows a
133 single configuration file to be shared among machines. Especially a server
134 should never have "free" interface elements. The macro or parameters are
135 only evaluated if data is gathered for the given interface. (Note that they
136 will be hidden by a client element for another interface.)
137 .RE
138 .PP
139 .B macro
140 .IR macro-name ;
141 .PP
142 .RS
143 Include the parameter list of the macro named
144 .I macro-name
145 defined elsewhere. (This means that "host flotsam stuff" is just short
146 for "host flotsam { macro stuff; }".)
147 .RE
148 .PP
149 .B macro
150 .I macro-name
151 .RI { params };
152 .PP
153 .RS
154 Defines a macro with the given parameter list. Whenever the macro is used
155 the parameter list is substituted instead. A macro can not be defined
156 within another parameter list.
157 .RE
158 .PP
159 .B option
160 .RB [ ip #]
161 .B server
162 .RB [ inform ];
163 .br
164 .B option
165 .RB [ ip #]
166 .B relay
167 .IR host ;
168 .br
169 .B option
170 .RB [ ip #]
171 .BR possessive ;
172 .br
173 .B option
174 .RB [ ip #]
175 .B hostname
176 .IR name ;
177 .PP
178 .RS
179 Makes
180 .B dhcpd
181 set special options for the interface that it is gathering data for, or the
182 interface denoted by the optional
183 .BR ip #
184 argument. The options are:
185 .SP
186 .B server
187 .RB [ inform ]
188 .RS
189 Be a DHCP server on the network connected to the interface. Add the word
190 .B inform
191 if DHCPINFORM requests must be answered for hosts we don't have an address
192 for.
193 .RE
194 .SP
195 .B relay
196 .I host
197 .RS
198 Be a DHCP relay to the indicated host.
199 .RE
200 .SP
201 .B possessive
202 .RS
203 Do not disable the interface if the DHCP lease expires. Useful if the
204 DHCP server of the provider is unreliable, crashing a lot and causing the
205 lease to expire. (Think twice before turning this option on. You have to
206 be absolutely sure that it's the DHCP server that's the culprit and not
207 a flaky network. You don't want an IP address conflict to be your fault.)
208 .RE
209 .SP
210 .B hostname
211 .I name
212 .RS
213 Use the given name as our hostname in the DHCP queries. Some sites key on
214 that bit of information instead of a client ID.
215 .RE
216 .RE
217 .PP
218 .B tag
219 .I number name type granularity
220 .IR max ;
221 .PP
222 .RS
223 Defines a DHCP tag for the given tag number and gives it a name. The name can
224 be used in the configuration file to set tag values when gathering data.
225 The
226 .I type
227 field can be one of
228 .BR ascii ,
229 .BR boolean ,
230 .BR ip ,
231 .BR number
232 or
233 .BR octet
234 to specify the type of the tag as a simple string, a boolean, an IP address,
235 a number, or a string of octet values.
236 The
237 .I granularity
238 field specifies that that number of items must be given or a multiple
239 thereof, unless the type is a number, then it is the size of the number (1,
240 2 or 4).
241 The
242 .I max
243 field tells the maximum number of items that may be used with the tag, with
244 0 meaning "unlimited".
245 .SP
246 Three tags, the ones that MINIX 3 really cares about, have been predefined,
247 and there are also a few pseudotags predefined for the static fields in a
248 DHCP packet that one may want to set:
249 .SP
250 .RS
251 .nf
252 tag ? siaddr ip 1 1;
253 tag ? sname ascii 1 64;
254 tag ? file ascii 1 128;
255 tag 1 netmask ip 1 1;
256 tag 3 gateway ip 1 0;
257 tag 6 DNSserver ip 1 0;
258 .fi
259 .RE
260 .SP
261 The file
262 .B /usr/etc/dhcptags.conf
263 contains tag definitions for all standard DHCP tags. It is wise to include
264 this file at the top of any DHCP configuration file.
265 .RE
266 .PP
267 .B no
268 .IR tag-name ;
269 .PP
270 .RS
271 Removes a tag with the given name from the data gathered at this point.
272 Useful if one host is different from all others, for instance if it doesn't
273 need a gateway definition, because it happens to be the gateway.
274 .RE
275 .PP
276 .IR "ascii-tag string" ;
277 .PP
278 .RS
279 Adds an ASCII tag to the gathered data. The string can be a simple word, or
280 a quoted string.
281 .RE
282 .PP
283 .I boolean-tag
284 .BR false | true ;
285 .PP
286 .RS
287 Set a boolean tag to be false or true. (Encoded as a octet of value 0 or 1.
288 Note that if you prefer to use 0 or 1 instead of false or true then you can
289 define a boolean tag as a size 1 number instead.)
290 .RE
291 .PP
292 .IR "ip-tag host" " ...;"
293 .PP
294 .RS
295 Sets a tag that needs one or more IP addresses. The host names are
296 translated as usual. To make it easier to specify netmasks one can use a
297 slash followed by a number, e.g.
298 .BR "netmask /27" ,
299 which is a handy alternative for
300 .BR "netmask 255.255.255.224" .
301 .RE
302 .PP
303 .IR "number-tag number" " ...;"
304 .PP
305 .RS
306 Set a number tag.
307 .RE
308 .PP
309 .IR "octet-tag hexdigits" ;
310 .PP
311 .RS
312 Set an octet string tag.
313 .I Hexdigits
314 is a series of hexadecimal digits that are two by two used to set the
315 octets.
316 .RE
317 .PP
318 .SH EXAMPLE
319 As an example the DHCP configuration used by the author of this document is
320 included. His network at home consists of a number of PCs, an ISDN router
321 named rhone and a PC named saone serving as router/tunnel to/via a cable
322 ISP. Both the rhone and the saone connect the home net to the network of
323 the Vrije Universiteit, but the rhone is only active if the cable doesn't
324 work.
325 .PP
326 The saone is a DHCP server, and one of the ordinary PCs is a backup DHCP
327 server. Both use the same configuration file, which is added below, with
328 extra commentary introduced by
329 .B ##
330 at a deeper indent level:
331 .RS
332 .de xS \" Example start
333 .sp
334 .nf
335 .ft C
336 ..
337 .de xE \" Example end
338 .fi
339 .ft R
340 ..
341 .de cS \" Commentary start
342 .sp
343 .in +12m
344 .ti -\w'## 'u
345 ##\ \c
346 ..
347 .de cE \" Commentary end
348 .in -12m
349 ..
350 .xS
351 .ta +8m +16m
352 include /usr/etc/dhcptags.conf;
353 .xE
354 .cS
355 With the help of the tag definitions we can use tags like "DHCPlease".
356 .cE
357 .xS
358 host 130.37.102.64/27 {
359 DNSserver saone darask;
360 host 130.37.102.88/29 { DHCPlease 259200; }
361 };
362 .xE
363 .cS
364 This defines the network 130.37.102.64/27, with netmask 255.255.255.224
365 (implicit from the network definition). The DNS servers for this net are
366 saone and darask. A smaller subrange of addresses is used as an address
367 pool on the saone, so a lease of 259200 seconds (3 days) is defined. The
368 netmask is still /27, as set by the outer network definition.
369 .cE
370 .xS
371 host 130.37.102.248/30 {};
372 .xE
373 .cS
374 A network of two addresses for routing tests.
375 .cE
376 .xS
377 host saone {
378 option server;
379 option ip1 possessive;
380 interface ip2 saone-net2;
381 DNSserver 130.37.24.3 130.37.24.6;
382 };
383 .xE
384 .cS
385 With the network definitions done we turn our attention to the hosts. Saone
386 is a DHCP server on its main interface. The second interface
387 .RB ( ip1 )
388 is connected to the cable modem. It gets its address from the cableco's
389 DHCP server, and if that server decides to go deaf then the saone keeps
390 the interface up ("possessive") even if the lease expires. The pseudo IP
391 interface
392 .B ip2
393 is set to the IP address of
394 .BR saone-net2 ,
395 one side of the encrypted tunnel over the cable to a Minix-vmd box at the VU.
396 The DNS servers specified override the default setting for the network, naming
397 two external servers at the VU that know the world.
398 .cE
399 .xS
400 host darask {
401 option server;
402 DNSserver saone;
403 class MINIX 3 { DNSserver saone 130.37.24.3 130.37.24.6; };
404 };
405 .xE
406 .cS
407 The darask is also a server, the backup for saone on the odd chance that it
408 is unavailable. It uses saone and the external name servers, but only
409 when it is running MINIX 3. When running Windows it only uses saone.
410 .cE
411 .xS
412 .ta +32m +16m
413 client 0:1:1b:a:68:ce darask; # NE2000
414 client 0:1:1b:a:77:23 burask; # NE2000
415 #lient 0:0:c0:b0:da:64 burask; # WD8013EWC
416 client 8:0:5a:38:b2:f finiah; # PCMCIA NE2000
417 client 0:0:c0:3a:12:10 bardelask; # WD8003
418 #lient 2:60:8c:ab:8a:6d bardelask; # 3C503
419 client 0:a0:c5:20:9:6d rhone;
420 client 0:1:1b:a:4c:3b saone; # NE2000
421 #lient 0:0:c0:fb:2:6a saone-net1; # WD8013EWC
422 .xE
423 .cS
424 Lastly the ethernet addresses of all the hosts are listed, so that they can
425 be translated to IP addresses. The lines that are commented out are for
426 extra network cards that are currently unused. The last is used to connect
427 to the cable modem, so it's only here because it's nice to have the ethernet
428 address written down somewhere.
429 .cE
430 .RE
431 .PP
432 The host names shown above are translated by DHCP using this
433 .BR /etc/hosts :
434 .RS
435 .xS
436 .ta +\w'130.37.102.249mm'u
437 604800 %ttl
438 2419200 %stale
440 130.37.102.65 darask.kjb.upwind.org
441 130.37.102.66 burask.kjb.upwind.org
442 130.37.102.67 finiah.kjb.upwind.org
443 130.37.102.68 bardelask.kjb.upwind.org
444 130.37.102.69 roniah.kjb.upwind.org
446 130.37.102.70 saone.kjb.upwind.org
447 130.37.102.2 saone-net2.kjb.upwind.org
449 130.37.102.88 rhone.kjb.upwind.org
450 130.37.102.89 dyn89.kjb.upwind.org
451 130.37.102.90 dyn90.kjb.upwind.org
452 130.37.102.91 dyn91.kjb.upwind.org
453 130.37.102.92 dyn92.kjb.upwind.org
454 130.37.102.93 dyn93.kjb.upwind.org
455 130.37.102.94 dyn94.kjb.upwind.org
457 130.37.102.249 tst1.kjb.upwind.org
458 130.37.102.250 tst2.kjb.upwind.org
459 .xE
460 .RE
461 .SH FILES
462 .TP
463 .B /usr/etc/dhcptags.conf
464 A supplied list of standard tag definitions as per RFC-1533. (Well, the
465 tag numbers and their meaning are standard, the names are made up.)
466 .SH "SEE ALSO"
467 .BR RFC-2131 ,
468 .BR RFC-1533 ,
469 .BR configfile (5),
470 .BR hosts (5),
471 .BR boot (8),
472 .BR dhcpd (8).
473 .SH NOTES
474 The amount of memory
475 .B dhcpd
476 needs increases with the size of configuration file. MINIX 3 can
477 handle
478 .B dhcptags.conf
479 and a modest sized
480 .BR dhcp.conf .
481 You have to increase the stack size to accommodate more. (No problem under
482 Minix-vmd, of course.)
483 .SH NOTES
484 Items that are only necessary for a certain host should only be specified
485 for that host. Items for a whole network are best added to a netblock
486 specification. Use class elements for a certain type of host, and macros
487 for exceptions. Try to limit information as much as possibly to those hosts
488 that need it. (Don't go overboard. A MINIX 3 machine won't be bothered by a
489 few NetBIOS tags.)
490 .PP
491 DHCPINFORM requests should always be answered when being a server, but
492 J. Random Sysadmin trying to diagnose problems doesn't like it when little
493 MINIX 3 machines show up in a packet trace unexpectedly. It's best to be
494 inconspicuous on a network you don't own.
495 .SH BUGS
496 There are a few too many subtle mistakes one can make.
497 .SH AUTHOR
498 Kees J. Bot <kjb@cs.vu.nl>