Commit 5f262cb1 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[3468] Whitespace clean-up in DDNS module.

parent 1d1af085
......@@ -70,9 +70,9 @@
<section id="d2-configuration">
<title>Configuring the DHCP-DDNS Server</title>
<para>
Before staring <command>kea-dhcp-ddns</command> module for the
Before staring <command>kea-dhcp-ddns</command> module for the
first time, a configuration file needs to be created. The following default
configuration seems reasonable in most cases:
configuration seems reasonable in most cases:
<screen>
<userinput>"DhcpDdns": {
"ip_address": "127.0.0.1",
......@@ -82,10 +82,10 @@
"ncr_format": "JSON",
"tsig_keys": [ ],
"forward_ddns": {
"ddns_domains": [ ]
"ddns_domains": [ ]
},
"reverse_ddns": {
"ddns_domains": [ ]
"ddns_domains": [ ]
}
}</userinput>
</screen>
......@@ -94,34 +94,34 @@
The configuration can be divided as follows, each of which is described
in its own section:
</para>
<itemizedlist>
<listitem>
<simpara>
<command>Global Server Parameters</command> &mdash;
values which control connectivity and global server behavior
</simpara>
</listitem>
<listitem>
<simpara>
<command>TSIG Key Info</command> &mdash;
defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
<command>Forward DDNS</command> &mdash;
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
<command>Reverse DDNS</command> &mdash;
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<simpara>
<command>Global Server Parameters</command> &mdash;
values which control connectivity and global server behavior
</simpara>
</listitem>
<listitem>
<simpara>
<command>TSIG Key Info</command> &mdash;
defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
<command>Forward DDNS</command> &mdash;
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
<command>Reverse DDNS</command> &mdash;
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
</itemizedlist>
<section id="d2-server-parameter-config">
<title>Global Server Parameters</title>
<title>Global Server Parameters</title>
<orderedlist>
<listitem><para>
ip_address - IP address on which D2 listens for requests. The default is
......@@ -148,11 +148,11 @@
message.
</para></listitem>
</orderedlist>
<para>
D2 must listen for change requests on a known address and port. By
default it listens at 127.0.0.1 on port 53001. The following example
illustrates how to change D2's global parameters so it will listen
at 192.168.1.10 port 900:
<para>
D2 must listen for change requests on a known address and port. By
default it listens at 127.0.0.1 on port 53001. The following example
illustrates how to change D2's global parameters so it will listen
at 192.168.1.10 port 900:
<screen>
"DhcpDdns": {
<userinput>"ip_address": "192.168.1.10",
......@@ -160,18 +160,18 @@
...
}
}</screen>
</para>
<warning>
<simpara>
When the DHCP-DDNS server is configured to listen at an address
other than the loopback address (127.0.0.1 or ::1), it is possible
for a malicious attacker to send bogus NameChangeRequests to it
and change entries in the DNS. For this reason, addresses other
than the IPv4 or IPv6 loopback addresses should only be used
for testing purposes. A future version of Kea will implement
authentication to guard against such attacks.
</simpara>
</warning>
</para>
<warning>
<simpara>
When the DHCP-DDNS server is configured to listen at an address
other than the loopback address (127.0.0.1 or ::1), it is possible
for a malicious attacker to send bogus NameChangeRequests to it
and change entries in the DNS. For this reason, addresses other
than the IPv4 or IPv6 loopback addresses should only be used
for testing purposes. A future version of Kea will implement
authentication to guard against such attacks.
</simpara>
</warning>
<note>
<simpara>
If the ip_address and port are changed, it will be necessary to change the
......@@ -181,85 +181,85 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</section> <!-- "d2-server-parameter-config" -->
<section id="d2-tsig-key-list-config">
<title>TSIG Key List</title>
<para>
A DDNS protocol exchange can be conducted with or without TSIG
(defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
2845</ulink>). This configuration section allows the administrator
to define the set of TSIG keys that may be used in such
exchanges.</para>
<title>TSIG Key List</title>
<para>
A DDNS protocol exchange can be conducted with or without TSIG
(defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
2845</ulink>). This configuration section allows the administrator
to define the set of TSIG keys that may be used in such
exchanges.</para>
<para>To use TSIG when updating entries in a DNS Domain,
a key must be defined in the TSIG Key List and referenced by
name in that domain's configuration entry. When D2 matches a
change request to a domain, it checks whether the domain has
a TSIG key associated with it. If so, D2 will use that key to
sign DNS update messages sent to and verify responses received
from the domain's DNS server(s). For each TSIG key required by
the DNS servers that D2 will be working with there must be a
corresponding TSIG key in the TSIG Key list.</para>
<para>To use TSIG when updating entries in a DNS Domain,
a key must be defined in the TSIG Key List and referenced by
name in that domain's configuration entry. When D2 matches a
change request to a domain, it checks whether the domain has
a TSIG key associated with it. If so, D2 will use that key to
sign DNS update messages sent to and verify responses received
from the domain's DNS server(s). For each TSIG key required by
the DNS servers that D2 will be working with there must be a
corresponding TSIG key in the TSIG Key list.</para>
<para>
As one might gather from the name, the tsig_key section of the
D2 configuration lists the TSIG keys. Each entry describes a
TSIG key used by one or more DNS servers to authenticate requests
and sign responses. Every entry in the list has three parameters:
<itemizedlist>
<listitem>
<simpara>
<command>name</command> &mdash;
a unique text label used to identify this key within the
list. This value is used to specify which key (if any) should be
used when updating a specific domain. So long as it is unique its
content is arbitrary, although for clarity and ease of maintenance
it is recommended that it match the name used on the DNS server(s).
It cannot be blank.
</simpara>
</listitem>
<listitem>
<simpara>
<command>algorithm</command> &mdash;
specifies which hashing algorithm should be used with this
key. This value must specify the same algorithm used for the
key on the DNS server(s). The supported algorithms are listed below:
<itemizedlist>
<listitem>
<command>HMAC-MD5</command>
</listitem>
<listitem>
<command>HMAC-SHA1</command>
</listitem>
<listitem>
<command>HMAC-SHA224</command>
</listitem>
<listitem>
<command>HMAC-SHA256</command>
</listitem>
<listitem>
<command>HMAC-SHA384</command>
</listitem>
<listitem>
<command>HMAC-SHA512</command>
</listitem>
</itemizedlist>
This value is not case sensitive.
</simpara>
</listitem>
<listitem>
<simpara>
<command>secret</command> &mdash;
is used to specify the shared secret key code for this key. This value is
case sensitive and must exactly match the value specified on the DNS server(s).
It is a base64-encoded text value.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
As an example, suppose that a domain D2 will be updating is
maintained by a BIND9 DNS server which requires dynamic updates
to be secured with TSIG. Suppose further that the entry for
the TSIG key in BIND9's named.conf file looks like this:
<para>
As one might gather from the name, the tsig_key section of the
D2 configuration lists the TSIG keys. Each entry describes a
TSIG key used by one or more DNS servers to authenticate requests
and sign responses. Every entry in the list has three parameters:
<itemizedlist>
<listitem>
<simpara>
<command>name</command> &mdash;
a unique text label used to identify this key within the
list. This value is used to specify which key (if any) should be
used when updating a specific domain. So long as it is unique its
content is arbitrary, although for clarity and ease of maintenance
it is recommended that it match the name used on the DNS server(s).
It cannot be blank.
</simpara>
</listitem>
<listitem>
<simpara>
<command>algorithm</command> &mdash;
specifies which hashing algorithm should be used with this
key. This value must specify the same algorithm used for the
key on the DNS server(s). The supported algorithms are listed below:
<itemizedlist>
<listitem>
<command>HMAC-MD5</command>
</listitem>
<listitem>
<command>HMAC-SHA1</command>
</listitem>
<listitem>
<command>HMAC-SHA224</command>
</listitem>
<listitem>
<command>HMAC-SHA256</command>
</listitem>
<listitem>
<command>HMAC-SHA384</command>
</listitem>
<listitem>
<command>HMAC-SHA512</command>
</listitem>
</itemizedlist>
This value is not case sensitive.
</simpara>
</listitem>
<listitem>
<simpara>
<command>secret</command> &mdash;
is used to specify the shared secret key code for this key. This value is
case sensitive and must exactly match the value specified on the DNS server(s).
It is a base64-encoded text value.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
As an example, suppose that a domain D2 will be updating is
maintained by a BIND9 DNS server which requires dynamic updates
to be secured with TSIG. Suppose further that the entry for
the TSIG key in BIND9's named.conf file looks like this:
<screen>
:
key "key.four.example.com." {
......@@ -268,7 +268,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
};
:
</screen>
By default, the TSIG Key list is empty:
By default, the TSIG Key list is empty:
<screen>
"DhcpDdns": {
<userinput>"tsig_keys": [ ]</userinput>,
......@@ -276,557 +276,557 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
}
</screen>
We must extend the list with a new key:
We must extend the list with a new key:
<screen>
"DhcpDdns": {
"tsig_keys": [
<userinput> {
"name": "key.four.example.com",
"name": "key.four.example.com",
"algorithm": "HMAC-SHA224",
"secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
}</userinput>
}</userinput>
],
...
}
</screen>
</para>
</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>
<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>
</section>
<!-- "d2-tsig-key-list-config" -->
<!-- "d2-tsig-key-list-config" -->
<section id="d2-forward-ddns-config">
<title>Forward DDNS</title>
<para>
The Forward DDNS section is used to configure D2's forward update
behavior. Currently it contains a single parameter, the catalog of
forward DDNS Domains, which is a list of structures.
<title>Forward DDNS</title>
<para>
The Forward DDNS section is used to configure D2's forward update
behavior. Currently it contains a single parameter, the catalog of
forward DDNS Domains, which is a list of structures.
<screen>
<userinput>"DhcpDdns": {
"forward_ddns": {
"ddns_domains": [ ]
"ddns_domains": [ ]
},
...
}</userinput>
</screen>
By default, this list is empty, which will cause the server to ignore
the forward update portions of requests.
</para>
<section id="add-forward-ddns-domain">
<title>Adding Forward DDNS Domains</title>
<para>
A forward DDNS Domain maps a forward DNS zone to a set of DNS servers
which maintain the forward DNS data for that zone. You will need one
forward DDNS Domain for each zone you wish to service. It may very
well be that some or all of your zones are maintained by the same
servers. You will still need one DDNS Domain per zone. Remember that
matching a request to the appropriate server(s) is done by zone and
a DDNS Domain only defines a single zone.
</para>
<para>
The section describes how to add Forward DDNS Domains. Repeat these
steps for each Forward DDNS Domain desired. Each Forward DDNS Domain
has the following parameters:
<itemizedlist>
<listitem>
<simpara>
<command>name</command> &mdash;
The fully qualified domain name (or zone) that this DDNS Domain
can update. This is value used to compare against the request
FQDN during forward matching. It must be unique within the
catalog.
</simpara>
</listitem>
<listitem>
<simpara>
<command>key_name</command> &mdash;
If TSIG is used with this domain's servers, this
value should be the name of the key from within the TSIG Key List
to use. If the value is blank (the default), TSIG will not be
used in DDNS conversations with this domain's servers. Currently
TSIG has not been implemented, so this value is ignored.
</simpara>
</listitem>
<listitem>
<simpara>
<command>dns_servers</command> &mdash;
A list of one or more DNS servers which can conduct the server
side of the DDNS protocol for this domain. The servers
are used in a first to last preference. In other words, when D2
begins to process a request for this domain it will pick the
first server in this list and attempt to communicate with it.
If that attempt fails, it will move to next one in the list and
so on until the it achieves success or the list is exhausted.
</simpara>
</listitem>
</itemizedlist>
To create a new forward DDNS Domain, one must add a new domain
element and set its parameters:
By default, this list is empty, which will cause the server to ignore
the forward update portions of requests.
</para>
<section id="add-forward-ddns-domain">
<title>Adding Forward DDNS Domains</title>
<para>
A forward DDNS Domain maps a forward DNS zone to a set of DNS servers
which maintain the forward DNS data for that zone. You will need one
forward DDNS Domain for each zone you wish to service. It may very
well be that some or all of your zones are maintained by the same
servers. You will still need one DDNS Domain per zone. Remember that
matching a request to the appropriate server(s) is done by zone and
a DDNS Domain only defines a single zone.
</para>
<para>
The section describes how to add Forward DDNS Domains. Repeat these
steps for each Forward DDNS Domain desired. Each Forward DDNS Domain
has the following parameters:
<itemizedlist>
<listitem>
<simpara>
<command>name</command> &mdash;
The fully qualified domain name (or zone) that this DDNS Domain
can update. This is value used to compare against the request
FQDN during forward matching. It must be unique within the
catalog.
</simpara>
</listitem>
<listitem>
<simpara>
<command>key_name</command> &mdash;
If TSIG is used with this domain's servers, this
value should be the name of the key from within the TSIG Key List
to use. If the value is blank (the default), TSIG will not be
used in DDNS conversations with this domain's servers. Currently
TSIG has not been implemented, so this value is ignored.
</simpara>
</listitem>
<listitem>
<simpara>
<command>dns_servers</command> &mdash;
A list of one or more DNS servers which can conduct the server
side of the DDNS protocol for this domain. The servers
are used in a first to last preference. In other words, when D2
begins to process a request for this domain it will pick the
first server in this list and attempt to communicate with it.
If that attempt fails, it will move to next one in the list and
so on until the it achieves success or the list is exhausted.
</simpara>
</listitem>
</itemizedlist>
To create a new forward DDNS Domain, one must add a new domain
element and set its parameters:
<screen>
"DhcpDdns": {
"forward_ddns": {
"ddns_domains": [
"ddns_domains": [
<userinput>{
"name": "other.example.com",
"key_name": "",
"dns_servers": [
]
}</userinput>
]
"name": "other.example.com",
"key_name": "",
"dns_servers": [
]
}</userinput>
]
}
}
</screen>
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
order to make the domain useful though, we must add at least one DNS
server to it.
</para>
<section id="add-forward-dns-servers">
<title>Adding Forward DNS Servers</title>
<para>
The section describes how to add DNS servers to a Forward DDNS Domain.
Repeat them for as many servers as desired for a each domain.
</para>
<para>
Forward DNS Server entries represent actual DNS servers which
support the server side of the DDNS protocol. Each Forward DNS Server
has the following parameters:
<itemizedlist>
<listitem>
<simpara>
<command>hostname</command> &mdash;
The resolvable host name of the DNS server. This value is not
yet implemented.
</simpara>
</listitem>
<listitem>
<simpara>
<command>ip_address</command> &mdash;
The IP address at which the server listens for DDNS requests.
This may be either an IPv4 or an IPv6 address.
</simpara>
</listitem>
<listitem>
<simpara>
<command>port</command> &mdash;
The port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
</simpara>
</listitem>
</itemizedlist>
To create a new forward DNS Server, one must add a new server
element to the domain and fill its parameters. If for
example the service is running at "172.88.99.10", then set it as
follows:
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
order to make the domain useful though, we must add at least one DNS
server to it.
</para>
<section id="add-forward-dns-servers">
<title>Adding Forward DNS Servers</title>
<para>
The section describes how to add DNS servers to a Forward DDNS Domain.
Repeat them for as many servers as desired for a each domain.
</para>
<para>
Forward DNS Server entries represent actual DNS servers which
support the server side of the DDNS protocol. Each Forward DNS Server
has the following parameters:
<itemizedlist>
<listitem>
<simpara>
<command>hostname</command> &mdash;
The resolvable host name of the DNS server. This value is not
yet implemented.
</simpara>
</listitem>
<listitem>
<simpara>
<command>ip_address</command> &mdash;
The IP address at which the server listens for DDNS requests.
This may be either an IPv4 or an IPv6 address.
</simpara>
</listitem>
<listitem>
<simpara>
<command>port</command> &mdash;
The port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
</simpara>
</listitem>
</itemizedlist>
To create a new forward DNS Server, one must add a new server
element to the domain and fill its parameters. If for
example the service is running at "172.88.99.10", then set it as
follows:
<screen>
"DhcpDdns": {
"forward_ddns": {
"ddns_domains": [
"ddns_domains": [
{
"name": "other.example.com",
"key_name": "",
"dns_servers": [
<userinput>{
"hostname": "",
"name": "other.example.com",
"key_name": "",
"dns_servers": [
<userinput>{
"hostname": "",
"ip_address": "172.88.99.10",
"port": 53
}</userinput>
]
}
]
}</userinput>
]
}
]
}
}
</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>
</section> <!-- "add-forward-dns-servers" -->
As stated earlier, "hostname" is not yet supported so, the parameter
"ip_address" must be set to the address of the DNS server.
</para>
</section> <!-- "add-forward-dns-servers" -->
</section> <!-- "add-forward-ddns-domains" -->
</section> <!-- "d2-forward-ddns-config" -->
<section id="d2-reverse-ddns-config">
<title>Reverse DDNS</title>
<para>
The Reverse DDNS section is used to configure D2's reverse update
behavior, and the concepts are the same as for the forward DDNS
section. Currently it contains a single parameter, the catalog of
reverse DDNS Domains, which is a list of structures.
<title>Reverse DDNS</title>
<para>
The Reverse DDNS section is used to configure D2's reverse update
behavior, and the concepts are the same as for the forward DDNS
section. Currently it contains a single parameter, the catalog of
reverse DDNS Domains, which is a list of structures.
<screen>
"DhcpDdns": {
"reverse_ddns": {
"ddns_domains": [ ]
"ddns_domains": [ ]
}
}
</screen>
By default, this list is empty, which will cause the server to ignore
the reverse update portions of requests.
</para>
<section id="add-reverse-ddns-domain">
<title>Adding Reverse DDNS Domains</title>
<para>
A reverse DDNS Domain maps a reverse DNS zone to a set of DNS servers
which maintain the reverse DNS data for that zone. You will need one