mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-01 06:25:34 +00:00
Code Issues Releases Wiki Activity

[3468] DDNS chapter updated.

Browse Source
This commit is contained in:
Tomek Mrugalski
2014-08-04 22:11:11 +02:00
parent 2e3a09b38f
commit 1d1af085db
2 changed files with 203 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/guide/Makefile.am
View File

@@ -6,7 +6,7 @@ dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) kea-guide.css dist_html_DATA = $(HTMLDOCS) kea-guide.css
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml config.xml DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml config.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml ddns.xml
EXTRA_DIST = $(DOCBOOK) EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml

383
doc/guide/ddns.xml
View File

@@ -51,36 +51,17 @@
<section id="dhcp-ddns-server-start-stop"> <section id="dhcp-ddns-server-start-stop">
<title>Starting and Stopping the DHCP-DDNS Server</title> <title>Starting and Stopping the DHCP-DDNS Server</title>
<para> <para>
<command>kea-dhcp-ddns</command> is the BIND 10 DHCP-DDNS server and, It is recommended to control DHCPv4 server in Kea using <command>keactl</command>,
like other parts of BIND 10, is configured through the which is described in details in <xref linkend="keactrl"/>.
<command>bindctl</command> program.
</para> </para>
<para> <para>
After starting BIND 10 and entering bindctl, the first step in <command>kea-dhcp-ddns</command> is the Kea DHCP-DDNS server and,
configuring the server is to add it to the list of running BIND 10 like other parts of Kea, is a separate binary that can be run on
services. its own or through <command>keactl</command>. Due to the nature
<screen> of DDNS, it is run along with either DHCPv4 or DHCPv6 components
&gt; <userinput>config add Init/components kea-dhcp-ddns</userinput> (or both).
&gt; <userinput>config set Init/components/kea-dhcp-ddns/kind dispensable</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para> </para>
<para>
To remove <command>kea-dhcp-ddns</command> from the set of running services,
the <command>kea-dhcp-ddns</command> is removed from list of Init components:
<screen>
&gt; <userinput>config remove Init/components kea-dhcp-ddns</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para>
<para>
Note that the server was only removed from the list, so it will not be
automatically restarted, but the server itself is still running. Hence it
is usually desired to stop it:
</para>
<screen>
&gt; <userinput>DhcpDdns shutdown</userinput>
</screen>
<para> <para>
Upon start up the module will load its configuration and begin listening Upon start up the module will load its configuration and begin listening
for NCRs based on that configuration. for NCRs based on that configuration.
@@ -89,27 +70,25 @@
<section id="d2-configuration"> <section id="d2-configuration">
<title>Configuring the DHCP-DDNS Server</title> <title>Configuring the DHCP-DDNS Server</title>
<para> <para>
Once the server is started, it can be configured. To view the Before staring <command>kea-dhcp-ddns</command> module for the
current configuration, use the following command in <command>bindctl</command>: first time, a configuration file needs to be created. The following default
<screen> configuration seems reasonable in most cases:
&gt; <userinput>config show DhcpDdns</userinput></screen>
When starting kea-dhcp-ddns module for the first time, the default
configuration will be available. It will look similar to this:
<screen> <screen>
&gt; <userinput>config show DhcpDdns</userinput> <userinput>"DhcpDdns": {
DhcpDdns/ip_address "127.0.0.1" string (default) "ip_address": "127.0.0.1",
DhcpDdns/port 53001 integer (default) "port": 53001,
DhcpDdns/dns_server_timeout 100 integer (default) "dns_server_timeout": 100,
DhcpDdns/ncr_protocol "UDP" string (default) "ncr_protocol": "UDP",
DhcpDdns/ncr_format "JSON" string (default) "ncr_format": "JSON",
DhcpDdns/tsig_keys [] list (default) "tsig_keys": [ ],
DhcpDdns/forward_ddns/ddns_domains [] list (default) "forward_ddns": {
DhcpDdns/reverse_ddns/ddns_domains [] list (default) "ddns_domains": [ ]
},
"reverse_ddns": {
"ddns_domains": [ ]
}
}</userinput>
</screen> </screen>
<para>
(While displayed, the parameter "interface" is not implemented, and
will be removed in the near future.)
</para>
</para> </para>
<para> <para>
The configuration can be divided as follows, each of which is described The configuration can be divided as follows, each of which is described
@@ -175,10 +154,12 @@ DhcpDdns/reverse_ddns/ddns_domains [] list (default)
illustrates how to change D2's global parameters so it will listen illustrates how to change D2's global parameters so it will listen
at 192.168.1.10 port 900: at 192.168.1.10 port 900:
<screen> <screen>
&gt; <userinput>config set DhcpDdns/ip_address "192.168.1.10"</userinput> "DhcpDdns": {
&gt; <userinput>config set DhcpDdns/port 900</userinput> <userinput>"ip_address": "192.168.1.10",
&gt; <userinput>config commit</userinput> "port": 900,</userinput>
</screen> ...
}
}</screen>
</para> </para>
<warning> <warning>
<simpara> <simpara>
@@ -289,42 +270,47 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</screen> </screen>
By default, the TSIG Key list is empty: By default, the TSIG Key list is empty:
<screen> <screen>
<userinput>> config show DhcpDdns/tsig_keys</userinput> "DhcpDdns": {
DhcpDdns/tsig_keys [] list (default) <userinput>"tsig_keys": [ ]</userinput>,
...
}
</screen> </screen>
We must first create a new key in the list:
We must extend the list with a new key:
<screen> <screen>
<userinput>> config add DhcpDdns/tsig_keys</userinput> "DhcpDdns": {
</screen> "tsig_keys": [
Displaying the new element, reveals: <userinput> {
<screen> "name": "key.four.example.com",
<userinput>> config show DhcpDdns/tsig_keys[0]</userinput> "algorithm": "HMAC-SHA224",
DhcpDdns/tsig_keys[0]/name "" string (default) "secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5" string (modified) }</userinput>
DhcpDdns/tsig_keys[0]/secret "" string (default) ],
</screen> ...
Now set all three values to match BIND9's key: }
<screen>
<userinput>> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com"</userinput>
<userinput>> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224"</userinput>
<userinput>> config set DhcpDdns/tsig_keys[0]/secret "bZEG7Ow8OgAUPfLWV3aAUQ=="</userinput>
<userinput>> config commit</userinput>
</screen> </screen>
</para> </para>
These steps would be repeated for each TSIG key needed. Note that the same TSIG key
can be used with more than one domain. <para>These steps would be repeated for each TSIG key needed. Note that
</section> <!-- "d2-tsig-key-list-config" --> the same TSIG key can be used with more than one domain.</para>
</section>
<!-- "d2-tsig-key-list-config" -->
<section id="d2-forward-ddns-config"> <section id="d2-forward-ddns-config">
<title>Forward DDNS</title> <title>Forward DDNS</title>
<para> <para>
The Forward DDNS section is used to configure D2's forward update The Forward DDNS section is used to configure D2's forward update
behavior. Currently it contains a single parameter, the catalog of behavior. Currently it contains a single parameter, the catalog of
forward DDNS Domains: forward DDNS Domains, which is a list of structures.
<screen> <screen>
<userinput>> config show DhcpDdns/forward_ddns/</userinput> <userinput>"DhcpDdns": {
DhcpDdns/forward_ddns/ddns_domains [] list (default) "forward_ddns": {
"ddns_domains": [ ]
},
...
}</userinput>
</screen> </screen>
By default, this list is empty, which will cause the server to ignore By default, this list is empty, which will cause the server to ignore
the forward update portions of requests. the forward update portions of requests.
</para> </para>
@@ -376,23 +362,23 @@ DhcpDdns/forward_ddns/ddns_domains [] list (default)
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
To create a new forward DDNS Domain, one must first add a new domain To create a new forward DDNS Domain, one must add a new domain
element: element and set its parameters:
<screen> <screen>
<userinput>> config add DhcpDdns/forward_ddns/ddns_domains</userinput> "DhcpDdns": {
</screen> "forward_ddns": {
Displaying the DDNS Domain reveals this: "ddns_domains": [
<screen> <userinput>{
<userinput>> config show DhcpDdns/forward_ddns/ddns_domains[0]</userinput> "name": "other.example.com",
DhcpDdns/forward_ddns/ddns_domains[0]/name "" string (default) "key_name": "",
DhcpDdns/forward_ddns/ddns_domains[0]/key_name "" string (default) "dns_servers": [
DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers [] list (default) ]
</screen> }</userinput>
To set the domain's name to "other.example.com": ]
<screen> }
<userinput>> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "other.example.com"</userinput> }
<userinput>> config commit</userinput>
</screen> </screen>
It is permissible to add a domain without any servers. If that domain It is permissible to add a domain without any servers. If that domain
should be matched to a request, however, the request will fail. In should be matched to a request, however, the request will fail. In
order to make the domain useful though, we must add at least one DNS order to make the domain useful though, we must add at least one DNS
@@ -432,26 +418,32 @@ DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers [] list (default)
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
To create a new forward DNS Server, one must first add a new server To create a new forward DNS Server, one must add a new server
element to the domain: element to the domain and fill its parameters. If for
<screen>
<userinput>> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers</userinput>
</screen>
Displaying the DNS Server element should appear as follows:
<screen>
<userinput>> config show DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]</userinput>
DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/hostname "" string (default)
DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "" string (default)
DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default)
</screen>
As stated earlier, "hostname" is not yet supported so, the parameter
"ip_address" must be set to the address of the DNS server. If for
example the service is running at "172.88.99.10", then set it as example the service is running at "172.88.99.10", then set it as
follows: follows:
<screen> <screen>
<userinput>> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10"</userinput> "DhcpDdns": {
<userinput>> config commit</userinput> "forward_ddns": {
"ddns_domains": [
{
"name": "other.example.com",
"key_name": "",
"dns_servers": [
<userinput>{
"hostname": "",
"ip_address": "172.88.99.10",
"port": 53
}</userinput>
]
}
]
}
}
</screen> </screen>
As stated earlier, "hostname" is not yet supported so, the parameter
"ip_address" must be set to the address of the DNS server.
</para> </para>
</section> <!-- "add-forward-dns-servers" --> </section> <!-- "add-forward-dns-servers" -->
@@ -465,10 +457,13 @@ DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default)
The Reverse DDNS section is used to configure D2's reverse update The Reverse DDNS section is used to configure D2's reverse update
behavior, and the concepts are the same as for the forward DDNS behavior, and the concepts are the same as for the forward DDNS
section. Currently it contains a single parameter, the catalog of section. Currently it contains a single parameter, the catalog of
reverse DDNS Domains: reverse DDNS Domains, which is a list of structures.
<screen> <screen>
<userinput>> config show DhcpDdns/reverse_ddns/</userinput> "DhcpDdns": {
DhcpDdns/reverse_ddns/ddns_domains [] list (default) "reverse_ddns": {
"ddns_domains": [ ]
}
}
</screen> </screen>
By default, this list is empty, which will cause the server to ignore By default, this list is empty, which will cause the server to ignore
the reverse update portions of requests. the reverse update portions of requests.
@@ -527,24 +522,24 @@ DhcpDdns/reverse_ddns/ddns_domains [] list (default)
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
To create a new reverse DDNS Domain, one must first add a new domain To create a new reverse DDNS Domain, one must add a new domain element
element: and set its parameters. For example, to support subnet 2001:db8:1::,
the following configuration could be used:
<screen> <screen>
<userinput>> config add DhcpDdns/reverse_ddns/ddns_domains</userinput> "DhcpDdns": {
</screen> "reverse_ddns": {
Displaying the DDNS Domain reveals this: "ddns_domains": [
<screen> <userinput>{
<userinput>> config show DhcpDdns/reverse_ddns/ddns_domains[0]</userinput> "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
DhcpDdns/reverse_ddns/ddns_domains[0]/name "" string (default) "key_name": "",
DhcpDdns/reverse_ddns/ddns_domains[0]/key_name "" string (default) "dns_servers": [
DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers [] list (default) ]
</screen> }</userinput>
For domain supporting the subnet 2001:db8:1::, we would set the ]
domain's name as follows: }
<screen> }
<userinput>> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."</userinput>
<userinput>> config commit</userinput>
</screen> </screen>
It is permissible to add a domain without any servers. If that domain It is permissible to add a domain without any servers. If that domain
should be matched to a request, however, the request will fail. In should be matched to a request, however, the request will fail. In
order to make the domain useful though, we must add at least one DNS order to make the domain useful though, we must add at least one DNS
@@ -584,25 +579,31 @@ DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers [] list (default)
</listitem> </listitem>
</itemizedlist> </itemizedlist>
To create a new reverse DNS Server, one must first add a new server To create a new reverse DNS Server, one must first add a new server
element to the domain: element to the domain and fill its parameters. If for
<screen>
<userinput>> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers</userinput>
</screen>
Displaying the DNS Server element should appear as follows:
<screen>
<userinput>> config show DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]</userinput>
DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/hostname "" string (default)
DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "" string (default)
DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default)
</screen>
As stated earlier, "hostname" is not yet supported so, the parameter
"ip_address" must be set to the address of the DNS server. If for
example the service is running at "172.88.99.10", then set it as example the service is running at "172.88.99.10", then set it as
follows: follows:
<screen> <screen>
<userinput>> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.88.99.10"</userinput> "DhcpDdns": {
<userinput>> config commit</userinput> "reverse_ddns": {
"ddns_domains": [
{
"name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
"key_name": "",
"dns_servers": [
<userinput>{
"hostname": "",
"ip_address": "172.88.99.10",
"port": 53
}</userinput>
]
}
]
}
}
</screen> </screen>
As stated earlier, "hostname" is not yet supported so, the parameter
"ip_address" must be set to the address of the DNS server.
</para> </para>
</section> <!-- "add-reverse-dns-servers" --> </section> <!-- "add-reverse-dns-servers" -->
@@ -699,28 +700,38 @@ DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default)
<para> <para>
The following series of commands in bindctl will create the Forward The following series of commands in bindctl will create the Forward
DDNS Domains. DDNS Domains.
<screen> <screen><userinput>
<userinput> "DhcpDdns": {
> config add DhcpDdns/forward_ddns/ddns_domains "forward_ddns": {
> config set DhcpDdns/forward_ddns/ddns_domains[0]/name "four.example.com." "ddns_domains": [
> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers {
> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5" "name": "four.example.com.",
> config add DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers "key_name": "",
> config set DhcpDdns/forward_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5" "dns_servers": [
> { "ip_address": "172.16.1.5" },
> config add DhcpDdns/forward_ddns/ddns_domains { "ip_address": "172.16.2.5" }
> config set DhcpDdns/forward_ddns/ddns_domains[1]/name "six.example.com." ]
> config add DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers },
> config set DhcpDdns/forward_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:" {
> "name": "six.example.com.",
> config add DhcpDdns/forward_ddns/ddns_domains "key_name": "",
> config set DhcpDdns/forward_ddns/ddns_domains[2]/name "example.com." "dns_servers": [
> config add DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers { "ip_address": "2001:db8::1" }
> config set DhcpDdns/forward_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5" ]
> },
> config commit {
</userinput> "name": "example.com.",
"key_name": "",
"dns_servers": [
{ "ip_address": "172.16.2.5" }
]
},
]
}
}</userinput>
</screen> </screen>
</para> </para>
<para> <para>
Similarly, we need to construct the three reverse DDNS Domains: Similarly, we need to construct the three reverse DDNS Domains:
@@ -763,28 +774,38 @@ DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/port 53 integer(default)
<para> <para>
The following series of commands in bindctl will create our Reverse The following series of commands in bindctl will create our Reverse
DDNS Domains. DDNS Domains.
<screen>
<userinput> <screen><userinput>
> config add DhcpDdns/reverse_ddns/ddns_domains "DhcpDdns": {
> config set DhcpDdns/reverse_ddns/ddns_domains[0]/name "2.0.192.in-addr.arpa." "reverse_ddns": {
> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers "ddns_domains": [
> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[0]/ip_address "172.16.1.5" {
> config add DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers "name": "2.0.192.in-addr.arpa.",
> config set DhcpDdns/reverse_ddns/ddns_domains[0]/dns_servers[1]/ip_address "172.16.2.5" "key_name": "",
> "dns_servers": [
> config add DhcpDdns/reverse_ddns/ddns_domains { "ip_address": "172.16.1.5" },
> config set DhcpDdns/reverse_ddns/ddns_domains[1]/name "1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa." { "ip_address": "172.16.2.5" }
> config add DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers ]
> config set DhcpDdns/reverse_ddns/ddns_domains[1]/dns_servers[0]/ip_address "3001:1::50:" }
> {
> config add DhcpDdns/reverse_ddns/ddns_domains "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
> config set DhcpDdns/reverse_ddns/ddns_domains[2]/name "0.192.in-addr.arpa." "key_name": "",
> config add DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers "dns_servers": [
> config set DhcpDdns/reverse_ddns/ddns_domains[2]/dns_servers[0]/ip_address "172.16.2.5" { "ip_address": "2001:db8::1" }
> ]
> config commit }
</userinput> {
"name": "0.192.in-addr.arpa.",
"key_name": "",
"dns_servers": [
{ "ip_address": "172.16.2.5" }
]
}
]
}
}</userinput>
</screen> </screen>
</para> </para>
</section> <!-- end of "d2-example" --> </section> <!-- end of "d2-example" -->
</section> <!-- end of section "d2-configuration" --> </section> <!-- end of section "d2-configuration" -->