catalog of servers from which to select. In fact, D2 has two such catalogs,
one for forward DNS and one for reverse DNS; these catalogs are referred
to as DDNS Domain Lists. Each list consists of one or more named DDNS
- Domains. Further, each DDNS Domain has a list of of one or more DNS
+ Domains. Further, each DDNS Domain has a list of one or more DNS
servers that publish the DNS data for that domain.
</para>
<para>
</para>
<section id="dhcp-ddns-server-start-stop">
<title>Starting and Stopping the DHCP-DDNS Server</title>
- <para>
- It is recommended to control DHCPv4 server in Kea using <command>keactl</command>,
- which is described in details in <xref linkend="keactrl"/>.
- </para>
<para>
- <command>kea-dhcp-ddns</command> is the Kea DHCP-DDNS server and,
- like other parts of Kea, is a separate binary that can be run on
- its own or through <command>keactl</command>. Due to the nature
- of DDNS, it is run along with either DHCPv4 or DHCPv6 components
- (or both).
+ <command>kea-dhcp-ddns</command> is the Kea DHCP-DDNS server
+ and, due to the nature of DDNS, it is run alongside either the
+ DHCPv4 or DHCPv6 components (or both). Like other parts of
+ Kea, is a separate binary that can be run on its own or through
+ <command>keactl</command> (see <xref linkend="keactrl"/>). In
+ normal operation, controlling <command>kea-dhcp-ddns</command>
+ with <command>keactl</command> is recommended.
</para>
+
<para>
Upon start up the module will load its configuration and begin listening
for NCRs based on that configuration.
<section id="d2-configuration">
<title>Configuring the DHCP-DDNS Server</title>
<para>
- Before staring <command>kea-dhcp-ddns</command> module for the
+ Before starting <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 is a template that can be customised to your requirements.
<screen>
<userinput>"DhcpDdns": {
"ip_address": "127.0.0.1",
<itemizedlist>
<listitem>
<simpara>
- <command>Global Server Parameters</command> —
+ <command>Global Server Parameters</command> -
values which control connectivity and global server behavior
</simpara>
</listitem>
<listitem>
<simpara>
- <command>TSIG Key Info</command> —
+ <command>TSIG Key Info</command> -
defines the TSIG keys used for secure traffic with DNS servers
</simpara>
</listitem>
<listitem>
<simpara>
- <command>Forward DDNS</command> —
+ <command>Forward DDNS</command> -
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
<listitem>
<simpara>
- <command>Reverse DDNS</command> —
+ <command>Reverse DDNS</command> -
defines the catalog of Forward DDNS Domains
</simpara>
</listitem>
</itemizedlist>
<section id="d2-server-parameter-config">
<title>Global Server Parameters</title>
- <orderedlist>
- <listitem><para>
- ip_address - IP address on which D2 listens for requests. The default is
- the local loopback interface at address 127.0.0.1. You may specify
- either an IPv4 or IPv6 address.
- </para></listitem>
- <listitem><para>
- port - Port on which D2 listens for requests. The default value
+ <itemizedlist>
+
+ <listitem><simpara>
+ <command>ip_address</command> - IP address on which D2
+ listens for requests. The default is the local loopback interface at
+ address 127.0.0.1. You may specify either an IPv4 or IPv6 address.
+ </simpara></listitem>
+
+ <listitem><simpara>
+ <command>port</command> - Port on which D2 listens for requests. The default value
is 53001.
- </para></listitem>
- <listitem><para>
- ncr_format - Socket protocol to use when sending requests to D2.
- Currently only UDP is supported. TCP may be available in an upcoming
- release.
- </para></listitem>
- <listitem><para>
- ncr_protocol - Packet format to use when sending requests to D2.
+ </simpara></listitem>
+
+ <listitem><simpara>
+ <command>dns_server_timeout</command> - The maximum amount
+ of time in milliseconds, that D2 will wait for a response from a
+ DNS server to a single DNS update message.
+ </simpara></listitem>
+
+ <listitem><simpara>
+ <command>ncr_protocol</command> - Packet format to use when sending requests to D2.
Currently only JSON format is supported. Other formats may be available
in future releases.
- </para></listitem>
- <listitem><para>
- dns_server_timeout - The maximum amount of time in milliseconds, that
- D2 will wait for a response from a DNS server to a single DNS update
- message.
- </para></listitem>
- </orderedlist>
+ </simpara></listitem>
+
+ <listitem><simpara>
+ <command>ncr_format</command> - Socket protocol to use when sending requests to D2.
+ Currently only UDP is supported. TCP may be available in an upcoming
+ release.
+ </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
<itemizedlist>
<listitem>
<simpara>
- <command>name</command> —
+ <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
</listitem>
<listitem>
<simpara>
- <command>algorithm</command> —
+ <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:
</listitem>
<listitem>
<simpara>
- <command>secret</command> —
+ <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.
behavior. Currently it contains a single parameter, the catalog of
forward DDNS Domains, which is a list of structures.
<screen>
-<userinput>"DhcpDdns": {
- "forward_ddns": {
+"DhcpDdns": {
+ <userinput>"forward_ddns": {
"ddns_domains": [ ]
- },
+ }</userinput>,
...
-}</userinput>
+}
</screen>
By default, this list is empty, which will cause the server to ignore
<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.
+ 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>
The section describes how to add Forward DDNS Domains. Repeat these
<itemizedlist>
<listitem>
<simpara>
- <command>name</command> —
+ <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
</listitem>
<listitem>
<simpara>
- <command>key_name</command> —
+ <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. Currently
- TSIG has not been implemented, so this value is ignored.
+ used in DDNS conversations with this domain's servers.
</simpara>
</listitem>
<listitem>
<simpara>
- <command>dns_servers</command> —
+ <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
<itemizedlist>
<listitem>
<simpara>
- <command>hostname</command> —
+ <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> —
+ <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> —
+ <command>port</command> -
The port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
</simpara>
}
}
</screen>
+ </para>
+ <note><simpara>
As stated earlier, "hostname" is not yet supported so, the parameter
"ip_address" must be set to the address of the DNS server.
- </para>
+ </simpara></note>
+
</section> <!-- "add-forward-dns-servers" -->
</section> <!-- "add-forward-ddns-domains" -->
reverse DDNS Domains, which is a list of structures.
<screen>
"DhcpDdns": {
- "reverse_ddns": {
+ <userinput>"reverse_ddns": {
"ddns_domains": [ ]
- }
+ }</userinput>
+ ...
}
</screen>
By default, this list is empty, which will cause the server to ignore
<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
- reverse 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; even then, you will still need one DDNS Domain entry for each
- zone. Remember that
- matching a request to the appropriate server(s) is done by zone and
- a DDNS Domain only defines a single zone.
+ A reverse DDNS Domain maps a reverse DNS zone to a set of DNS
+ servers which maintain the reverse DNS data (address to name
+ mapping) for that zone. You will need one reverse 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;
+ even then, you will still need one DDNS Domain entry for each
+ 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 Reverse DDNS Domains. Repeat these
<itemizedlist>
<listitem>
<simpara>
- <command>name</command> —
+ <command>name</command> -
The fully qualified reverse zone that this DDNS Domain
can update. This is the value used during reverse matching
which will compare it with a reversed version of the request's
</listitem>
<listitem>
<simpara>
- <command>key_name</command> —
+ <command>key_name</command> -
If TSIG should be used with this domain's servers, then this
value should be the name of that key from the TSIG Key List.
If the value is blank (the default), TSIG will not be
</listitem>
<listitem>
<simpara>
- <command>dns_servers</command> —
+ <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. Currently the servers
are used in a first to last preference. In other words, when D2
<itemizedlist>
<listitem>
<simpara>
- <command>hostname</command> —
+ <command>hostname</command> -
The resolvable host name of the DNS server. This value is
currently ignored.
</simpara>
</listitem>
<listitem>
<simpara>
- <command>ip_address</command> —
+ <command>ip_address</command> -
The IP address at which the server listens for DDNS requests.
</simpara>
</listitem>
<listitem>
<simpara>
- <command>port</command> —
+ <command>port</command> -
The port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
</simpara>
}
}
</screen>
+</para>
+
+ <note>
+ <simpara>
+ As stated earlier, "hostname" is not yet supported so, the parameter
+ "ip_address" must be set to the address of the DNS server.
+ </simpara>
+ </note>
- 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-reverse-dns-servers" -->
</section> <!-- "add-reverse-ddns-domains" -->
be rejected.
</para>
<para>
- The following series of commands in bindctl will create the Forward
- DDNS Domains.
+ The following example configuration specified the Forward DDNS Domains.
<screen><userinput>
"DhcpDdns": {
"forward_ddns": {
the third domain.
</para>
<para>
- The following series of commands in bindctl will create our Reverse
- DDNS Domains.
+ These Reverse DDNS Domains are specified as follows:
<screen><userinput>
"DhcpDdns": {
<!-- @todo Rewrite this section once #3422 is done -->
<para>
- It is recommended to control DHCPv4 server in Kea using <command>keactl</command>,
- which is described in details in <xref linkend="keactrl"/>.
- </para>
-
- <para>
- However, it is also possible to run the server on its own, not using any
- scripts. The server accepts the following command-line parameters:
+ It is recommended that the Kea DHCPv4 server be started and stopped
+ using <command>keactl</command> (described in <xref linkend="keactrl"/>).
+ However, it is also possible to run the server directly: it accepts
+ the following command-line switches:
</para>
<itemizedlist>
<listitem>
- <simpara>-c file - specifies the configuration file. This is the
- only mandatory parameter (it may be optional for configuration
- parameters other than Kea)</simpara>
+ <simpara>
+ <command>-c <replaceable>file</replaceable></command> -
+ specifies the configuration file. This is the only mandatory
+ switch.</simpara>
</listitem>
<listitem>
- <simpara>-v - specifies whether the server logging should be
- switched to verbose mode. In verbose mode, logging severity and
- debuglevel specified in a configuration file are ignored and
- severity debug and maximum debuglevel (99) is assumed. That flag is
- convenient, for temporarily switching the server into maximum
- verbosity, e.g. when debugging.</simpara>
+ <simpara>
+ <command>-v</command> - specifies whether the server
+ logging should be switched to verbose mode. In verbose mode,
+ the logging severity and debuglevel specified in a configuration
+ file are ignored and "debug" severity and the maximum debuglevel
+ (99) are assumed. The flag is convenient, for temporarily
+ switching the server into maximum verbosity, e.g. when
+ debugging.</simpara>
</listitem>
<listitem>
- <simpara>-p port - specifies UDP port the server will listen
- on. This is only useful during testing, as the DHCPv4 server
- listening on ports other than default DHCPv4 ports will not be able
- to handle regular DHCPv4 queries.</simpara>
+ <simpara>
+ <command>-p <replaceable>port</replaceable></command> -
+ specifies UDP port the server will listen on. This is only
+ useful during testing, as the DHCPv4 server listening on
+ ports other than default DHCPv4 ports will not be able to
+ handle regular DHCPv4 queries.</simpara>
</listitem>
</itemizedlist>
<para>
- The server running in a console can be shut down by pressing ctrl-c. The
- server will detect such a key combination and will initialize shutdown procedure.
+ When running in a console, the server can be shut down by
+ pressing ctrl-c. It detects the key combination and shuts
+ down gracefully.
</para>
<para>
On start-up, the server will detect available network interfaces
- and will attempt to open UDP sockets on all interfaces that
- are mentioned in the configuration file.
+ and will attempt to open UDP sockets on all interfaces
+ mentioned in the configuration file.
</para>
<para>
<title>Introduction</title>
<para>
This section explains how to configure the DHCPv4 server using the
- Kea configuration backend. Kea configuration using any other
- backends is outside of scope for this document. Before DHCPv4
+ Kea configuration backend. (Kea configuration using any other
+ backends is outside of scope of this document.) Before DHCPv4
is started, its configuration file has to be created. The
basic configuration looks as follows:
<screen>
# Next we specify the type of lease database
"lease-database": {
"type": "memfile",
- "persist": true,
+ "persist": "true",
"name": "/var/kea/dhcp4.leases"
},
object called Dhcp4. This is a simplified configuration, as usually
there will be additional objects, like <command>Logging</command> or
<command>DhcpDns</command>, but we omit them now for clarity. The Dhcp4
-configuration starts with the the <command>"Dhcp4: {"</command> line
+configuration starts with the <command>"Dhcp4": {</command> line
and ends with the corresponding closing brace (in the above example,
the brace after the last comment). Everything defined between those
lines is considered to be the Dhcp4 configuration.</para>
<para>After all parameters are specified, we have two contexts open:
global and Dhcp4, hence we need two closing curly brackets to close them.
-In a real life configuration file there likely would be additional
-components defined like Logging or DhcpDdns, so the closing brace would
+In a real life configuration file there most likely would be additional
+components defined such as Logging or DhcpDdns, so the closing brace would
be followed by a comma and another object definition.</para>
<para>Kea 0.9 does not have configuration syntax validation
"Dhcp4": {
"lease-database": {
<userinput>"type": "memfile"</userinput>,
- <userinput>"persist": true</userinput>,
+ <userinput>"persist": "true"</userinput>,
<userinput>"name": "/tmp/kea-leases4.csv"</userinput>
}
...
<userinput>"name": "domain-name-servers",
"code": 6,
"space": "dhcp4",
- "csv-format": true,
+ "csv-format": "true",
"data": "192.0.2.1, 192.0.2.2"</userinput>
},
...
<userinput>"name": "domain-name-servers",
"code": 6,
"space": "dhcp4",
- "csv-format": false,
+ "csv-format": "false",
"data": "C0 00 03 01 C0 00 03 02"</userinput>
},
...
"name": "domain-name-servers",
"code": 6,
"space: "dhcp4",
- "csv-format": true,
+ "csv-format": "true",
"data": "192.0.2.3"
},
...
</screen>
</para>
- <note>
- <!-- @todo Ticket #3467 created for this -->
- <para>In a future version of Kea, it will not be necessary to specify
- the option code, space and csv-format fields as they will be set
- automatically.</para>
- </note>
+ <note>
+ <para>
+ In future versions of Kea, it will not be necessary to specify
+ the <command>code</command>, <command>space</command>
+ and <command>csv-format</command> fields, as they will
+ be set automatically.
+ </para>
+ </note>
<para>
The currently supported standard DHCPv4 options are
Some options are designated as arrays, which means that more than one
value is allowed in such an option. For example the option time-servers
allows the specification of more than one IPv4 address, so allowing
- clients to obtain the the addresses of multiple NTP servers.
+ clients to obtain the addresses of multiple NTP servers.
</para>
<!-- @todo: describe record types -->
<title>List of standard DHCPv4 options</title>
<tgroup cols='4'>
<colspec colname='name'/>
- <colspec colname='code'/>
- <colspec colname='type'/>
- <colspec colname='array'/>
+ <colspec colname='code' align='center'/>
+ <colspec colname='type' align='center'/>
+ <colspec colname='array' align='center'/>
<thead>
<row>
<entry>Name</entry>
<userinput>"name": "foo",
"code": 222,
"type": "uint32",
- "array": false,
+ "array": "false",
"record-types": "",
"space": "dhcp4",
"encapsulate": ""</userinput>
<userinput>name "foo",
"code": 222,
"space": "dhcp4",
- "csv-format": true,
+ "csv-format": "true",
"data": "12345"</userinput>
}, ...
],
"code": 223,
"space": "dhcp4",
"type": "record",
- "array": false,
+ "array": "false",
"record-types": "ipv4-address, uint16, boolean, string",
"encapsulate": ""</userinput>
}, ...
<userinput>"name": "bar",
"space": "dhcp4",
"code": 223,
- "csv-format": true,
+ "csv-format": "true",
"data": "192.0.2.100, 123, true, Hello World"</userinput>
}
],
"code": 1,
"space": "vendor-encapsulated-options-space",
"type": "record",
- "array: false,
+ "array": "false",
"record-types": "ipv4-address, uint16, string",
"encapsulates": ""</userinput>
}
<userinput>"name": "foo"
"space": "vendor-encapsulated-options-space",
"code": 1,
- "csv-format": true,
+ "csv-format": "true",
"data": "192.0.2.3, 123, Hello World"</userinput>
}
],
<userinput>"name": "vendor-encapsulated-options"
"space": "dhcp4",
"code": 43,
- "csv-format": false,
- "data: ""</userinput>
+ "csv-format": "false",
+ "data": ""</userinput>
}
],
...
"space": "isc",
"type": "ipv4-address".
"record-types": "",
- "array": false,
+ "array": "false",
"encapsulate ""
},
{
"space": "isc",
"type": "string",
"record-types": "",
- "array": false
+ "array": "false"
"encapsulate": ""</userinput>
}
],
"code": 222,
"space": "dhcp4",
"type": "empty",
- "array": false,
+ "array": "false",
"record-types": "",
"encapsulate": "isc"</userinput>
}
<userinput>"name": "subopt1",
"space": "isc",
"code": 1,
- "csv-format": true,
+ "csv-format": "true",
"data": "192.0.2.3"</userinput>
},
}
<userinput>"name": "subopt2",
"space": "isc",
"code": 2,
- "csv-format": true,
+ "csv-format": "true",
"data": "Hello world"</userinput>
},
{
<userinput>"name": "container",
"space": "dhcp4",
"code": 222,
- "csv-format": true,
+ "csv-format": "true",
"data": ""</userinput>
}
],
"name": "domain-name-servers",
"code": 6,
"data": "192.0.2.200,192.0.2.201",
- "csv-format": true,
+ "csv-format": "true",
"space": "dhcp4"
} ]
}
<screen>
"Dhcp4": {
"dhcp-ddns": {
- <userinput>"enable-updates": true,
+ <userinput>"enable-updates": "true",
"server-ip": "127.0.0.1",
"server-port": 53001,
"sender-ip": "",
"max-queue-size": 1024,
"ncr-protocol": "UDP",
"ncr-format": "JSON",
- "override-no-update": false,
- "override-client-update": false,
- "replace-client-name": false,
+ "override-no-update": "false",
+ "override-client-update": "false",
+ "replace-client-name": "false",
"generated-prefix": "myhost",
"qualifying-suffix": "example.com"</userinput>
},
}
</screen>
</para>
- <!-- this paragraph no longer applies as we don't have default values
- <para>
- The "enable-updates" parameter determines whether or not kea-dhcp4 will
- generate NCRs. By default, this value is false hence DDNS updates are
- disabled. To enable DDNS updates set this value to true:
- </para>
-<screen>
-> <userinput>config set Dhcp4/dhcp-ddns/enable-updates true</userinput>
-> <userinput>config commit</userinput>
-</screen> -->
+
<section id="dhcpv4-d2-io-config">
<title>DHCP-DDNS Server Connectivity</title>
<para>
In order for NCRs to reach the DHCP-DDNS server, kea-dhcp4 must be able
to communicate with it. kea-dhcp4 uses the following configuration
parameters to control how it communications with DHCP-DDNS:
- <orderedlist>
- <listitem><para>
+ <itemizedlist>
+ <listitem><simpara>
+ <command>enable-updates</command> - determines whether or not kea-dhcp4 will
+ generate NCRs. By default, this value is false hence DDNS updates are
+ disabled. To enable DDNS updates set this value to true:
+ </simpara></listitem>
+
+ <listitem><simpara>
<command>server-ip</command> - IP address on which DHCP-DDNS listens for requests. The default is
the local loopback interface at address 127.0.0.1. You may specify
either an IPv4 or IPv6 address.
- </para></listitem>
- <listitem><para>
+ </simpara></listitem>
+
+ <listitem><simpara>
<command>server-port</command> - port on which DHCP-DDNS listens for requests. The default value
is 53001.
- </para></listitem>
- <listitem><para>
+ </simpara></listitem>
+
+ <listitem><simpara>
<command>sender-ip</command> - IP address which kea-dhcp4 should use to send requests to the DHCP-DDNS server.
The default value is blank which instructs kea-dhcp4 to select a suitable
address.
- </para></listitem>
- <listitem><para>
+ </simpara></listitem>
+
+ <listitem><simpara>
<command>sender-port</command> - port which kea-dhcp4 should use to send requests to the DHCP-DDNS server. The
default value of 0 instructs kea-dhcp4 to select suitable port.
- </para></listitem>
- <listitem><para>
- <command>ncr-format</command> - Socket protocol use when sending requests to the DHCP-DDNS server. Currently
- only UDP is supported. TCP may be available in an upcoming release.
- </para></listitem>
- <listitem><para>
- <command>ncr-protocol</command> - Packet format to use when sending requests to the DHCP-DDNS server.
- Currently only JSON format is supported. Other formats may be available
- in future releases.
- </para></listitem>
- <listitem><para>
+ </simpara></listitem>
+
+ <listitem><simpara>
<command>max-queue-size</command> - maximum number of requests allowed to queue waiting to
be sent to the DHCP-DDNS server. This value guards against requests accumulating
uncontrollably if they are being generated faster than they can be
been sufficiently reduced. The intention is allow the kea-dhcp4 server to
continue lease operations without running the risk that its memory usage
grows without limit. The default value is 1024.
- </para></listitem>
- </orderedlist>
+ </simpara></listitem>
+
+ <listitem><simpara>
+ <command>ncr-format</command> - socket protocol use when sending requests to the DHCP-DDNS server. Currently
+ only UDP is supported. TCP may be available in an upcoming release.
+ </simpara></listitem>
+
+ <listitem><simpara>
+ <command>ncr-protocol</command> - packet format to use when sending requests to the DHCP-DDNS server.
+ Currently only JSON format is supported. Other formats may be available
+ in future releases.
+ </simpara></listitem>
+
+ </itemizedlist>
By default, the DHCP-DDNS server is assumed to running on the same machine as kea-dhcp4, and
all of the default values mentioned above should be sufficient.
If, however, the DHCP-DDNS server has been configured to listen on a different address or
<screen>
"Dhcp4": {
"dhcp-ddns": {
- <userinput>"override-client-update": true</userinput>,
+ <userinput>"override-client-update": "true"</userinput>,
...
},
...
<screen>
"Dhcp4": {
"dhcp-ddns": {
- <userinput>"override-no-update": true</userinput>,
+ <userinput>"override-no-update": "true"</userinput>,
...
},
...
<screen>
"Dhcp4": {
"dhcp-ddns": {
- <userinput>"replace-client-name": true</userinput>,
+ <userinput>"replace-client-name": "true"</userinput>,
...
},
...
<screen>
"Dhcp4": {
- <userinput>"echo-client-id": false</userinput>,
+ <userinput>"echo-client-id": "false"</userinput>,
...
}
</screen>
<title>Starting and Stopping the DHCPv6 Server</title>
<para>
- It is recommended to control DHCPv6 server in Kea using <command>keactl</command>,
- which is described in details in <xref linkend="keactrl"/>.
- </para>
-
- <para>
- However, it is also possible to run the server on its own, not using any
- scripts. The server accepts the following command-line parameters:
+ It is recommended that the Kea DHCPv4 server be started and stopped
+ using <command>keactl</command> (described in <xref linkend="keactrl"/>).
+ However, it is also possible to run the server directly: it accepts
+ the following command-line switches:
</para>
<itemizedlist>
<listitem>
- <simpara>-c file - specifies the configuration file. This is the
- only mandatory parameter (it may be optional for configuration
- parameters other than Kea)</simpara>
+ <simpara>
+ <command>-c <replaceable>file</replaceable></command> -
+ specifies the configuration file. This is the only mandatory
+ switch.</simpara>
</listitem>
<listitem>
- <simpara>-v - specifies whether the server logging should be
- switched to verbose mode. In verbose mode, logging severity and
- debuglevel specified in a configuration file are ignored and
- severity debug and maximum debuglevel (99) is assumed. That flag is
- convenient, for temporarily switching the server into maximum
- verbosity, e.g. when debugging.</simpara>
+ <simpara>
+ <command>-v</command> - specifies whether the server
+ logging should be switched to verbose mode. In verbose mode,
+ the logging severity and debuglevel specified in a configuration
+ file are ignored and "debug" severity and the maximum debuglevel
+ (99) are assumed. The flag is convenient, for temporarily
+ switching the server into maximum verbosity, e.g. when
+ debugging.</simpara>
</listitem>
<listitem>
- <simpara>-p port - specifies UDP port the server will listen
- on. This is only useful during testing, as the DHCPv4 server
- listening on ports other than default DHCPv6 ports will not be able
- to handle regular DHCPv6 queries.</simpara>
+ <simpara>
+ <command>-p <replaceable>port</replaceable></command> -
+ specifies UDP port the server will listen on. This is only
+ useful during testing, as the DHCPv6 server listening on
+ ports other than default DHCPv6 ports will not be able to
+ handle regular DHCPv6 queries.</simpara>
</listitem>
</itemizedlist>
<para>
- The server running in a console can be shut down by pressing ctrl-c. The
- server will detect such a key combination and will initialize shutdown procedure.
+ When running in a console, the server can be shut down by
+ pressing ctrl-c. It detects the key combination and shuts
+ down gracefully.
</para>
<para>
On start-up, the server will detect available network interfaces
- and will attempt to open UDP sockets on all interfaces that
- are mentioned in the configuration file.
+ and will attempt to open UDP sockets on all interfaces
+ mentioned in the configuration file.
</para>
<para>
<title>Introduction</title>
<para>
This section explains how to configure the DHCPv6 server using the
- Kea configuration backend. Kea configuration using any other
- backends is outside of scope for this document. Before DHCPv6
+ Kea configuration backend. (Kea configuration using any other
+ backends is outside of scope of this document.) Before DHCPv6
is started, its configuration file has to be created. The
basic configuration looks as follows:
<screen>
{
-# DHCPv6 configuration starts in this line
+# DHCPv6 configuration starts on the next line
"Dhcp6": {
# First we set up global values
# Next we specify the type of lease database
"lease-database": {
"type": "memfile",
- "persist": true,
+ "persist": "true",
"name": "/var/kea/dhcp6.leases"
},
]
}
]
-
-# DHCPv6 configuration ends with this line
+# DHCPv6 configuration ends with the next line
}
} </screen>
object called Dhcp6. This is a simplified configuration, as usually
there will be additional objects, like <command>Logging</command> or
<command>DhcpDns</command>, but we omit them now for clarity. The Dhcp6
-configuration starts with the the <command>"Dhcp6: {"</command> line
+configuration starts with the <command>"Dhcp6": {</command> line
and ends with the corresponding closing brace (in the above example,
the brace after the last comment). Everything defined between those
lines is considered to be the Dhcp6 configuration.</para>
"subnet": "2001:db8:1::/64"
},
{
- "pools": [ { "pool": "2001:db8:2::1-2001:db8:2::ff" } ],
- "subnet": "192.0.3.0/24",
+ "pools": [ { "pool": "2001:db8:2::1-2001:db8:2::ffff" } ],
+ "subnet": "2001:db8:2::/64",
"interface": "eth0"
}
]
<para>After all parameters are specified, we have two contexts open:
global and Dhcp6, hence we need two closing curly brackets to close them.
-In a real life configuration file there likely would be additional
-components defined like Logging or DhcpDdns, so the closing brace would
+In a real life configuration file there most likely would be additional
+components defined such as Logging or DhcpDdns, so the closing brace would
be followed by a comma and another object definition.</para>
<para>Kea 0.9 does not have configuration syntax validation
<para>The server is able to store lease data in different repositories. Larger
deployments may elect to store leases in a database. <xref
- linkend="database-configuration4"/> describes this option. In typical
+ linkend="database-configuration6"/> describes this option. In typical
smaller deployments though, the server will use a CSV file rather than a database to
store lease information. As well as requiring less administration, an
advantage of using a file for storage is that it
eliminates a dependency on third-party database software.</para>
<para>The configuration of the file backend (Memfile) is controlled through
- the Dhcp4/lease-database parameters. <!-- @todo: we don't have default
+ the Dhcp6/lease-database parameters. <!-- @todo: we don't have default
parameters. Let's comment this out When default parameters are used, the
Memfile backend will write leases to a disk in the
[kea-install-dir]/var/kea/kea-leases4.csv. -->
The following configuration:
<screen>
-"Dhcp4": {
+"Dhcp6": {
"lease-database": {
<userinput>"type": "memfile"</userinput>,
- <userinput>"persist": true</userinput>,
- <userinput>"name": "/tmp/kea-leases4.csv"</userinput>
+ <userinput>"persist": "true"</userinput>,
+ <userinput>"name": "/tmp/kea-leases6.csv"</userinput>
}
...
}
</screen>
- ...sets the name of the lease file to /tmp/kea-leases4.csv.
+ ...sets the name of the lease file to /tmp/kea-leases6.csv.
</para>
<para>The "persist" parameter controls whether the leases are written to disk.
<para>
Subnet identifier is a unique number associated with a particular subnet.
In principle, it is used to associate clients' leases with respective subnets.
- When subnet identifier is not specified for a subnet being configured, it will
+ When the subnet identifier is not specified for a subnet being configured, it will
be automatically assigned by the configuration mechanism. The identifiers
are assigned from 1 and are monotonically increased for each subsequent
subnet: 1, 2, 3 ....
"subnet": "2001:db8:1::/64",
"pools": [
{
- pool: "2001:db8:1::1-2001:db8:1::ff"
+ pool: "2001:db8:1::1-2001:db8:1::ffff"
}
],
...
In this example, we allow server to
dynamically assign all addresses available in the whole subnet. Although
rather wasteful, it is certainly a valid configuration to dedicate the
- whole /64 subnet for that purpose. Note that Kea server does not preallocate
+ whole /64 subnet for that purpose. Note that the Kea server does not preallocate
the leases, so there is no danger of using gigantic address pools.
</para>
<para>
When configuring a DHCPv6 server using prefix/length notation, please pay
attention to the boundary values. When specifying that the server should use
a given pool, it will be able to allocate also first (typically network
- address) address from that pool. For example for pool 2001:db8::/64 the
- 2001:db8:: address may be assigned as well. If you want to avoid this,
- please use the "min-max" notation.
+ address) address from that pool. For example for pool 2001:db8:2::/64 the
+ 2001:db8:2:: address may be assigned as well. If you want to avoid this,
+ use the "min-max" notation.
</para>
</section>
global and apply to all configured subnets.
<screen>
-"Dhcp4": {
+"Dhcp6": {
"option-data": [
{
<userinput>"name": "dns-servers",
"code": 23,
"space": "dhcp6",
- "csv-format": true,
+ "csv-format": "true",
"data": "2001:db8::cafe, 2001:db8::babe"</userinput>
},
...
subnets with the following addresses: 2001:db8:1::cafe and
2001:db8:1::babe.
<screen>
-"Dhcp4": {
+"Dhcp6": {
"option-data": [
{
<userinput>"name": "dns-servers",
"code": 23,
"space": "dhcp6",
- "csv-format": false,
+ "csv-format": "false",
"data": "2001 0DB8 0001 0000 0000 0000 0000 CAFE
2001 0DB8 0001 0000 0000 0000 0000 BABE"</userinput>
},
The value for the setting of the "data" element is split across two
lines in this document for clarity: when entering the command, the
whole string should be entered on the same line. Care should be taken
- to use proper encoding when using hex format as Kea ability to validate
- data correctness in hex format is limited.
+ to use proper encoding when using hexadecimal format as Kea's ability
+ to validate data correctness in hexadecimal is limited.
</para>
<para>
"name": "dns-servers",
"code": 23,
"space: "dhcp6",
- "csv-format": true,
+ "csv-format": "true",
"data": "2001:db8:1::3"
},
...
<note>
<para>
- In future versions of Kea, it will not be necessary to specify option
- code, space and csv-format fields, as those fields will be set
- automatically.
+ In future versions of Kea, it will not be necessary to specify
+ the <command>code</command>, <command>space</command>
+ and <command>csv-format</command> fields, as they will
+ be set automatically.
</para>
</note>
Some options are designated as arrays, which means that more than one
value is allowed in such an option. For example the option dns-servers
allows the specification of more than one IPv6 address, so allowing
- clients to obtain the the addresses of multiple DNS servers.
+ clients to obtain the addresses of multiple DNS servers.
</para>
<!-- @todo: describe record types -->
<title>List of standard DHCPv6 options</title>
<tgroup cols='4'>
<colspec colname='name'/>
- <colspec colname='code'/>
- <colspec colname='type'/>
- <colspec colname='array'/>
+ <colspec colname='code' align='center'/>
+ <colspec colname='type' align='center'/>
+ <colspec colname='array' align='center'/>
<thead>
<row><entry>Name</entry><entry>Code</entry><entry>Type</entry><entry>Array?</entry></row>
</thead>
<userinput>"name": "foo",
"code": 100,
"type": "uint32",
- "array": false,
+ "array": "false",
"record-types": "",
"space": "dhcp6",
"encapsulate": ""</userinput>
<userinput>name "foo",
"code": 100,
"space": "dhcp6",
- "csv-format": true,
+ "csv-format": "true",
"data": "12345"</userinput>
}, ...
],
"code": 101,
"space": "dhcp6",
"type": "record",
- "array": false,
+ "array": "false",
"record-types": "ipv4-address, uint16, boolean, string",
"encapsulate": ""</userinput>
}, ...
<userinput>"name": "bar",
"space": "dhcp6",
"code": 101,
- "csv-format": true,
+ "csv-format": "true",
"data": "2001:db8:1::10, 123, false, Hello World"</userinput>
}
],
"code": 1,
"space": "vendor-encapsulated-options-space",
"type": "record",
- "array: false,
+ "array": "false",
"record-types": "ipv6-address, uint16, string",
"encapsulates": ""</userinput>
}
<userinput>"name": "foo"
"space": "vendor-encapsulated-options-space",
"code": 1,
- "csv-format": true,
+ "csv-format": "true",
"data": "2001:db8:1::10, 123, Hello World"</userinput>
},
...
<userinput>"name": "vendor-encapsulated-options"
"space": "dhcp6",
"code": 17,
- "csv-format": true,
- "data: "12345"</userinput>
+ "csv-format": "true",
+ "data": "12345"</userinput>
}
],
...
"space": "isc",
"type": "ipv6-address".
"record-types": "",
- "array": false,
+ "array": "false",
"encapsulate ""
},
{
"space": "isc",
"type": "string",
"record-types": "",
- "array": false
+ "array": "false"
"encapsulate": ""</userinput>
}
],
The next step is to define a regular DHCPv6 option and specify that it
should include options from the isc option space:
<screen>
-"Dhcp4": {
+"Dhcp6": {
"option-def": [
...,
{
"code": 102,
"space": "dhcp6",
"type": "empty",
- "array": false,
+ "array": "false",
"record-types": "",
"encapsulate": "isc"</userinput>
}
<userinput>"name": "subopt1",
"space": "isc",
"code": 1,
- "csv-format": true,
+ "csv-format": "true",
"data": "2001:db8::abcd"</userinput>
},
}
<userinput>"name": "subopt2",
"space": "isc",
"code": 2,
- "csv-format": true,
+ "csv-format": "true",
"data": "Hello world"</userinput>
},
{
<userinput>"name": "container",
"space": "dhcp6",
"code": 102,
- "csv-format": true,
+ "csv-format": "true",
"data": ""</userinput>
}
],
<screen>
"Dhcp6": {
"dhcp-ddns": {
- <userinput>"enable-updates": true,
+ <userinput>"enable-updates": "true",
"server-ip": "127.0.0.1",
"server-port": 53001,
"sender-ip": "",
"max-queue-size": 1024,
"ncr-protocol": "UDP",
"ncr-format": "JSON",
- "override-no-update": false,
- "override-client-update": false,
- "replace-client-name": false,
+ "override-no-update": "false",
+ "override-client-update": "false",
+ "replace-client-name": "false",
"generated-prefix": "myhost",
"qualifying-suffix": "example.com"</userinput>
},
</screen>
</para>
- <para>
- The "enable-updates" parameter determines whether or not kea-dhcp6 will
- generate NCRs. If missing, this value is assumed false hence DDNS updates are
- disabled.
- </para>
<section id="dhcpv6-d2-io-config">
<title>DHCP-DDNS Server Connectivity</title>
In order for NCRs to reach the D2 server, kea-dhcp6 must be able
to communicate with it. kea-dhcp6 uses the following configuration
parameters to control how it communications with D2:
- <orderedlist>
- <listitem><para>
- server-ip - IP address on which D2 listens for requests. The default is
+ <itemizedlist>
+ <listitem><simpara>
+ <command>enable-updates</command> - determines whether or not kea-dhcp6 will
+ generate NCRs. If missing, this value is assumed to be false hence DDNS updates
+ are disabled. To enable DDNS updates set this value to true:
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>server-ip</command> - IP address on which D2 listens for requests. The default is
the local loopback interface at address 127.0.0.1. You may specify
either an IPv4 or IPv6 address.
- </para></listitem>
- <listitem><para>
- server-port - port on which D2 listens for requests. The default value
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>server-port</command> - port on which D2 listens for requests. The default value
is 53001.
- </para></listitem>
- <listitem><para>
- sender-ip - IP address which kea-dhcp6 should use to send requests to D2.
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>sender-ip</command> - IP address which kea-dhcp6 should use to send requests to D2.
The default value is blank which instructs kea-dhcp6 to select a suitable
address.
- </para></listitem>
- <listitem><para>
- sender-port - port which kea-dhcp6 should use to send requests to D2. The
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>sender-port</command> - port which kea-dhcp6 should use to send requests to D2. The
default value of 0 instructs kea-dhcp6 to select suitable port.
- </para></listitem>
- <listitem><para>
- ncr-format - Socket protocol use when sending requests to D2. Currently
- only UDP is supported. TCP may be available in an upcoming release.
- </para></listitem>
- <listitem><para>
- ncr-protocol - Packet format to use when sending requests to D2.
- Currently only JSON format is supported. Other formats may be available
- in future releases.
- </para></listitem>
- <listitem><para>
- max-queue-size - maximum number of requests allowed to queue waiting to
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>max-queue-size</command> - maximum number of requests allowed to queue waiting to
be sent to D2. This value guards against requests accumulating
uncontrollably if they are being generated faster than they can be
delivered. If the number of requests queued for transmission reaches
this value, DDNS updating will be turned off until the queue backlog has
been sufficiently reduced. The intent is allow kea-dhcp6 to
continue lease operations. The default value is 1024.
- </para></listitem>
- </orderedlist>
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>ncr-format</command> - Socket protocol use when sending requests to D2. Currently
+ only UDP is supported. TCP may be available in an upcoming release.
+ </simpara></listitem>
+ <listitem><simpara>
+ <command>ncr-protocol</command> - Packet format to use when sending requests to D2.
+ Currently only JSON format is supported. Other formats may be available
+ in future releases.
+ </simpara></listitem>
+ </itemizedlist>
By default, D2 is assumed to running on the same machine as kea-dhcp6, and
all of the default values mentioned above should be sufficient.
If, however, D2 has been configured to listen on a different address or
<title>When does kea-dhcp6 generate DDNS request</title>
- <para>kea-dhcp6 follows the behavior prescribed for DHCP servers
- in RFC 4704. It is important to keep in mind that kea-dhcp6
- 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 purview of D2 (<xref
- linkend="dhcp-ddns-server"/>).</para>
+ <para>kea-dhcp6 follows the behavior prescribed for DHCP servers in
+ <ulink url="http://tools.ietf.org/html/rfc4704">RFC 4704</ulink>.
+ It is important to keep in mind that kea-dhcp6 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 purview of D2 (<xref linkend="dhcp-ddns-server"/>).</para>
<para>
This section describes when kea-dhcp6 will generate NCRs and the
<screen>
"Dhcp6": {
"dhcp-ddns": {
- <userinput>"override-client-update": true</userinput>,
+ <userinput>"override-client-update": "true"</userinput>,
...
},
...
<screen>
"Dhcp6": {
"dhcp-ddns": {
- <userinput>"override-no-update": true</userinput>,
+ <userinput>"override-no-update": "true"</userinput>,
...
},
...
<screen>
"Dhcp6": {
"dhcp-ddns": {
- <userinput>"replace-client-name": true</userinput>,
+ <userinput>"replace-client-name": "true"</userinput>,
...
},
...
is no default value. To set its value simply set it to the desired string:
</para>
<screen>
-"Dhcp4": {
+"Dhcp6": {
"dhcp-ddns": {
<userinput>"qualifying-suffix": "foo.example.org"</userinput>,
...
projects / thirdparty / kea.git / commitdiff
