Commit 23319d1c authored by Francis Dupont's avatar Francis Dupont
Browse files

[master] Began -t support for D2/CA

parent b2c5cb75
......@@ -97,9 +97,14 @@
</listitem>
<listitem>
<simpara>
<command>-W</command> - prints out Kea configuration report
and exits.
</simpara>
<command>-t <replaceable>file</replaceable></command>
specifies the configuration file to be tested. Kea-dhcp-ddns
will attempt to load it, and will conduct sanity checks.
Note that certain checks are possible only while running
the actual server. The actual status is reported with exit
code (0 = configuration looks ok, 1 = error encountered).
Kea will print out log messages to standard output and error
to standard error when testing configuration.</simpara>
</listitem>
</itemizedlist>
......@@ -152,9 +157,9 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
<section id="d2-configuration">
<title>Configuring the DHCP-DDNS Server</title>
<para>
Before starting <command>kea-dhcp-ddns</command> module for the
first time, a configuration file needs to be created. The following default
configuration is a template that can be customised to your requirements.
Before starting <command>kea-dhcp-ddns</command> module for the
first time, a configuration file needs to be created. The following default
configuration is a template that can be customised to your requirements.
<screen>
<userinput>"DhcpDdns": {
"ip-address": "127.0.0.1",
......@@ -164,10 +169,10 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
"ncr-format": "JSON",
"tsig-keys": [ ],
"forward-ddns": {
"ddns-domains": [ ]
"ddns-domains": [ ]
},
"reverse-ddns": {
"ddns-domains": [ ]
"ddns-domains": [ ]
}
}</userinput>
</screen>
......@@ -176,30 +181,30 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
The configuration can be divided as follows, each of which is described
in its own section:
</para>
<itemizedlist>
<listitem>
<simpara>
<itemizedlist>
<listitem>
<simpara>
<emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
</simpara>
</listitem>
<listitem>
<simpara>
<emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
<emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
<emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
</itemizedlist>
</simpara>
</listitem>
<listitem>
<simpara>
<emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
<emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
<emphasis>Reverse DDNS</emphasis> - 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>
<itemizedlist>
<listitem><simpara>
......@@ -231,11 +236,11 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
</simpara></listitem>
</itemizedlist>
<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",
......@@ -243,19 +248,19 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
...
}
}</screen>
</para>
<warning>
<simpara>
It is possible for a malicious attacker to send bogus
NameChangeRequests to the DHCP-DDNS server. Addresses
other than the IPv4 or IPv6 loopback addresses (127.0.0.1
or ::1) should only be used for testing purposes, but
note that local users may still communicate with the
DHCP-DDNS server. A future version of Kea will implement
authentication to guard against such attacks.
</simpara>
</para>
<warning>
<simpara>
It is possible for a malicious attacker to send bogus
NameChangeRequests to the DHCP-DDNS server. Addresses
other than the IPv4 or IPv6 loopback addresses (127.0.0.1
or ::1) should only be used for testing purposes, but
note that local users may still communicate with the
DHCP-DDNS server. A future version of Kea will implement
authentication to guard against such attacks.
</simpara>
<!-- see ticket #3514 -->
</warning>
</warning>
<note>
<simpara>
If the ip-address and port are changed, it will be necessary to change the
......@@ -265,96 +270,96 @@ 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>
<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> -
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> -
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>digest-bits</command> -
is used to specify the minimum truncated length in bits.
The default value 0 means truncation is forbidden, non-zero
values must be an integral number of octets, be greater
than 80 and the half of the full length. Note in BIND9
this parameter is appended after a dash to the algorithm
name.
</simpara>
</listitem>
<listitem>
<simpara>
<command>secret</command> -
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:
<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>
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> -
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> -
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>digest-bits</command> -
is used to specify the minimum truncated length in bits.
The default value 0 means truncation is forbidden, non-zero
values must be an integral number of octets, be greater
than 80 and the half of the full length. Note in BIND9
this parameter is appended after a dash to the algorithm
name.
</simpara>
</listitem>
<listitem>
<simpara>
<command>secret</command> -
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." {
......@@ -363,7 +368,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>,
......@@ -371,333 +376,333 @@ 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.",
"algorithm": "HMAC-SHA224",
"secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
}</userinput>
"name": "key.four.example.com.",
"algorithm": "HMAC-SHA224",
"secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
}</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>
"DhcpDdns": {
<userinput>"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 (i.e. name to
address mapping) 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>
This 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> -
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> -
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.
</simpara>
</listitem>
<listitem>
<simpara>
<command>dns-servers</command> -
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 (i.e. name to
address mapping) 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>
This 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> -
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> -
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.
</simpara>
</listitem>
<listitem>
<simpara>
<command>dns-servers</command> -
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": [
<userinput>{
"name": "other.example.com.",
"key-name": "",
"dns-servers": [
]
}</userinput>
]
"ddns-domains": [
<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>
This 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> -
The resolvable host name of the DNS server. This value is not
yet implemented.
</simpara>
</listitem>
<listitem>
<simpara>
<command>ip-address</command> -
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> -
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 in 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>
This 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> -
The resolvable host name of the DNS server. This value is not
yet implemented.
</simpara>
</listitem>
<listitem>
<simpara>
<command>ip-address</command> -
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> -
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 in 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": [
{
"name": "other.example.com.",
"key-name": "",
"dns-servers": [
<userinput>{
"hostname": "",
"ip-address": "172.88.99.10",
"port": 53
}</userinput>
]
}
]
"ddns-domains": [
{
"name": "other.example.com.",
"key-name": "",
"dns-servers": [
<userinput>{
"hostname": "",
"ip-address": "172.88.99.10",
"port": 53
}</userinput>
]
}
]
}
}
</screen>
</para>
</para>