Commit 5dfada0e authored by Thomas Markwalder's avatar Thomas Markwalder
Browse files

[3283] Added DDNS config sections for Kea

    Added secctions for configuring dhcp-ddns to DHCPv4 and DHCPv6 sections.
    Added empty Chapter for DHCP-DDNS server.
parent dbedf186
......@@ -3539,9 +3539,18 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
and one for DHCPv6. The DHCP part of the BIND 10 project is codenamed
Kea. The DHCPv4 component is colloquially referred to as Kea4 and its
DHCPv6 counterpart is called Kea6.</para>
<para> In addition to providing lease management services, both Kea4 and
Kea6 can provide dynamic DNS (DDNS) updates driven by the lease changes they
make. These updates are carried out with the assistance of the
DHCP-DDNS server, colloquially referred to as D2. When configured
to do so, Kea servers will notify D2 of lease changes. D2 will match
them to the appropriate DNS servers and instruct those severs to add or
delete the requisite DNS entries.
</para>
<para>This chapter covers those parts of BIND 10 that are common to
both servers. DHCPv4-specific details are covered in <xref linkend="dhcp4"/>,
while those details specific to DHCPv6 are described in <xref linkend="dhcp6"/>
while those details specific to DHCPv6 are described in <xref linkend="dhcp6"/>.
The DHCP-DDNS server details are covered in <xref linkend="dhcp-ddns-server"/>
</para>
<note>
......@@ -3684,17 +3693,31 @@ $</screen>
will be available. It will look similar to this:
<screen>
&gt; <userinput>config show Dhcp4</userinput>
Dhcp4/interfaces/ list (default)
Dhcp4/renew-timer 1000 integer (default)
Dhcp4/hooks-libraries [] list (default)
Dhcp4/interfaces/ list
Dhcp4/renew-timer 1800 integer
Dhcp4/rebind-timer 2000 integer (default)
Dhcp4/valid-lifetime 4000 integer (default)
Dhcp4/next-server "" string (default)
Dhcp4/echo-client-id true boolean (default)
Dhcp4/option-def [] list (default)
Dhcp4/option-data [] list (default)
Dhcp4/lease-database/type "memfile" string (default)
Dhcp4/lease-database/type "" string (default)
Dhcp4/lease-database/name "" string (default)
Dhcp4/lease-database/user "" string (default)
Dhcp4/lease-database/host "" string (default)
Dhcp4/lease-database/password "" string (default)
Dhcp4/subnet4 [] list (default)
Dhcp4/subnet4/ list
Dhcp4/dhcp-ddns/enable-updates true boolean
Dhcp4/dhcp-ddns/server-ip "127.0.0.1" string
Dhcp4/dhcp-ddns/server-port 53001 integer
Dhcp4/dhcp-ddns/ncr-protocol "UDP" string
Dhcp4/dhcp-ddns/ncr-format "JSON" string
Dhcp4/dhcp-ddns/override-no-update false boolean
Dhcp4/dhcp-ddns/override-client-update false boolean
Dhcp4/dhcp-ddns/replace-client-name false boolean
Dhcp4/dhcp-ddns/generated-prefix "myhost" string
Dhcp4/dhcp-ddns/qualifying-suffix "example.com" string
</screen>
</para>
......@@ -4499,6 +4522,265 @@ Dhcp4/subnet4 [] list (default)
clients that do not meet class criteria to be denied any service altogether.
</para>
</section>
<section id="dhcp4-ddns-config">
<title>Configuring DHCPv4 for DDNS</title>
<para>
As mentioned earlier, DHCPv4 can be configured to generate requests to the
DHCP-DDNS server to update DNS entries. These requests are known as
NameChangeRequests or NCRs. Each NCR contains the following information:
<para>
1. Whether it is a request to add(update) or remove DNS entries
</para>
<para>
2. Whether the change requests forward DNS updates (As), reverse
DNS udpates (PTRs), or both.
</para>
<para>
3. The FQDN, lease address, and DHCID
</para>
The paramaters for controlling the generation of NCRs for submission to D2
are contained in the "dhcp-ddns" section of the DHCPv4 server
configuration. The default values for this secion appears as follows:
<screen>
&gt; <userinput>config show Dhcp4/dhcp-ddns</userinput>
Dhcp4/dhcp-ddns/enable-updates true boolean
Dhcp4/dhcp-ddns/server-ip "127.0.0.1" string
Dhcp4/dhcp-ddns/server-port 53001 integer
Dhcp4/dhcp-ddns/ncr-protocol "UDP" string
Dhcp4/dhcp-ddns/ncr-format "JSON" string
Dhcp4/dhcp-ddns/override-no-update false boolean
Dhcp4/dhcp-ddns/override-client-update false boolean
Dhcp4/dhcp-ddns/replace-client-name false boolean
Dhcp4/dhcp-ddns/generated-prefix "myhost" string
Dhcp4/dhcp-ddns/qualifying-suffix "example.com" string
</screen>
</para>
<para>
The "enable-updates" parameter determines whether or not DHCPv4 will
generate NCRs. By default, this value is false hence DDNS updates are
disabled. To enable DDNS updates set this value to true as follows:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/enable-updates true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<section id="dhcpv4-d2-io-config">
<title>DHCP-DDNS Server Connectivty</title>
In order for NCRs to reach D2, DHCPv4 must be able to communicate with it.
The following parameters are used to establish connectivty between DHCPv4
and D2.
<para>
The parameters, "server-ip" and "server-port", specify the address of the
D2 server. By default, D2 is assumed to running on the same machine as
DHCPv4, and the default values for these two parameters should be
sufficient. However, if D2 has been configured to listen on a different
address or port, these values must altered accordingly. For example, if
D2 has been configured to listen on 198.162.1.43 port 900, the following
commands would be required:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/server-ip "172.16.1.47"</userinput>
&gt; <userinput>config set Dhcp4/dhcp-ddns/server-port 900</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The socket protocol that DHCPv4 should use to communicate with D2 is
specified with the "ncr-protocol" parameter. Currently only UDP is
supported.
</para>
<para>
The internal format for DDNS update requests sent by DHCPv4 is specified
with the "ncr-format" parameter. Currently only JSON is supported.
</para>
</section>
<section id="dhcpv4-d2-rules-config">
<title>When does DHCPv4 generates DDNS request</title>
DHCPv4 follows the behavior prescribed for DHCP servers in RFC 4702.
It is important to keep in mind that DHCPv4 provides the initial decision
making of when and what to update and forwards that information to D2 in
the form of NCRs. Carrying out the actual DNS updates and dealing with
such things as conflict resolution are the purvue of D2 (<xref linkend="dhcp-ddns-server"/>).
<para>
This section describes when DHCPv4 will generate NCRs and the
configuration parameters that can be used to influence this decision.
It assumes that the "enable-updates" paramater is true.
</para>
<para>
In general, DHCPv4 will generate DDNS udpate requests when:
</para>
<para>
1. A new lease is granted in response to a DHCP REQUEST
</para>
<para>
2. An existing lease is renewed but the FQDN associated with it has
changed.
</para>
<para>
3. An existing lease is released in response to a DHCP RELEASE
</para>
<para>
In the second case, lease renewal, to DDNS requests will be issued: one
request to remove entries for the previous FQDN and a second request to
add entries for th new FQDN. In the last case, a lease release, a
single DDNS request to remove its entries will be made. The decision
making involved when granting a new lease, the first case, is more
involved and is discussed next.
</para>
<para>
DHCPv4 will generate a DDNS update request if the DHCP REQUEST contains
either the FQDN option (code 81) or the Host Name option (code 12). If
both are present, the server will use the FQDN option. By default the
DHCPv4 server will respect the FQDN N and S flags specified by
the client as shown in the following table:
</para>
<table id="fqdn-flag-table">
<title>Default FQDN Flag Behavior</title>
<tgroup cols='4' align='left'>
<colspec colname='cflags'/>
<colspec colname='meaning'/>
<colspec colname='response'/>
<colspec colname='sflags'/>
<thead>
<row>
<entry>Client Flags:N-S</entry>
<entry>Client Intent</entry>
<entry>Server Response</entry>
<entry>Server Flags:N-S-O</entry>
</row>
</thead>
<tbody>
<row>
<entry>0-0</entry>
<entry>Client wants to perform forward DNS updates</entry>
<entry>Server does not generate request</entry>
<entry>1-0-0</entry>
</row>
<row>
<entry>0-1</entry>
<entry>Client wants the server to perform forward DNS updates</entry>
<entry>Server generates request</entry>
<entry>0-1-0</entry>
</row>
<row>
<entry>1-0</entry>
<entry>Client wants no DNS udpates done</entry>
<entry>Server does not generate request</entry>
<entry>1-0-0</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The first row in the table above represents "client delegation". Here
the DHCP client states that it intends to do the forward DNS updates and
therefore the server should not attempt them. The parameter,
"override-client-update", can be used to instruct the server to override
client delegation requests. When this parameter is true, DHCPv4 will
generate DDNS udpate request to D2 even if the client requests delegation.
The N-S-O flags in the server's response to the client will be 0-1-1
respectively.
</para>
<para>
To override client delegation, issue the following commands:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/override-client-update true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The third row in the table above describes the case in which the client
requests that no DNS updates be done. The parameter, "override-no-update",
can be used to instruct the server to disregard the client's wishes. When
this parameter is true, DHCPv4 will generate DDNS udpate request to D2
even if the client requests no updates be done. The N-S-O flags in the
server's response to the client will be 0-1-1.
</para>
<para>
To override client delegation, issue the following commands:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/override-no-update true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
DHCPv4 will always generate DDNS update requests if the client request
only contains the Host Name option. In addition it will include an FQDN
option in the response to the client with the FQDN N-S-O flags set to
0-1-0 respectively. The domain name portion of the FQDN option will be
the name submitted to D2 in the DDNS update request.
</para>
</section>
<section id="dhcpv4-fqdn-name-generation">
<title>DHCPv4 name generation for DDNS update requests</title>
Each NameChangeRequest must of course include the fully qualified domain
name whose DNS entries are to be affected. DHCPv4 can be configured to
supply a portion or all of that name based upon what it receives from
the client in the DHCP REQUEST.
<para>
The rules for determining the FQDN option are as follows:
</para>
<para>
1. If configured to do so ignore the REQUEST contents and generate a
FQDN using a configurable prefix and suffix.
</para>
<para>
2. If the REQUEST contains the client FQDN option than the candidate
name is taken from there, otherwise it is taken from the Host Name option.
</para>
<para>
3. If the candidate name is a fully qualified domain name then use
it.
4. If the candidate name is a partial (i.e. unqualified) name then
add a configurable suffix to the name and use the result as the FQDN.
</para>
<para>
5. If the candidate name is a empty then generate a FQD using a
configurable prefix and suffix.
</para>
<para>
To instruct DHCPv4 to always generate a FQDN, set the parmeter,
"replace-client-name", to true as follows:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/replace-client-name true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The prefix used when generating a FQDN is specified by the
"generated-prefix" parameter. The default value is "myhost". To alter
its value simply set it to the desired string:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/generated-prefix "another.host"</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The suffix used when generating a FQDN or when qualifying a partial
name is specified by the "qualifying-suffix" parameter. The default
value is "example.com". To alter its value simply set it to the desired
string:
</para>
<screen>
&gt; <userinput>config set Dhcp4/dhcp-ddns/generated-prefix "our.net"</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</section>
<para>
When generating a name, DHCPv4 will construct name of the format:
</para>
<para>
[generated-prefix]-[address-text].[qualifying-suffix].
</para>
<para>
where address-text is simply the lease IP address converted to a
hyphenated string. For example, if lease address is 172.16.1.10 and
assuming default values for generated-prefix and qualifying-suffix, the
generated FQDN would be:
</para>
<para>
myhost-172-16-1-10.example.com.
</para>
</section>
</section> <!-- end of configuring DHCPv4 server section with many subsections -->
......@@ -4843,18 +5125,31 @@ Dhcp4/renew-timer 1000 integer (default)
will be available. It will look similar to this:
<screen>
&gt; <userinput>config show Dhcp6</userinput>
Dhcp6/interfaces/ list (default)
Dhcp6/renew-timer 1000 integer (default)
Dhcp6/rebind-timer 2000 integer (default)
Dhcp6/preferred-lifetime 3000 integer (default)
Dhcp6/valid-lifetime 4000 integer (default)
Dhcp6/option-data [] list (default)
Dhcp6/lease-database/type "memfile" string (default)
Dhcp6/lease-database/name "" string (default)
Dhcp6/lease-database/user "" string (default)
Dhcp6/lease-database/host "" string (default)
Dhcp6/lease-database/password "" string (default)
Dhcp6/subnet6/ list
Dhcp6/hooks-libraries [] list (default)
Dhcp6/interfaces/ list (default)
Dhcp6/renew-timer 1000 integer (default)
Dhcp6/rebind-timer 2000 integer (default)
Dhcp6/preferred-lifetime 3000 integer (default)
Dhcp6/valid-lifetime 4000 integer (default)
Dhcp6/option-def [] list (default)
Dhcp6/option-data [] list (default)
Dhcp6/lease-database/type "" string (default)
Dhcp6/lease-database/name "" string (default)
Dhcp6/lease-database/user "" string (default)
Dhcp6/lease-database/host "" string (default)
Dhcp6/lease-database/password "" string (default)
Dhcp6/subnet6/ list
Dhcp6/dhcp-ddns/enable-updates true boolean
Dhcp6/dhcp-ddns/server-ip "127.0.0.1" string
Dhcp6/dhcp-ddns/server-port 53001 integer
Dhcp6/dhcp-ddns/ncr-protocol "UDP" string
Dhcp6/dhcp-ddns/ncr-format "JSON" string
Dhcp6/dhcp-ddns/always-include-fqdn false boolean
Dhcp6/dhcp-ddns/override-no-update false boolean
Dhcp6/dhcp-ddns/override-client-update false boolean
Dhcp6/dhcp-ddns/replace-client-name false boolean
Dhcp6/dhcp-ddns/generated-prefix "myhost" string
Dhcp6/dhcp-ddns/qualifying-suffix "example.com" string
</screen>
</para>
<para>
......@@ -5705,6 +6000,285 @@ should include options from the isc option space:
</para>
</section>
<section id="dhcp6-ddns-config">
<title>Configuring DHCPv6 for DDNS</title>
<para>
As mentioned earlier, DHCPv6 can be configured to generate requests to the
DHCP-DDNS server to update DNS entries. These requests are known as
NameChangeRequests or NCRs. Each NCR contains the following information:
<para>
1. Whether it is a request to add(update) or remove DNS entries
</para>
<para>
2. Whether the change requests forward DNS updates (AAAAs), reverse
DNS udpates (PTRs), or both.
</para>
<para>
3. The FQDN, lease address, and DHCID
</para>
The paramaters for controlling the generation of NCRs for submission to D2
are contained in the "dhcp-ddns" section of the DHCPv6 server
configuration. The default values for this secion appears as follows:
<screen>
&gt; <userinput>config show Dhcp6/dhcp-ddns</userinput>
Dhcp6/dhcp-ddns/enable-updates true boolean
Dhcp6/dhcp-ddns/server-ip "127.0.0.1" string
Dhcp6/dhcp-ddns/server-port 53001 integer
Dhcp6/dhcp-ddns/ncr-protocol "UDP" string
Dhcp6/dhcp-ddns/ncr-format "JSON" string
Dhcp6/dhcp-ddns/override-no-update false boolean
Dhcp6/dhcp-ddns/override-client-update false boolean
Dhcp6/dhcp-ddns/replace-client-name false boolean
Dhcp6/dhcp-ddns/generated-prefix "myhost" string
Dhcp6/dhcp-ddns/qualifying-suffix "example.com" string
</screen>
</para>
<para>
The "enable-updates" parameter determines whether or not DHCPv6 will
generate NCRs. By default, this value is false hence DDNS updates are
disabled. To enable DDNS updates set this value to true as follows:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/enable-updates true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<section id="dhcpv6-d2-io-config">
<title>DHCP-DDNS Server Connectivty</title>
In order for NCRs to reach D2, DHCPv6 must be able to communicate with it.
The following parameters are used to establish connectivty between DHCPv6
and D2.
<para>
The parameters, "server-ip" and "server-port", specify the address of the
D2 server. By default, D2 is assumed to running on the same machine as
DHCPv6, and the default values for these two parameters should be
sufficient. However, if D2 has been configured to listen on a different
address or port, these values must altered accordingly. For example, if
D2 has been configured to listen on 198.162.1.43 port 900, the following
commands would be required:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/server-ip "172.16.1.47"</userinput>
&gt; <userinput>config set Dhcp6/dhcp-ddns/server-port 900</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The socket protocol that DHCPv6 should use to communicate with D2 is
specified with the "ncr-protocol" parameter. Currently only UDP is
supported.
</para>
<para>
The internal format for DDNS update requests sent by DHCPv6 is specified
with the "ncr-format" parameter. Currently only JSON is supported.
</para>
</section>
<section id="dhcpv6-d2-rules-config">
<title>When does DHCPv6 generates DDNS request</title>
DHCPv6 follows the behavior prescribed for DHCP servers in RFC 4704.
It is important to keep in mind that DHCPv6 provides the initial decision
making of when and what to update and forwards that information to D2 in
the form of NCRs. Carrying out the actual DNS updates and dealing with
such things as conflict resolution are the purvue of D2 (<xref linkend="dhcp-ddns-server"/>).
<para>
This section describes when DHCPv6 will generate NCRs and the
configuration parameters that can be used to influence this decision.
It assumes that the "enable-updates" paramater is true.
</para>
<note>
<para>
Currently the interface between DHCPv6 and D2 only supports requests
which update DNS entries for a single IP address. If a lease grants
more than one address, DHCPv6 will create the DDNS update request for
only the first of these addresses. Support for multiple address
mappings may be provided in a future release.
</para>
</note>
<para>
In general, DHCPv6 will generate DDNS udpate requests when:
</para>
<para>
1. A new lease is granted in response to a DHCP REQUEST
</para>
<para>
2. An existing lease is renewed but the FQDN associated with it has
changed.
</para>
<para>
3. An existing lease is released in response to a DHCP RELEASE
</para>
<para>
In the second case, lease renewal, to DDNS requests will be issued: one
request to remove entries for the previous FQDN and a second request to
add entries for th new FQDN. In the last case, a lease release, a
single DDNS request to remove its entries will be made. The decision
making involved when granting a new lease is more involved and is
discussed next.
</para>
<para>
DHCPv6 will generate a DDNS update request only if the DHCP REQUEST
contains the FQDN option (code 39). By default the DHCPv6 server will
respect the FQDN N and S flags specified by the client as shown in the
following table:
</para>
<table id="fqdn-flag-table">
<title>Default FQDN Flag Behavior</title>
<tgroup cols='4' align='left'>
<colspec colname='cflags'/>
<colspec colname='meaning'/>
<colspec colname='response'/>
<colspec colname='sflags'/>
<thead>
<row>
<entry>Client Flags:N-S</entry>
<entry>Client Intent</entry>
<entry>Server Response</entry>
<entry>Server Flags:N-S-O</entry>
</row>
</thead>
<tbody>
<row>
<entry>0-0</entry>
<entry>Client wants to perform forward DNS updates</entry>
<entry>Server does not generate request</entry>
<entry>1-0-0</entry>
</row>
<row>
<entry>0-1</entry>
<entry>Client wants the server to perform forward DNS updates</entry>
<entry>Server generates request</entry>
<entry>0-1-0</entry>
</row>
<row>
<entry>1-0</entry>
<entry>Client wants no DNS udpates done</entry>
<entry>Server does not generate request</entry>
<entry>1-0-0</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The first row in the table above represents "client delegation". Here
the DHCP client states that it intends to do the forward DNS updates and
therefore the server should not attempt them. The parameter,
"override-client-update", can be used to instruct the server to override
client delegation requests. When this parameter is true, DHCPv6 will
generate DDNS udpate request to D2 even if the client requests delegation.
The N-S-O flags in the server's response to the client will be 0-1-1
respectively.
</para>
<para>
To override client delegation, issue the following commands:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/override-client-update true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The third row in the table above describes the case in which the client
requests that no DNS updates be done. The parameter, "override-no-update",
can be used to instruct the server to disregard the client's wishes. When
this parameter is true, DHCPv6 will generate DDNS udpate request to D2
even if the client requests no updates be done. The N-S-O flags in the
server's response to the client will be 0-1-1.
</para>
<para>
To override client delegation, issue the following commands:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/override-no-update true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</section>
<section id="dhcpv6-fqdn-name-generation">
<title>DHCPv6 name generation for DDNS update requests</title>
Each NameChangeRequest must of course include the fully qualified domain
name whose DNS entries are to be affected. DHCPv6 can be configured to
supply a portion or all of that name based upon what it receives from
the client in the DHCP REQUEST.
<para>
The rules for determining the FQDN option are as follows:
</para>
<para>
If configured to do so ignore the REQUEST contents and generate a
FQDN using a configurable prefix and suffix.
</para>
<para>
Otherwise, using is the domain name value from the client FQDN option as
the candidate name:
</para>
<para>
1. If the candidate name is a fully qualified domain name then use it.
</para>
<para>
2. If the candidate name is a partial (i.e. unqualified) name then
add a configurable suffix to the name and use the result as the FQDN.
</para>
<para>
3. If the candidate name is a empty then generate a FQDN using a
configurable prefix and suffix.
</para>
<para>
To instruct DHCPv6 to always generate a FQDN, set the parmeter,
"replace-client-name", to true as follows:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/replace-client-name true</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The prefix used when generating a FQDN is specified by the
"generated-prefix" parameter. The default value is "myhost". To alter
its value simply set it to the desired string:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/generated-prefix "another.host"</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<para>
The suffix used when generating a FQDN or when qualifying a partial
name is specified by the "qualifying-suffix" parameter. The default
value is "example.com". To alter its value simply set it to the desired
string:
</para>
<screen>
&gt; <userinput>config set Dhcp6/dhcp-ddns/generated-prefix "our.net"</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</section>
<para>
When qualifying a partial name, DHCPv6 will construct name of with the
format:
</para>
<para>
[candidate-name].[qualifying-suffix].
</para>
<para>
where candidate-name is the partial name supplied in the REQUEST.
For example, if FQDN domain name value was "some-computer" and assuming
the default value for qualifying-suffix, the generated FQDN would be:
</para>
<para>
some-computer.example.com.
</para>
<para>
When generating a the entire name, DHCPv6 will construct name of the
format:
</para>
<para>
[generated-prefix]-[address-text].[qualifying-suffix].
</para>
<para>