.\" dhcpd.conf.5
.\"
-.\" Copyright (c) 2004-2017 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 2004-2019 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
.\" This Source Code Form is subject to the terms of the Mozilla Public
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" Internet Systems Consortium, Inc.
-.\" 950 Charter Street
-.\" Redwood City, CA 94063
+.\" PO Box 360
+.\" Newmarket, NH 03857 USA
.\" <info@isc.org>
.\" https://www.isc.org/
.\"
may not be included directly in a shared network declaration.
In addition to the \fBrange6\fR statement it allows the \fBprefix6\fR
statement to be included. You may include \fBrange6\fR statements
-for both NA and TA and \fBprefixy6\fR statements in a single
+for both NA and TA and \fBprefix6\fR statements in a single
\fBpool6\fR statement.
.SH DYNAMIC ADDRESS ALLOCATION
Address allocation is actually only done when a client is in the INIT
}
.fi
.PP
+Please note that the values used in match expressions may only come from
+data or options that are part of the client packet. It is not possible to
+use values constructed through one or more executable statements. This
+stems from the fact that client classification occurs before any statements
+are executed. Attempting to do so will yield indeterminate results.
+.PP
Note that whether you use matching expressions or add statements (or
both) to classify clients, you must always write a class declaration
for any class that you use. If there will be no match statement and
In the final RFC this requirement was relaxed such that a server may
add a DHCID RR to the PTR record.
.PP
+.SH DDNS IN DUAL STACK ENVIRONMENTS
+As described in RFC 4703, section 5.2, in order to perform DDNS in dual
+stack environments, both IPv4 and IPv6 servers would need to be configured
+to use the standard update style and participating IPv4 clients MUST
+convey DUIDs as described in RFC 4361, section 6.1., in their
+dhcp-client-identifiers.
+.PP
+In a nutshell, this mechanism is intended to use globally unique DUIDs
+to idenfity both IPv4 and IPv6 clients, and where a device has both
+IPv4 and IPv6 leases it is identified by the same DUID. This allows
+a dual stack client to use the same FQDN for both mappings, while
+being protected from updates for other clients by the rules of conflict
+detection.
+.PP
+However, not all IPv4 clients implement this behavior which makes
+supporting them dual stack environments problematic. In order to
+address this issue ISC DHCP (as of 4.4.0) supports a new mode of
+DDNS conflict resolution referred to as Dual Stack Mixed Mode (DSMM).
+.PP
+The concept behind DSMM is relatively simple. All dhcp servers of one
+protocol (IPv4 or v6) use one ddns-update-style (interim or standard)
+while all servers of the "other" protocol will use the "other"
+ddns-udpate-style. In this way, all servers of a given protocol are
+using the same record type (TXT or DHCID) for their DHCID RR entries.
+This allows conflict detection to be enforced within each protocol
+without interferring with the other's entries.
+.PP
+DSMM modifications now ensure that IPv4 DSMM servers only ever modify
+A records, their associated PTR records and DHCID records, while DSMM
+IPv6 severs only modify AAAA records, their associated PTR records,
+and DHCID records.
+.PP
+Note that DSMM is not a perfect solution, it is a compromise that can
+work well provided all participating DNS updaters play by DSMM rules.
+As with anything else in life, it only works as well as those who
+particpate behave.
+.PP
+While conflict detection is enabled by default, DSMM is not. To enable
+DSMM, both update-conflict-detection and ddns-dual-stack-mixed-mode must
+be true.
+.PP
+.SH PROTECTING DNS ENTRIES FOR STATIC CLIENTS
+Built into conflict resolution is the protection of manually made entries
+for static clients. Per the rules of conflict resolution, a DNS updater
+may not alter forward DNS entries unless there is a DHCID RR which matches
+for whom the update is being made. Therefore, any forward DNS entries
+without a corresponding DHCID RR cannot be altered by such an updater.
+.PP
+In some environments, it may be desirable to use only this aspect of conflict
+resolution and allow DNS updaters to overwrite entries for dynamic clients
+regardless of what client owns them. In other words, the presence or lack
+of a DHCID RR is used to determine whether entries may or may not be
+overwritten. Whether or not the client matches the data value of the DHCID
+RR is irrelevant. This behavior, off by default, can be configured through
+the parameter, ddns-guard-id-must-match. As with DSMM, this behavior is
+can only be enabled if conflict resolution is enabled. This behavior should
+be considered carefully before electing to use it.
+.PP
+There is an additional parameter that can be used with DSMM
+ddns-other-guard-is-dynamic. When enabled along with DSMM, a server will
+regard the presence of a DHCID RR of the other style type as indicating that
+the forward DNS entries for that FQDN should be dynamic and may be overwritten.
+For example, such a server using interim style could overwrite the DNS entries
+for an FQDN if there is only a DHDID type DHDID RR for the FQDN. Essentially,
+if there are dynamic entries for one protocol, that is enough to overcome the
+static protection of entries for the other protocol. This behavior warrants
+careful consideration before electing to use it.
+.PP
.SH DYNAMIC DNS UPDATE SECURITY
.PP
When you set your DNS server up to allow updates from the DHCP server,
network, but not authoritative for others, nor is it meaningful to
specify that the server is authoritative for some host declarations
and not others.
+.PP
+In order for DHCPINFORMs to be responded to by the server,
+they must match to subnets over which the server has authority;
+otherwise they will be ignored and logged. To minimize the
+impact on logging volume, only the first and every subsequent 100th
+occurrence of an ignored DHCPINFORM is logged.
.RE
.PP
The \fIboot-unknown-clients\fR statement
domain-name (FQDN).
.RE
.PP
+The \fIddns-dual-stack-mixed-mode\fR statement
+.RS 0.25i
+.PP
+.B ddns-dual-stack-mixed-mode \fIflag\fB;\fR
+.PP
+The \fIddns-dual-stack-mixed-mode\fR parameter controls whether or not the
+server applies Dual Stack Mixed Mode rules during DDNS conflict resolution.
+This parameter is off by default, has no effect unless
+update-conflict-detection is enabled, and may only be specified at the
+global scope.
+.RE
+.PP
+The \fIddns-guard-id-must-match\fR statement
+.RS 0.25i
+.PP
+.B ddns-guard-id-must-match \fIflag\fB;\fR
+.PP
+The \fIddns-guard-id-must-match\fR parameter controls whether or not a
+the client id within a DHCID RR must match that of the DNS update's client
+to permit DNS entries associated with that DHCID RR to be ovewritten.
+Proper conflict resolution requires ID matching and should only be disabled
+after careful consideration. When disabled, it is allows any DNS updater to
+replace DNS entries that have an associated DHCID RR, regardless of client
+identity. This parameter is on by default, has no effect unless
+update-conflict-detection is enabled, and may only be specified at the global
+scope.
+.RE
+.PP
The \fddns-local-address4\fR and \fddns-local-address6\fR statements
.RS 0.25i
.PP
requests.
.RE
.PP
+The \fIddns-other-guard-is-dynamic\fR statement
+.RS 0.25i
+.PP
+.B ddns-other-guard-is-dynamic \fIflag\fB;\fR
+.PP
+The \fIddns-other-guard-is-dynamic\fR parameter controls whether or not a
+a server running DSMM will consider the presence of the other update style
+DHCID RR as an indcation that a DNS entries may be overwritten. It should
+only be enabled after careful study as it allows DNS entries that would
+otherwise be protected as static, to be overwritten in certain cases. This
+paramater is off by default, has no effect unless ddns-dual-stack-mixed-mode
+is enabled, and may only be specified at the global scope.
+.RE
+.PP
The \fIddns-rev-domainname\fR statement
.RS 0.25i
.PP
.B max-ack-delay \fImicroseconds\fR\fB;\fR
.PP
.I Count
-should be an integer value from zero to 2^16-1, and defaults to 28. The
-count represents how many DHCPv4 replies maximum will be queued pending
-transmission until after a database commit event. If this number is
-reached, a database commit event (commonly resulting in fsync() and
-representing a performance penalty) will be made, and the reply packets
-will be transmitted in a batch afterwards. This preserves the RFC2131
-direction that "stable storage" be updated prior to replying to clients.
-Should the DHCPv4 sockets "go dry" (select() returns immediately with no
-read sockets), the commit is made and any queued packets are transmitted.
+should be an integer value from zero to 2^16-1 and defaults to 0, which means
+that the feature is disabled. Otherwise, 28 may be a sensible starting point
+for many configurations (SO_SNDBUF size / 576 bytes.) The count represents how
+many DHCPv4 replies maximum will be queued pending transmission until after a
+database commit event. If this number is reached, a database commit event
+(commonly resulting in fsync() and representing a performance penalty) will be
+made, and the reply packets will be transmitted in a batch afterwards. This
+preserves the RFC2131 direction that "stable storage" be updated prior to
+replying to clients. Should the DHCPv4 sockets "go dry" (select() returns
+immediately with no read sockets), the commit is made and any queued packets
+are transmitted.
.PP
Similarly, \fImicroseconds\fR indicates how many microseconds are permitted
to pass inbetween queuing a packet pending an fsync, and performing the
fsync. Valid values range from 0 to 2^32-1, and defaults to 250,000 (1/4 of
a second).
.PP
-The delayed-ack feature is not compiled in by default, but must be enabled
-at compile time with \'./configure --enable-delayed-ack\'. While we no
-longer consider it experimental and we don't know of any issues with it,
-in order to minimize problems with existing configuration files we have
-left it disabled by default.
+The delayed-ack feature is compiled in by default, but can be disabled
+at compile time with \'./configure --disable-delayed-ack\'. Please note
+that the delayed-ack feature is not currently compatible with support for
+DHPCv4-over-DHCPv6 so when a 4to6 port ommand line argument enables this
+in the server the delayed-ack value is reset to 0.
.RE
.PP
The
the lease time). This parameter expresses the percentage of the total
lease time, measured from the beginning, during which a
client's attempt to renew its lease will result in getting
-the already assigned lease, rather than an extended lease.
+the already assigned lease, rather than an extended lease. This feature
+is supported for both IPv4 and IPv6 and down to the pool level and for
+IPv6 all three pool types: NA, TA and PD.
.PP
Clients that attempt renewal frequently can cause the server to
update and write the database frequently resulting in a performance
impact on the server. The \fIdhcp-cache-threshold\fR
statement instructs the DHCP server to avoid updating leases too
-frequently thus avoiding this behavior. Instead the server assigns the
+frequently thus avoiding this behavior. Instead the server replies with the
same lease (i.e. reuses it) with no modifications except for CLTT (Client Last
-Transmission Time) which does not require disk operations. This
-feature applies to IPv4 only.
+Transmission Time) and for IPv4:
+
+ the lease time sent to the client is shortened by the age of
+ the lease
+
+while for IPv6:
+
+ the preferred and valid lifetimes sent to the client are
+ shortened by the age of the lease.
+
+None of these changes require writing the lease to disk.
+
.PP
When an existing lease is matched to a renewing client, it will be reused
if all of the following conditions are true:
4. The client information provided in the renewal does not alter
any of the following:
a. DNS information and DNS updates are enabled
- b. Billing class to which the lease is associated
- c. The host declaration associated with the lease
+ b. Billing class to which the lease is associated (IPv4 only)
+ c. The host declaration associated with the lease (IPv4 only)
d. The client id - this may happen if a client boots without
- a client id and then starts using one in subsequent requests.
+ a client id and then starts using one in subsequent
+ requests. (IPv4 only)
.fi
.PP
+While lease data is not written to disk when a lease is reused, the server
+will still execute any on-commit statements.
+.PP
Note that the lease can be reused if the options the client or relay agent
sends are changed. These changes will not be recorded in the in-memory or
on-disk databases until the client renews after the threshold time is reached.
.B lease-file-name \fIname\fB;\fR
.PP
.I Name
-should be the name of the DHCP server's lease file. By default, this
-is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer
-scope of the configuration file - if it appears in some other scope,
-it will have no effect. Furthermore, it has no effect if overridden
-by the
-.B -lf
-flag or the
-.B PATH_DHCPD_DB
-environment variable.
-.RE
+Where \fIname\fR is the name of the DHCP server's lease file. By default,
+this is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer
+scope of the configuration file - if it appears in some other scope, it will
+have no effect. The value must be the absolute path of the file to use.
+The order of precedence the server uses for the lease file name
+is:
.PP
-The
-.I limit-addrs-per-ia
-statement
-.RS 0.25i
-.PP
-.B limit-addrs-per-ia \fInumber\fB;\fR
-.PP
-By default, the DHCPv6 server will limit clients to one IAADDR per IA
-option, meaning one address. If you wish to permit clients to hang onto
-multiple addresses at a time, configure a larger \fInumber\fR here.
-.PP
-Note that there is no present method to configure the server to forcibly
-configure the client with one IP address per each subnet on a shared network.
-This is left to future work.
+ 1. \fBlease-file-name\fR configuration file statement.
+ 2. \fB-lf\fR command line flag.
+ 3. \fBPATH_DHCPD_DB\fR environment variable.
.RE
.PP
The
.PP
.B dhcpv6-lease-file-name \fIname\fB;\fR
.PP
-.I Name
-is the name of the lease file to use if and only if the server is running
-in DHCPv6 mode. By default, this is DBDIR/dhcpd6.leases. This statement,
-like
-.I lease-file-name,
-\fBmust\fR appear in the outer scope of the configuration file. It
-has no effect if overridden by the
-.B -lf
-flag or the
-.B PATH_DHCPD6_DB
-environment variable. If
-.I dhcpv6-lease-file-name
-is not specified, but
-.I lease-file-name
-is, the latter value will be used.
+Where \fIname\fR is the name of the DHCP server's lease file when the server
+is running DHCPv6. By default, this is DBDIR/dhcpd6.leases. This statement
+\fBmust\fR appear in the outer scope of the configuration file - if it appears
+in some other scope, it will have no effect. The value must be the absolute
+path of the file to use. The order of precedence the server uses
+for the lease file name is:
+.PP
+ 1. \fBdhcpv6-lease-file-name\fR configuration file statement.
+ 2. \fB-lf\fR command line flag.
+ 3. \fBPATH_DHCPD6_DB\fR environment variable.
.RE
.PP
The
.RE
.PP
The
+.I limit-addrs-per-ia
+statement
+.RS 0.25i
+.PP
+.B limit-addrs-per-ia \fInumber\fB;\fR
+.PP
+By default, the DHCPv6 server will limit clients to one IAADDR per IA
+option, meaning one address. If you wish to permit clients to hang onto
+multiple addresses at a time, configure a larger \fInumber\fR here.
+.PP
+Note that there is no present method to configure the server to forcibly
+configure the client with one IP address per each subnet on a shared network.
+This is left to future work.
+.RE
+.PP
+The
.I local-port
statement
.RS 0.25i
.RE
.PP
The
+.I local-address6
+and
+.I bind-local-address6
+statements
+.RS 0.25i
+.PP
+.B local-address6 \fIaddress\fB;\fR
+.PP
+.B bind-local-address6 \fIflag\fB;\fR
+.PP
+The \fIlocal-address6\fR statement causes the DHCP server to send IPv6
+packets as originating from the specified IPv6 \fIaddress\fR, rather than
+leaving the kernel to fill in the source address field.
+.PP
+When \fIbind-local-address6\fR is present and has a value of true or on,
+service sockets are bound to \fIaddress\fR too.
+.PP
+By default \fIaddress\fR is the undefined address and the
+\fIbind-local-address6\fR is disabled, both may only be set at the global
+scope.
+.RE
+.PP
+The
.I log-facility
statement
.RS 0.25i
.RE
.PP
The
+.I persist-eui-64-leases
+statement
+.RS 0.25i
+.PP
+.B persist-eui-64-leases \fIflag\fR\fB;\fR
+.PP
+When this flag is enabled, the server will write EUI-64 based leases to the
+leases file. Since such leases can only, ever be valid for a single DUID value
+it can be argued that writing them to the leases file isn't essential and not
+doing so may have perfomance advantages. See \fIuse-eui-64\fR statement for
+more details on EUI-64 based address allocation. The flag is enabled by
+default and may only be set at the global scope.
+.RE
+.PP
+The
.I pid-file-name
statement
.RS 0.25i
.I Name
should be the name of the DHCP server's process ID file. This is the
file in which the DHCP server's process ID is stored when the server
-starts. By default, this is RUNDIR/dhcpd.pid. Like the
-.I lease-file-name
-statement, this statement must appear in the outer scope
-of the configuration file. It has no effect if overridden by the
-.B -pf
-flag or the
-.B PATH_DHCPD_PID
-environment variable.
+starts. By default, this is RUNDIR/dhcpd.pid. Like the \fIlease-file-name\fR
+statement, this statement must appear in the outer scope of the configuration
+file. The order of precedence used by the server is:
+.PP
+ 1. \fBpid-file-name\fR configuration file statement.
+ 2. \fB-lf\fR command line flag.
+ 3. \fBPATH_DHCPD_PID\fR environment variable.
.PP
The
.I dhcpv6-pid-file-name
.I Name
is the name of the pid file to use if and only if the server is running
in DHCPv6 mode. By default, this is DBDIR/dhcpd6.pid. This statement,
-like
-.I pid-file-name,
-\fBmust\fR appear in the outer scope of the configuration file. It
-has no effect if overridden by the
-.B -pf
-flag or the
-.B PATH_DHCPD6_PID
-environment variable. If
-.I dhcpv6-pid-file-name
-is not specified, but
-.I pid-file-name
-is, the latter value will be used.
+like \fIpid-file-name\fr, \fBmust\fR appear in the outer scope of the
+configuration file. The order of precedence used by the server is:
+.PP
+ 1. \fBdhcpv6-pid-file-name\fR configuration file statement.
+ 2. \fB-lf\fR command line flag.
+ 3. \fBPATH_DHCPD6_PID\fR environment variable.
+.PP
.RE
.PP
The
.RE
.PP
The
+.I ping-cltt-secs
+statement
+.RS 0.25i
+.PP
+.B ping-cltt-secs
+.I seconds\fR\fB;\fR
+.PP
+The server will conduct a ping check if all the following conditions are true:
+.PP
+1. Ping checking is enabled.
+.PP
+2. The server is responding to a DISCOVER.
+.PP
+3. The lease to be offered is neither static nor active (i.e. still a valid
+lease).
+.PP
+4. And any of the following are true:
+ a. This will be the first offer of this lease (CLTT is 0).
+ b. The lease is being offered to a client other than its previous owner
+ c. The lease is being offered to its previous owner and more than
+ \fBping-cltt-secs\fR have elapsed since CLTT of the original lease.
+ d. The lease was abandoned and the server is attempting to reclaim it.
+
+.PP
+The \fBping-cltt-secs\fR statement allows the user to specify the amount of
+time that must elaspe after CLTT before a ping check will be conducted.
+The default value is sixty seconds.
+.RE
+.PP
+The
.I ping-timeout
statement
.RS 0.25i
ICMP Echo response to be heard, if no ICMP Echo response has been received
before the timeout expires, it assigns the address. If a response \fIis\fR
heard, the lease is abandoned, and the server does not respond to the client.
-If no value is set, ping-timeout defaults to 1 second.
+If no value is set, ping-timeout defaults to 1 second. (See also ping-timeout-ms
+below)
+.RE
+.PP
+The
+.I ping-timeout-ms
+statement
+.RS 0.25i
+.PP
+.B ping-timeout-ms
+.I milliseconds\fR\fB;\fR
+.PP
+Allows you to specify the ping timeout in milliseconds rather than
+seconds. If this value is greater than zero, the server will use it
+in place of ping-timeout. The default value is zero.
.RE
.PP
The
.PP
2. prefer - The server will offer the first available prefix with the same
length as the requested length. If none are found then it will offer the
-first available prefix of any length.
+first available prefix of any length. This is the default behavior.
.PP
3. exact - The server will offer the first available prefix with the same
length as the requested length. If none are found, it will return a status
-indicating no prefixes available. This is the default behavior.
+indicating no prefixes available.
.PP
4. minimum - The server will offer the first available prefix with the same
length as the requested length. If none are found, it will return the first
.RE
.PP
The
+.I release-on-roam
+statement
+.RS 0.25i
+.PP
+.B release-on-roam \fIflag\fB;\fR
+.PP
+When enabled and the dhcpd server detects that a DHCPv6 client (IAID+DUID)
+has roamed to a new network, it will release the pre-existing leases on the
+old network and emit a log statement similiar to the following:
+
+ "Client: <id> roamed to new network, releasing lease: <address>"
+
+The server will carry out all of the same steps that would normally occur
+when a client explicitly releases a lease. When release-on-roam is disabled
+(the default) the server makes such leases unavailable until they expire or
+the server is restarted. Clients that need leases in multiple networks must
+supply a unique IAID in each IA. This parameter may only be specified at
+the global level.
+.RE
+.PP
+The
.I remote-port
statement
.RS 0.25i
A value of zero tells the client it may choose its own value.
When those options are not defined then values will be set to zero unless the
-global \fIdhcpv6-set-tee-times\R is enabled. When this option is enabled the
+global \fIdhcpv6-set-tee-times\fR is enabled. When this option is enabled the
times are calculated as recommended by RFC 3315, Section 22.4:
T1 will be set to 0.5 times the shortest preferred lifetime
perform standard DHCID multiple-client, one-name conflict detection. If
the parameter has been set false, the server will skip this check and
instead simply tear down any previous bindings to install the new
-binding without question. The default is true.
+binding without question. The default is true and this parameter may only
+be specified at the global scope.
.RE
.PP
The
.PP
The \fIupdate-static-leases\fR flag, if enabled, causes the DHCP
server to do DNS updates for clients even if those clients are being
-assigned their IP address using a \fIfixed-address\fR statement - that
-is, the client is being given a static assignment. It is not
-recommended because the DHCP server has no way to tell that the update
-has been done, and therefore will not delete the record when it is not
-in use. Also, the server must attempt the update each time the
-client renews its lease, which could have a significant performance
-impact in environments that place heavy demands on the DHCP server.
+assigned their IP address using a \fIfixed-address\fR or
+\fIfixed-address6\fR statement - that is, the client is being given a
+static assignment. It is not recommended because the DHCP server has
+no way to tell that the update has been done, and therefore will not
+delete the record when it is not in use. Also, the server must attempt
+the update each time the client renews its lease, which could have a
+significant performance impact in environments that place heavy demands
+on the DHCP server. This feature is supported for both DHCPv4 and DHCPv6,
+and update modes standard or interim. It is disabled by default.
.RE
-
-
.PP
The
.I use-eui-64
Request - Server will send "an address not on link status", and no ia
suboption Renew/Rebind - Server will send the requested address ia
suboption with lifetimes of 0, plus an EUI-64 ia
+
+Whether or not EUI-64 based leases are written out to the lease database
+may be controlled by \fIpersist-eui-64-leases\fR statement.
.RE
.PP
The
projects / thirdparty / dhcp.git / blobdiff