- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="admin">
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="admin">
<title>Kea Database Administration</title>
- <section id="kea-database-version">
+ <section xml:id="kea-database-version">
<title>Databases and Database Version Numbers</title>
<para>
backend may be essential for success or failure of your deployment.</para>
<para>
- <table frame="all" id="backends">
+ <table frame="all" xml:id="backends">
<title>List of available backends</title>
- <tgroup cols="2">
- <colspec colname="feature"/>
- <colspec colname="memfile"/>
- <colspec colname="mysql"/>
- <colspec colname="pgsql"/>
- <colspec colname="cql"/>
+ <tgroup cols='5'>
+ <colspec colname='feature'/>
+ <colspec colname='memfile'/>
+ <colspec colname='mysql'/>
+ <colspec colname='pgsql'/>
+ <colspec colname='cql' colwidth='1.5*'/>
<thead>
<row>
<entry>Feature</entry>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "‗" >
- ]>
-
- <chapter id="kea-ctrl-agent">
++<!--
++ - Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-ctrl-agent">
<title>Kea Control Agent</title>
- <section id="agent-overview">
+ <section xml:id="agent-overview">
<title>Overview</title>
<para>Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which
exposes a RESTful control interface for managing Kea servers. The daemon
organization which apply to this setup.</simpara>
</note>
+ <para>When you use an HTTP client without TLS support as <command>
+ kea-shell</command> you can use an HTTP/HTTPS translator such as stunnel
+ in client mode. A sample configuration is provided in the
+ <filename>doc/examples/https/shell/</filename> directory</para>
+
</section>
- <section id="agent-limitations">
+ <section xml:id="agent-limitations">
<title>Control Agent Limitations</title>
<para>
Control Agent is a new component, first released in Kea 1.2. In
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+
- <chapter id="classify">
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="classify">
<title>Client Classification</title>
<section>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
- <chapter id="kea-config">
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-config">
<title>Kea Configuration</title>
<para>Kea is using JSON structures to handle configuration. Previously
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- <!ENTITY % version SYSTEM "version.ent">
- %version;
- ]>
-
- <chapter id="ctrl-channel">
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ctrl-channel">
<title>Management API</title>
<para>A classic approach to daemon configuration assumes that
</para>
</section> <!-- end of command-shutdown -->
- <section id="command-version-get">
+ <section id="command-dhcp-disable">
+ <title>dhcp-disable</title>
+ <para>
+ The <emphasis>dhcp-disable</emphasis> command globally disables the DHCP
+ service. The server continues to operate, but it drops all received DHCP
+ messages. This command is useful when the server's maintenance requires that
+ the server temporarily stops allocating new leases and renew existing leases.
+ It is also useful in failover like configurations during a synchronization of
+ the lease databases at startup or recovery after a failure. The optional parameter
+ <emphasis>max-period</emphasis> specifies the time in seconds after which the
+ DHCP service should be automatically re-enabled if the
+ <emphasis>dhcp-enable</emphasis> command is not sent before this time elapses.
+ </para>
+<screen>
+{
+ "command": "dhcp-disable",
+ "arguments": {
+ "max-period": 20
+ }
+}
+</screen>
+ </section> <!-- end of command-dhcp-disable -->
+
+ <section id="command-dhcp-enable">
+ <title>dhcp-enable</title>
+ <para>
+ The <emphasis>dhcp-enable</emphasis> command globally enables the DHCP
+ service.
+ </para>
+<screen>
+{
+ "command": "dhcp-enable"
+}
+</screen>
+ </section> <!-- end of command-dhcp-disable -->
+
+ <section xml:id="command-version-get">
<title>version-get</title>
<para>
The <emphasis>version-get</emphasis> command returns on the control
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="dhcp-ddns-server">
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp-ddns-server">
<title>The DHCP-DDNS Server</title>
- <para>
- The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of
- the DDNS protocol (defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2136">RFC 2136</link>)
- on behalf of the DHCPv4 and DHCPv6
- servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
- DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP
- lease change events and then post these to D2. D2 attempts to match
- each such request to the appropriate DNS server(s) and carry out the
- necessary conversation with those servers to update the DNS data.
- </para>
- <para>
- In order to match a request to the appropriate DNS servers, D2 must have a
- 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 one or more DNS
- servers that publish the DNS data for that domain.
- </para>
- <para>
- When conducting forward domain matching, D2 will compare the FQDN in
- the request against the name of each forward DDNS Domain. The domain
- whose name matches the longest portion of the FQDN is considered the
- best match. For example, if the FQDN is "myhost.sample.example.com.",
- and there are two forward domains in the catalog: "sample.example.com."
- and "example.com.", the former is regarded as the best match. In some
- cases, it may not be possible to find a suitable match. Given the same two
- forward domains there would be no match for the FQDN, "bogus.net", so the
- request would be rejected. Finally, if there are no forward DDNS Domains
- defined, D2 will simply disregard the forward update portion of requests.
- </para>
- <para>
- When conducting reverse domain matching, D2 constructs a reverse
- FQDN from the lease address in the request and compare that against
- the name of each reverse DDNS Domain. Again, the domain whose name matches
- the longest portion of the FQDN is considered the best match. For instance,
- if the lease address is "172.16.1.40" and there are two reverse domains in
- the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the
- former is the best match. As with forward matching, it is possible to not
- find a suitable match. Given the same two domains, there would be no
- match for the lease address, "192.168.1.50", and the request would be
- rejected. Finally, if there are no reverse DDNS Domains defined, D2 will
- simply disregard the reverse update portion of requests.
++
+ <section id="dhcp-ddns-overview">
+ <title>Overview</title>
+ <para>
+ The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts
- the client side of the DDNS protocol (defined in
- <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
++ the client side of the DDNS protocol (defined in <link
++ xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2136">RFC 2136</link>)
+ on behalf of the DHCPv4 and DHCPv6 servers (kea-dhcp4 and kea-dhcp6
+ respectively). The DHCP servers construct DDNS update requests, known
+ as NameChangeRequests (NCRs), based upon DHCP lease change events and
+ then post these to D2. D2 attempts to match each such request to the
+ appropriate DNS server(s) and carry out the necessary conversation with
+ those servers to update the DNS data.
</para>
- <section xml:id="dhcp-ddns-server-start-stop">
+ <section id="dhcp-ddns-dns-server-selection">
+ <title>DNS Server selection</title>
+ <para>
+ In order to match a request to the appropriate DNS servers, D2 must have a
+ 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 one or more DNS
+ servers that publish the DNS data for that domain.
+ </para>
+ <para>
+ When conducting forward domain matching, D2 will compare the FQDN in
+ the request against the name of each forward DDNS Domain. The domain
+ whose name matches the longest portion of the FQDN is considered the
+ best match. For example, if the FQDN is "myhost.sample.example.com.",
+ and there are two forward domains in the catalog: "sample.example.com."
+ and "example.com.", the former is regarded as the best match. In some
+ cases, it may not be possible to find a suitable match. Given the same two
+ forward domains there would be no match for the FQDN, "bogus.net", so the
+ request would be rejected. Finally, if there are no forward DDNS Domains
+ defined, D2 will simply disregard the forward update portion of requests.
+ </para>
+ <para>
+ When conducting reverse domain matching, D2 constructs a reverse
+ FQDN from the lease address in the request and compare that against
+ the name of each reverse DDNS Domain. Again, the domain whose name matches
+ the longest portion of the FQDN is considered the best match. For instance,
+ if the lease address is "172.16.1.40" and there are two reverse domains in
+ the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the
+ former is the best match. As with forward matching, it is possible to not
+ find a suitable match. Given the same two domains, there would be no
+ match for the lease address, "192.168.1.50", and the request would be
+ rejected. Finally, if there are no reverse DDNS Domains defined, D2 will
+ simply disregard the reverse update portion of requests.
+ </para>
+ </section>
- <section id="dhcp-ddns-conflict-resolution">
++ <section xml:id="dhcp-ddns-conflict-resolution">
+ <title>Conflict Resolution</title>
+ <para>
+ D2 implements the conflict resolution strategy prescribed by
+ <ulink url="http://tools.ietf.org/html/rfc4703">RFC 4703</ulink>.
+ Conflict resolution is intended to prevent different clients from
+ mapping to the same FQDN at the same time. To make this possible, the
+ RFC requires that forward DNS entries for a given FQDN must be
+ accompanied by a DHCID resource record (RR). This record contains a
+ client identifier that uniquely identifies the client to whom the name
+ belongs. Furthermore, any DNS updater who wishes to update or remove
+ existing forward entries for an FQDN may only do so if their client
+ matches that of the DHCID RR.
+ </para>
+ <para>
+ In other words, the DHCID RR maps an FQDN to the client to whom it
+ belongs and thereafter only changes to that mapping should only be
+ done by or at the behest of that client.
+ </para>
+ <para>
+ Currently, conflict detection is always performed. Future releases may
+ offer alternative behavior.
+ </para>
+ </section>
+ <section id="dhcp-ddns-dual-stack">
+ <title>Dual Stack Environments</title>
+ <para>
+ <ulink url="http://tools.ietf.org/html/rfc4703#section-5.2">RFC 4703,
+ sec. 5.2,</ulink> describes issues that may arise with dual stack
+ clients. These are clients that wish to have have both IPv4 and IPv6
+ mappings for the same FQDN. In order for this work properly, such
+ clients are required to embed ther IPv6 DUID within their IPv4 client
+ identifier option as described in
+ <ulink url="http://tools.ietf.org/html/rfc4361">RFC 4703</ulink>.
+ In this way, DNS upates for both IPv4 and IPv6 can be managed under
+ the same DHCID RR. Support for this does not yet exist in Kea but is
+ called for in the ticket, http://kea.isc.org/ticket/4519, which we
+ hope to include in a future release.
+ </para>
+ </section>
+ </section>
+ <section id="dhcp-ddns-server-start-stop">
<title>Starting and Stopping the DHCP-DDNS Server</title>
<para>
</listitem>
</itemizedlist>
</section>
- </chapter> <!-- DHCP-DDNS Server -->
- </chapter>
++ </chapter>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="dhcp4">
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp4">
<title>The DHCPv4 Server</title>
- <section id="dhcp4-start-stop">
+ <section xml:id="dhcp4-start-stop">
<title>Starting and Stopping the DHCPv4 Server</title>
<para>
<row><entry>ipv4-address</entry><entry>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</entry></row>
<row><entry>ipv6-address</entry><entry>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</entry></row>
<row><entry>ipv6-prefix</entry><entry>IPv6 prefix and prefix length specified using CIDR notation, e.g. 2001:db8:1::/64. This data type is used to represent an 8-bit field conveying a prefix length and the variable length prefix value</entry></row>
- <row><entry>psid</entry><entry>PSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See <ulink url="http://tools.ietf.org/html/rfc7597">RFC 7597</ulink> for the details about the PSID wire representation</entry></row>
+ <row><entry>psid</entry><entry>PSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7597">RFC 7597</link> for the details about the PSID wire representation</entry></row>
- <row><entry>record</entry><entry>Structured data that may comprise any types (except "record" and "empty")</entry></row>
+ <row><entry>record</entry><entry>Structured data that may be comprised of any types (except "record" and "empty"). The array flag applies to the last field only.</entry></row>
<row><entry>string</entry><entry>Any text</entry></row>
<row><entry>tuple</entry><entry>A length encoded as a 8 (16 for DHCPv6) bit unsigned integer followed by a string of this length</entry></row>
<row><entry>uint8</entry><entry>8 bit unsigned integer with allowed values 0 to 255</entry></row>
</note>
</section>
- <section id="dhcp4-vendor-opts">
+ <section id="dhcp4-private-opts">
+ <title>DHCPv4 Private Options</title>
+ <para>
+ Options with code between 224 and 254 are reserved for private use.
+ They can be defined at the global scope or at client class local
+ scope: this allows to use option definitions depending on context
+ and to set option data accordingly. For instance to configure
+ an old PXEClient vendor:
+<screen>
+"Dhcp4": {
+ "client-class": [
+ {
+ <userinput>"name": "pxeclient",
+ "test": "option[vendor-class-identifier].text == 'PXEClient'",
+ "option-def": [
+ {
+ "name": "configfile",
+ "code": 209,
+ "type": "string"
+ }
+ ],</userinput>
+ ...
+ }, ...
+ ],
+ ...
+}
+</screen>
+ </para>
+ <para>
+ As the Vendor Specific Information option (code 43) has vendor
+ specific format, i.e. can carry either raw binary value or
+ sub-options, this mechanism is available for this option too.
+ </para>
+ <para>
+ In the following example taken from a real configuration two vendor
+ classes use the option 43 for different and incompatible purposes:
+<screen>
+"Dhcp4": {
+ "option-def": [
+ {
+ <userinput>"name": "cookie",
+ "code": 1,
+ "type": "string",
+ "space": "APC"
+ },
+ {
+ "name": "mtftp-ip",
+ "code": 1,
+ "type": "ipv4-address",
+ "space": "PXE"
+ },</userinput>
+ ...
+ ],
+ "client-class": [
+ {
+ <userinput>"name": "APC",
+ "test": "(option[vendor-class-identifier].text == 'APC'",
+ "option-def": [
+ {
+ "name": "vendor-encapsulated-options",
+ "type": "empty",
+ "encapsulate": "APC"
+ }
+ ],
+ "option-data": [
+ {
+ "name": "cookie",
+ "space": "APC",
+ "data": "1APC"
+ },
+ {
+ "name": "vendor-encapsulated-options"
+ },</userinput>
+ ...
+ ],
+ ...
+ },
+ {
+ <userinput>"name": "PXE",
+ "test": "(option[vendor-class-identifier].text == 'PXE'",
+ "option-def": [
+ {
+ "name": "vendor-encapsulated-options",
+ "type": "empty",
+ "encapsulate": "PXE"
+ }
+ ],
+ "option-data": [
+ {
+ "name": "mtftp-ip",
+ "space": "PXE",
+ "data": "0.0.0.0"
+ },
+ {
+ "name": "vendor-encapsulated-options"
+ },</userinput>
+ ...
+ ],
+ ...
+ },
+ ...
+ ],
+ ...
+}
+</screen>
+ </para>
+ <para>
+ The definition used to decode a VSI option is:
+ <orderedlist>
+ <listitem><para>
+ The local definition of a client class the incoming packet belongs to
+ </para></listitem>
+ <listitem><para>
+ If none, the global definition
+ </para></listitem>
+ <listitem><para>
+ If none, the last resort definition described in the next section
+ <xref linkend="dhcp4-vendor-opts"/> (backward compatible with
+ previous Kea versions).
+ </para></listitem>
+ </orderedlist>
+ </para>
+ <note>
+ <para>
+ This last resort definition for the Vendor Specific Information
+ option (code 43) is not compatible with a raw binary value.
+ So when there are some known cases where a raw binary value
+ will be used, a client class must be defined with a classification
+ expression matching these cases and an option definition for
+ the VSI option with a binary type and no encapsulation.
+ </para>
+ </note>
+ <note>
+ <para>
+ Option definitions in client classes is allowed only for these
+ limited option set (codes 43 and from 224 to 254), and only
+ for DHCPv4.
+ </para>
+ </note>
+ </section>
+
+ <section xml:id="dhcp4-vendor-opts">
<title>DHCPv4 Vendor Specific Options</title>
<para>
Currently there are two option spaces defined for the DHCPv4 daemon:
...
}</screen>
</para>
+
+ <para>
+ Another possibility, added in Kea 1.3, is to redefine the option,
+ see <xref linkend="dhcp4-private-opts"/>.
+ </para>
</section>
- <section id="dhcp4-option-spaces">
+ <section xml:id="dhcp4-option-spaces">
<title>Nested DHCPv4 Options (Custom Option Spaces)</title>
<para>It is sometimes useful to define a completely new option
<para>
myhost-172-16-1-10.example.com.
</para>
+ </section>
</section>
- <section id="dhcp4-next-server">
+ <section xml:id="dhcp4-next-server">
<title>Next Server (siaddr)</title>
<para>In some cases, clients want to obtain configuration from a TFTP server.
Although there is a dedicated option for it, some devices may use the siaddr field
with classification using expressions.</para>
</section>
- <section xml:id="reservations4-mysql-pgsql">
- <title>Storing Host Reservations in MySQL or PostgreSQL</title>
+ <section id="reservations4-mysql-pgsql-cql">
+ <title>Storing Host Reservations in MySQL, PostgreSQL or Cassandra</title>
<para>
- It is possible to store host reservations in MySQL or PostgreSQL database. See
- <xref linkend="hosts4-storage"/> for information on how to configure Kea to use
- reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
- tools for managing reservations in a database. The Kea wiki <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri> provides detailed
- information and examples of how reservations can be inserted into the
- database.
+ It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See
+ <xref linkend="hosts6-storage" /> for information on how to configure Kea to use
+ reservations stored in MySQL, PostgreSQL or Cassandra. Kea provides dedicated hook for
+ managing reservations in a database, section <xref linkend="host-cmds" /> provide
- detailed information.
++ detailed information. <uri
++ xmlns:xlink="http://www.w3.org/1999/xlink"
++ xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri>
++ provides some examples how to conduct common host reservation operations.
</para>
- <note><simpara>In Kea 1.1.0 maximum length of an option specified per host is
+ <note><simpara>In Kea maximum length of an option specified per host is
arbitrarily set to 4096 bytes.</simpara></note>
</section>
- <section id="reservations4-tuning">
- <section xml:id="reservations4-cql">
- <title>Storing host reservations in CQL (Cassandra)</title>
- <para>Kea currently does not support storing reservations in
- Cassandra (CQL).</para>
- </section>
-
-
+ <section xml:id="reservations4-tuning">
<title>Fine Tuning DHCPv4 Host Reservation</title>
<para>The host reservation capability introduces additional restrictions for the
src/lib/dhcpsrv/cfg_host_operations.cc -->
</para>
+ </section>
+ </section>
+ <!-- end of host reservations section -->
- </section>
+ <!-- shared networks -->
+
+ <section id="shared-network4">
+ <title>Shared networks in DHCPv4</title>
+
+ <para>DHCP servers use subnet information in two ways. First, it is used
+ to determine the point of attachment, or simply put, where the client is
+ connected to the network. Second, the subnet information is used to group
+ information pertaining to specific location in the network. This approach
+ works well in general case, but the are scenarios where the boundaries are
+ blurred. Sometimes it is useful to have more than one logical IP subnet
+ being deployed on the same physical link. The need to understand
+ that two or more subnets are used on the same link requires additional logic
+ in the DHCP server. This capability has been added in Kea 1.3.0. It is
+ called "shared networks" in Kea and ISC DHCP projects. It is sometimes also
+ called "shared subnets". In Microsoft's nomenclature it is called "multinet".
+ </para>
+
+ <para>There are many use cases where the feature is useful. This paragraph
+ explains just a handful of the most common ones. The first and by far the most
+ common use case is an existing network that has grown and is running out of
+ available address space. Rather than migrating all devices to a new, larger
+ subnet, it is easier to simply configure additional subnet on top of the
+ existing one. Sometimes, due to address space fragmentation (e.g. only many
+ disjoint /24s are available) this is the only choice. Also, configuring
+ additional subnet has the advantage of not disrupting the operation of
+ existing devices.</para>
+
+ <para>Another very frequent use case comes from cable networks. There are two types
+ of devices in cable networks: cable modems and the end user devices behind
+ them. It is a common practice to use different subnet for cable modems to
+ prevent users from tinkering with their cable modems. In this case, the
+ distinction is based on the type of device, rather than address space
+ exhaustion.</para>
+
+ <para>A client connected to a shared network may be assigned an address from
+ any of the address pools defined within the subnets belonging to the shared
+ network. Internally, the server selects one of the subnets belonging to a
+ shared network and tries to allocate an address from this subnet. If the
+ server is unable to allocate an address from the selected subnet (e.g. due
+ to address pools exhaustion) it will use another subnet from the same shared
+ network and try to allocate an address from this subnet etc. Therefore, in the
+ typical case, the server will allocate all addresses available for a given
+ subnet before it starts allocating addresses from other subnets belonging to
+ the same shared network. However, in certain situations the client can be
+ allocated an address from the other subnets before the address pools in the
+ first subnet get exhausted, e.g. when the client provides a hint that
+ belongs to another subnet or the client has reservations in a different than
+ default subnet.
+ </para>
+
+ <note>
+ <para>It is strongly discouraged for the Kea deployments to assume that the
+ server doesn't allocate addresses from other subnets until it uses all
+ the addresses from the first subnet in the shared network. Apart from the
+ fact that hints, host reservations and client classification affect subnet
+ selection, it is also foreseen that we will enhance allocation strategies
+ for shared networks in the future versions of Kea, so as the selection
+ of subnets within a shared network is equally probable (unpredictable).</para>
+ </note>
+
+ <para>In order to define a shared network an additional configuration scope
+ is introduced:
+<screen>
+{
+"Dhcp4": {
+ <userinput>"shared-networks": [
+ {
+ // Name of the shared network. It may be an arbitrary string
+ // and it must be unique among all shared networks.
+ "name": "my-secret-lair-level-1",
+
+ // Subnet selector can be specifed on the shared network level.
+ // Subnets from this shared network will be selected for directly
+ // connected clients sending requests to server's "eth0" interface.
+ "interface": "eth0",
+
+ // This starts a list of subnets in this shared network.
+ // There are two subnets in this example.
+ "subnet4": [
+ {
+ "subnet": "10.0.0.0/8",
+ "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ],
+ },
+ {
+ "subnet": "192.0.2.0/24",
+ "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ]
+ }
+ ],
+ } ]</userinput>, // end of shared-networks
+
+ // It is likely that in your network you'll have a mix of regular,
+ // "plain" subnets and shared networks. It is perfectly valid to mix
+ // them in the same config file.
+ //
+ // This is regular subnet. It's not part of any shared-network.
+ "subnet4": [
+ {
+ "subnet": "192.0.3.0/24",
+ "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ],
+ "interface": "eth1"
+ }
+ ]
+
+} // end of Dhcp4
+}
+</screen>
+ </para>
+ <para>As you see in the example, it is possible to mix shared and regular
+ ("plain") subnets. Each shared network must have a unique name. This is
+ similar to ID for subnets, but gives you more flexibility. This is used
+ for logging, but also internally for identifying shared networks.</para>
+
+ <para>In principle it makes sense to define only shared networks that
+ consist of two or more subnets. However, for testing purposes it is allowed
+ to define a shared network with just one subnet or even an empty one. This
+ is not a recommended practice in production networks, as the shared network
+ logic requires additional processing and thus lowers server's performance.
+ To avoid unnecessary performance degradation the shared subnets should only
+ be defined when required by the deployment.
+ </para>
+
+ <para>Shared networks provide an ability to specify many parameters in
+ the shared network scope that will apply to all subnets within it. If
+ necessary, you can specify a parameter on the shared network scope and then
+ override its value in the subnet scope. For example:
+<screen>
+"shared-networks": [
+ {
+ "name": "lab-network3",
+
+ "interface": "eth0",
+
+ // This applies to all subnets in this shared network, unless
+ // values are overridden on subnet scope.
+ <userinput>"valid-lifetime": 600</userinput>,
+
+ // This option is made available to all subnets in this shared
+ // network.
+ <userinput>"option-data": [ {
+ "name": "log-servers",
+ "data": "1.2.3.4"
+ } ]</userinput>,
+
+ "subnet4": [
+ {
+ "subnet": "10.0.0.0/8",
+ "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ],
+
+ // This particular subnet uses different values.
+ <userinput>"valid-lifetime": 1200,
+ "option-data": [
+ {
+ "name": "log-servers",
+ "data": "10.0.0.254"
+ },
+ {
+ "name": "routers",
+ "data": "10.0.0.254"
+ } ]</userinput>
+ },
+ {
+ "subnet": "192.0.2.0/24",
+ "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ],
+
+ // This subnet does not specify its own valid-lifetime value,
+ // so it is inherited from shared network scope.
+ <userinput>"option-data": [
+ {
+ "name": "routers",
+ "data": "192.0.2.1"
+ } ]</userinput>
+ }
+ ]
+ } ]</screen>
+ In this example, there is a log-servers option defined that is available to
+ clients in both subnets in this shared network. Also, a valid lifetime is
+ set to 10 minutes (600s). However, the first subnet overrides some of the values
+ (valid lifetime is 20 minutes, different IP address for log-servers), but
+ also adds its own option (router address). Assuming a client asking for
+ router and log servers options is assigned a lease from this subnet, he will
+ get a lease for 20 minutes and log-servers and routers value of 10.0.0.254.
+ If the same client is assigned to the second subnet, he will get a 10
+ minutes long lease, log-servers value of 1.2.3.4 and routers set to 192.0.2.1.
+ </para>
+
+ <section>
+ <title>Local and relayed traffic in shared networks</title>
+
+ <para>It is possible to specify interface name in the shared network scope to
+ tell the server that this specific shared network is reachable directly (not
+ via relays) using local network interface. It is sufficient to specify
+ it once on the shared network level. As all subnets in a shared network are
+ expected to be used on the same physical link, it is a configuration error
+ to attempt to define a shared network using subnets that are reachable over
+ different interfaces. It is allowed to specify interface parameter on each
+ subnet, although its value must be the same for each subnet. Thus it's
+ usually more convenient to specify it once on the shared network level.
+<screen>
+"shared-networks": [
+ {
+ "name": "office-floor-2",
+
+ // This tells Kea that the whole shared networks is reachable over
+ // local interface. This applies to all subnets in this network.
+ <userinput>"interface": "eth0"</userinput>,
+
+ "subnet4": [
+ {
+ "subnet": "10.0.0.0/8",
+ "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ],
+ <userinput>"interface": "eth0"</userinput>
+ },
+ {
+ "subnet": "192.0.2.0/24",
+ "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ]
+
+ // Specifying a different interface name is configuration
+ // error:
+ // "interface": "eth1"
+ }
+ ]
+ } ]
+</screen>
+</para>
+
+<para>Somewhat similar to interface names, also relay IP addresses can be
+specified for the whole shared network. However, depending on your relay
+configuration, it may use different IP addresses depending on which subnet
+is being used. Thus there is no requirement to use the same IP relay address
+for each subnet. Here's an example:
+
+<screen>
+"shared-networks": [
+ {"
+ "name": "kakapo",
+ <userinput>"relay": {
+ "ip-address": "192.3.5.6"
+ }</userinput>,
+ "subnet4": [
+ {
+ "subnet": "192.0.2.0/26",
+ <userinput>"relay": {
+ "ip-address": "192.1.1.1"
+ }</userinput>,
+ "pools": [ { "pool": "192.0.2.63 - 192.0.2.63" } ]
+ },
+ {
+ "subnet": "10.0.0.0/24",
+ <userinput>"relay": {
+ "ip-address": "192.2.2.2"
+ }</userinput>,
+ "pools": [ { "pool": "10.0.0.16 - 10.0.0.16" } ]
+ }
+ ]
+ }
+]</screen>
+In this particular case the relay IP address specified on network level doesn't
+have much sense, as it is overridden in both subnets, but it was left there
+as an example of how one could be defined on network level. Note that the
+relay agent IP address typically belongs to the subnet it relays packets from,
+but this is not a strict requirement. Therefore Kea accepts any value here
+as long as it is valid IPv4 address.</para>
+
+ </section>
+ <section>
+ <title>Client classification in shared networks</title>
+
+ <para>Sometimes it is desired to segregate clients into specific subnets
+ based on some properties. This mechanism is called client classification
+ and is described in <xref linkend="classify"/>. Client classification
+ can be applied to subnets belonging to shared networks in the same way
+ as it is used for subnets specified outside of shared networks.
+ It is important to understand how the server selects subnets for
+ the clients when client classification is in use, to assure that the
+ desired subnet is selected for a given client type.</para>
+
+ <para>If a subnet is associated with some classes, only the clients
+ belonging to any of these classes can use this subnet. If there are no
+ classes specified for a subnet, any client connected to a given shared
+ network can use this subnet. A common mistake is to assume that the
+ subnet including client classes is preferred over subnets without
+ client classes. Consider the following example:
+
+<screen>
+{
+ "client-classes": [
+ {
+ "name": "b-devices",
+ "test": "option[93].hex == 0x0002"
+ }
+ ],
+ "shared-networks": [
+ {
+ "name": "galah",
+ "interface": "eth0",
+ "subnet4": [
+ {
+ "subnet": "192.0.2.0/26",
+ "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ],
+ },
+ {
+ "subnet": "10.0.0.0/24",
+ "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ],
+ <userinput>"client-class": "b-devices"</userinput>
+ }
+ ]
+ }
+ ]
+}
+</screen>
+
+ If the client belongs to "b-devices" class (because it includes option
+ 93 with a value of 0x0002) it doesn't guarantee that the subnet 10.0.0.0/24
+ will be used (or preferred) for this client. The server can use any of
+ the two subnets because the subnet 192.0.2.0/26 is also allowed for
+ this client. The client classification used in this case should be pereceived
+ as a way to restrict access to certain subnets, rather than a way to express
+ subnet preference. For example, if the client doesn't belong to the
+ "b-devices" class it may only use the subnet 192.0.2.0/26 and will
+ never use the subnet 10.0.0.0/24.
+ </para>
+
+ <para>A typical use case for client classification is in the cable network,
+ where cable modems should use one subnet and other devices should use
+ another subnet within the same shared network. In this case it is required
+ to apply classification on all subnets. The following example defines two
+ classes of devices. The subnet selection is made based on option 93 values.
+<screen>
+{
+ "client-classes": [
+ {
+
+ "name": "a-devices",
+ "test": "option[93].hex == 0x0001"
+ },
+ {
+ "name": "b-devices",
+ "test": "option[93].hex == 0x0002"
+ }
+ ],
+ "shared-networks": [
+ {
+ "name": "galah",
+ "interface": "eth0",
+ "subnet4": [
+ {
+ "subnet": "192.0.2.0/26",
+ "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ],
+ <userinput>"client-class": "a-devices"</userinput>
+ },
+ {
+ "subnet": "10.0.0.0/24",
+ "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ],
+ <userinput>"client-class": "b-devices"</userinput>
+ }
+ ]
+ }
+ ]
+}
+</screen>
+In this example each class has its own restriction. Only clients that belong to
+class "a-devices" will be able to use subnet 192.0.2.0/26 and only clients
+belonging to b-devices will be able to use subnet 10.0.0.0/24. Care should be
+taken to not define too restrictive classification rules, as clients that are
+unable to use any subnets will be refused service. Although, this may be a
+desired outcome if one desires to service only clients of known properties
+(e.g. only VoIP phones allowed on a given link).</para>
+
+ <para>
+ Note that it is possible to achieve similar effect as presented in this
+ section without the use of shared networks. If the subnets are placed in
+ the global subnets scope, rather than in the shared network, the server
+ will still use classification rules to pick the right subnet for a given
+ class of devices. The major benefit of placing subnets within the
+ shared network is that common parameters for the logically grouped
+ subnets can be specified once, in the shared network scope, e.g.
+ "interface" or "relay" parameter. All subnets belonging to this shared
+ network will inherit those parameters.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Host reservations in shared networks</title>
+
+<para>
+ Subnets being part of a shared network allow host reservations, similar to
+ regular subnets:
+ <screen>
+{
+ "shared-networks": [
+ {
+ "name": "frog",
+ "interface": "eth0",
+ "subnet4": [
+ {
+ "subnet": "192.0.2.0/26",
+ "id": 100,
+ "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ],
+ <userinput>"reservations": [
+ {
+ "hw-address": "aa:bb:cc:dd:ee:ff",
+ "ip-address": "192.0.2.28"
+ }
+ ]</userinput>
+ },
+ {
+ "subnet": "10.0.0.0/24",
+ "id": 101,
+ "pools": [ { "pool": "10.0.0.1 - 10.0.0.254" } ],
+ <userinput>"reservations": [
+ {
+ "hw-address": "11:22:33:44:55:66",
+ "ip-address": "10.0.0.29"
+ }
+ ]</userinput>
+ }
+ ]
+ }
+ ]
+}
+ </screen>
+</para>
+<para>It is worth noting that Kea conducts additional checks when processing a
+packet if shared networks are defined. First, instead of simply checking if
+there's a reservation for a given client in his initially selected subnet, it
+goes through all subnets in a shared network looking for a reservation. This is
+one of the reasons why defining a shared network may impact performance. If
+there is a reservation for a client in any subnet, that particular subnet will
+be picked for the client. Although it's technically not an error, it is
+considered a bad practice to define reservations for the same host in multiple
+subnets belonging to the same shared network.</para>
+
+<para>While not strictly mandatory, it is strongly recommended to use explicit
+"id" values for subnets if you plan to use database storage for host
+reservations. If ID is not specified, the values for it be autogenerated,
+i.e. it will assign increasing integer values starting from 1. Thus, the
+autogenerated IDs are not stable across configuration changes.</para>
+ </section>
</section>
- <!-- end of host reservations section -->
- <section id="dhcp4-serverid">
+ <section xml:id="dhcp4-serverid">
<title>Server Identifier in DHCPv4</title>
<para>
The DHCPv4 protocol uses a "server identifier" to allow clients
received. A single server instance will use multiple server identifiers
if it is receiving queries on multiple interfaces.
</para>
+
<para>
- Currently there is no mechanism to override the default server identifiers
- by an administrator. In the future, the configuration mechanism will be used
- to specify the custom server identifier.
+ It is possible to override default server identifier values by specifying
+ "dhcp-server-identifier" option. This option is only supported on the
+ global, shared network and subnet level. It must not be specified
+ on client class and host reservation level.
</para>
+
+ <para>
+ The following example demonstrates how to override server identifier for
+ a subnet:
+<screen>
+"subnet4": [
+ {
+ "subnet": "192.0.2.0/24",
+ "option-data": [
+ {
+ "name": "dhcp-server-identifier",
+ "data": "10.2.5.76"
+ }
+ ],
+ ...
+ }
+]</screen>
+</para>
</section>
- <section id="dhcp4-subnet-selection">
+ <section xml:id="dhcp4-subnet-selection">
<title>How the DHCPv4 Server Selects a Subnet for the Client</title>
<para>
The DHCPv4 server differentiates between the directly connected clients,
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="dhcp6">
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp6">
<title>The DHCPv6 Server</title>
- <section id="dhcp6-start-stop">
+ <section xml:id="dhcp6-start-stop">
<title>Starting and Stopping the DHCPv6 Server</title>
<para>
</section>
- <section id="dhcp6-interface-selection">
-
+ <section xml:id="dhcp6-interface-selection">
<title>Interface Selection</title>
<para>The DHCPv6 server has to be configured to listen on specific network
interfaces. The simplest network interface configuration instructs the server to
no means to validate the format at the moment.
</para>
-
<para>
- <table frame="all" id="dhcp6-std-options-list">
+ <table frame="all" xml:id="dhcp6-std-options-list">
<title>List of Standard DHCPv6 Options</title>
- <tgroup cols='4'>
- <colspec colname='name'/>
- <colspec colname='code' align='center'/>
- <colspec colname='type' align='center'/>
- <colspec colname='array' align='center'/>
+ <tgroup cols="4">
+ <colspec colname="name"/>
+ <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>
<!-- Vendor-specific Information is configurable by the administrator -->
<row><entry>vendor-opts</entry><entry>17</entry><entry>uint32</entry><entry>false</entry></row>
<!--
-<row><entry>interface-id</entry><entry>18</entry><entry>binary</entry><entry>false</entry></row>
+<row><entry>interface-id</entry><entry>18</entry><entry>hex</entry><entry>false</entry></row>
<row><entry>reconf-msg</entry><entry>19</entry><entry>uint8</entry><entry>false</entry></row>
<row><entry>reconf-accept</entry><entry>20</entry><entry>empty</entry><entry>false</entry></row> -->
- -->
+ -->
<row><entry>sip-server-dns</entry><entry>21</entry><entry>fqdn</entry><entry>true</entry></row>
<row><entry>sip-server-addr</entry><entry>22</entry><entry>ipv6-address</entry><entry>true</entry></row>
<row><entry>dns-servers</entry><entry>23</entry><entry>ipv6-address</entry><entry>true</entry></row>
</para>
</section>
- <section id="dhcp6-custom-options">
+ <section id="s46-options">
+ <title>Common Softwire46 Options</title>
+ <para>
+ Softwire46 options are involved in IPv4 over IPv6 provisioning by
+ means of tunneling or translation as specified in the
+ <ulink url="http://tools.ietf.org/html/rfc7598">RFC 7598</ulink>.
+ The following sections provide configuration examples of these
+ options.
+ </para>
+
+ <section id="s46-containers">
+ <title>Softwire46 Container Options</title>
+ <para>
+ S46 container options group rules and optional port parameters
+ for a specified domain. There are three container options specified
+ in the "dhcp6" (top level) option space: MAP-E Container option,
+ MAP-T Container option and S46 Lightweight 4over6 Container option.
+ These options only contain encapsulated options specified below.
+ They do not include any data fields.
+ </para>
+
+ <para>
+ In order to configure the server to send specific container option
+ along with all encapsulated options, the container option must be
+ included in the server configuration as shown below:
+<screen>
+"Dhcp6": {
+ ...
+ "option-data": [
+ {
+ "name": "s46-cont-mape"
+ } ],
+ ...
+}
+</screen>
+
+ This configuration will cause the server to include MAP-E Container
+ option to the client. Use "s46-cont-mapt" or "s46-cont-lw" for the
+ MAP-T Container and S46 Lightweight 4over6 Container options
+ respectively.
+ </para>
+
+ <para>
+ All remaining softwire options described below are included in one
+ of the container options. Thus, they have to be included in appropriate
+ option spaces by selecting a "space" name, which specifies in which
+ option they are supposed to be included.
+ </para>
+ </section>
+
+ <section>
+ <title>S46 Rule Option</title>
+ <para>
+ The S46 Rule option is used for conveying the Basic Mapping Rule (BMR)
+ and Forwarding Mapping Rule (FMR).
+<screen>
+{
+ "space": "s46-cont-mape-options",
+ "name": "s46-rule",
+ "data": "128, 0, 24, 192.0.2.0, 2001:db8:1::/64"
+}
+</screen>
+ Other possible "space" value is "s46-cont-mapt-options".
+ </para>
+
+ <para>
+ The S46 Rule option conveys a number of parameters:
+
+ <itemizedlist>
+ <listitem>
+ <simpara><command>flags</command>, an unsigned 8 bits integer, with
+ currently only the most significant bit specified. It denotes whether
+ the rule can be used for forwarding (128) or not (0).
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><command>ea-len</command>, an 8 bits long Embedded Address length. Allowed values
+ range from 0 to 48.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><command>IPv4 prefix length</command>, 8 bits long; expresses the prefix length of the
+ Rule IPv4 prefix specified in the ipv4-prefix field. Allowed
+ values range from 0 to 32.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><command>IPv4 prefix</command>, a fixed-length 32-bit field that specifies the IPv4
+ prefix for the S46 rule. The bits in the prefix after prefix4-len
+ number of bits are reserved and MUST be initialized to zero by the
+ sender and ignored by the receiver.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><command>IPv6 prefix</command> in prefix/length notation that specifies the IPv6 domain
+ prefix for the S46 rule. The field is padded on the right with zero
+ bits up to the nearest octet boundary when prefix6-len is not evenly
+ divisible by 8.</simpara>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </section>
+ <section>
+ <title>S46 BR Option</title>
+ <para>
+ The S46 BR option is used to convey the IPv6 address of the
+ Border Relay. This option is mandatory in the MAP-E
+ Container option and not permitted in the MAP-T and
+ S46 Lightweight 4over6 Container options.
+<screen>
+{
+ "space": "s46-cont-mape-options",
+ "name": "s46-br",
+ "data": "2001:db8:cafe::1",
+}
+</screen>
+ Other possible "space" value is "s46-cont-lw-options".
+ </para>
+ </section>
+
+ <section>
+ <title>S46 DMR Option</title>
+ <para>
+ The S46 DMR option is used to convey values for the Default
+ Mapping Rule (DMR). This option is mandatory in the MAP-T
+ container option and not permitted in the MAP-E and S46
+ Lightweight 4over6 Container options.
+<screen>
+{
+ "space": "s46-cont-mapt-options",
+ "name": "s46-dmr",
+ "data": "2001:db8:cafe::/64",
+}
+</screen>
+ This option must not be included in other containers.
+ </para>
+ </section>
+
+ <section>
+ <title>S46 IPv4/IPv6 Address Binding option.</title>
+ <para>
+ The S46 IPv4/IPv6 Address Binding option may be used to specify
+ the full or shared IPv4 address of the Customer Edge (CE).
+ The IPv6 prefix field is used by the CE to identify the
+ correct prefix to use for the tunnel source.
+<screen>
+{
+ "space": "s46-cont-lw",
+ "name": "s46-v4v6bind",
+ "data": "192.0.2.3, 2001:db8:1:cafe::/64"
+}
+</screen>
+ This option must not be included in other containers.
+ </para>
+ </section>
+ <section>
+ <title>S46 Port Parameters</title>
+ <para>
+ The S46 Port Parameters option specifies optional port set
+ information that MAY be provided to CEs
+<screen>
+{
+ "space": "s46-rule-options",
+ "name": "s46-portparams",
+ "data": "2, 3/4",
+}
+</screen>
+ Other possible "space" value is "s46-v4v6bind" to include
+ this option in the S46 IPv4/IPv6 Address Binding option.
+ </para>
+ <para>
+ Note that the second value in the example above specifies the
+ PSID and PSID length fields in the format of PSID/PSID length.
+ This is equivalent to the values of PSID-len=4 and
+ PSID=12288 conveyed in the S46 Port Parameters option.
+ </para>
+ </section>
+ </section>
+
+ <section xml:id="dhcp6-custom-options">
<title>Custom DHCPv6 Options</title>
<para>It is possible to define options in addition to the standard ones.
Assume that we want to define a new DHCPv6 option called "foo" which will have
</itemizedlist>
</para>
- <section id="dhcpv6-d2-io-config">
-
+ <section xml:id="dhcpv6-d2-io-config">
<title>DHCP-DDNS Server Connectivity</title>
<para>
In order for NCRs to reach the D2 server, kea-dhcp6 must be able
with classification using expressions.</para>
</section>
- <section xml:id="reservations6-mysql-pgsql">
- <title>Storing Host Reservations in MySQL or PostgreSQL</title>
+ <section id="reservations6-mysql-pgsql-cql">
+ <title>Storing Host Reservations in MySQL, PostgreSQL or Cassandra</title>
<para>
- It is possible to store host reservations in MySQL or PostgreSQL. See <xref linkend="hosts6-storage"/> for information on how to configure Kea to use
- reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
- tools for managing reservations in a database. The Kea wiki <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri> provides detailed
- information and examples of how reservations can be inserted into the
- database.
+ It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See
+ <xref linkend="hosts6-storage" /> for information on how to configure Kea to use
+ reservations stored in MySQL, PostgreSQL or Cassandra. Kea provides dedicated hook for
+ managing reservations in a database, section <xref linkend="host-cmds" /> provide
- detailed information.
++ detailed information. The Kea wiki <uri
++ xmlns:xlink="http://www.w3.org/1999/xlink"
++ xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri>
++ provides some examples how to conduct some common operations
++ on host reservations.
</para>
- <note><simpara>In Kea 1.1.0 maximum length of an option specified per host is
+ <note><simpara>In Kea maximum length of an option specified per host is
arbitrarily set to 4096 bytes.</simpara></note>
</section>
- <section id="reservations6-tuning">
- <section xml:id="reservations6-cql">
- <title>Storing Host Reservations in CQL (Cassandra)</title>
- <para>Kea currently does not support storing reservations in
- Cassandra (CQL).</para>
- </section>
-
+ <section xml:id="reservations6-tuning">
<title>Fine Tuning DHCPv6 Host Reservation</title>
<para>The host reservation capability introduces additional restrictions for the
</section>
<!-- end of host reservations section -->
- <section id="dhcp6-serverid">
+ <!-- shared networks starts here -->
+ <section id="shared-network6">
+ <title>Shared networks in DHCPv6</title>
+
+ <para>DHCP servers use subnet information in two ways. First, it is used
+ to determine the point of attachment, or simply put, where the client is
+ connected to the network. Second, the subnet information is used to group
+ information pertaining to specific location in the network. This approach
+ works well in general case, but the are scenarios where the boundaries are
+ blurred. Sometimes it is useful to have more than one logical IP subnet
+ being deployed on the same physical link. The need to understand
+ that two or more subnets are used on the same link requires additional logic
+ in the DHCP server. This capability has been added in Kea 1.3.0. It is
+ called "shared networks" in Kea and ISC DHCP projects. It is sometimes also
+ called "shared subnets". In Microsoft's nomenclature it is called "multinet".
+ </para>
+
+ <para>There are many use cases where the feature is useful. The most common
+ example in the IPv4 case is when the server is running out of available
+ addresses in a subnet. This is less common in IPv6, but the shared networks
+ are still useful in IPv6. One of the use cases is an exhaustion of IPv6
+ delegated prefixes within a subnet. Another IPv6 specific example
+ is an experiment with addressing scheme. With the advent of IPv6 deployment
+ and vast address space, many organizations split the address space into
+ subnets, then deploy it and after a while discover that they want to split it
+ differently. In the transition period they want both old and new addressing
+ to be available. Thus the need for more than one subnet on the same physical
+ link.</para>
+
+ <para>Finally, the case of cable networks is directly applicable in
+ IPv6. There are two types of devices in cable networks: cable modems and the
+ end user devices behind them. It is a common practice to use different
+ subnet for cable modems to prevent users from tinkering with their cable
+ modems. In this case, the distinction is based on the type of device, rather
+ than coming out of running out address space.</para>
+
+ <para>A client connected to a shared network may be assigned a lease (address
+ or prefix) from any of the pools defined within the subnets belonging to the
+ shared network. Internally, the server selects one of the subnets belonging to the
+ shared network and tries to allocate a lease from this subnet. If the
+ server is unable to allocate a lease from the selected subnet (e.g. due
+ to pools exhaustion) it will use another subnet from the same shared
+ network and try to allocate a lease from this subnet etc. Therefore, in the
+ typical case, the server will allocate all leases available in a given
+ subnet before it starts allocating leases from other subnets belonging to
+ the same shared network. However, in certain situations the client can be
+ allocated a lease from the other subnets before the pools in the first
+ subnet get exhausted, e.g. when the client provides a hint that belongs
+ to another subnet or the client has reservations in a different than
+ default subnet.
+ </para>
+
+ <note>
+ <para>It is strongly discouraged for the Kea deployments to assume that the
+ server doesn't allocate leases from other subnets until it uses all
+ the leases from the first subnet in the shared network. Apart from the
+ fact that hints, host reservations and client classification affect subnet
+ selection, it is also foreseen that we will enhance allocation strategies
+ for shared networks in the future versions of Kea, so as the selection
+ of subnets within a shared network is equally probable (unpredictable).</para>
+ </note>
+
+ <para>In order to define a shared network an additional configuration scope
+ is introduced:
+<screen>
+{
+"Dhcp6": {
+ <userinput>"shared-networks": [
+ {
+ // Name of the shared network. It may be an arbitrary string
+ // and it must be unique among all shared networks.
+ "name": "ipv6-lab-1",
+
+ // Subnet selector can be specifed on the shared network level.
+ // Subnets from this shared network will be selected for clients
+ // communicating via relay agent having the specified IP address.
+ "relay": {
+ "ip-address": "2001:db8:2:34::1"
+ },
+
+ // This starts a list of subnets in this shared network.
+ // There are two subnets in this example.
+ "subnet6": [
+ {
+ "subnet": "2001:db8::/48",
+ "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ]
+ },
+ {
+ "subnet": "3ffe:ffe::/64",
+ "pools": [ { "pool": "3ffe:ffe::/64" } ]
+ }
+ ]
+ } ]</userinput>, // end of shared-networks
+
+ // It is likely that in your network you'll have a mix of regular,
+ // "plain" subnets and shared networks. It is perfectly valid to mix
+ // them in the same config file.
+ //
+ // This is regular subnet. It's not part of any shared-network.
+ "subnet6": [
+ {
+ "subnet": "2001:db9::/48",
+ "pools": [ { "pool": "2001:db9::/64" } ],
+ "relay": {
+ "ip-address": "2001:db8:1:2::1"
+ }
+ }
+ ]
+
+} // end of Dhcp6
+}
+</screen>
+ </para>
+ <para>As you see in the example, it is possible to mix shared and regular
+ ("plain") subnets. Each shared network must have a unique name. This is a
+ similar concept to ID for subnets, but it offers more flexibility. This is used
+ for logging, but also internally for identifying shared networks.</para>
+
+ <para>In principle it makes sense to define only shared networks that
+ consist of two or more subnets. However, for testing purposes it is allowed
+ to define a shared network with just one subnet or even an empty one. This
+ is not a recommended practice in production networks, as the shared network
+ logic requires additional processing and thus lowers server's performance.
+ To avoid unnecessary performance degradation the shared subnets should only
+ be defined when required by the deployment.
+ </para>
+
+ <para>Shared networks provide an ability to specify many parameters in
+ the shared network scope that will apply to all subnets within it. If
+ necessary, you can specify a parameter in the shared network scope and then
+ override its value on the subnet scope. For example:
+<screen>
+"shared-networks": [
+ {
+ "name": "lab-network3",
+ "relay": {
+ "ip-address": "2001:db8:2:34::1"
+ },
+
+ // This applies to all subnets in this shared network, unless
+ // values are overridden on subnet scope.
+ <userinput>"valid-lifetime": 600</userinput>,
+
+ // This option is made available to all subnets in this shared
+ // network.
+ <userinput>"option-data": [ {
+ "name": "dns-servers",
+ "data": "2001:db8::8888"
+ } ]</userinput>,
+
+ "subnet6": [
+ {
+ "subnet": "2001:db8:1::/48",
+ "pools": [ { "pool": "2001:db8:1::1 - 2001:db8:1::ffff" } ],
+
+ // This particular subnet uses different values.
+ <userinput>"valid-lifetime": 1200,
+ "option-data": [
+ {
+ "name": "dns-servers",
+ "data": "2001:db8::1:2"
+ },
+ {
+ "name": "unicast",
+ "data": "2001:abcd::1"
+ } ]</userinput>
+ },
+ {
+ "subnet": "2001:db8:2::/48",
+ "pools": [ { "pool": "2001:db8:2::1 - 2001:db8:2::ffff" } ],
+
+ // This subnet does not specify its own valid-lifetime value,
+ // so it is inherited from shared network scope.
+ <userinput>"option-data": [
+ {
+ "name": "dns-servers",
+ "data": "2001:db8:cafe::1"
+ } ]</userinput>
+ }
+ ],
+ } ]</screen>
+
+ In this example, there is a dns-servers option defined that is available to
+ clients in both subnets in this shared network. Also, a valid lifetime is
+ set to 10 minutes (600s). However, the first subnet overrides some of the values
+ (valid lifetime is 20 minutes, different IP address for dns-servers), but
+ also adds its own option (unicast address). Assuming a client asking for a
+ server unicast and dns servers options is assigned a lease from this subnet,
+ he will get a lease for 20 minutes and dns-servers and be allowed to use
+ server unicast at address 2001:abcd::1. If the same client is assigned to
+ the second subnet, he will get a 10 minutes long lease, dns-servers value of
+ 2001:db8:cafe::1 and no server unicast.
+ </para>
+
+ <para>Some parameters must be the same in all subnets in the same shared
+ network. This restriction applies to <command>interface</command> and
+ <command>rapid-commit</command> settings. The most convenient way is to
+ define them on shared network scope, but you may specify them for each
+ subnet. However, care should be taken for each subnet to have the same
+ value.</para>
+
+ <section>
+ <title>Local and relayed traffic in shared networks</title>
+
+ <para>It is possible to specify interface name in the shared network scope to
+ tell the server that this specific shared network is reachable directly (not
+ via relays) using local network interface. It is sufficient to specify
+ it once in the shared network level. As all subnets in a shared network are
+ expected to be used on the same physical link, it is a configuration error
+ to attempt to make a shared network out of subnets that are reachable over
+ different interfaces. It is allowed to specify interface parameter on each
+ subnet, although its value must be the same for each subnet. Thus it's
+ usually more convenient to specify it once on the shared network level.
+<screen>
+"shared-networks": [
+ {
+ "name": "office-floor-2",
+
+ // This tells Kea that the whole shared networks is reachable over
+ // local interface. This applies to all subnets in this network.
+ <userinput>"interface": "eth0"</userinput>,
+
+ "subnet6": [
+ {
+ "subnet": "2001:db8::/64",
+ "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ],
+ <userinput>"interface": "eth0"</userinput>
+ },
+ {
+ "subnet": "3ffe:abcd::/64",
+ "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ]
+
+ // Specifying a different interface name is configuration
+ // error:
+ // "interface": "eth1"
+ }
+ ],
+ } ]
+</screen>
+</para>
+
+<para>Somewhat similar to interface names, also relay IP addresses can be
+specified for the whole shared network. However, depending on your relay
+configuration, it may use different IP addresses depending on which subnet
+is being used. Thus there is no requirement to use the same IP relay address
+for each subnet. Here's an example:
+
+<screen>
+"shared-networks": [
+ {"
+ "name": "kakapo",
+ <userinput>"relay": {
+ "ip-address": "2001:db8::abcd"
+ }</userinput>,
+ "subnet6": [
+ {
+ "subnet": "2001:db8::/64",
+ <userinput>"relay": {
+ "ip-address": "2001:db8::1234"
+ }</userinput>,
+ "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ]
+ },
+ {
+ "subnet": "3ffe:abcd::/64",
+ "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ],
+ <userinput>"relay": {
+ "ip-address": "3ffe:abcd::cafe"
+ }</userinput>
+ }
+ ]
+ }
+]</screen>
+In this particular case the relay IP address specified on network level doesn't
+have much sense, as it is overridden in both subnets, but it was left there
+as an example of how one could be defined on network level. Note that the
+relay agent IP address typically belongs to the subnet it relays packets from,
+but this is not a strict requirement. Therefore Kea accepts any value here
+as long as it is valid IPv6 address.</para>
+
+ </section>
+ <section>
+ <title>Client classification in shared networks</title>
+
+ <para>Sometimes it is desired to segregate clients into specific subnets
+ based on some properties. This mechanism is called client classification
+ and is described in <xref linkend="classify"/>. Client classification
+ can be applied to subnets belonging to shared networks in the same way
+ as it is used for subnets specified outside of shared networks.
+ It is important to understand how the server selects subnets for
+ the clients when client classification is in use, to assure that the
+ desired subnet is selected for a given client type.</para>
+
+ <para>If a subnet is associated with some classes, only the clients
+ belonging to any of these classes can use this subnet. If there are no
+ classes specified for a subnet, any client connected to a given shared
+ network can use this subnet. A common mistake is to assume that the
+ subnet including client classes is preferred over subnets without
+ client classes. Consider the following example:
+
+<screen>
+{
+ "client-classes": [
+ {
+ "name": "b-devices",
+ "test": "option[1234].hex == 0x0002"
+ }
+ ],
+ "shared-networks": [
+ {
+ "name": "galah",
+ "relay": {
+ "ip-address": "2001:db8:2:34::1"
+ },
+ "subnet6": [
+ {
+ "subnet": "2001:db8:1::/64",
+ "pools": [ { "pool": "2001:db8:1::20 - 2001:db8:1::ff" } ],
+ },
+ {
+ "subnet": "2001:db8:3::/64",
+ "pools": [ { "pool": "2001:db8:3::20 - 2001:db8:3::ff" } ],
+ <userinput>"client-class": "b-devices"</userinput>
+ }
+ ]
+ }
+ ]
+}
+</screen>
+
+ If the client belongs to "b-devices" class (because it includes option
+ 1234 with a value of 0x0002) it doesn't guarantee that the subnet 2001:db8:3::/64
+ will be used (or preferred) for this client. The server can use any of
+ the two subnets because the subnet 2001:db8:1::/64 is also allowed for
+ this client. The client classification used in this case should be pereceived
+ as a way to restrict access to certain subnets, rather than a way to express
+ subnet preference. For example, if the client doesn't belong to the
+ "b-devices" class it may only use the subnet 2001:db8:1::/64 and will
+ never use the subnet 2001:db8:3::/64.
+ </para>
+
+ <para>A typical use case for client classification is in the cable network,
+ where cable modems should use one subnet and other devices should use
+ another subnet within the same shared network. In this case it is required
+ to apply classification on all subnets. The following example defines two
+ classes of devices. The subnet selection is made based on option 1234 values.
+<screen>
+{
+ "client-classes": [
+ {
+
+ "name": "a-devices",
+ "test": "option[1234].hex == 0x0001"
+ },
+ {
+ "name": "b-devices",
+ "test": "option[1234].hex == 0x0002"
+ }
+ ],
+ "shared-networks": [
+ {
+ "name": "galah",
+ "relay": {
+ "ip-address": "2001:db8:2:34::1"
+ },
+ "subnet6": [
+ {
+ "subnet": "2001:db8:1::/64",
+ "pools": [ { "pool": "2001:db8:1::20 - 2001:db8:1::ff" } ],
+ <userinput>"client-class": "a-devices"</userinput>
+ },
+ {
+ "subnet": "2001:db8:3::/64",
+ "pools": [ { "pool": "2001:db8:3::20 - 2001:db8:3::ff" } ],
+ <userinput>"client-class": "b-devices"</userinput>
+ }
+ ]
+ }
+ ]
+}
+</screen>
+In this example each class has its own restriction. Only clients that belong to
+class a-devices will be able to use subnet 2001:db8:1::/64 and only clients
+belonging to b-devices will be able to use subnet 2001:db8:3::/64. Care should
+be taken to not define too restrictive classification rules, as clients that are
+unable to use any subnets will be refused service. Although, this may be
+desired outcome if one desires to service only clients of known properties
+(e.g. only VoIP phones allowed on a given link).</para>
+
+ <para>
+ Note that it is possible to achieve similar effect as presented in this
+ section without the use of shared networks. If the subnets are placed in
+ the global subnets scope, rather than in the shared network, the server
+ will still use classification rules to pick the right subnet for a given
+ class of devices. The major benefit of placing subnets within the
+ shared network is that common parameters for the logically grouped
+ subnets can be specified once, in the shared network scope, e.g.
+ "interface" or "relay" parameter. All subnets belonging to this shared
+ network will inherit those parameters.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Host reservations in shared networks</title>
+
+<para>
+ Subnets being part of a shared network allow host reservations, similar to
+ regular subnets:
+ <screen>
+{
+ "shared-networks": [
+ {
+ "name": "frog",
+ "relay": {
+ "ip-address": "2001:db8:2:34::1"
+ },
+ "subnet6": [
+ {
+ "subnet": "2001:db8:1::/64",
+ "id": 100,
+ "pools": [ { "2001:db8:1::1 - 2001:db8:1::64" } ],
+ <userinput>"reservations": [
+ {
+ "duid": "00:03:00:01:11:22:33:44:55:66",
+ "ip-addresses": [ "2001:db8:1::28" ]
+ }
+ ]</userinput>
+ },
+ {
+ "subnet": "2001:db8:3::/64",
+ "id": 101,
+ "pools": [ { "pool": "2001:db8:3::1 - 2001:db8:3::64" } ],
+ <userinput>"reservations": [
+ {
+ "duid": "00:03:00:01:aa:bb:cc:dd:ee:ff",
+ "ip-addresses": [ "2001:db8:2::28" ]
+ }
+ ]</userinput>
+ }
+ ]
+ }
+ ]
+}
+ </screen>
+</para>
+<para>It is worth noting that Kea conducts additional checks when processing a
+packet if shared networks are defined. First, instead of simply checking if
+there's a reservation for a given client in his initially selected subnet, it
+goes through all subnets in a shared network looking for a reservation. This is
+one of the reasons why defining a shared network may impact performance. If
+there is a reservation for a client in any subnet, that particular subnet will
+be picked for the client. Although it's technically not an error, it is
+considered a bad practice to define reservations for the same host in multiple
+subnets belonging to the same shared network.</para>
+
+<para>While not strictly mandatory, it is strongly recommended to use explicit
+"id" values for subnets if you plan to use database storage for host
+reservations. If ID is not specified, the values for it be autogenerated,
+i.e. it will assign increasing integer values starting from 1. Thus, the
+autogenerated IDs are not stable across configuration changes.
+</para>
+ </section>
+
+ </section>
+
+ <!-- end of shared networks -->
+
+ <section xml:id="dhcp6-serverid">
<title>Server Identifier in DHCPv6</title>
<para>The DHCPv6 protocol uses a "server identifier" (also known
as a DUID) for clients to be able to discriminate between several
<listitem>
<simpara><emphasis>Issues and Recommendations with Multiple
Stateful DHCPv6 Options</emphasis>,
- <ulink url="http://tools.ietf.org/html/rfc7550">RFC
- 7550</ulink>: All recommendations related to the DHCPv6 server
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7550">RFC
+ 7550</link>: All recommendations related to the DHCPv6 server
operation are supported.</simpara>
</listitem>
+ <listitem>
+ <simpara><emphasis>DHCPv6 Options for Configuration of Softwire
+ Address and Port-Mapped Clients</emphasis>,
+ <ulink url="http://tools.ietf.org/html/rfc7598">RFC
+ 7598</ulink>: All options specified in this specification are
+ supported by the DHCPv6 server.</simpara>
+ </listitem>
</itemizedlist>
</section>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="faq">
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="faq">
<title>Frequently Asked Questions</title>
<para>This chapter contains a number of frequently asked questions and
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="hooks-libraries">
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hooks-libraries">
<title>Hooks Libraries</title>
- <section id="hooks-libraries-introduction">
+ <section xml:id="hooks-libraries-introduction">
<title>Introduction</title>
<para>
Although Kea offers a lot of flexibility, there may be cases where
link address: 3001::1, hop count: 1, identified by remote-id:
01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f
</screen>
- </para>
+ </para>
+ <para>
+ In addition to logging lease activity driven by DHCPv6 client traffic, it also
+ logs entries for the following lease management control channel commands:
+ lease6-add, lease6-update, and lease6-del. Each entry is a single string
+ with no embedded end-of-line markers and they will typically have the following
+ forms:
+ </para>
+ <para>
+ <command>lease6-add:</command>
+<screen>
+ Administrator added a lease of address: *address* to a device with DUID: *DUID*
+</screen>
+ Dependent on the arguments of the add command, it may also include the hardware address and duration.
+ </para>
+ <para>
+ Example:
+<screen>
+Administrator added a lease of address: 2001:db8::3 to a device with DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24 for 1 days 0 hrs 0 mins 0 secs
+</screen>
+ </para>
+ <para>
+ <command>lease6-update:</command>
+<screen>
+Administrator updated information on the lease of address: *address* to a device with DUID: *DUID*
+</screen>
+ Dependent on the arguments of the update command, it may also include the hardware address and lease duration.
+ </para>
+ <para>
+ Example:
+<screen>
+Administrator updated information on the lease of address: 2001:db8::3 to a device with DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24, hardware address: 1a:1b:1c:1d:1e:1f
+</screen>
+ </para>
+ <para>
+ <command>lease6-del:</command>
+ Deletes have two forms, one by address and one by identifier and identifier type:
+<screen>
+Administrator deleted the lease for address: *address*
+</screen>
+ or
+<screen>
+Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
+</screen>
+ Currently only a type of DUID is supported.
+ </para>
+ <para>
+Examples:
+<screen>
+Administrator deleted the lease for address: 2001:db8::3
+
+Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24
+</screen>
+ </para>
</section>
- <section id="forensic-log-configuration">
+ <section xml:id="forensic-log-configuration">
<title>Configuring the Forensic Log Hooks</title>
<para>
To use this functionality the hook library must be included in the
]
}
</screen>
+
+ <para>
+ When "replace-client-id" is set to false (which is the default setting),
+ the flex-id hook library uses evaluated flexible identifier solely for
+ identifying host reservations, i.e. searching for reservations within a
+ database. This is a functional equivalent of other identifiers,
+ similar to hardware address or circuit-id. However,
+ this mode of operation has an implication that if a client device is
+ replaced, it may cause a conflict between an existing lease (allocated
+ for old device) and the new lease being allocated for the new device. The
+ conflict arises because the same flexible identifier is computed for the
+ replaced device and the server will try to allocate the same lease. The
+ mismatch between client identifiers sent by new device and old device causes
+ the server to refuse this new allocation until the old lease expires.
+ A manifestation of this problem is dependant on specific expression
+ used as flexible identifier and is likely to appear if you only use options
+ and other parameters that are identifying where the device is
+ connected (e.g. circuit-id), rather than the device identification
+ itself (e.g. MAC address).
+ </para>
+
+ <para>
+ The flex-id library offers a way to overcome the problem with lease conflicts
+ by dynamically replacing client identifier (or DUID in DHCPv6 case) with a
+ value derived from flexible identifier. The server processes the client's
+ query as if flexible identifier was sent in the client identifier (or DUID)
+ option. This guarantees that returning client (for which the same flexible
+ identifier is evaluated) will be assigned the same lease despite the client
+ identifier and/or MAC address change.
+ </para>
+
+ <para>
+ The following is a stub configuration that enables this behavior:
+<screen>
+"Dhcp4": { <userinput>
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_flex_id.so",
+ "parameters": {
+ "identifier-expression": "<userinput>expression</userinput>",
+ "replace-client-id": "<userinput>true</userinput>"
+ }
+ },
+ ...
+ ] </userinput>
+}
+</screen>
+ </para>
+
+ <para>
+ In the DHCPv4 case, the value derived from the flexible identifier is formed
+ by prepending 1 byte with a value of zero to flexible identifier. In the IPv6
+ case, it is formed by prepanding two zero bytes before the flexible identifier.
+ </para>
+
+ <para>
+ Note that for this mechanism to take effect, the DHCPv4 server must be configured
+ to respect the client identifier option value during lease allocation, i.e.
+ "match-client-id" must be set to true. See
+ <xref linkend="dhcp4-match-client-id"/> for details. No additional settings
+ are required for DHCPv6.
+ </para>
+ <para>
+ If "replace-client-id" option is set to true, the value of "echo-client-id"
+ parameter (that governs whether to send back a client-id option or
+ not) is ignored.
+ </para>
+
+ <para>
+ The <xref linkend="lease-cmds"/> section describes commands used to retrieve,
+ update and delete leases using various identifiers, e.g. "hw-address",
+ "client-id". The lease_cmds library doesn't natively support querying for
+ leases by flexible identifier. However, when "replace-client-id" is set to
+ true, it makes it possible to query for leases using a value derived from
+ the flexible identifier. In the DHCPv4 case, the query will look similar to this:
+<screen>
+{
+ "command": "lease4-get",
+ "arguments": {
+ "identifier-type": "client-id",
+ "identifier": "00:<userinput>54:64:45:66</userinput>",
+ "subnet-id": 44
+ }
+}
+</screen>
+
+ where hexadecimal value of "54:64:45:66" is a flexible identifier computed
+ for the client.
+ </para>
+
+ <para>
+ In the DHCPv6 case, the corresponding query will look similar to this:
+<screen>
+{
+ "command": "lease6-get",
+ "arguments": {
+ "identifier-type": "duid",
+ "identifier": "00:00:<userinput>54:64:45:66</userinput>",
+ "subnet-id": 10
+ }
+}</screen>
+
+ </para>
</section>
- <section id="host-cmds">
+ <section xml:id="host-cmds">
<title>host_cmds: Host Commands</title>
<para>
This section describes a hook application that offers a number of new
</para>
</section>
+ <section>
+ <title>network4-list, network6-list commands</title>
+ <para>
+ These commands are used to retrieve full list of currently configured
+ shared networks. The list contains only very basic information about
+ each shared network. If more details are needed, please use
+ <command>network4-get</command> or <command>network6-get</command> to
+ retrieve all information available. This command does not require any
+ parameters and its invocation is very simple:
+<screen>
+{
+ "command": "network4-list"
+}
+</screen>
+An example response for <command>network4-list</command> looks as follows:
+<screen>
+{
+ "arguments": {
+ "shared-networks": [
+ { "name": "floor1" },
+ { "name": "office" }
+ ]
+ },
+ "result": 0,
+ "text": "2 IPv4 network(s) found"
+}</screen>
+<command>network6-list</command> follows exactly the same syntax for
+both the query and the response.
+ </para>
+ </section>
+
+ <section>
+ <title>network4-get, network6-get commands</title>
+ <para>
+ These commands are used to retrieve detailed information
+ about shared networks, including subnets currently
+ being part of a given network. Both commands take one
+ mandatory parameter <command>name</command>, which specify
+ the name of shared network. An example command to retrieve
+ details about IPv4 shared network with a name "floor13"
+ looks as follows:
+<screen>
+{
+ "command": "network4-get",
+ "arguments": {
+ "name": "floor13"
+ }
+}</screen>
+An example response could look as follows:
+<screen>
+{
+ "result": 0,
+ "text": "Info about IPv4 shared network 'floor13' returned",
+ "arguments": {
+ "shared-networks": [
+ {
+ "match-client-id": true,
+ "name": "floor13",
+ "option-data": [ ],
+ "rebind-timer": 90,
+ "relay": {
+ "ip-address": "0.0.0.0"
+ },
+ "renew-timer": 60,
+ "reservation-mode": "all",
+ "subnet4": [
+ {
+ "subnet": "192.0.2.0/24",
+ "id": 5,
+ // many other subnet specific details here
+ },
+ {
+ "id": 6,
+ "subnet": "192.0.3.0/31",
+ // many other subnet specific details here
+ }
+ ],
+ "valid-lifetime": 120
+ }
+ ]
+ }
+}
+</screen>
+Note that actual response contains many additional fields that are
+omitted here for clarity. The response format is exactly the same as
+used in <command>config-get</command>, just is limited to returning
+shared networks information.
+ </para>
</section>
-</section> <!-- end of subnet commands -->
+
+ <section>
+ <title>network4-add, network6-add commands</title>
+ <para>
+ These commands are used to add a new shared network. New
+ network has to have unique name. This command requires one parameter
+ <command>shared-networks</command>, which is a list and
+ should contain exactly one entry that defines the
+ network. The only mandatory element for a network is its
+ name. Although it does not make operational sense, it is
+ allowed to add an empty shared network that does not have
+ any subnets in it. That is allowed for testing purposes, but
+ having empty networks (or with only one subnet) is
+ discouraged in production environments. For details regarding
+ syntax, see <xref linkend="shared-network4"/> and <xref
+ linkend="shared-network6"/>.
+ </para>
+ <note><para>As opposed to parameter inheritance during full
+ new configuration processing, this command does not fully handle
+ parameter inheritance and any missing parameters will be
+ filled with default values, rather than inherited from
+ global scope.</para></note>
+ <para>
+ An example that showcases how to add a new IPv4 shared network looks
+ as follows:
+<screen>
+{
+ "command": "network4-add",
+ "arguments": {
+ "shared-networks": [ {
+ "name": "floor13",
+ "subnet4": [
+ {
+ "id": 100,
+ "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
+ "subnet": "192.0.2.0/24",
+ "option-data": [
+ {
+ "name": "routers",
+ "data": "192.0.2.1"
+ }
+ ]
+ },
+ {
+ "id": 101,
+ "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
+ "subnet": "192.0.3.0/24",
+ "option-data": [
+ {
+ "name": "routers",
+ "data": "192.0.3.1"
+ }
+ ]
+ } ]
+ } ]
+ }
+}
+</screen>
+Assuming there was no shared network with a name floor13 and no subnets with id
+100 and 101 previously configured, the command will be successful and will
+return the following response:
+<screen>
+{
+ "arguments": {
+ "shared-networks": [ { "name": "floor13" } ]
+ },
+ "result": 0,
+ "text": "A new IPv4 shared network 'floor13' added"
+}
+</screen>
+The <command>network6-add</command> uses the same syntax for both the query and
+the response. However, there are some parameters that are IPv4-only
+(e.g. match-client-id) and some are IPv6-only (e.g. interface-id). The same
+applies to subnets within the network.
+ </para>
+ </section>
+ <section>
+ <title>network4-del, network6-del commands</title>
+ <para>
+ These commands are used to delete existing shared networks. Each
+ subnet within the network being removed will be demoted to a plain
+ subnet. If you want to completely remove the subnets, please use
+ <command>subnet4-del</command> or <command>subnet6-del</command>
+ commands. Both commands take exactly one parameter 'name' that
+ specifies the name of the network to be removed. An example invocation
+ of <command>network4-del</command> command looks as follows:
+<screen>
+{
+ "command": "network4-del",
+ "arguments": {
+ "name": "floor13"
+ }
+}
+</screen>
+Assuming there was such a network configured, the response will look similar to
+the following:
+<screen>
+{
+ "arguments": {
+ "shared-networks": [
+ {
+ "name": "floor1"
+ }
+ ]
+ },
+ "result": 0,
+ "text": "IPv4 shared network 'floor13' deleted"
+}</screen>
+The <command>network6-del</command> command uses exactly the same syntax for
+both the command and the response.
+ </para>
+
+ </section>
+ <section>
+ <title>network4-subnet-add, network6-subnet-add commands</title>
+ <para>
+ These commands are used to add existing subnets to existing shared
+ networks. There are several ways to add new shared network. System
+ administrator can add the whole shared network at once, either by
+ editing a configuration file or by calling
+ <command>network4-add</command> or <command>network6-add</command>
+ commands with desired subnets in it. This approach works better for completely
+ new shared subnets. However, there may be cases when an existing
+ subnet is running out of addresses and needs to be extended with
+ additional address space. In other words another subnet has to be
+ added on top of it. For this scenario, a system administrator can use
+ <command>network4-add</command> or <command>network6-add</command> and
+ then add existing subnet to this newly created shared network using
+ <command>network4-subnet-add</command> or
+ <command>network6-subnet-add</command>.
+ </para>
+ <para>
+ The <command>network4-subnet-add</command> and
+ <command>network6-subnet-add</command> commands take two parameters:
+ <command>id</command>, which is an integer and specifies subnet-id of existing subnet to
+ be added to a shared network; and <command>name</command>, which
+ specifies name of the shared network the subnet will be added to. The
+ subnet must not belong to any existing network. In case you want to
+ reassign a subnet from one shared network to another, please use
+ <command>network4-subnet-del</command> or
+ <command>network6-subnet-del</command> commands first.
+ </para>
+ <para>
+ An example invocation of <command>network4-subnet-add</command>
+ command looks as follows:
+<screen>
+{
+ "command": "network4-subnet-add",
+ "arguments": {
+ "name": "floor13",
+ "id": 5
+ }
+}</screen>
+Assuming there is a network named 'floor13', there is a subnet with subnet-id 5
+and it is not a part of existing network, the command will return a response
+similar to the following:
+<screen>
+{
+ "result": 0,
+ "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
+}</screen>
+ The <command>network6-subnet-add</command> command uses exactly the same syntax for
+both the command and the response.
+ </para>
+
+ <note><para>As opposed to parameter inheritance during full
+ new configuration processing or when adding a new shared network with
+ new subnets, this command does not fully handle
+ parameter inheritance and any missing parameters will be
+ filled with default values, rather than inherited from
+ global scope or from the shared network.</para></note>
+ </section>
+ <section>
+ <title>network4-subnet-del, network6-subnet-del commands</title>
+ <para>
+ These commands are used to remove a subnet that is part of existing shared
+ network and demote it to a plain, stand-alone subnet. If you want to
+ remove a subnet completely, use <command>subnet4-del</command> or
+ <command>subnet6-del</command> commands instead.
+ The <command>network4-subnet-del</command> and
+ <command>network6-subnet-del</command> commands take two parameters:
+ <command>id</command>, which is an integer and specifies subnet-id of
+ existing subnet to be removed from a shared network; and
+ <command>name</command>, which specifies name of the shared network
+ the subnet will be removed from.
+ </para>
+ <para>An example invocation of the
+ <command>network4-subnet-del</command> command looks as follows:
+ <screen>
+ {
+ "command": "network4-subnet-del",
+ "arguments": {
+ "name": "floor13",
+ "id": 5
+ }
+ }</screen>
+ Assuming there was a subnet with subnet-id equal to 5 that was part of a shared
+ network named 'floor13', the response would look similar to the following:
+<screen>
+{
+ "result": 0,
+ "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
+}</screen>
+The <command>network6-subnet-del</command> command uses exactly the same syntax for
+both the command and the response.
+ </para>
+ </section>
+
+ </section> <!-- end of subnet commands -->
+
+ <section id="high-availability-library">
+ <title>libdhcp_ha: High Availability</title>
+ <para>
+ This section will describe the <command>libdhcp_ha</command> hook library
+ being developed for the Kea 1.4.0 release.
+ </para>
+ </section> <!-- end of high-availability-library -->
+
+ </section>
+
+
- <section id="user-context">
+ <section xml:id="user-context">
<title>User contexts</title>
<para>Hook libraries can have their own configuration parameters. That is
convenient if the parameter applies to the whole library. However,
- </chapter> <!-- hooks-libraries -->
- </chapter>
++ </chapter>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+
- <chapter id="installation">
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation">
<title>Installation</title>
- <section id="packages">
+ <section xml:id="packages">
<title>Packages</title>
<para>
on the system:</para>
<itemizedlist>
<listitem>
- <para>Boost build-time headers
+ <para>Boost C++ Libraries
- (<ulink url="http://www.boost.org/"/>).
+ (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/">http://www.boost.org/</uri>).
- At least Boost version 1.41 is required.
- When header-only Boost error code is not available or wanted, the
- Boost system library is required too.
+ The oldest Boost version used for testing is 1.57 (it may work with
+ older versions). Boost system library is required. Building boost
+ header only is no longer recommended.
</para>
</listitem>
</itemizedlist>
- <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/SystemSpecificNotes">http://kea.isc.org/wiki/SystemSpecificNotes</uri>
+ <para>
+ Visit the user-contributed wiki at
-
++ <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/Install">http://kea.isc.org/wiki/Install</uri>
+ for system-specific installation tips.
+ </para>
</section>
- <section id="install">
+ <section xml:id="install">
<title>Installation from Source</title>
<para>
Kea is open source software written in C++. It is freely available in
are a developer planning to contribute to Kea, please fork our Github
repository and use the "pull request" mechanism to request integration of
your code. Please consult
- <ulink url="https://help.github.com/articles/fork-a-repo/"/> for help on
+ <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://help.github.com/articles/fork-a-repo/">https://help.github.com/articles/fork-a-repo/</uri> for help on
how to fork a Github repository.
- The <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
- Developer's Guide</ulink> contains more information about the process, as
- The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
++ The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
+ Developer's Guide</link> contains more information about the process, as
well as describing the requirements for contributed code to be accepted by ISC.
</para>
<para>The install step may require superuser privileges.</para>
</note>
<para>
-- If required, run <command>ldconfig</command> as root with
-- <filename>/usr/local/lib</filename> (or with <replaceable>prefix</replaceable>/lib if
-- configured with --prefix) in
-- <filename>/etc/ld.so.conf</filename> (or the relevant linker
-- cache configuration file for your OS):
-- <screen>$ <userinput>ldconfig</userinput></screen>
++ If required, run <command>ldconfig</command> as root with
++ <filename>/usr/local/lib</filename> (or with <replaceable>prefix</replaceable>/lib if
++ configured with --prefix) in
++ <filename>/etc/ld.so.conf</filename> (or the relevant linker
++ cache configuration file for your OS):
++ <screen>$ <userinput>ldconfig</userinput></screen>
</para>
<note>
<para>
-- If you do not run <command>ldconfig</command> where it is
-- required, you may see errors like the following:
++ If you do not run <command>ldconfig</command> where it is
++ required, you may see errors like the following:
<screen>
-- program: error while loading shared libraries: libkea-something.so.1:
-- cannot open shared object file: No such file or directory
-- </screen>
-- </para>
++ program: error while loading shared libraries: libkea-something.so.1:
++ cannot open shared object file: No such file or directory
++ </screen>
++ </para>
</note>
</section>
<varlistentry>
<term>JSON</term>
<listitem>
- <simpara>JSON is the default configuration backend
- <simpara>JSON is the new default configuration backend
-- that allows Kea to read JSON configuration files from
-- disk. It does not require any framework and thus is
- considered more lightweight. It allows dynamic on-line
- considered more lightweight. It will allow dynamic
- on-line reconfiguration, but lacks remote capabilities
- (i.e. no RESTful API).</simpara>
++ <simpara>JSON is the default configuration backend
++ that allows Kea to read JSON configuration files from
++ disk. It does not require any framework and thus is
++ considered more lightweight. It allows dynamic on-line
+ reconfiguration using Kea API.</simpara>
</listitem>
</varlistentry>
</variablelist>
"configure" step (see <xref linkend="configure"/>), the --with-dhcp-mysql switch
should be specified:
<screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
-- If MySQL was not installed in the default location, the location of the MySQL
++ If MySQL was not installed in the default location, the location of the MySQL
configuration program "mysql_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
</para>
"configure" step (see <xref linkend="configure"/>), the --with-dhcp-pgsql switch
should be specified:
<screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
-- If PostgreSQL was not installed in the default location, the location of the PostgreSQL
++ If PostgreSQL was not installed in the default location, the location of the PostgreSQL
configuration program "pg_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
</para>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- <!ENTITY % version SYSTEM "version.ent">
- %version;
-<!-- Converted by db4-upgrade version 1.1 -->
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
++<!-- need this include to make the &keaversion; macro work -->
++<!DOCTYPE book [
++<!ENTITY % keaversion SYSTEM "version.ent">
++%keaversion;
+]>
+
- <chapter id="intro">
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="intro">
<title>Introduction</title>
<para>
Kea is the next generation of DHCP software developed by ISC.
</para>
<para>
- This guide covers Kea version &__VERSION__;.
- This guide covers Kea version .
++ This guide covers Kea version &keaversion;.
</para>
<section>
</simpara>
</listitem>
- <command>kea-ctrl-agent</command> —
+ <listitem>
+ <simpara>
++ <command>kea-ctrl-agent</command> —
+ Kea Control Agent (CA) is a daemon exposes a RESTful control
+ interface for managing Kea servers.
+ </simpara>
+ </listitem>
+
<listitem>
<simpara>
- <command>perfdhcp</command> —
+ <command>perfdhcp</command> —
A DHCP benchmarking tool which simulates multiple clients to
test both DHCPv4 and DHCPv6 server performance.
</simpara>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- <!ENTITY % version SYSTEM "version.ent">
- %version;
- ]>
-
++<?xml version="1.0"?>
+<!--
- - Copyright (C) 2010-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <book>
++<!-- need this include to make the &keaversion; macro work -->
++<!DOCTYPE book [
++<!ENTITY % keaversion SYSTEM "version.ent">
++%keaversion;
++]>
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <book xmlns="http://docbook.org/ns/docbook" version="5.0">
<?xml-stylesheet href="kea-guide.css" type="text/css"?>
- <bookinfo>
+ <info>
<title>
<inlinemediaobject>
Kea Administrator Reference Manual
</title>
-- <releaseinfo>This is the reference guide for Kea version
- &__VERSION__;.</releaseinfo>
- .</releaseinfo>
++ <releaseinfo>This is the reference guide for Kea version &keaversion;.</releaseinfo>
<copyright>
- <year>2010-2017</year><holder>Internet Systems Consortium, Inc.</holder>
+ <year>2010-2017</year>
+ <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<abstract>
</para>
<para>
- This is the reference guide for Kea version &__VERSION__;.
- This is the reference guide for Kea version .
++ This is the reference guide for Kea version &keaversion;.
The most up-to-date version of this document (in PDF, HTML,
and plain text formats), along with other documents for
- Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
+ Kea, can be found at <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/docs">http://kea.isc.org/docs</uri>.
</para> </abstract>
- </bookinfo>
+ </info>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="admin.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="admin.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lease-expiration.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lease-expiration.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="classify.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="classify.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stats.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stats.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ctrl-channel.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ctrl-channel.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shell.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shell.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml"/>
- <chapter id="acknowledgments">
- <chapter xml:id="acknowledgments">
++ <chapter xml:id="acknowledgments">
<title>Acknowledgments</title>
- <para>Kea is primarily designed, developed, and maintained by
- Internet Systems Consortium, Inc. It is an open source project
- and contributions are welcomed.</para>
-
- <para>Support for the development of the DHCPv4, DHCPv6 and
- DHCP-DDNS components was provided by
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.comcast.com/">Comcast</link>.</para>
+ <para>Kea is an open source project designed, developed, and maintained by Internet Systems
+ Consortium, Inc, a 501(c)3 non-profit organization. ISC is primarily funded by revenues from
+ support subscriptions for our open source and we encourage all professional users to consider
+ this option. To learn more, see <ulink
+ url="https://www.isc.org/support/">https://www.isc.org/support/</ulink>.</para>
- <para>Kea was initially implemented as a collection of applications
- within the BIND 10 framework. Hence, Kea development would not be
- possible without the generous support of past BIND 10 project sponsors.</para>
+ <para>If you would like to contribute to ISC to assist us in continuing to make quality open
+ source software, please visit our donations page at <ulink
+ url="http://www.isc.org/donate/">http://www.isc.org/donate/</ulink>.</para>
-
- <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://jprs.co.jp/">JPRS</link> and
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cira.ca/">CIRA</link> were Patron Level
- BIND 10 sponsors.</para>
+ <para>We thank all the organizations and individuals who have helped to make Kea
- possible. Comcast and the Comcast Innovation Fund provided major support for the development
++ possible. <link xmlns:xlink="http://www.w3.org/1999/xlink"
++ xlink:href="http://www.comcast.com/">Comcast</link>
++ and the Comcast Innovation Fund provided major support for the development
+ of Kea's DHCPv4, DHCPv6 and DDNS modules. Mozilla funded initial work on the REST API via a
+ MOSS award.</para>
-
- <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afnic.fr/">AFNIC</link>,
+ <para>Kea was initially implemented as a collection of applications
+ within the BIND 10 framework. We thank the founding sponsors of the BIND10 project:
- <ulink url="https://www.afilias.info/">Afilias</ulink>,
- <ulink url="https://www.iis.se/">IIS.SE</ulink>,
- <ulink url="http://www.nominet.org.uk/">Nominet</ulink>, and
- <ulink url="https://www.sidn.nl/">SIDN</ulink>; BIND10 patrons
- <ulink url="http://jprs.co.jp/">JPRS</ulink> and
- <ulink url="http://cira.ca/">CIRA</ulink>; and additional sponsors
- <ulink url="https://www.afnic.fr/">AFNIC</ulink>,
- <ulink url="https://www.cnnic.net.cn/">CNNIC</ulink>,
- <ulink url="https://www.nic.cz/">CZ.NIC</ulink>,
- <ulink url="http://www.denic.de/">DENIC eG</ulink>,
- <ulink url="https://www.google.com/">Google</ulink>,
- <ulink url="https://www.ripe.net/">RIPE NCC</ulink>,
- <ulink url="https://registro.br/">Registro.br</ulink>,
- <ulink url="https://nzrs.net.nz/">.nz Registry Services</ulink>, and
- <ulink url="https://www.tcinet.ru/">Technical Center of Internet</ulink>.</para>
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afilias.info/">Afilias</link>,
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iis.se/">IIS.SE</link>,
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.nominet.org.uk/">Nominet</link>,
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.sidn.nl/">SIDN</link>,
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://jprs.co.jp/">JPRS</link>,
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cira.ca/">CIRA</link>; and additional sponsors
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afnic.fr/">AFNIC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.cnnic.net.cn/">CNNIC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.nic.cz/">CZ.NIC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.denic.de/">DENIC eG</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.google.com/">Google</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ripe.net/">RIPE NCC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://registro.br/">Registro.br</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://nzrs.net.nz/">.nz Registry Services</link>, and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.tcinet.ru/">Technical Center of Internet</link>
- were past BIND 10 sponsors.</para>
-
- <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afilias.info/">Afilias</link>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iis.se/">IIS.SE</link>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.nominet.org.uk/">Nominet</link>, and
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.sidn.nl/">SIDN</link> were founding
- sponsors of the BIND 10 project.</para>
++ .</para>
</chapter>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+
- <chapter id="keactrl">
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="keactrl">
<title>Managing Kea with keactrl</title>
- <section id="keactrl-overview">
+ <section xml:id="keactrl-overview">
<title>Overview</title>
<para>keactrl is a shell script which controls the startup, shutdown
and reconfiguration of the Kea servers (<command>kea-dhcp4</command>,
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
- <chapter id="lease-expiration">
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="lease-expiration">
<title>Lease Expiration in DHCPv4 and DHCPv6</title>
<para>The primary role of the DHCP server is to assign addresses and/or
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+
- <chapter id="kea-lfc">
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-lfc">
<title>The LFC process</title>
- <section id="kea-lfc-overview">
+ <section xml:id="kea-lfc-overview">
<title>Overview</title>
<para><command>kea-lfc</command> is a service process that removes
redundant information from the files used to provide persistent storage
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+
- <chapter id="libdhcp">
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="libdhcp">
<title>The libdhcp++ Library</title>
<para>
libdhcp++ is a library written in C++ that handles
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <!-- Note: Please use the following terminology:
- - daemon - one process (e.g. kea-dhcp4)
- - component - one piece of code within a daemon (e.g. libdhcp or hooks)
- - server - currently equal to daemon, but the difference will be more
- prominent once we add client or relay support
- - logger - one instance of isc::log::Logger
- - structure - an element in config file (e.g. "Dhcp4")
-
- Do not use:
- - module => daemon
- -->
-
- <chapter id="logging">
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="logging">
<title>Logging</title>
<section>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- <!ENTITY % version SYSTEM "version.ent">
- %version;
++<!--
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
++
++<!-- need this include to make the &keaversion; macro work -->
++<!DOCTYPE book [
++<!ENTITY % keaversion SYSTEM "version.ent">
++%keaversion;
+]>
+
- <chapter id="quickstart">
+ <!-- Converted by db4-upgrade version 1.1 -->
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="quickstart">
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
++ xml:id="quickstart">
++
++
<title>Quick Start</title>
<para>
<listitem>
<para>
Extract the tarball. For example:
- <screen>$ <userinput>tar xvzf kea-&__VERSION__;.tar.gz</userinput></screen>
- <screen>$ <userinput>tar xvzf kea-.tar.gz</userinput></screen>
++ <screen>$ <userinput>tar xvzf kea-&keaversion;.tar.gz</userinput></screen>
</para>
</listitem>
<listitem>
<para>Go into the source directory and run the configure script:
- <screen>$ <userinput>cd kea-&__VERSION__;</userinput>
- <screen>$ <userinput>cd kea-</userinput>
++ <screen>$ <userinput>cd kea-&keaversion;</userinput>
$ <userinput>./configure [your extra parameters]</userinput></screen>
</para>
</listitem>
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "‗" >
- ]>
-
- <chapter id="kea-shell">
++<!--
++ - Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-shell">
<title>The Kea Shell</title>
- <section id="shell-overview">
+ <section xml:id="shell-overview">
<title>Overview</title>
<para>Kea 1.2.0 introduced the Control Agent (CA, see <xref linkend="kea-ctrl-agent"/>) that
provides a RESTful control interface over HTTP. That API is typically expected to be used by
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY mdash "—" >
- ]>
-
- <chapter id="stats">
++<!--
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
++ -
++ - This Source Code Form is subject to the terms of the Mozilla Public
++ - License, v. 2.0. If a copy of the MPL was not distributed with this
++ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
++-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats">
<title>Statistics</title>
<section>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
+<!--
- - Copyright (C) 2014-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
- <refentryinfo>
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+ <info>
<productname>ISC Kea</productname>
- <date>Oct. 27, 2017</date>
- <edition>1.3.0</edition>
- <author>
- <contrib>The Kea software has been written by a number of
+ <date>Sep. 28, 2016</date>
+ <edition>1.1.0</edition>
+ <author><personname/><contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
+<!--
- - Copyright (C) 2016-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2016-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
+<!--
- - Copyright (C) 2013-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2013-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentry>
-
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
+<!--
- - Copyright (C) 2011-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2011-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentry>
-
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!-- Converted by db4-upgrade version 1.1 -->
+<!--
- - Copyright (C) 2011-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2011-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentry>
-
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!-- Converted by db4-upgrade version 1.1 -->
+<!--
- - Copyright (C) 2014-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
- <refentryinfo>
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
++ <personname/>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
+<!--
- - Copyright (C) 2015-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
+ <!-- Converted by db4-upgrade version 1.1 -->
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
- <author>
- <contrib>The Kea software has been written by a number of
+ <author><personname/><contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!-- Converted by db4-upgrade version 1.1 -->
+<!--
- - Copyright (C) 2014-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>Sep. 28, 2016</date>
- <edition>1.1.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
++ <personname/>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!-- Converted by db4-upgrade version 1.1 -->
+<!--
- - Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
- <refentryinfo>
+ <info>
<productname>ISC Kea</productname>
- <date>0008-03-2017</date>
- <edition>1.2.0</edition>
- <author><personname/><contrib>The Kea software has been written by a number of
+ <date>Oct. 28, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
+ <contrib>The Kea software has been written by a number of
engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
Wlodek Wencel and Shawn Routhier. That list is roughly in the
</docinfo>
<refsynopsisdiv>
- <cmdsynopsis>
+ <cmdsynopsis sepchar=" ">
<command>kea-shell</command>
- <arg><option>-h</option></arg>
- <arg><option>-v</option></arg>
- <arg><option>--host</option></arg>
- <arg><option>--port</option></arg>
- <arg><option>--path</option></arg>
- <arg><option>--timeout</option></arg>
- <arg><option>--service</option></arg>
- <arg><option>command</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-h</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-v</option></arg>
+ <arg choice="opt" rep="norepeat"><option>--host</option></arg>
+ <arg choice="opt" rep="norepeat"><option>--port</option></arg>
++ <arg choice="opt" rep="norepeat"><option>--path</option></arg>
+ <arg choice="opt" rep="norepeat"><option>--timeout</option></arg>
+ <arg choice="opt" rep="norepeat"><option>--service</option></arg>
+ <arg choice="opt" rep="norepeat"><option>command</option></arg>
</cmdsynopsis>
</refsynopsisdiv>
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!-- Converted by db4-upgrade version 1.1 -->
+<!--
- - Copyright (C) 2012-2017 Internet Systems Consortium, Inc. ("ISC")
++ - Copyright (C) 2012-2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
- <refentry>
+ <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+ <refentryinfo>
+ <productname>ISC Kea</productname>
+ <date>Oct. 27, 2017</date>
+ <edition>1.3.0</edition>
+ <author>
+ <contrib>The Kea software has been written by a number of
+ engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
+ Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
+ Wlodek Wencel and Shawn Routhier. That list is roughly in the
+ chronological order in which the authors made their first
+ contribution. For a complete list of authors and
+ contributors, see AUTHORS file.</contrib>
+ <orgname>Internet Systems Consortium, Inc.</orgname>
+ </author>
+ </refentryinfo>
+
+ <info>
+ <date>2014-07-01</date>
+ </info>
+
<refmeta>
<refentrytitle>kea-sockcreator</refentrytitle>
<manvolnum>8</manvolnum>
</para>
</refsect1>
- </refentry><!--
- - Local variables:
- - mode: sgml
- - End:
- -->
-</refentry>
++</refentry>
projects / thirdparty / kea.git / commitdiff
