From: Andrei Pavel Date: Fri, 23 Dec 2016 17:43:28 +0000 (+0200) Subject: Style changes to documentation X-Git-Tag: trac5524_base~10^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5d2c941f3d81895d1dac9761166e143969bfbf48;p=thirdparty%2Fkea.git Style changes to documentation --- diff --git a/doc/guide/admin.xml b/doc/guide/admin.xml index 9a613ce249..ef0be587bf 100644 --- a/doc/guide/admin.xml +++ b/doc/guide/admin.xml @@ -563,10 +563,9 @@ $ kea-admin lease-upgrade pgsql -u database-user Cassandra, or Cassandra Query Language (CQL), is the newest backend added to Kea. Since it was added recently and has not undergone as much - testing as other backends, it is considered experimental: please use - with caution. The CQL backend is currently able to store leases only. - The ability to store host reservations will likely be added some time in - the future. + testing as other backends, it is considered experimental. Please use + with caution. The Casandra backend is currently able to store leases, + host reservations and options defined on a per host basis. @@ -707,4 +706,4 @@ $ kea-admin lease-upgrade cql -n database-name - \ No newline at end of file + diff --git a/doc/guide/classify.xml b/doc/guide/classify.xml index b9e6ed3b5e..f34e06f0b3 100644 --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@ -592,6 +592,7 @@ concatenation of the strings substring('foobar', 10, 2) == '' +
Concat The concat function "concat(string1, string2)" returns the concatenation of its two arguments. For instance: @@ -599,6 +600,7 @@ concatenation of the strings concat('foo', 'bar') == 'foobar'
+ @@ -881,4 +883,4 @@ concatenation of the strings - \ No newline at end of file + diff --git a/doc/guide/config.xml b/doc/guide/config.xml index 7c75f55c70..595fc8df9b 100644 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@ -140,4 +140,4 @@ - \ No newline at end of file + diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 1aa2e76c82..25c4b85aa3 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -35,9 +35,9 @@ { "command": "foo", "arguments": { - "param1": "value1", - "param2": "value2", - ... + "param1": "value1", + "param2": "value2", + ... } } @@ -54,9 +54,9 @@ "result": 0|1, "text": "textual description", "arguments": { - "argument1": "value1", - "argument2": "value2", - ... + "argument1": "value1", + "argument2": "value2", + ... } } @@ -99,6 +99,7 @@ will be sent to Kea and the responses received from Kea printed to standard outp
Commands Supported by Both the DHCPv4 and DHCPv6 Servers +
leases-reclaim leases-reclaim command instructs the server to @@ -127,9 +128,9 @@ will be sent to Kea and the responses received from Kea printed to standard outp
list-commands - The list-commands command retrieves a list of all - commands supported by the server. It does not take any arguments. - An example command may look like this: + The list-commands command retrieves a list of all + commands supported by the server. It does not take any arguments. + An example command may look like this: { "command": "list-commands", @@ -138,18 +139,18 @@ will be sent to Kea and the responses received from Kea printed to standard outp - The server will respond with a list of all supported commands. The - arguments element will be a list of strings. Each string will convey - one supported command. + The server will respond with a list of all supported commands. The + arguments element will be a list of strings. Each string will convey + one supported command.
shutdown - The shutdown command instructs the server to initiate - its shutdown procedure. It is the equivalent of sending a SIGTERM signal - to the process. This command does not take any arguments. An example - command may look like this: + The shutdown command instructs the server to initiate + its shutdown procedure. It is the equivalent of sending a SIGTERM signal + to the process. This command does not take any arguments. An example + command may look like this: { "command": "shutdown", @@ -158,11 +159,11 @@ will be sent to Kea and the responses received from Kea printed to standard outp - The server will respond with a confirmation that the shutdown procedure - has been initiated. + The server will respond with a confirmation that the shutdown procedure + has been initiated.
- \ No newline at end of file + diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml index f684b87aef..bc281cd502 100644 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@ -139,14 +139,13 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' and the process to which the PID belongs is unrelated to Kea. In such a case it would be necessary to manually delete the PID file. - -
+
Configuring the DHCP-DDNS Server - Before starting kea-dhcp-ddns module for the - first time, a configuration file needs to be created. The following default - configuration is a template that can be customised to your requirements. + Before starting kea-dhcp-ddns module for the + first time, a configuration file needs to be created. The following default + configuration is a template that can be customised to your requirements. "DhcpDdns": { "ip-address": "127.0.0.1", @@ -156,10 +155,10 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' "ncr-format": "JSON", "tsig-keys": [ ], "forward-ddns": { - "ddns-domains": [ ] + "ddns-domains": [ ] }, "reverse-ddns": { - "ddns-domains": [ ] + "ddns-domains": [ ] } } @@ -168,31 +167,31 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' The configuration can be divided as follows, each of which is described in its own section: - - - + + + Global Server Parameters - values which control connectivity and global server behavior - - - - - TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers - - - - - Forward DDNS - defines the catalog of Forward DDNS Domains - - - - - Reverse DDNS - defines the catalog of Forward DDNS Domains - - - + + + + + TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers + + + + + Forward DDNS - defines the catalog of Forward DDNS Domains + + + + + Reverse DDNS - defines the catalog of Forward DDNS Domains + + + +
Global Server Parameters - ip-address - IP address on which D2 listens for requests. The default is the local loopback interface at @@ -222,11 +221,11 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' - - D2 must listen for change requests on a known address and port. By - default it listens at 127.0.0.1 on port 53001. The following example - illustrates how to change D2's global parameters so it will listen - at 192.168.1.10 port 900: + + D2 must listen for change requests on a known address and port. By + default it listens at 127.0.0.1 on port 53001. The following example + illustrates how to change D2's global parameters so it will listen + at 192.168.1.10 port 900: "DhcpDdns": { "ip-address": "192.168.1.10", @@ -234,19 +233,19 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' ... } } - - - - It is possible for a malicious attacker to send bogus - NameChangeRequests to the DHCP-DDNS server. Addresses - other than the IPv4 or IPv6 loopback addresses (127.0.0.1 - or ::1) should only be used for testing purposes, but - note that local users may still communicate with the - DHCP-DDNS server. A future version of Kea will implement - authentication to guard against such attacks. - + + + + It is possible for a malicious attacker to send bogus + NameChangeRequests to the DHCP-DDNS server. Addresses + other than the IPv4 or IPv6 loopback addresses (127.0.0.1 + or ::1) should only be used for testing purposes, but + note that local users may still communicate with the + DHCP-DDNS server. A future version of Kea will implement + authentication to guard against such attacks. + - + If the ip-address and port are changed, it will be necessary to change the @@ -256,95 +255,95 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
TSIG Key List - - A DDNS protocol exchange can be conducted with or without TSIG - (defined in RFC - 2845). This configuration section allows the administrator - to define the set of TSIG keys that may be used in such - exchanges. - - To use TSIG when updating entries in a DNS Domain, - a key must be defined in the TSIG Key List and referenced by - name in that domain's configuration entry. When D2 matches a - change request to a domain, it checks whether the domain has - a TSIG key associated with it. If so, D2 will use that key to - sign DNS update messages sent to and verify responses received - from the domain's DNS server(s). For each TSIG key required by - the DNS servers that D2 will be working with there must be a - corresponding TSIG key in the TSIG Key list. - - - As one might gather from the name, the tsig-key section of the - D2 configuration lists the TSIG keys. Each entry describes a - TSIG key used by one or more DNS servers to authenticate requests - and sign responses. Every entry in the list has three parameters: - - - - name - - a unique text label used to identify this key within the - list. This value is used to specify which key (if any) should be - used when updating a specific domain. So long as it is unique its - content is arbitrary, although for clarity and ease of maintenance - it is recommended that it match the name used on the DNS server(s). - It cannot be blank. - - - - - algorithm - - specifies which hashing algorithm should be used with this - key. This value must specify the same algorithm used for the - key on the DNS server(s). The supported algorithms are listed below: - - - HMAC-MD5 - - - HMAC-SHA1 - - - HMAC-SHA224 - - - HMAC-SHA256 - - - HMAC-SHA384 - - - HMAC-SHA512 - - - This value is not case sensitive. - - - - - digest-bits - - is used to specify the minimum truncated length in bits. - The default value 0 means truncation is forbidden, non-zero - values must be an integral number of octets, be greater - than 80 and the half of the full length. Note in BIND9 - this parameter is appended after a dash to the algorithm - name. - - - - - secret - - is used to specify the shared secret key code for this key. This value is - case sensitive and must exactly match the value specified on the DNS server(s). - It is a base64-encoded text value. - - - - - - As an example, suppose that a domain D2 will be updating is - maintained by a BIND9 DNS server which requires dynamic updates - to be secured with TSIG. Suppose further that the entry for - the TSIG key in BIND9's named.conf file looks like this: + + A DDNS protocol exchange can be conducted with or without TSIG + (defined in RFC + 2845). This configuration section allows the administrator + to define the set of TSIG keys that may be used in such + exchanges. + + To use TSIG when updating entries in a DNS Domain, + a key must be defined in the TSIG Key List and referenced by + name in that domain's configuration entry. When D2 matches a + change request to a domain, it checks whether the domain has + a TSIG key associated with it. If so, D2 will use that key to + sign DNS update messages sent to and verify responses received + from the domain's DNS server(s). For each TSIG key required by + the DNS servers that D2 will be working with there must be a + corresponding TSIG key in the TSIG Key list. + + + As one might gather from the name, the tsig-key section of the + D2 configuration lists the TSIG keys. Each entry describes a + TSIG key used by one or more DNS servers to authenticate requests + and sign responses. Every entry in the list has three parameters: + + + + name - + a unique text label used to identify this key within the + list. This value is used to specify which key (if any) should be + used when updating a specific domain. So long as it is unique its + content is arbitrary, although for clarity and ease of maintenance + it is recommended that it match the name used on the DNS server(s). + It cannot be blank. + + + + + algorithm - + specifies which hashing algorithm should be used with this + key. This value must specify the same algorithm used for the + key on the DNS server(s). The supported algorithms are listed below: + + + HMAC-MD5 + + + HMAC-SHA1 + + + HMAC-SHA224 + + + HMAC-SHA256 + + + HMAC-SHA384 + + + HMAC-SHA512 + + + This value is not case sensitive. + + + + + digest-bits - + is used to specify the minimum truncated length in bits. + The default value 0 means truncation is forbidden, non-zero + values must be an integral number of octets, be greater + than 80 and the half of the full length. Note in BIND9 + this parameter is appended after a dash to the algorithm + name. + + + + + secret - + is used to specify the shared secret key code for this key. This value is + case sensitive and must exactly match the value specified on the DNS server(s). + It is a base64-encoded text value. + + + + + + As an example, suppose that a domain D2 will be updating is + maintained by a BIND9 DNS server which requires dynamic updates + to be secured with TSIG. Suppose further that the entry for + the TSIG key in BIND9's named.conf file looks like this: : key "key.four.example.com." { @@ -353,7 +352,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. }; : - By default, the TSIG Key list is empty: + By default, the TSIG Key list is empty: "DhcpDdns": { "tsig-keys": [ ], @@ -361,327 +360,329 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. } - We must extend the list with a new key: + We must extend the list with a new key: "DhcpDdns": { "tsig-keys": [ { - "name": "key.four.example.com.", - "algorithm": "HMAC-SHA224", - "secret": "bZEG7Ow8OgAUPfLWV3aAUQ==" - } + "name": "key.four.example.com.", + "algorithm": "HMAC-SHA224", + "secret": "bZEG7Ow8OgAUPfLWV3aAUQ==" + } ], ... } - + - These steps would be repeated for each TSIG key needed. Note that - the same TSIG key can be used with more than one domain. + These steps would be repeated for each TSIG key needed. Note that + the same TSIG key can be used with more than one domain.
- +
Forward DDNS - - The Forward DDNS section is used to configure D2's forward update - behavior. Currently it contains a single parameter, the catalog of - forward DDNS Domains, which is a list of structures. + + The Forward DDNS section is used to configure D2's forward update + behavior. Currently it contains a single parameter, the catalog of + forward DDNS Domains, which is a list of structures. "DhcpDdns": { "forward-ddns": { - "ddns-domains": [ ] + "ddns-domains": [ ] }, ... } - By default, this list is empty, which will cause the server to ignore - the forward update portions of requests. - -
Adding Forward DDNS Domains - - A forward DDNS Domain maps a forward DNS zone to a set of - DNS servers which maintain the forward DNS data (i.e. name to - address mapping) for that zone. You will need one forward DDNS - Domain for each zone you wish to service. It may very well - be that some or all of your zones are maintained by the same - servers. You will still need one DDNS Domain per zone. Remember - that matching a request to the appropriate server(s) is done - by zone and a DDNS Domain only defines a single zone. - - - This section describes how to add Forward DDNS Domains. Repeat these - steps for each Forward DDNS Domain desired. Each Forward DDNS Domain - has the following parameters: - - - - name - - The fully qualified domain name (or zone) that this DDNS Domain - can update. This is value used to compare against the request - FQDN during forward matching. It must be unique within the - catalog. - - - - - key-name - - If TSIG is used with this domain's servers, this - value should be the name of the key from within the TSIG Key List - to use. If the value is blank (the default), TSIG will not be - used in DDNS conversations with this domain's servers. - - - - - dns-servers - - A list of one or more DNS servers which can conduct the server - side of the DDNS protocol for this domain. The servers - are used in a first to last preference. In other words, when D2 - begins to process a request for this domain it will pick the - first server in this list and attempt to communicate with it. - If that attempt fails, it will move to next one in the list and - so on until the it achieves success or the list is exhausted. - - - - To create a new forward DDNS Domain, one must add a new domain - element and set its parameters: + By default, this list is empty, which will cause the server to ignore + the forward update portions of requests. + + +
Adding Forward DDNS Domains + + A forward DDNS Domain maps a forward DNS zone to a set of + DNS servers which maintain the forward DNS data (i.e. name to + address mapping) for that zone. You will need one forward DDNS + Domain for each zone you wish to service. It may very well + be that some or all of your zones are maintained by the same + servers. You will still need one DDNS Domain per zone. Remember + that matching a request to the appropriate server(s) is done + by zone and a DDNS Domain only defines a single zone. + + + This section describes how to add Forward DDNS Domains. Repeat these + steps for each Forward DDNS Domain desired. Each Forward DDNS Domain + has the following parameters: + + + + name - + The fully qualified domain name (or zone) that this DDNS Domain + can update. This is value used to compare against the request + FQDN during forward matching. It must be unique within the + catalog. + + + + + key-name - + If TSIG is used with this domain's servers, this + value should be the name of the key from within the TSIG Key List + to use. If the value is blank (the default), TSIG will not be + used in DDNS conversations with this domain's servers. + + + + + dns-servers - + A list of one or more DNS servers which can conduct the server + side of the DDNS protocol for this domain. The servers + are used in a first to last preference. In other words, when D2 + begins to process a request for this domain it will pick the + first server in this list and attempt to communicate with it. + If that attempt fails, it will move to next one in the list and + so on until the it achieves success or the list is exhausted. + + + + To create a new forward DDNS Domain, one must add a new domain + element and set its parameters: "DhcpDdns": { "forward-ddns": { - "ddns-domains": [ - { - "name": "other.example.com.", - "key-name": "", - "dns-servers": [ - ] - } - ] + "ddns-domains": [ + { + "name": "other.example.com.", + "key-name": "", + "dns-servers": [ + ] + } + ] } } - It is permissible to add a domain without any servers. If that domain - should be matched to a request, however, the request will fail. In - order to make the domain useful though, we must add at least one DNS - server to it. - - -
Adding Forward DNS Servers - - This section describes how to add DNS servers to a Forward DDNS Domain. - Repeat them for as many servers as desired for a each domain. - - - Forward DNS Server entries represent actual DNS servers which - support the server side of the DDNS protocol. Each Forward DNS Server - has the following parameters: - - - - hostname - - The resolvable host name of the DNS server. This value is not - yet implemented. - - - - - ip-address - - The IP address at which the server listens for DDNS requests. - This may be either an IPv4 or an IPv6 address. - - - - - port - - The port on which the server listens for DDNS requests. It - defaults to the standard DNS service port of 53. - - - - To create a new forward DNS Server, one must add a new server - element to the domain and fill in its parameters. If for - example the service is running at "172.88.99.10", then set it as - follows: + It is permissible to add a domain without any servers. If that domain + should be matched to a request, however, the request will fail. In + order to make the domain useful though, we must add at least one DNS + server to it. + + +
Adding Forward DNS Servers + + This section describes how to add DNS servers to a Forward DDNS Domain. + Repeat them for as many servers as desired for a each domain. + + + Forward DNS Server entries represent actual DNS servers which + support the server side of the DDNS protocol. Each Forward DNS Server + has the following parameters: + + + + hostname - + The resolvable host name of the DNS server. This value is not + yet implemented. + + + + + ip-address - + The IP address at which the server listens for DDNS requests. + This may be either an IPv4 or an IPv6 address. + + + + + port - + The port on which the server listens for DDNS requests. It + defaults to the standard DNS service port of 53. + + + + To create a new forward DNS Server, one must add a new server + element to the domain and fill in its parameters. If for + example the service is running at "172.88.99.10", then set it as + follows: "DhcpDdns": { "forward-ddns": { - "ddns-domains": [ - { - "name": "other.example.com.", - "key-name": "", - "dns-servers": [ - { - "hostname": "", - "ip-address": "172.88.99.10", - "port": 53 - } - ] - } - ] + "ddns-domains": [ + { + "name": "other.example.com.", + "key-name": "", + "dns-servers": [ + { + "hostname": "", + "ip-address": "172.88.99.10", + "port": 53 + } + ] + } + ] } } - + - As stated earlier, "hostname" is not yet supported so, the parameter - "ip-address" must be set to the address of the DNS server. + As stated earlier, "hostname" is not yet supported so, the parameter + "ip-address" must be set to the address of the DNS server. -
+
Reverse DDNS - - The Reverse DDNS section is used to configure D2's reverse update - behavior, and the concepts are the same as for the forward DDNS - section. Currently it contains a single parameter, the catalog of - reverse DDNS Domains, which is a list of structures. + + The Reverse DDNS section is used to configure D2's reverse update + behavior, and the concepts are the same as for the forward DDNS + section. Currently it contains a single parameter, the catalog of + reverse DDNS Domains, which is a list of structures. "DhcpDdns": { "reverse-ddns": { - "ddns-domains": [ ] + "ddns-domains": [ ] } ... } - By default, this list is empty, which will cause the server to ignore - the reverse update portions of requests. - -
Adding Reverse DDNS Domains - - A reverse DDNS Domain maps a reverse DNS zone to a set of DNS - servers which maintain the reverse DNS data (address to name - mapping) for that zone. You will need one reverse DDNS Domain - for each zone you wish to service. It may very well be that - some or all of your zones are maintained by the same servers; - even then, you will still need one DDNS Domain entry for each - zone. Remember that matching a request to the appropriate - server(s) is done by zone and a DDNS Domain only defines a - single zone. - - - This section describes how to add Reverse DDNS Domains. Repeat these - steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain - has the following parameters: - - - - name - - The fully qualified reverse zone that this DDNS Domain - can update. This is the value used during reverse matching - which will compare it with a reversed version of the request's - lease address. The zone name should follow the appropriate - standards: for example, to to support the IPv4 subnet 172.16.1, - the name should be. "1.16.172.in-addr.arpa.". Similarly, - to support an IPv6 subnet of 2001:db8:1, the name should be - "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." - Whatever the name, it must be unique within the catalog. - - - - - key-name - - If TSIG should be used with this domain's servers, then this - value should be the name of that key from the TSIG Key List. - If the value is blank (the default), TSIG will not be - used in DDNS conversations with this domain's servers. Currently - this value is not used as TSIG has not been implemented. - - - - - dns-servers - - a list of one or more DNS servers which can conduct the server - side of the DDNS protocol for this domain. Currently the servers - are used in a first to last preference. In other words, when D2 - begins to process a request for this domain it will pick the - first server in this list and attempt to communicate with it. - If that attempt fails, it will move to next one in the list and - so on until the it achieves success or the list is exhausted. - - - - To create a new reverse DDNS Domain, one must add a new domain element - and set its parameters. For example, to support subnet 2001:db8:1::, - the following configuration could be used: + By default, this list is empty, which will cause the server to ignore + the reverse update portions of requests. + + +
Adding Reverse DDNS Domains + + A reverse DDNS Domain maps a reverse DNS zone to a set of DNS + servers which maintain the reverse DNS data (address to name + mapping) for that zone. You will need one reverse DDNS Domain + for each zone you wish to service. It may very well be that + some or all of your zones are maintained by the same servers; + even then, you will still need one DDNS Domain entry for each + zone. Remember that matching a request to the appropriate + server(s) is done by zone and a DDNS Domain only defines a + single zone. + + + This section describes how to add Reverse DDNS Domains. Repeat these + steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain + has the following parameters: + + + + name - + The fully qualified reverse zone that this DDNS Domain + can update. This is the value used during reverse matching + which will compare it with a reversed version of the request's + lease address. The zone name should follow the appropriate + standards: for example, to to support the IPv4 subnet 172.16.1, + the name should be. "1.16.172.in-addr.arpa.". Similarly, + to support an IPv6 subnet of 2001:db8:1, the name should be + "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." + Whatever the name, it must be unique within the catalog. + + + + + key-name - + If TSIG should be used with this domain's servers, then this + value should be the name of that key from the TSIG Key List. + If the value is blank (the default), TSIG will not be + used in DDNS conversations with this domain's servers. Currently + this value is not used as TSIG has not been implemented. + + + + + dns-servers - + a list of one or more DNS servers which can conduct the server + side of the DDNS protocol for this domain. Currently the servers + are used in a first to last preference. In other words, when D2 + begins to process a request for this domain it will pick the + first server in this list and attempt to communicate with it. + If that attempt fails, it will move to next one in the list and + so on until the it achieves success or the list is exhausted. + + + + To create a new reverse DDNS Domain, one must add a new domain element + and set its parameters. For example, to support subnet 2001:db8:1::, + the following configuration could be used: "DhcpDdns": { "reverse-ddns": { - "ddns-domains": [ - { - "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", - "key-name": "", - "dns-servers": [ - ] - } - ] + "ddns-domains": [ + { + "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", + "key-name": "", + "dns-servers": [ + ] + } + ] } } - It is permissible to add a domain without any servers. If that domain - should be matched to a request, however, the request will fail. In - order to make the domain useful though, we must add at least one DNS - server to it. - - -
Adding Reverse DNS Servers - - This section describes how to add DNS servers to a Reverse DDNS Domain. - Repeat them for as many servers as desired for each domain. - - - Reverse DNS Server entries represents a actual DNS servers which - support the server side of the DDNS protocol. Each Reverse DNS Server - has the following parameters: - - - - hostname - - The resolvable host name of the DNS server. This value is - currently ignored. - - - - - ip-address - - The IP address at which the server listens for DDNS requests. - - - - - port - - The port on which the server listens for DDNS requests. It - defaults to the standard DNS service port of 53. - - - - To create a new reverse DNS Server, one must first add a new server - element to the domain and fill in its parameters. If for - example the service is running at "172.88.99.10", then set it as - follows: + It is permissible to add a domain without any servers. If that domain + should be matched to a request, however, the request will fail. In + order to make the domain useful though, we must add at least one DNS + server to it. + + +
Adding Reverse DNS Servers + + This section describes how to add DNS servers to a Reverse DDNS Domain. + Repeat them for as many servers as desired for each domain. + + + Reverse DNS Server entries represents a actual DNS servers which + support the server side of the DDNS protocol. Each Reverse DNS Server + has the following parameters: + + + + hostname - + The resolvable host name of the DNS server. This value is + currently ignored. + + + + + ip-address - + The IP address at which the server listens for DDNS requests. + + + + + port - + The port on which the server listens for DDNS requests. It + defaults to the standard DNS service port of 53. + + + + To create a new reverse DNS Server, one must first add a new server + element to the domain and fill in its parameters. If for + example the service is running at "172.88.99.10", then set it as + follows: "DhcpDdns": { "reverse-ddns": { - "ddns-domains": [ - { - "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", - "key-name": "", - "dns-servers": [ - { - "hostname": "", - "ip-address": "172.88.99.10", - "port": 53 - } - ] - } - ] + "ddns-domains": [ + { + "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", + "key-name": "", + "dns-servers": [ + { + "hostname": "", + "ip-address": "172.88.99.10", + "port": 53 + } + ] + } + ] } } @@ -694,214 +695,216 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. -
+
Example DHCP-DDNS Server Configuration - - This section provides an example DHCP-DDNS server configuration based - on a small example network. Let's suppose our example network has - three domains, each with their own subnet. - - Our example network - - - - - - - - Domain - Subnet - Forward DNS Servers - Reverse DNS Servers - - - - - four.example.com - 192.0.2.0/24 - 172.16.1.5, 172.16.2.5 - 172.16.1.5, 172.16.2.5 - - - six.example.com - 2001:db8:1::/64 - 3001:1::50 - 3001:1::51 - - - example.com - 192.0.0.0/16 - 172.16.2.5 - 172.16.2.5 - - - -
- - - We need to construct three forward DDNS Domains: - Forward DDNS Domains Needed - - - - - - - # - DDNS Domain Name - DNS Servers - - - - - 1. - four.example.com. - 172.16.1.5, 172.16.2.5 - - - 2. - six.example.com. - 3001:1::50 - - - 3. - example.com. - 172.16.2.5 - - - -
- As discussed earlier, FQDN to domain matching is based on the longest - match. The FQDN, "myhost.four.example.com.", will match the first - domain ("four.example.com") while "admin.example.com." will match the - third domain ("example.com"). The - FQDN, "other.example.net." will fail to match any domain and would - be rejected. - - - The following example configuration specified the Forward DDNS Domains. + + This section provides an example DHCP-DDNS server configuration based + on a small example network. Let's suppose our example network has + three domains, each with their own subnet. + + Our example network + + + + + + + + Domain + Subnet + Forward DNS Servers + Reverse DNS Servers + + + + + four.example.com + 192.0.2.0/24 + 172.16.1.5, 172.16.2.5 + 172.16.1.5, 172.16.2.5 + + + six.example.com + 2001:db8:1::/64 + 3001:1::50 + 3001:1::51 + + + example.com + 192.0.0.0/16 + 172.16.2.5 + 172.16.2.5 + + + +
+ + + We need to construct three forward DDNS Domains: + Forward DDNS Domains Needed + + + + + + + # + DDNS Domain Name + DNS Servers + + + + + 1. + four.example.com. + 172.16.1.5, 172.16.2.5 + + + 2. + six.example.com. + 3001:1::50 + + + 3. + example.com. + 172.16.2.5 + + + +
+ As discussed earlier, FQDN to domain matching is based on the longest + match. The FQDN, "myhost.four.example.com.", will match the first + domain ("four.example.com") while "admin.example.com." will match the + third domain ("example.com"). The + FQDN, "other.example.net." will fail to match any domain and would + be rejected. + + + The following example configuration specified the Forward DDNS Domains. "DhcpDdns": { "forward-ddns": { - "ddns-domains": [ - { - "name": "four.example.com.", - "key-name": "", - "dns-servers": [ - { "ip-address": "172.16.1.5" }, - { "ip-address": "172.16.2.5" } - ] - }, - { - "name": "six.example.com.", - "key-name": "", - "dns-servers": [ - { "ip-address": "2001:db8::1" } - ] - }, - { - "name": "example.com.", - "key-name": "", - "dns-servers": [ - { "ip-address": "172.16.2.5" } - ] - }, - - ] + "ddns-domains": [ + { + "name": "four.example.com.", + "key-name": "", + "dns-servers": [ + { "ip-address": "172.16.1.5" }, + { "ip-address": "172.16.2.5" } + ] + }, + { + "name": "six.example.com.", + "key-name": "", + "dns-servers": [ + { "ip-address": "2001:db8::1" } + ] + }, + { + "name": "example.com.", + "key-name": "", + "dns-servers": [ + { "ip-address": "172.16.2.5" } + ] + }, + + ] } } - - - Similarly, we need to construct the three reverse DDNS Domains: - Reverse DDNS Domains Needed - - - - - - - # - DDNS Domain Name - DNS Servers - - - - - 1. - 2.0.192.in-addr.arpa. - 172.16.1.5, 172.16.2.5 - - - 2. - 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. - 3001:1::50 - - - 3. - 0.182.in-addr.arpa. - 172.16.2.5 - - - -
- An address of "192.0.2.150" will match the first domain, - "2001:db8:1::10" will match the second domain, and "192.0.50.77" - the third domain. - - - These Reverse DDNS Domains are specified as follows: + + + Similarly, we need to construct the three reverse DDNS Domains: + Reverse DDNS Domains Needed + + + + + + + # + DDNS Domain Name + DNS Servers + + + + + 1. + 2.0.192.in-addr.arpa. + 172.16.1.5, 172.16.2.5 + + + 2. + 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. + 3001:1::50 + + + 3. + 0.182.in-addr.arpa. + 172.16.2.5 + + + +
+ An address of "192.0.2.150" will match the first domain, + "2001:db8:1::10" will match the second domain, and "192.0.50.77" + the third domain. + + + These Reverse DDNS Domains are specified as follows: "DhcpDdns": { "reverse-ddns": { - "ddns-domains": [ - { - "name": "2.0.192.in-addr.arpa.", - "key-name": "", - "dns-servers": [ - { "ip-address": "172.16.1.5" }, - { "ip-address": "172.16.2.5" } - ] - } - { - "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", - "key-name": "", - "dns-servers": [ - { "ip-address": "2001:db8::1" } - ] - } - { - "name": "0.192.in-addr.arpa.", - "key-name": "", - "dns-servers": [ - { "ip-address": "172.16.2.5" } - ] - } - ] + "ddns-domains": [ + { + "name": "2.0.192.in-addr.arpa.", + "key-name": "", + "dns-servers": [ + { "ip-address": "172.16.1.5" }, + { "ip-address": "172.16.2.5" } + ] + } + { + "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.", + "key-name": "", + "dns-servers": [ + { "ip-address": "2001:db8::1" } + ] + } + { + "name": "0.192.in-addr.arpa.", + "key-name": "", + "dns-servers": [ + { "ip-address": "172.16.2.5" } + ] + } + ] } } - -
+ +
+
+
DHCP-DDNS Server Limitations The following are the current limitations of the DHCP-DDNS Server. - - - Requests received from the DHCP servers are placed in a - queue until they are processed. Currently all queued requests - are lost when the server shuts down. - - + + + Requests received from the DHCP servers are placed in a + queue until they are processed. Currently all queued requests + are lost when the server shuts down. + +
- \ No newline at end of file + diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index c78c28661c..9e97f2981a 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -115,6 +115,7 @@ strings path/kea-dhcp4 | sed -n 's/;;;; //p'
DHCPv4 Server Configuration
Introduction + This section explains how to configure the DHCPv4 server using the Kea configuration backend. (Kea configuration using any other @@ -452,6 +453,7 @@ If a timeout is given though, it should be an integer greater than zero. If there is no password to the account, set the password to the empty string "". (This is also the default.)
+
Hosts Storage @@ -510,7 +512,6 @@ If a timeout is given though, it should be an integer greater than zero.
Using Read-Only Databases for Host Reservations - In some deployments the database user whose name is specified in the database backend configuration may not have write privileges to the database. This is often @@ -1015,6 +1016,7 @@ temporarily override a list of interface names and listen on all interfaces. List of standard DHCPv4 options + @@ -1083,6 +1085,7 @@ This rather belong to the DDNS configuration
List of standard DHCPv4 options (continued) + @@ -1175,6 +1178,7 @@ It is merely echoed by the server
List of standard DHCP option types + @@ -1565,7 +1569,6 @@ It is merely echoed by the server -
Stateless Configuration of DHCPv4 Clients @@ -1805,6 +1808,7 @@ It is merely echoed by the server }
+
DDNS for DHCPv4 @@ -1957,6 +1961,7 @@ It is merely echoed by the server
+
When Does the kea-dhcp4 Server Generate DDNS Requests? kea-dhcp4 follows the behavior prescribed for DHCP servers in RFC 4702. @@ -1997,6 +2002,7 @@ It is merely echoed by the server in the following table:
Default FQDN Flag Behavior + @@ -2191,6 +2197,7 @@ It is merely echoed by the server } + When generating a name, kea-dhcp4 will construct name of the format: @@ -2423,7 +2430,6 @@ It is merely echoed by the server assumed to belong to another client and the new lease will be allocated. -
DHCPv4-over-DHCPv6: DHCPv4 Side @@ -2830,7 +2836,6 @@ It is merely echoed by the server if there are options defined with the same type on global, subnet, class and host level, the host specific values will be used. -
Reserving Next Server, Server Hostname and Boot File Name @@ -2915,7 +2920,7 @@ It is merely echoed by the server with classification using expressions.
-
Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra) +
Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra) It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See for information on how to configure Kea to use @@ -3057,9 +3062,6 @@ If not specified, the default value is: src/lib/dhcpsrv/cfg_host_operations.cc --> - - -
@@ -3271,7 +3273,6 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> potential for major issues, we decided not to decrease assigned addresses immediately after receiving DHCPDECLINE, but to do it later when we recover the address back to the available pool. -
Statistics in the DHCPv4 Server @@ -3284,6 +3285,7 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> The DHCPv4 server supports the following statistics:
DHCPv4 Statistics + @@ -3750,4 +3752,4 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> --> - \ No newline at end of file + diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index b3bfe33b90..45fe6a4932 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -115,6 +115,7 @@ strings path/kea-dhcp6 | sed -n 's/;;;; //p'
DHCPv6 Server Configuration
Introduction + This section explains how to configure the DHCPv6 server using the Kea configuration backend. (Kea configuration using any other @@ -507,7 +508,6 @@ If a timeout is given though, it should be an integer greater than zero.
Using Read-Only Databases for Host Reservations - In some deployments the database user whose name is specified in the database backend configuration may not have write privileges to the database. This is often @@ -539,7 +539,6 @@ for MySQL and PostgreSQL databases.
-
Interface Selection The DHCPv6 server has to be configured to listen on specific network interfaces. The simplest network interface configuration instructs the server to @@ -810,7 +809,6 @@ temporarily override a list of interface names and listen on all interfaces. ... } -
Prefix Exclude Option @@ -1050,6 +1048,7 @@ temporarily override a list of interface names and listen on all interfaces.
List of Standard DHCPv6 Options + @@ -1140,6 +1139,7 @@ temporarily override a list of interface names and listen on all interfaces.
List of Experimental DHCPv6 Options + @@ -1260,6 +1260,7 @@ temporarily override a list of interface names and listen on all interfaces. +
S46 BR Option The S46 BR option is used to convey the IPv6 address of the @@ -1310,6 +1311,7 @@ temporarily override a list of interface names and listen on all interfaces. This option must not be included in other containers.
+
S46 Port Parameters The S46 Port Parameters option specifies optional port set @@ -1331,6 +1333,7 @@ temporarily override a list of interface names and listen on all interfaces. PSID=12288 conveyed in the S46 Port Parameters option.
+
Custom DHCPv6 Options @@ -1454,7 +1457,6 @@ temporarily override a list of interface names and listen on all interfaces. "1". Future versions of Kea will accept all those values for all boolean parameters. -
DHCPv6 Vendor-Specific Options @@ -1876,7 +1878,6 @@ should include options from the isc option space: it could also work for custom options, but due to the nature of the parser code this may be unreliable and should be avoided. -
Client Classification in DHCPv6 @@ -1994,6 +1995,7 @@ should include options from the isc option space:
+
DDNS for DHCPv6 @@ -2080,7 +2082,6 @@ should include options from the isc option space: -
DHCP-DDNS Server Connectivity In order for NCRs to reach the D2 server, kea-dhcp6 must be able @@ -2147,6 +2148,7 @@ should include options from the isc option space:
+
When Does kea-dhcp6 Generate a DDNS Request? kea-dhcp6 follows the behavior prescribed for DHCP servers in RFC 4704. @@ -2195,6 +2197,7 @@ should include options from the isc option space: as shown in the following table:
Default FQDN Flag Behavior + @@ -2282,6 +2285,7 @@ should include options from the isc option space: } +
kea-dhcp6 Name Generation for DDNS Update Requests Each NameChangeRequest must of course include the fully qualified domain name whose DNS entries are to be affected. kea-dhcp6 can be @@ -2381,6 +2385,7 @@ should include options from the isc option space: }
+ When qualifying a partial name, kea-dhcp6 will construct a name with the format: @@ -2972,7 +2977,6 @@ If not specified, the default value is: - - \ No newline at end of file + diff --git a/doc/guide/faq.xml b/doc/guide/faq.xml index 3e6ad35c45..a0ea00ebdc 100644 --- a/doc/guide/faq.xml +++ b/doc/guide/faq.xml @@ -113,4 +113,4 @@ - \ No newline at end of file + diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index d4bd3ebdce..36c8e181a8 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -2,7 +2,6 @@ Hooks Libraries
Introduction - Although Kea offers a lot of flexibility, there may be cases where its behavior needs customisation. To accommodate this possibility, @@ -157,6 +156,7 @@ Currently the following libraries are available or planned from ISC:
List of available hooks libraries + @@ -532,7 +532,9 @@ link address: 3001::1, hop count: 1, identified by remote-id: + +
User contexts @@ -553,4 +555,5 @@ link address: 3001::1, hop count: 1, identified by remote-id: user context capability.
- \ No newline at end of file + + diff --git a/doc/guide/install.xml b/doc/guide/install.xml index f8e222604d..b1332c9ef7 100644 --- a/doc/guide/install.xml +++ b/doc/guide/install.xml @@ -133,7 +133,7 @@ Debian and Ubuntu: Kea 1.1.0 builds have been tested with GCC g++ 4.2.1, 4.4.7, 4.6.3, 4.8.3, 4.8.4, 4.8.5, 5.4.0; Clang++ 3.4.1; and Apple Clang++ 703.0.31. - + @@ -188,7 +188,6 @@ Debian and Ubuntu: http://kea.isc.org/wiki/SystemSpecificNotes for system-specific installation tips. -
Installation from Source @@ -260,10 +259,8 @@ Debian and Ubuntu: Developer's Guide contains more information about the process, as well as describing the requirements for contributed code to be accepted by ISC. -
-
Configure Before the Build Kea uses the GNU Build System to discover build environment @@ -400,7 +397,6 @@ Debian and Ubuntu: the file config.report and is also embedded into the executable binaries, e.g., kea-dhcp4. -
Build @@ -426,22 +422,22 @@ Debian and Ubuntu: The install step may require superuser privileges. - If required, run ldconfig as root with - /usr/local/lib (or with prefix/lib if - configured with --prefix) in - /etc/ld.so.conf (or the relevant linker - cache configuration file for your OS): - $ ldconfig + If required, run ldconfig as root with + /usr/local/lib (or with prefix/lib if + configured with --prefix) in + /etc/ld.so.conf (or the relevant linker + cache configuration file for your OS): + $ ldconfig - If you do not run ldconfig where it is - required, you may see errors like the following: + If you do not run ldconfig where it is + required, you may see errors like the following: - program: error while loading shared libraries: libkea-something.so.1: - cannot open shared object file: No such file or directory - - + program: error while loading shared libraries: libkea-something.so.1: + cannot open shared object file: No such file or directory + +
@@ -460,16 +456,15 @@ Debian and Ubuntu: JSON - 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 will allow dynamic - on-line reconfiguration, but lacks remote capabilities - (i.e. no RESTful API). + 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 will allow dynamic + on-line reconfiguration, but lacks remote capabilities + (i.e. no RESTful API). -
DHCP Database Installation and Configuration @@ -506,7 +501,7 @@ Debian and Ubuntu: "configure" step (see ), the --with-mysql switch should be specified: ./configure [other-options] --with-mysql - 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. ./configure [other-options] --with-mysql=path-to-mysql_config @@ -527,7 +522,7 @@ Debian and Ubuntu: "configure" step (see ), the --with-pgsql switch should be specified: ./configure [other-options] --with-pgsql - 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. ./configure [other-options] --with-pgsql=path-to-pg_config @@ -576,4 +571,4 @@ $ make
- \ No newline at end of file + diff --git a/doc/guide/intro.xml b/doc/guide/intro.xml index 0129b6d236..43735a5d1b 100644 --- a/doc/guide/intro.xml +++ b/doc/guide/intro.xml @@ -21,8 +21,8 @@
Supported Platforms Kea is officially supported on Red Hat Enterprise Linux, - CentOS, Fedora and FreeBSD systems. It is also likely to work on many - other platforms: Kea 1.1.0 builds have been tested on (in no + CentOS, Fedora and FreeBSD systems. It is also likely to work on many + other platforms: Kea 1.1.0 builds have been tested on (in no particular order) Red Hat Enteprise Linux 6.4, Debian GNU/Linux 7, Ubuntu 12.04, Ubuntu 14.04, Ubuntu 16.04, Fedora Linux 19, Fedora 20, Fedora 22, CentOS Linux 7, NetBSD 6, FreeBSD 10.3, @@ -64,7 +64,7 @@ - In order to store lease information in a MySQL database, Kea requires MySQL + In order to store lease information in a MySQL database, Kea requires MySQL headers and libraries. This is an optional dependency in that Kea can be built without MySQL support. @@ -72,7 +72,7 @@ - In order to store lease information in a PostgreSQL database, Kea requires PostgreSQL + In order to store lease information in a PostgreSQL database, Kea requires PostgreSQL headers and libraries. This is an optional dependency in that Kea can be built without PostgreSQL support. @@ -80,7 +80,7 @@ - In order to store lease information in a Cassandra database (CQL), Kea + In order to store lease information in a Cassandra database (CQL), Kea requires Cassandra headers and libraries. This is an optional dependency in that Kea can be built without Cassandra support. @@ -162,7 +162,6 @@ -
@@ -178,4 +177,4 @@ - \ No newline at end of file + diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index 1b12fa347b..3d239f6fb2 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -97,4 +97,4 @@ - \ No newline at end of file + diff --git a/doc/guide/keactrl.xml b/doc/guide/keactrl.xml index 1b941cd290..cfd74c7eb5 100644 --- a/doc/guide/keactrl.xml +++ b/doc/guide/keactrl.xml @@ -297,4 +297,4 @@ keactrl configuration file: /usr/local/etc/kea/keactrl.conf - \ No newline at end of file + diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index 1838516c22..888ba65539 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -317,7 +317,6 @@ expired-leases-processing map may be omitted entirely in the configuration, in which case the default values are used for all parameters listed above. -
Reclaiming Expired Leases with Command @@ -327,4 +326,4 @@ command.
- \ No newline at end of file + diff --git a/doc/guide/lfc.xml b/doc/guide/lfc.xml index 54bc92f1d6..164a6b31fe 100644 --- a/doc/guide/lfc.xml +++ b/doc/guide/lfc.xml @@ -89,4 +89,4 @@ kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o ou - \ No newline at end of file + diff --git a/doc/guide/libdhcp.xml b/doc/guide/libdhcp.xml index 2f40580fed..f61b288ab3 100644 --- a/doc/guide/libdhcp.xml +++ b/doc/guide/libdhcp.xml @@ -47,4 +47,4 @@ --> - \ No newline at end of file + diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml index 633f65f7e9..457b95d3b0 100644 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@ -833,4 +833,5 @@ - \ No newline at end of file + + diff --git a/doc/guide/quickstart.xml b/doc/guide/quickstart.xml index 952af23141..820dc01edd 100644 --- a/doc/guide/quickstart.xml +++ b/doc/guide/quickstart.xml @@ -9,7 +9,6 @@
Quick Start Guide for DHCPv4 and DHCPv6 Services - Install required run-time and build dependencies. See for details. @@ -116,4 +115,4 @@ $ ./configure [your extra parameters]
- \ No newline at end of file + diff --git a/doc/guide/stats.xml b/doc/guide/stats.xml index 91950744db..f70fb4821d 100644 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@ -238,7 +238,6 @@ and the text field will contain the error description. - - \ No newline at end of file +