Annotation of embedaddon/dhcp/server/dhcpd.8, revision 1.1
1.1 ! misho 1: .\" dhcpd.8
! 2: .\"
! 3: .\" Copyright (c) 2009-2011 by Internet Systems Consortium, Inc. ("ISC")
! 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: .\"
! 31: .\" $Id: dhcpd.8,v 1.29.32.4.6.1 2011-04-15 22:26:21 sar Exp $
! 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
! 108: pool of IP addresses for its network. In order for this to work, the
! 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
! 133: dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it
! 134: records the lease in this file and makes sure that the contents of the
! 135: file are flushed to disk. This ensures that even in the event of a
! 136: system crash, dhcpd will not forget about a lease that it has
! 137: assigned. On startup, after reading the dhcpd.conf file, dhcpd
! 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
! 142: file. In order to prevent the file from becoming arbitrarily large,
! 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~ ,
! 147: and the new file is renamed dhcpd.leases. If the system crashes in
! 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
! 154: dynamically-assigned addresses once they are no longer needed. It is
! 155: still possible to dynamically assign addresses to BOOTP clients, but
! 156: some administrative process for reclaiming addresses is required. By
! 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
! 166: restarted. To restart dhcpd, send a SIGTERM (signal 15) to the
! 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
! 173: Note: We get a lot of complaints about this. We realize that it would
! 174: be nice if one could send a SIGHUP to the server and have it reload
! 175: the database. This is not technically impossible, but it would
! 176: require a great deal of work, our resources are extremely limited, and
! 177: they can be better spent elsewhere. So please don't complain about
! 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
! 226: reliable or otherwise cannot be used. Normally,
! 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
! 243: operations. This can be used to test a new configuration file
! 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
! 249: operations. This can be used to test a new leaes file
! 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
! 296: The syntax of the dhcpd.conf(5) file is discussed separately. This
! 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
! 303: which it will be providing service. In addition, in order to
! 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
! 306: hosts as they boot. Thus, a very simple configuration providing DHCP
! 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
! 330: infinity. What lease length makes sense for any given subnet, or for
! 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
! 337: more. In a final test environment on a manufacturing floor, it may
! 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
! 344: length, and a maximum lease length. These are specified as clauses
! 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
! 357: (two hours). Other common values would be 86400 (one day), 604800
! 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
! 366: file. A very basic client declaration will specify the client
! 367: network interface's hardware address and the IP address to assign to
! 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
! 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
! 387: clients, also on a per-client basis. In the event that a BOOTP
! 388: client declaration specifies options that are also specified in its
! 389: subnet declaration, the options specified in the client declaration
! 390: take precedence. A reasonably complete DHCP configuration might
! 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
! 429: programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
! 430: wrapper that handles some of the housekeeping chores that OMAPI does
! 431: not do automatically. Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR
! 432: and \fBomapi(3)\fR.
! 433: .PP
! 434: OMAPI exports objects, which can then be examined and modified. The
! 435: DHCP server exports the following objects: lease, host,
! 436: failover-state and group. Each object has a number of methods that
! 437: are provided: lookup, create, and destroy. In addition, it is
! 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
! 545: information will be recorded in the dhcpd.leases file. It is
! 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
! 553: the name of the host declaration. This name must be unique among all
! 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
! 571: client, if any. Only valid if hardware-address is also present.
! 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
! 583: this host declaration. The IP address will only be assigned to the
! 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
! 597: will be treated as \fIknown\fR in pool permit lists. If zero, the
! 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
! 609: to more than one host declaration.
! 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
! 626: The control object allows you to shut the server down. If the server
! 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
! 703: relationship. Possible values for state are:
! 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
! 731: down. At this point the DHCP server will take over service of the
! 732: failover partner's leases as soon as possible, and will give out
! 733: normal leases, not leases that are restricted by MCLT. If you do put
! 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
! 736: assignment conflicts are possible, even likely. Once a server has
! 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
! 803: Consortium. Version 3 of the DHCP server was funded by Nominum, Inc.
! 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