Annotation of embedaddon/dhcp/server/dhcpd.8, revision 1.1.1.1
1.1 misho 1: .\" dhcpd.8
2: .\"
1.1.1.1 ! misho 3: .\" Copyright (c) 2009-2012 by Internet Systems Consortium, Inc. ("ISC")
1.1 misho 4: .\" Copyright (c) 2004-2007 by Internet Systems Consortium, Inc. ("ISC")
5: .\" Copyright (c) 1996-2003 by Internet Software Consortium
6: .\"
7: .\" Permission to use, copy, modify, and distribute this software for any
8: .\" purpose with or without fee is hereby granted, provided that the above
9: .\" copyright notice and this permission notice appear in all copies.
10: .\"
11: .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
12: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
14: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
17: .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18: .\"
19: .\" Internet Systems Consortium, Inc.
20: .\" 950 Charter Street
21: .\" Redwood City, CA 94063
22: .\" <info@isc.org>
23: .\" https://www.isc.org/
24: .\"
25: .\" This software has been written for Internet Systems Consortium
26: .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
27: .\"
28: .\" Support and other services are available for ISC products - see
29: .\" https://www.isc.org for more information or to learn more about ISC.
30: .\"
1.1.1.1 ! misho 31: .\" $Id: dhcpd.8,v 1.29.32.4.6.1 2011/04/15 22:26:21 sar Exp $
1.1 misho 32: .\"
33: .TH dhcpd 8
34: .SH NAME
35: dhcpd - Dynamic Host Configuration Protocol Server
36: .SH SYNOPSIS
37: .B dhcpd
38: [
39: .B -p
40: .I port
41: ]
42: [
43: .B -f
44: ]
45: [
46: .B -d
47: ]
48: [
49: .B -q
50: ]
51: [
52: .B -t
53: |
54: .B -T
55: ]
56: [
57: .B -4
58: |
59: .B -6
60: ]
61: [
62: .B -s
63: .I server
64: ]
65: [
66: .B -cf
67: .I config-file
68: ]
69: [
70: .B -lf
71: .I lease-file
72: ]
73: [
74: .B -pf
75: .I pid-file
76: ]
77: [
78: .B --no-pid
79: ]
80: [
81: .B -tf
82: .I trace-output-file
83: ]
84: [
85: .B -play
86: .I trace-playback-file
87: ]
88: [
89: .I if0
90: [
91: .I ...ifN
92: ]
93: ]
94:
95: .B dhcpd
96: --version
97: .SH DESCRIPTION
98: The Internet Systems Consortium DHCP Server, dhcpd, implements the
99: Dynamic Host Configuration Protocol (DHCP) and the Internet Bootstrap
100: Protocol (BOOTP). DHCP allows hosts on a TCP/IP network to request
101: and be assigned IP addresses, and also to discover information about
102: the network to which they are attached. BOOTP provides similar
103: functionality, with certain restrictions.
104: .SH OPERATION
105: .PP
106: The DHCP protocol allows a host which is unknown to the network
107: administrator to be automatically assigned a new IP address out of a
1.1.1.1 ! misho 108: pool of IP addresses for its network. In order for this to work, the
1.1 misho 109: network administrator allocates address pools in each subnet and
110: enters them into the dhcpd.conf(5) file.
111: .PP
112: There are two versions of the DHCP protocol DHCPv4 and DHCPv6. At
113: startup the server may be started for one or the other via the
114: .B -4
115: or
116: .B -6
117: arguments.
118: .PP
119: On startup, dhcpd reads the
120: .IR dhcpd.conf
121: file and stores a list of available addresses on each subnet in
122: memory. When a client requests an address using the DHCP protocol,
123: dhcpd allocates an address for it. Each client is assigned a lease,
124: which expires after an amount of time chosen by the administrator (by
125: default, one day). Before leases expire, the clients to which leases
126: are assigned are expected to renew them in order to continue to use
127: the addresses. Once a lease has expired, the client to which that
128: lease was assigned is no longer permitted to use the leased IP
129: address.
130: .PP
131: In order to keep track of leases across system reboots and server
132: restarts, dhcpd keeps a list of leases it has assigned in the
1.1.1.1 ! misho 133: dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it
1.1 misho 134: records the lease in this file and makes sure that the contents of the
1.1.1.1 ! misho 135: file are flushed to disk. This ensures that even in the event of a
1.1 misho 136: system crash, dhcpd will not forget about a lease that it has
1.1.1.1 ! misho 137: assigned. On startup, after reading the dhcpd.conf file, dhcpd
1.1 misho 138: reads the dhcpd.leases file to refresh its memory about what leases
139: have been assigned.
140: .PP
141: New leases are appended to the end of the dhcpd.leases
1.1.1.1 ! misho 142: file. In order to prevent the file from becoming arbitrarily large,
1.1 misho 143: from time to time dhcpd creates a new dhcpd.leases file from its
144: in-core lease database. Once this file has been written to disk, the
145: old file is renamed
146: .IR dhcpd.leases~ ,
1.1.1.1 ! misho 147: and the new file is renamed dhcpd.leases. If the system crashes in
1.1 misho 148: the middle of this process, whichever dhcpd.leases file remains will
149: contain all the lease information, so there is no need for a special
150: crash recovery process.
151: .PP
152: BOOTP support is also provided by this server. Unlike DHCP, the BOOTP
153: protocol does not provide a protocol for recovering
1.1.1.1 ! misho 154: dynamically-assigned addresses once they are no longer needed. It is
1.1 misho 155: still possible to dynamically assign addresses to BOOTP clients, but
1.1.1.1 ! misho 156: some administrative process for reclaiming addresses is required. By
1.1 misho 157: default, leases are granted to BOOTP clients in perpetuity, although
158: the network administrator may set an earlier cutoff date or a shorter
159: lease length for BOOTP leases if that makes sense.
160: .PP
161: BOOTP clients may also be served in the old standard way, which is to
162: simply provide a declaration in the dhcpd.conf file for each
163: BOOTP client, permanently assigning an address to each client.
164: .PP
165: Whenever changes are made to the dhcpd.conf file, dhcpd must be
1.1.1.1 ! misho 166: restarted. To restart dhcpd, send a SIGTERM (signal 15) to the
1.1 misho 167: process ID contained in
168: .IR RUNDIR/dhcpd.pid ,
169: and then re-invoke dhcpd. Because the DHCP server database is not as
170: lightweight as a BOOTP database, dhcpd does not automatically restart
171: itself when it sees a change to the dhcpd.conf file.
172: .PP
1.1.1.1 ! misho 173: Note: We get a lot of complaints about this. We realize that it would
1.1 misho 174: be nice if one could send a SIGHUP to the server and have it reload
1.1.1.1 ! misho 175: the database. This is not technically impossible, but it would
1.1 misho 176: require a great deal of work, our resources are extremely limited, and
1.1.1.1 ! misho 177: they can be better spent elsewhere. So please don't complain about
1.1 misho 178: this on the mailing list unless you're prepared to fund a project to
179: implement this feature, or prepared to do it yourself.
180: .SH COMMAND LINE
181: .PP
182: The names of the network interfaces on which dhcpd should listen for
183: broadcasts may be specified on the command line. This should be done
184: on systems where dhcpd is unable to identify non-broadcast interfaces,
185: but should not be required on other systems. If no interface names
186: are specified on the command line dhcpd will identify all network
187: interfaces which are up, eliminating non-broadcast interfaces if
188: possible, and listen for DHCP broadcasts on each interface.
189: .PP
190: .SH COMMAND LINE OPTIONS
191: .TP
192: .BI \-4
193: Run as a DHCP server. This cannot be combined with \fB\-6\fR.
194: .TP
195: .BI \-6
196: Run as a DHCPv6 server. This is the default and cannot be combined
197: with \fB\-4\fR.
198: .TP
199: .BI \-p \ port
200: The udp port number on which
201: .B dhcpd
202: should listen. If unspecified
203: .B dhcpd
204: uses the default port of 67. This is mostly useful for debugging
205: purposes.
206: .TP
207: .BI \-s \ address
208: Specify an address or host name to which
209: .B dhcpd
210: should send replies rather than the broadcast address (255.255.255.255).
211: This option is only supported in IPv4.
212: .TP
213: .BI \-f
214: Force
215: .B dhcpd
216: to run as a foreground process instead of as a daemon in the background.
217: This is useful when running
218: .B dhcpd
219: under a debugger, or when running it
220: out of inittab on System V systems.
221: .TP
222: .BI \-d
223: Send log messages to the standard error descriptor.
224: This can be useful for debugging, and also at sites where a
225: complete log of all dhcp activity must be kept but syslogd is not
1.1.1.1 ! misho 226: reliable or otherwise cannot be used. Normally,
1.1 misho 227: .B dhcpd
228: will log all
229: output using the \fBsyslog(3)\fR function with the log facility set to
230: LOG_DAEMON. Note that \fB\-d\fR implies \fB\-f\fR (the daemon will
231: not fork itself into the background).
232: .TP
233: .BI \-q
234: Be quiet at startup. This suppresses the printing of the entire
235: copyright message during startup. This might be desirable when
236: starting
237: .B dhcpd
238: from a system startup script (e.g., /etc/rc).
239: .TP
240: .BI \-t
241: Test the configuration file. The server tests the configuration file
242: for correct syntax, but will not attempt to perform any network
1.1.1.1 ! misho 243: operations. This can be used to test a new configuration file
1.1 misho 244: automatically before installing it.
245: .TP
246: .BI \-T
247: Test the lease file. The server tests the lease file
248: for correct syntax, but will not attempt to perform any network
1.1.1.1 ! misho 249: operations. This can be used to test a new leaes file
1.1 misho 250: automatically before installing it.
251: .TP
252: .BI \-tf \ tracefile
253: Specify a file into which the entire startup state of the server and
254: all the transactions it processes are logged. This can be
255: useful in submitting bug reports - if you are getting a core dump
256: every so often, you can start the server with the \fB-tf\fR option and
257: then, when the server dumps core, the trace file will contain all the
258: transactions that led up to it dumping core, so that the problem can
259: be easily debugged with \fB-play\fR.
260: .TP
261: .BI \-play \ playfile
262: Specify a file from which the entire startup state of the server and
263: all the transactions it processed are read. The \fB-play\fR option
264: must be specified with an alternate lease file,
265: using the \fB-lf\fR switch, so that the DHCP server doesn't wipe out
266: your existing lease file with its test data. The DHCP server will
267: refuse to operate in playback mode unless you specify an alternate
268: lease file.
269: .TP
270: .BI --version
271: Print version number and exit.
272: .PP
273: .I Modifying default file locations:
274: The following options can be used to modify the locations
275: .B dhcpd
276: uses for it's files. Because of the importance of using the same
277: lease database at all times when running dhcpd in production, these
278: options should be used \fBonly\fR for testing lease files or database
279: files in a non-production environment.
280: .TP
281: .BI \-cf \ config-file
282: Path to alternate configuration file.
283: .TP
284: .BI \-lf \ lease-file
285: Path to alternate lease file.
286: .TP
287: .BI \-pf \ pid-file
288: Path to alternate pid file.
289: .TP
290: .BI \--no-pid
291: Option to disable writing pid files. By default the program
292: will write a pid file. If the program is invoked with this
293: option it will not check for an existing server process.
294: .PP
295: .SH CONFIGURATION
1.1.1.1 ! misho 296: The syntax of the dhcpd.conf(5) file is discussed separately. This
1.1 misho 297: section should be used as an overview of the configuration process,
298: and the dhcpd.conf(5) documentation should be consulted for detailed
299: reference information.
300: .PP
301: .SH Subnets
302: dhcpd needs to know the subnet numbers and netmasks of all subnets for
1.1.1.1 ! misho 303: which it will be providing service. In addition, in order to
1.1 misho 304: dynamically allocate addresses, it must be assigned one or more ranges
305: of addresses on each subnet which it can in turn assign to client
1.1.1.1 ! misho 306: hosts as they boot. Thus, a very simple configuration providing DHCP
1.1 misho 307: support might look like this:
308: .nf
309: .sp 1
310: subnet 239.252.197.0 netmask 255.255.255.0 {
311: range 239.252.197.10 239.252.197.250;
312: }
313: .fi
314: .PP
315: Multiple address ranges may be specified like this:
316: .nf
317: .sp 1
318: subnet 239.252.197.0 netmask 255.255.255.0 {
319: range 239.252.197.10 239.252.197.107;
320: range 239.252.197.113 239.252.197.250;
321: }
322: .fi
323: .PP
324: If a subnet will only be provided with BOOTP service and no dynamic
325: address assignment, the range clause can be left out entirely, but the
326: subnet statement must appear.
327: .PP
328: .SH Lease Lengths
329: DHCP leases can be assigned almost any length from zero seconds to
1.1.1.1 ! misho 330: infinity. What lease length makes sense for any given subnet, or for
1.1 misho 331: any given installation, will vary depending on the kinds of hosts
332: being served.
333: .PP
334: For example, in an office environment where systems are added from
335: time to time and removed from time to time, but move relatively
336: infrequently, it might make sense to allow lease times of a month or
1.1.1.1 ! misho 337: more. In a final test environment on a manufacturing floor, it may
1.1 misho 338: make more sense to assign a maximum lease length of 30 minutes -
339: enough time to go through a simple test procedure on a network
340: appliance before packaging it up for delivery.
341: .PP
342: It is possible to specify two lease lengths: the default length that
343: will be assigned if a client doesn't ask for any particular lease
1.1.1.1 ! misho 344: length, and a maximum lease length. These are specified as clauses
1.1 misho 345: to the subnet command:
346: .nf
347: .sp 1
348: subnet 239.252.197.0 netmask 255.255.255.0 {
349: range 239.252.197.10 239.252.197.107;
350: default-lease-time 600;
351: max-lease-time 7200;
352: }
353: .fi
354: .PP
355: This particular subnet declaration specifies a default lease time of
356: 600 seconds (ten minutes), and a maximum lease time of 7200 seconds
1.1.1.1 ! misho 357: (two hours). Other common values would be 86400 (one day), 604800
1.1 misho 358: (one week) and 2592000 (30 days).
359: .PP
360: Each subnet need not have the same lease\(emin the case of an office
361: environment and a manufacturing environment served by the same DHCP
362: server, it might make sense to have widely disparate values for
363: default and maximum lease times on each subnet.
364: .SH BOOTP Support
365: Each BOOTP client must be explicitly declared in the dhcpd.conf
1.1.1.1 ! misho 366: file. A very basic client declaration will specify the client
1.1 misho 367: network interface's hardware address and the IP address to assign to
1.1.1.1 ! misho 368: that client. If the client needs to be able to load a boot file from
! 369: the server, that file's name must be specified. A simple bootp
1.1 misho 370: client declaration might look like this:
371: .nf
372: .sp 1
373: host haagen {
374: hardware ethernet 08:00:2b:4c:59:23;
375: fixed-address 239.252.197.9;
376: filename "/tftpboot/haagen.boot";
377: }
378: .fi
379: .SH Options
380: DHCP (and also BOOTP with Vendor Extensions) provide a mechanism
381: whereby the server can provide the client with information about how
382: to configure its network interface (e.g., subnet mask), and also how
383: the client can access various network services (e.g., DNS, IP routers,
384: and so on).
385: .PP
386: These options can be specified on a per-subnet basis, and, for BOOTP
1.1.1.1 ! misho 387: clients, also on a per-client basis. In the event that a BOOTP
1.1 misho 388: client declaration specifies options that are also specified in its
389: subnet declaration, the options specified in the client declaration
1.1.1.1 ! misho 390: take precedence. A reasonably complete DHCP configuration might
1.1 misho 391: look something like this:
392: .nf
393: .sp 1
394: subnet 239.252.197.0 netmask 255.255.255.0 {
395: range 239.252.197.10 239.252.197.250;
396: default-lease-time 600 max-lease-time 7200;
397: option subnet-mask 255.255.255.0;
398: option broadcast-address 239.252.197.255;
399: option routers 239.252.197.1;
400: option domain-name-servers 239.252.197.2, 239.252.197.3;
401: option domain-name "isc.org";
402: }
403: .fi
404: .PP
405: A bootp host on that subnet that needs to be in a different domain and
406: use a different name server might be declared as follows:
407: .nf
408: .sp 1
409: host haagen {
410: hardware ethernet 08:00:2b:4c:59:23;
411: fixed-address 239.252.197.9;
412: filename "/tftpboot/haagen.boot";
413: option domain-name-servers 192.5.5.1;
414: option domain-name "vix.com";
415: }
416: .fi
417: .PP
418: A more complete description of the dhcpd.conf file syntax is provided
419: in dhcpd.conf(5).
420: .SH OMAPI
421: The DHCP server provides the capability to modify some of its
422: configuration while it is running, without stopping it, modifying its
423: database files, and restarting it. This capability is currently
424: provided using OMAPI - an API for manipulating remote objects. OMAPI
425: clients connect to the server using TCP/IP, authenticate, and can then
426: examine the server's current status and make changes to it.
427: .PP
428: Rather than implementing the underlying OMAPI protocol directly, user
1.1.1.1 ! misho 429: programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
1.1 misho 430: wrapper that handles some of the housekeeping chores that OMAPI does
1.1.1.1 ! misho 431: not do automatically. Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR
1.1 misho 432: and \fBomapi(3)\fR.
433: .PP
1.1.1.1 ! misho 434: OMAPI exports objects, which can then be examined and modified. The
1.1 misho 435: DHCP server exports the following objects: lease, host,
1.1.1.1 ! misho 436: failover-state and group. Each object has a number of methods that
! 437: are provided: lookup, create, and destroy. In addition, it is
1.1 misho 438: possible to look at attributes that are stored on objects, and in some
439: cases to modify those attributes.
440: .SH THE LEASE OBJECT
441: Leases can't currently be created or destroyed, but they can be looked
442: up to examine and modify their state.
443: .PP
444: Leases have the following attributes:
445: .PP
446: .B state \fIinteger\fR lookup, examine
447: .RS 0.5i
448: .nf
449: 1 = free
450: 2 = active
451: 3 = expired
452: 4 = released
453: 5 = abandoned
454: 6 = reset
455: 7 = backup
456: 8 = reserved
457: 9 = bootp
458: .fi
459: .RE
460: .PP
461: .B ip-address \fIdata\fR lookup, examine
462: .RS 0.5i
463: The IP address of the lease.
464: .RE
465: .PP
466: .B dhcp-client-identifier \fIdata\fR lookup, examine, update
467: .RS 0.5i
468: The
469: client identifier that the client used when it acquired the lease.
470: Not all clients send client identifiers, so this may be empty.
471: .RE
472: .PP
473: .B client-hostname \fIdata\fR examine, update
474: .RS 0.5i
475: The value the client sent in the host-name option.
476: .RE
477: .PP
478: .B host \fIhandle\fR examine
479: .RS 0.5i
480: the host declaration associated with this lease, if any.
481: .RE
482: .PP
483: .B subnet \fIhandle\fR examine
484: .RS 0.5i
485: the subnet object associated with this lease (the subnet object is not
486: currently supported).
487: .RE
488: .PP
489: .B pool \fIhandle\fR examine
490: .RS 0.5i
491: the pool object associated with this lease (the pool object is not
492: currently supported).
493: .RE
494: .PP
495: .B billing-class \fIhandle\fR examine
496: .RS 0.5i
497: the handle to the class to which this lease is currently billed, if
498: any (the class object is not currently supported).
499: .RE
500: .PP
501: .B hardware-address \fIdata\fR examine, update
502: .RS 0.5i
503: the hardware address (chaddr) field sent by the client when it
504: acquired its lease.
505: .RE
506: .PP
507: .B hardware-type \fIinteger\fR examine, update
508: .RS 0.5i
509: the type of the network interface that the client reported when it
510: acquired its lease.
511: .RE
512: .PP
513: .B ends \fItime\fR examine
514: .RS 0.5i
515: the time when the lease's current state ends, as understood by the
516: client.
517: .RE
518: .PP
519: .B tstp \fItime\fR examine
520: .RS 0.5i
521: the time when the lease's current state ends, as understood by the
522: server.
523: .RE
524: .B tsfp \fItime\fR examine
525: .RS 0.5i
526: the adjusted time when the lease's current state ends, as understood by
527: the failover peer (if there is no failover peer, this value is
528: undefined). Generally this value is only adjusted for expired, released,
529: or reset leases while the server is operating in partner-down state, and
530: otherwise is simply the value supplied by the peer.
531: .RE
532: .B atsfp \fItime\fR examine
533: .RS 0.5i
534: the actual tsfp value sent from the peer. This value is forgotten when a
535: lease binding state change is made, to facilitate retransmission logic.
536: .RE
537: .PP
538: .B cltt \fItime\fR examine
539: .RS 0.5i
540: The time of the last transaction with the client on this lease.
541: .RE
542: .SH THE HOST OBJECT
543: Hosts can be created, destroyed, looked up, examined and modified.
544: If a host declaration is created or deleted using OMAPI, that
1.1.1.1 ! misho 545: information will be recorded in the dhcpd.leases file. It is
1.1 misho 546: permissible to delete host declarations that are declared in the
547: dhcpd.conf file.
548: .PP
549: Hosts have the following attributes:
550: .PP
551: .B name \fIdata\fR lookup, examine, modify
552: .RS 0.5i
1.1.1.1 ! misho 553: the name of the host declaration. This name must be unique among all
1.1 misho 554: host declarations.
555: .RE
556: .PP
557: .B group \fIhandle\fR examine, modify
558: .RS 0.5i
559: the named group associated with the host declaration, if there is one.
560: .RE
561: .PP
562: .B hardware-address \fIdata\fR lookup, examine, modify
563: .RS 0.5i
564: the link-layer address that will be used to match the client, if any.
565: Only valid if hardware-type is also present.
566: .RE
567: .PP
568: .B hardware-type \fIinteger\fR lookup, examine, modify
569: .RS 0.5i
570: the type of the network interface that will be used to match the
1.1.1.1 ! misho 571: client, if any. Only valid if hardware-address is also present.
1.1 misho 572: .RE
573: .PP
574: .B dhcp-client-identifier \fIdata\fR lookup, examine, modify
575: .RS 0.5i
576: the dhcp-client-identifier option that will be used to match the
577: client, if any.
578: .RE
579: .PP
580: .B ip-address \fIdata\fR examine, modify
581: .RS 0.5i
582: a fixed IP address which is reserved for a DHCP client that matches
1.1.1.1 ! misho 583: this host declaration. The IP address will only be assigned to the
1.1 misho 584: client if it is valid for the network segment to which the client is
585: connected.
586: .RE
587: .PP
588: .B statements \fIdata\fR modify
589: .RS 0.5i
590: a list of statements in the format of the dhcpd.conf file that will be
591: executed whenever a message from the client is being processed.
592: .RE
593: .PP
594: .B known \fIinteger\fR examine, modify
595: .RS 0.5i
596: if nonzero, indicates that a client matching this host declaration
1.1.1.1 ! misho 597: will be treated as \fIknown\fR in pool permit lists. If zero, the
1.1 misho 598: client will not be treated as known.
599: .RE
600: .SH THE GROUP OBJECT
601: Named groups can be created, destroyed, looked up, examined and
602: modified. If a group declaration is created or deleted using OMAPI,
603: that information will be recorded in the dhcpd.leases file. It is
604: permissible to delete group declarations that are declared in the
605: dhcpd.conf file.
606: .PP
607: Named groups currently can only be associated with
608: hosts - this allows one set of statements to be efficiently attached
1.1.1.1 ! misho 609: to more than one host declaration.
1.1 misho 610: .PP
611: Groups have the following attributes:
612: .PP
613: .B name \fIdata\fR
614: .RS 0.5i
615: the name of the group. All groups that are created using OMAPI must
616: have names, and the names must be unique among all groups.
617: .RE
618: .PP
619: .B statements \fIdata\fR
620: .RS 0.5i
621: a list of statements in the format of the dhcpd.conf file that will be
622: executed whenever a message from a client whose host declaration
623: references this group is processed.
624: .RE
625: .SH THE CONTROL OBJECT
1.1.1.1 ! misho 626: The control object allows you to shut the server down. If the server
1.1 misho 627: is doing failover with another peer, it will make a clean transition
628: into the shutdown state and notify its peer, so that the peer can go
629: into partner down, and then record the "recover" state in the lease
630: file so that when the server is restarted, it will automatically
631: resynchronize with its peer.
632: .PP
633: On shutdown the server will also attempt to cleanly shut down all
634: OMAPI connections. If these connections do not go down cleanly after
635: five seconds, they are shut down preemptively. It can take as much
636: as 25 seconds from the beginning of the shutdown process to the time
637: that the server actually exits.
638: .PP
639: To shut the server down, open its control object and set the state
640: attribute to 2.
641: .SH THE FAILOVER-STATE OBJECT
642: The failover-state object is the object that tracks the state of the
643: failover protocol as it is being managed for a given failover peer.
644: The failover object has the following attributes (please see
645: .B dhcpd.conf (5)
646: for explanations about what these attributes mean):
647: .PP
648: .B name \fIdata\fR examine
649: .RS 0.5i
650: Indicates the name of the failover peer relationship, as described in
651: the server's \fBdhcpd.conf\fR file.
652: .RE
653: .PP
654: .B partner-address \fIdata\fR examine
655: .RS 0.5i
656: Indicates the failover partner's IP address.
657: .RE
658: .PP
659: .B local-address \fIdata\fR examine
660: .RS 0.5i
661: Indicates the IP address that is being used by the DHCP server for
662: this failover pair.
663: .RE
664: .PP
665: .B partner-port \fIdata\fR examine
666: .RS 0.5i
667: Indicates the TCP port on which the failover partner is listening for
668: failover protocol connections.
669: .RE
670: .PP
671: .B local-port \fIdata\fR examine
672: .RS 0.5i
673: Indicates the TCP port on which the DHCP server is listening for
674: failover protocol connections for this failover pair.
675: .RE
676: .PP
677: .B max-outstanding-updates \fIinteger\fR examine
678: .RS 0.5i
679: Indicates the number of updates that can be outstanding and
680: unacknowledged at any given time, in this failover relationship.
681: .RE
682: .PP
683: .B mclt \fIinteger\fR examine
684: .RS 0.5i
685: Indicates the maximum client lead time in this failover relationship.
686: .RE
687: .PP
688: .B load-balance-max-secs \fIinteger\fR examine
689: .RS 0.5i
690: Indicates the maximum value for the secs field in a client request
691: before load balancing is bypassed.
692: .RE
693: .PP
694: .B load-balance-hba \fIdata\fR examine
695: .RS 0.5i
696: Indicates the load balancing hash bucket array for this failover
697: relationship.
698: .RE
699: .PP
700: .B local-state \fIinteger\fR examine, modify
701: .RS 0.5i
702: Indicates the present state of the DHCP server in this failover
1.1.1.1 ! misho 703: relationship. Possible values for state are:
1.1 misho 704: .RE
705: .RS 1i
706: .PP
707: .nf
708: 1 - startup
709: 2 - normal
710: 3 - communications interrupted
711: 4 - partner down
712: 5 - potential conflict
713: 6 - recover
714: 7 - paused
715: 8 - shutdown
716: 9 - recover done
717: 10 - resolution interrupted
718: 11 - conflict done
719: 254 - recover wait
720: .fi
721: .RE
722: .PP
723: .RS 0.5i
724: (Note that some of the above values have changed since DHCP 3.0.x.)
725: .RE
726: .PP
727: .RS 0.5i
728: In general it is not a good idea to make changes to this state.
729: However, in the case that the failover partner is known to be down, it
730: can be useful to set the DHCP server's failover state to partner
1.1.1.1 ! misho 731: down. At this point the DHCP server will take over service of the
1.1 misho 732: failover partner's leases as soon as possible, and will give out
1.1.1.1 ! misho 733: normal leases, not leases that are restricted by MCLT. If you do put
1.1 misho 734: the DHCP server into the partner-down when the other DHCP server is
735: not in the partner-down state, but is not reachable, IP address
1.1.1.1 ! misho 736: assignment conflicts are possible, even likely. Once a server has
1.1 misho 737: been put into partner-down mode, its failover partner must not be
738: brought back online until communication is possible between the two
739: servers.
740: .RE
741: .PP
742: .B partner-state \fIinteger\fR examine
743: .RS 0.5i
744: Indicates the present state of the failover partner.
745: .RE
746: .PP
747: .B local-stos \fIinteger\fR examine
748: .RS 0.5i
749: Indicates the time at which the DHCP server entered its present state
750: in this failover relationship.
751: .RE
752: .PP
753: .B partner-stos \fIinteger\fR examine
754: .RS 0.5i
755: Indicates the time at which the failover partner entered its present state.
756: .RE
757: .PP
758: .B hierarchy \fIinteger\fR examine
759: .RS 0.5i
760: Indicates whether the DHCP server is primary (0) or secondary (1) in
761: this failover relationship.
762: .RE
763: .PP
764: .B last-packet-sent \fIinteger\fR examine
765: .RS 0.5i
766: Indicates the time at which the most recent failover packet was sent
767: by this DHCP server to its failover partner.
768: .RE
769: .PP
770: .B last-timestamp-received \fIinteger\fR examine
771: .RS 0.5i
772: Indicates the timestamp that was on the failover message most recently
773: received from the failover partner.
774: .RE
775: .PP
776: .B skew \fIinteger\fR examine
777: .RS 0.5i
778: Indicates the skew between the failover partner's clock and this DHCP
779: server's clock
780: .RE
781: .PP
782: .B max-response-delay \fIinteger\fR examine
783: .RS 0.5i
784: Indicates the time in seconds after which, if no message is received
785: from the failover partner, the partner is assumed to be out of
786: communication.
787: .RE
788: .PP
789: .B cur-unacked-updates \fIinteger\fR examine
790: .RS 0.5i
791: Indicates the number of update messages that have been received from
792: the failover partner but not yet processed.
793: .RE
794: .SH FILES
795: .B ETCDIR/dhcpd.conf, DBDIR/dhcpd.leases, RUNDIR/dhcpd.pid,
796: .B DBDIR/dhcpd.leases~.
797: .SH SEE ALSO
798: dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5)
799: .SH AUTHOR
800: .B dhcpd(8)
801: was originally written by Ted Lemon under a contract with Vixie Labs.
802: Funding for this project was provided by Internet Systems
1.1.1.1 ! misho 803: Consortium. Version 3 of the DHCP server was funded by Nominum, Inc.
1.1 misho 804: Information about Internet Systems Consortium is available at
805: .B https://www.isc.org/\fR.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dhcpd.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / server