From: Stephen Morris Date: Tue, 5 Aug 2014 19:29:39 +0000 (+0100) Subject: [3468] Minor editorial changes during review X-Git-Tag: trac3482_base~57^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=14ce7e33024411d434031de9fcfd61a1708f5544;p=thirdparty%2Fkea.git [3468] Minor editorial changes during review Including: ensuring consistent formaat for lists, ensuring order of items in a list explaining an example JSON map corresponds to the order of the elements in the map, etc. --- diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml index 7d853d7240..67bf2c6767 100644 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@ -20,7 +20,7 @@ catalog of servers from which to select. In fact, D2 has two such catalogs, one for forward DNS and one for reverse DNS; these catalogs are referred to as DDNS Domain Lists. Each list consists of one or more named DDNS - Domains. Further, each DDNS Domain has a list of of one or more DNS + Domains. Further, each DDNS Domain has a list of one or more DNS servers that publish the DNS data for that domain. @@ -50,18 +50,17 @@
Starting and Stopping the DHCP-DDNS Server - - It is recommended to control DHCPv4 server in Kea using keactl, - which is described in details in . - - kea-dhcp-ddns is the Kea DHCP-DDNS server and, - like other parts of Kea, is a separate binary that can be run on - its own or through keactl. Due to the nature - of DDNS, it is run along with either DHCPv4 or DHCPv6 components - (or both). + kea-dhcp-ddns is the Kea DHCP-DDNS server + and, due to the nature of DDNS, it is run alongside either the + DHCPv4 or DHCPv6 components (or both). Like other parts of + Kea, is a separate binary that can be run on its own or through + keactl (see ). In + normal operation, controlling kea-dhcp-ddns + with keactl is recommended. + Upon start up the module will load its configuration and begin listening for NCRs based on that configuration. @@ -70,9 +69,9 @@
Configuring the DHCP-DDNS Server - Before staring kea-dhcp-ddns module for the + Before starting kea-dhcp-ddns module for the first time, a configuration file needs to be created. The following default - configuration seems reasonable in most cases: + configuration is a template that can be customised to your requirements. "DhcpDdns": { "ip_address": "127.0.0.1", @@ -97,57 +96,63 @@ - Global Server Parameters — + Global Server Parameters - values which control connectivity and global server behavior - TSIG Key Info — + TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers - Forward DDNS — + Forward DDNS - defines the catalog of Forward DDNS Domains - Reverse DDNS — + 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 address 127.0.0.1. You may specify - either an IPv4 or IPv6 address. - - - port - Port on which D2 listens for requests. The default value + + + + ip_address - IP address on which D2 + listens for requests. The default is the local loopback interface at + address 127.0.0.1. You may specify either an IPv4 or IPv6 address. + + + + port - Port on which D2 listens for requests. The default value is 53001. - - - ncr_format - Socket protocol to use when sending requests to D2. - Currently only UDP is supported. TCP may be available in an upcoming - release. - - - ncr_protocol - Packet format to use when sending requests to D2. + + + + dns_server_timeout - The maximum amount + of time in milliseconds, that D2 will wait for a response from a + DNS server to a single DNS update message. + + + + ncr_protocol - Packet format to use when sending requests to D2. Currently only JSON format is supported. Other formats may be available in future releases. - - - dns_server_timeout - The maximum amount of time in milliseconds, that - D2 will wait for a response from a DNS server to a single DNS update - message. - - + + + + ncr_format - Socket protocol to use when sending requests to D2. + Currently only UDP is supported. TCP may be available in an upcoming + release. + + + 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 @@ -207,7 +212,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - name — + 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 @@ -218,7 +223,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - algorithm — + 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: @@ -247,7 +252,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - secret — + 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. @@ -303,12 +308,12 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. behavior. Currently it contains a single parameter, the catalog of forward DDNS Domains, which is a list of structures. -"DhcpDdns": { - "forward_ddns": { +"DhcpDdns": { + "forward_ddns": { "ddns_domains": [ ] - }, + }, ... -} +} By default, this list is empty, which will cause the server to ignore @@ -317,13 +322,14 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
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 for that zone. You will need one - forward DDNS Domain for each zone you wish to service. It may very - well be that some or all of your zones are maintained by the same - servers. You will still need one DDNS Domain per zone. Remember that - matching a request to the appropriate server(s) is done by zone and - a DDNS Domain only defines a single zone. + A forward DDNS Domain maps a forward DNS zone to a set of + DNS servers which maintain the forward DNS data (i.e. name to + address mapping) for that zone. You will need one forward DDNS + Domain for each zone you wish to service. It may very well + be that some or all of your zones are maintained by the same + servers. You will still need one DDNS Domain per zone. Remember + that matching a request to the appropriate server(s) is done + by zone and a DDNS Domain only defines a single zone. The section describes how to add Forward DDNS Domains. Repeat these @@ -332,7 +338,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - name — + 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 @@ -341,17 +347,16 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - key_name — + 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. Currently - TSIG has not been implemented, so this value is ignored. + used in DDNS conversations with this domain's servers. - dns_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 @@ -398,21 +403,21 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - hostname — + hostname - The resolvable host name of the DNS server. This value is not yet implemented. - ip_address — + ip_address - The IP address at which the server listens for DDNS requests. This may be either an IPv4 or an IPv6 address. - port — + port - The port on which the server listens for DDNS requests. It defaults to the standard DNS service port of 53. @@ -441,10 +446,13 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. } } + + As stated earlier, "hostname" is not yet supported so, the parameter "ip_address" must be set to the address of the DNS server. - + +
@@ -460,9 +468,10 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. reverse DDNS Domains, which is a list of structures. "DhcpDdns": { - "reverse_ddns": { + "reverse_ddns": { "ddns_domains": [ ] - } + } + ... } By default, this list is empty, which will cause the server to ignore @@ -471,14 +480,15 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
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 for that zone. You will need one - reverse DDNS Domain for each zone you wish to service. It may very - well be that some or all of your zones are maintained by the same - servers; even then, you will still need one DDNS Domain entry for each - zone. Remember that - matching a request to the appropriate server(s) is done by zone and - a DDNS Domain only defines a single zone. + A reverse DDNS Domain maps a reverse DNS zone to a set of DNS + servers which maintain the reverse DNS data (address to name + mapping) for that zone. You will need one reverse DDNS Domain + for each zone you wish to service. It may very well be that + some or all of your zones are maintained by the same servers; + even then, you will still need one DDNS Domain entry for each + zone. Remember that matching a request to the appropriate + server(s) is done by zone and a DDNS Domain only defines a + single zone. The section describes how to add Reverse DDNS Domains. Repeat these @@ -487,7 +497,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - name — + 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 @@ -501,7 +511,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - key_name — + 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 @@ -511,7 +521,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - dns_servers — + 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 @@ -559,20 +569,20 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. - hostname — + hostname - The resolvable host name of the DNS server. This value is currently ignored. - ip_address — + ip_address - The IP address at which the server listens for DDNS requests. - port — + port - The port on which the server listens for DDNS requests. It defaults to the standard DNS service port of 53. @@ -601,10 +611,15 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. } } + + + + + 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. -
@@ -698,8 +713,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. be rejected. - The following series of commands in bindctl will create the Forward - DDNS Domains. + The following example configuration specified the Forward DDNS Domains. "DhcpDdns": { "forward_ddns": { @@ -772,8 +786,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. the third domain. - The following series of commands in bindctl will create our Reverse - DDNS Domains. + These Reverse DDNS Domains are specified as follows: "DhcpDdns": { diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 36bb93878e..9fc19fdf17 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -13,46 +13,49 @@ - It is recommended to control DHCPv4 server in Kea using keactl, - which is described in details in . - - - - However, it is also possible to run the server on its own, not using any - scripts. The server accepts the following command-line parameters: + It is recommended that the Kea DHCPv4 server be started and stopped + using keactl (described in ). + However, it is also possible to run the server directly: it accepts + the following command-line switches: - -c file - specifies the configuration file. This is the - only mandatory parameter (it may be optional for configuration - parameters other than Kea) + + -c file - + specifies the configuration file. This is the only mandatory + switch. - -v - specifies whether the server logging should be - switched to verbose mode. In verbose mode, logging severity and - debuglevel specified in a configuration file are ignored and - severity debug and maximum debuglevel (99) is assumed. That flag is - convenient, for temporarily switching the server into maximum - verbosity, e.g. when debugging. + + -v - specifies whether the server + logging should be switched to verbose mode. In verbose mode, + the logging severity and debuglevel specified in a configuration + file are ignored and "debug" severity and the maximum debuglevel + (99) are assumed. The flag is convenient, for temporarily + switching the server into maximum verbosity, e.g. when + debugging. - -p port - specifies UDP port the server will listen - on. This is only useful during testing, as the DHCPv4 server - listening on ports other than default DHCPv4 ports will not be able - to handle regular DHCPv4 queries. + + -p port - + specifies UDP port the server will listen on. This is only + useful during testing, as the DHCPv4 server listening on + ports other than default DHCPv4 ports will not be able to + handle regular DHCPv4 queries. - The server running in a console can be shut down by pressing ctrl-c. The - server will detect such a key combination and will initialize shutdown procedure. + When running in a console, the server can be shut down by + pressing ctrl-c. It detects the key combination and shuts + down gracefully. On start-up, the server will detect available network interfaces - and will attempt to open UDP sockets on all interfaces that - are mentioned in the configuration file. + and will attempt to open UDP sockets on all interfaces + mentioned in the configuration file. @@ -68,8 +71,8 @@ Introduction This section explains how to configure the DHCPv4 server using the - Kea configuration backend. Kea configuration using any other - backends is outside of scope for this document. Before DHCPv4 + Kea configuration backend. (Kea configuration using any other + backends is outside of scope of this document.) Before DHCPv4 is started, its configuration file has to be created. The basic configuration looks as follows: @@ -86,7 +89,7 @@ # Next we specify the type of lease database "lease-database": { "type": "memfile", - "persist": true, + "persist": "true", "name": "/var/kea/dhcp4.leases" }, @@ -119,7 +122,7 @@ one or more objects. In this specific example, we have only one object called Dhcp4. This is a simplified configuration, as usually there will be additional objects, like Logging or DhcpDns, but we omit them now for clarity. The Dhcp4 -configuration starts with the the "Dhcp4: {" line +configuration starts with the "Dhcp4": { line and ends with the corresponding closing brace (in the above example, the brace after the last comment). Everything defined between those lines is considered to be the Dhcp4 configuration. @@ -208,8 +211,8 @@ syntax would be used: After all parameters are specified, we have two contexts open: global and Dhcp4, hence we need two closing curly brackets to close them. -In a real life configuration file there likely would be additional -components defined like Logging or DhcpDdns, so the closing brace would +In a real life configuration file there most likely would be additional +components defined such as Logging or DhcpDdns, so the closing brace would be followed by a comma and another object definition. Kea 0.9 does not have configuration syntax validation @@ -247,7 +250,7 @@ url="http://jsonviewer.stack.hu/"/>. "Dhcp4": { "lease-database": { "type": "memfile", - "persist": true, + "persist": "true", "name": "/tmp/kea-leases4.csv" } ... @@ -471,7 +474,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "domain-name-servers", "code": 6, "space": "dhcp4", - "csv-format": true, + "csv-format": "true", "data": "192.0.2.1, 192.0.2.2" }, ... @@ -509,7 +512,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "domain-name-servers", "code": 6, "space": "dhcp4", - "csv-format": false, + "csv-format": "false", "data": "C0 00 03 01 C0 00 03 02" }, ... @@ -541,7 +544,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "domain-name-servers", "code": 6, "space: "dhcp4", - "csv-format": true, + "csv-format": "true", "data": "192.0.2.3" }, ... @@ -555,12 +558,14 @@ temporarily override a list of interface names and listen on all interfaces. - - - In a future version of Kea, it will not be necessary to specify - the option code, space and csv-format fields as they will be set - automatically. - + + + In future versions of Kea, it will not be necessary to specify + the code, space + and csv-format fields, as they will + be set automatically. + + The currently supported standard DHCPv4 options are @@ -575,7 +580,7 @@ temporarily override a list of interface names and listen on all interfaces. Some options are designated as arrays, which means that more than one value is allowed in such an option. For example the option time-servers allows the specification of more than one IPv4 address, so allowing - clients to obtain the the addresses of multiple NTP servers. + clients to obtain the addresses of multiple NTP servers. @@ -598,9 +603,9 @@ temporarily override a list of interface names and listen on all interfaces. List of standard DHCPv4 options - - - + + + Name @@ -763,7 +768,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "foo", "code": 222, "type": "uint32", - "array": false, + "array": "false", "record-types": "", "space": "dhcp4", "encapsulate": "" @@ -803,7 +808,7 @@ temporarily override a list of interface names and listen on all interfaces. name "foo", "code": 222, "space": "dhcp4", - "csv-format": true, + "csv-format": "true", "data": "12345" }, ... ], @@ -827,7 +832,7 @@ temporarily override a list of interface names and listen on all interfaces. "code": 223, "space": "dhcp4", "type": "record", - "array": false, + "array": "false", "record-types": "ipv4-address, uint16, boolean, string", "encapsulate": "" }, ... @@ -848,7 +853,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "bar", "space": "dhcp4", "code": 223, - "csv-format": true, + "csv-format": "true", "data": "192.0.2.100, 123, true, Hello World" } ], @@ -892,7 +897,7 @@ temporarily override a list of interface names and listen on all interfaces. "code": 1, "space": "vendor-encapsulated-options-space", "type": "record", - "array: false, + "array": "false", "record-types": "ipv4-address, uint16, string", "encapsulates": "" } @@ -909,7 +914,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "foo" "space": "vendor-encapsulated-options-space", "code": 1, - "csv-format": true, + "csv-format": "true", "data": "192.0.2.3, 123, Hello World" } ], @@ -924,8 +929,8 @@ temporarily override a list of interface names and listen on all interfaces. "name": "vendor-encapsulated-options" "space": "dhcp4", "code": 43, - "csv-format": false, - "data: "" + "csv-format": "false", + "data": "" } ], ... @@ -972,7 +977,7 @@ temporarily override a list of interface names and listen on all interfaces. "space": "isc", "type": "ipv4-address". "record-types": "", - "array": false, + "array": "false", "encapsulate "" }, { @@ -981,7 +986,7 @@ temporarily override a list of interface names and listen on all interfaces. "space": "isc", "type": "string", "record-types": "", - "array": false + "array": "false" "encapsulate": "" } ], @@ -1002,7 +1007,7 @@ temporarily override a list of interface names and listen on all interfaces. "code": 222, "space": "dhcp4", "type": "empty", - "array": false, + "array": "false", "record-types": "", "encapsulate": "isc" } @@ -1023,21 +1028,21 @@ temporarily override a list of interface names and listen on all interfaces. "name": "subopt1", "space": "isc", "code": 1, - "csv-format": true, + "csv-format": "true", "data": "192.0.2.3" }, } "name": "subopt2", "space": "isc", "code": 2, - "csv-format": true, + "csv-format": "true", "data": "Hello world" }, { "name": "container", "space": "dhcp4", "code": 222, - "csv-format": true, + "csv-format": "true", "data": "" } ], @@ -1085,7 +1090,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "domain-name-servers", "code": 6, "data": "192.0.2.200,192.0.2.201", - "csv-format": true, + "csv-format": "true", "space": "dhcp4" } ] } @@ -1232,7 +1237,7 @@ temporarily override a list of interface names and listen on all interfaces. "Dhcp4": { "dhcp-ddns": { - "enable-updates": true, + "enable-updates": "true", "server-ip": "127.0.0.1", "server-port": 53001, "sender-ip": "", @@ -1240,9 +1245,9 @@ temporarily override a list of interface names and listen on all interfaces. "max-queue-size": 1024, "ncr-protocol": "UDP", "ncr-format": "JSON", - "override-no-update": false, - "override-client-update": false, - "replace-client-name": false, + "override-no-update": "false", + "override-client-update": "false", + "replace-client-name": "false", "generated-prefix": "myhost", "qualifying-suffix": "example.com" }, @@ -1250,51 +1255,43 @@ temporarily override a list of interface names and listen on all interfaces. } - +
DHCP-DDNS Server Connectivity In order for NCRs to reach the DHCP-DDNS server, kea-dhcp4 must be able to communicate with it. kea-dhcp4 uses the following configuration parameters to control how it communications with DHCP-DDNS: - - + + + enable-updates - determines whether or not kea-dhcp4 will + generate NCRs. By default, this value is false hence DDNS updates are + disabled. To enable DDNS updates set this value to true: + + + server-ip - IP address on which DHCP-DDNS listens for requests. The default is the local loopback interface at address 127.0.0.1. You may specify either an IPv4 or IPv6 address. - - + + + server-port - port on which DHCP-DDNS listens for requests. The default value is 53001. - - + + + sender-ip - IP address which kea-dhcp4 should use to send requests to the DHCP-DDNS server. The default value is blank which instructs kea-dhcp4 to select a suitable address. - - + + + sender-port - port which kea-dhcp4 should use to send requests to the DHCP-DDNS server. The default value of 0 instructs kea-dhcp4 to select suitable port. - - - ncr-format - Socket protocol use when sending requests to the DHCP-DDNS server. Currently - only UDP is supported. TCP may be available in an upcoming release. - - - ncr-protocol - Packet format to use when sending requests to the DHCP-DDNS server. - Currently only JSON format is supported. Other formats may be available - in future releases. - - + + + max-queue-size - maximum number of requests allowed to queue waiting to be sent to the DHCP-DDNS server. This value guards against requests accumulating uncontrollably if they are being generated faster than they can be @@ -1303,8 +1300,20 @@ temporarily override a list of interface names and listen on all interfaces. been sufficiently reduced. The intention is allow the kea-dhcp4 server to continue lease operations without running the risk that its memory usage grows without limit. The default value is 1024. - - + + + + ncr-format - socket protocol use when sending requests to the DHCP-DDNS server. Currently + only UDP is supported. TCP may be available in an upcoming release. + + + + ncr-protocol - packet format to use when sending requests to the DHCP-DDNS server. + Currently only JSON format is supported. Other formats may be available + in future releases. + + + By default, the DHCP-DDNS server is assumed to running on the same machine as kea-dhcp4, and all of the default values mentioned above should be sufficient. If, however, the DHCP-DDNS server has been configured to listen on a different address or @@ -1427,7 +1436,7 @@ temporarily override a list of interface names and listen on all interfaces. "Dhcp4": { "dhcp-ddns": { - "override-client-update": true, + "override-client-update": "true", ... }, ... @@ -1447,7 +1456,7 @@ temporarily override a list of interface names and listen on all interfaces. "Dhcp4": { "dhcp-ddns": { - "override-no-update": true, + "override-no-update": "true", ... }, ... @@ -1499,7 +1508,7 @@ temporarily override a list of interface names and listen on all interfaces. "Dhcp4": { "dhcp-ddns": { - "replace-client-name": true, + "replace-client-name": "true", ... }, ... @@ -1603,7 +1612,7 @@ temporarily override a list of interface names and listen on all interfaces. "Dhcp4": { - "echo-client-id": false, + "echo-client-id": "false", ... } diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 022159f89b..a61d888e58 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -11,46 +11,49 @@ Starting and Stopping the DHCPv6 Server - It is recommended to control DHCPv6 server in Kea using keactl, - which is described in details in . - - - - However, it is also possible to run the server on its own, not using any - scripts. The server accepts the following command-line parameters: + It is recommended that the Kea DHCPv4 server be started and stopped + using keactl (described in ). + However, it is also possible to run the server directly: it accepts + the following command-line switches: - -c file - specifies the configuration file. This is the - only mandatory parameter (it may be optional for configuration - parameters other than Kea) + + -c file - + specifies the configuration file. This is the only mandatory + switch. - -v - specifies whether the server logging should be - switched to verbose mode. In verbose mode, logging severity and - debuglevel specified in a configuration file are ignored and - severity debug and maximum debuglevel (99) is assumed. That flag is - convenient, for temporarily switching the server into maximum - verbosity, e.g. when debugging. + + -v - specifies whether the server + logging should be switched to verbose mode. In verbose mode, + the logging severity and debuglevel specified in a configuration + file are ignored and "debug" severity and the maximum debuglevel + (99) are assumed. The flag is convenient, for temporarily + switching the server into maximum verbosity, e.g. when + debugging. - -p port - specifies UDP port the server will listen - on. This is only useful during testing, as the DHCPv4 server - listening on ports other than default DHCPv6 ports will not be able - to handle regular DHCPv6 queries. + + -p port - + specifies UDP port the server will listen on. This is only + useful during testing, as the DHCPv6 server listening on + ports other than default DHCPv6 ports will not be able to + handle regular DHCPv6 queries. - The server running in a console can be shut down by pressing ctrl-c. The - server will detect such a key combination and will initialize shutdown procedure. + When running in a console, the server can be shut down by + pressing ctrl-c. It detects the key combination and shuts + down gracefully. On start-up, the server will detect available network interfaces - and will attempt to open UDP sockets on all interfaces that - are mentioned in the configuration file. + and will attempt to open UDP sockets on all interfaces + mentioned in the configuration file. @@ -68,13 +71,13 @@ Introduction This section explains how to configure the DHCPv6 server using the - Kea configuration backend. Kea configuration using any other - backends is outside of scope for this document. Before DHCPv6 + Kea configuration backend. (Kea configuration using any other + backends is outside of scope of this document.) Before DHCPv6 is started, its configuration file has to be created. The basic configuration looks as follows: { -# DHCPv6 configuration starts in this line +# DHCPv6 configuration starts on the next line "Dhcp6": { # First we set up global values @@ -87,7 +90,7 @@ # Next we specify the type of lease database "lease-database": { "type": "memfile", - "persist": true, + "persist": "true", "name": "/var/kea/dhcp6.leases" }, @@ -102,8 +105,7 @@ ] } ] - -# DHCPv6 configuration ends with this line +# DHCPv6 configuration ends with the next line } } @@ -124,7 +126,7 @@ one or more objects. In this specific example, we have only one object called Dhcp6. This is a simplified configuration, as usually there will be additional objects, like Logging or DhcpDns, but we omit them now for clarity. The Dhcp6 -configuration starts with the the "Dhcp6: {" line +configuration starts with the "Dhcp6": { line and ends with the corresponding closing brace (in the above example, the brace after the last comment). Everything defined between those lines is considered to be the Dhcp6 configuration. @@ -206,8 +208,8 @@ syntax would be used: "subnet": "2001:db8:1::/64" }, { - "pools": [ { "pool": "2001:db8:2::1-2001:db8:2::ff" } ], - "subnet": "192.0.3.0/24", + "pools": [ { "pool": "2001:db8:2::1-2001:db8:2::ffff" } ], + "subnet": "2001:db8:2::/64", "interface": "eth0" } ] @@ -219,8 +221,8 @@ In some cases in may be preferable to use more compact notation. After all parameters are specified, we have two contexts open: global and Dhcp6, hence we need two closing curly brackets to close them. -In a real life configuration file there likely would be additional -components defined like Logging or DhcpDdns, so the closing brace would +In a real life configuration file there most likely would be additional +components defined such as Logging or DhcpDdns, so the closing brace would be followed by a comma and another object definition. Kea 0.9 does not have configuration syntax validation @@ -241,29 +243,29 @@ JSON validator is available at . The server is able to store lease data in different repositories. Larger deployments may elect to store leases in a database. describes this option. In typical + linkend="database-configuration6"/> describes this option. In typical smaller deployments though, the server will use a CSV file rather than a database to store lease information. As well as requiring less administration, an advantage of using a file for storage is that it eliminates a dependency on third-party database software. The configuration of the file backend (Memfile) is controlled through - the Dhcp4/lease-database parameters. The following configuration: -"Dhcp4": { +"Dhcp6": { "lease-database": { "type": "memfile", - "persist": true, - "name": "/tmp/kea-leases4.csv" + "persist": "true", + "name": "/tmp/kea-leases6.csv" } ... } - ...sets the name of the lease file to /tmp/kea-leases4.csv. + ...sets the name of the lease file to /tmp/kea-leases6.csv. The "persist" parameter controls whether the leases are written to disk. @@ -348,7 +350,7 @@ temporarily override a list of interface names and listen on all interfaces. Subnet identifier is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with respective subnets. - When subnet identifier is not specified for a subnet being configured, it will + When the subnet identifier is not specified for a subnet being configured, it will be automatically assigned by the configuration mechanism. The identifiers are assigned from 1 and are monotonically increased for each subsequent subnet: 1, 2, 3 .... @@ -442,7 +444,7 @@ temporarily override a list of interface names and listen on all interfaces. "subnet": "2001:db8:1::/64", "pools": [ { - pool: "2001:db8:1::1-2001:db8:1::ff" + pool: "2001:db8:1::1-2001:db8:1::ffff" } ], ... @@ -502,16 +504,16 @@ temporarily override a list of interface names and listen on all interfaces. In this example, we allow server to dynamically assign all addresses available in the whole subnet. Although rather wasteful, it is certainly a valid configuration to dedicate the - whole /64 subnet for that purpose. Note that Kea server does not preallocate + whole /64 subnet for that purpose. Note that the Kea server does not preallocate the leases, so there is no danger of using gigantic address pools. When configuring a DHCPv6 server using prefix/length notation, please pay attention to the boundary values. When specifying that the server should use a given pool, it will be able to allocate also first (typically network - address) address from that pool. For example for pool 2001:db8::/64 the - 2001:db8:: address may be assigned as well. If you want to avoid this, - please use the "min-max" notation. + address) address from that pool. For example for pool 2001:db8:2::/64 the + 2001:db8:2:: address may be assigned as well. If you want to avoid this, + use the "min-max" notation.
@@ -560,13 +562,13 @@ temporarily override a list of interface names and listen on all interfaces. global and apply to all configured subnets. -"Dhcp4": { +"Dhcp6": { "option-data": [ { "name": "dns-servers", "code": 23, "space": "dhcp6", - "csv-format": true, + "csv-format": "true", "data": "2001:db8::cafe, 2001:db8::babe" }, ... @@ -600,13 +602,13 @@ temporarily override a list of interface names and listen on all interfaces. subnets with the following addresses: 2001:db8:1::cafe and 2001:db8:1::babe. -"Dhcp4": { +"Dhcp6": { "option-data": [ { "name": "dns-servers", "code": 23, "space": "dhcp6", - "csv-format": false, + "csv-format": "false", "data": "2001 0DB8 0001 0000 0000 0000 0000 CAFE 2001 0DB8 0001 0000 0000 0000 0000 BABE" }, @@ -618,8 +620,8 @@ temporarily override a list of interface names and listen on all interfaces. The value for the setting of the "data" element is split across two lines in this document for clarity: when entering the command, the whole string should be entered on the same line. Care should be taken - to use proper encoding when using hex format as Kea ability to validate - data correctness in hex format is limited. + to use proper encoding when using hexadecimal format as Kea's ability + to validate data correctness in hexadecimal is limited. @@ -645,7 +647,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "dns-servers", "code": 23, "space: "dhcp6", - "csv-format": true, + "csv-format": "true", "data": "2001:db8:1::3" }, ... @@ -661,9 +663,10 @@ temporarily override a list of interface names and listen on all interfaces. - In future versions of Kea, it will not be necessary to specify option - code, space and csv-format fields, as those fields will be set - automatically. + In future versions of Kea, it will not be necessary to specify + the code, space + and csv-format fields, as they will + be set automatically. @@ -680,7 +683,7 @@ temporarily override a list of interface names and listen on all interfaces. Some options are designated as arrays, which means that more than one value is allowed in such an option. For example the option dns-servers allows the specification of more than one IPv6 address, so allowing - clients to obtain the the addresses of multiple DNS servers. + clients to obtain the addresses of multiple DNS servers. @@ -705,9 +708,9 @@ temporarily override a list of interface names and listen on all interfaces. List of standard DHCPv6 options - - - + + + NameCodeTypeArray? @@ -780,7 +783,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "foo", "code": 100, "type": "uint32", - "array": false, + "array": "false", "record-types": "", "space": "dhcp6", "encapsulate": "" @@ -811,7 +814,7 @@ temporarily override a list of interface names and listen on all interfaces. name "foo", "code": 100, "space": "dhcp6", - "csv-format": true, + "csv-format": "true", "data": "12345" }, ... ], @@ -837,7 +840,7 @@ temporarily override a list of interface names and listen on all interfaces. "code": 101, "space": "dhcp6", "type": "record", - "array": false, + "array": "false", "record-types": "ipv4-address, uint16, boolean, string", "encapsulate": "" }, ... @@ -858,7 +861,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "bar", "space": "dhcp6", "code": 101, - "csv-format": true, + "csv-format": "true", "data": "2001:db8:1::10, 123, false, Hello World" } ], @@ -902,7 +905,7 @@ temporarily override a list of interface names and listen on all interfaces. "code": 1, "space": "vendor-encapsulated-options-space", "type": "record", - "array: false, + "array": "false", "record-types": "ipv6-address, uint16, string", "encapsulates": "" } @@ -919,7 +922,7 @@ temporarily override a list of interface names and listen on all interfaces. "name": "foo" "space": "vendor-encapsulated-options-space", "code": 1, - "csv-format": true, + "csv-format": "true", "data": "2001:db8:1::10, 123, Hello World" }, ... @@ -936,8 +939,8 @@ temporarily override a list of interface names and listen on all interfaces. "name": "vendor-encapsulated-options" "space": "dhcp6", "code": 17, - "csv-format": true, - "data: "12345" + "csv-format": "true", + "data": "12345" } ], ... @@ -972,7 +975,7 @@ temporarily override a list of interface names and listen on all interfaces. "space": "isc", "type": "ipv6-address". "record-types": "", - "array": false, + "array": "false", "encapsulate "" }, { @@ -981,7 +984,7 @@ temporarily override a list of interface names and listen on all interfaces. "space": "isc", "type": "string", "record-types": "", - "array": false + "array": "false" "encapsulate": "" } ], @@ -994,7 +997,7 @@ temporarily override a list of interface names and listen on all interfaces. The next step is to define a regular DHCPv6 option and specify that it should include options from the isc option space: -"Dhcp4": { +"Dhcp6": { "option-def": [ ..., { @@ -1002,7 +1005,7 @@ should include options from the isc option space: "code": 102, "space": "dhcp6", "type": "empty", - "array": false, + "array": "false", "record-types": "", "encapsulate": "isc" } @@ -1024,21 +1027,21 @@ should include options from the isc option space: "name": "subopt1", "space": "isc", "code": 1, - "csv-format": true, + "csv-format": "true", "data": "2001:db8::abcd" }, } "name": "subopt2", "space": "isc", "code": 2, - "csv-format": true, + "csv-format": "true", "data": "Hello world" }, { "name": "container", "space": "dhcp6", "code": 102, - "csv-format": true, + "csv-format": "true", "data": "" } ], @@ -1280,7 +1283,7 @@ should include options from the isc option space: "Dhcp6": { "dhcp-ddns": { - "enable-updates": true, + "enable-updates": "true", "server-ip": "127.0.0.1", "server-port": 53001, "sender-ip": "", @@ -1288,9 +1291,9 @@ should include options from the isc option space: "max-queue-size": 1024, "ncr-protocol": "UDP", "ncr-format": "JSON", - "override-no-update": false, - "override-client-update": false, - "replace-client-name": false, + "override-no-update": "false", + "override-client-update": "false", + "replace-client-name": "false", "generated-prefix": "myhost", "qualifying-suffix": "example.com" }, @@ -1299,11 +1302,6 @@ should include options from the isc option space: - - The "enable-updates" parameter determines whether or not kea-dhcp6 will - generate NCRs. If missing, this value is assumed false hence DDNS updates are - disabled. -
DHCP-DDNS Server Connectivity @@ -1311,44 +1309,49 @@ should include options from the isc option space: In order for NCRs to reach the D2 server, kea-dhcp6 must be able to communicate with it. kea-dhcp6 uses the following configuration parameters to control how it communications with D2: - - - server-ip - IP address on which D2 listens for requests. The default is + + + enable-updates - determines whether or not kea-dhcp6 will + generate NCRs. If missing, this value is assumed to be false hence DDNS updates + are disabled. To enable DDNS updates set this value to true: + + + server-ip - IP address on which D2 listens for requests. The default is the local loopback interface at address 127.0.0.1. You may specify either an IPv4 or IPv6 address. - - - server-port - port on which D2 listens for requests. The default value + + + server-port - port on which D2 listens for requests. The default value is 53001. - - - sender-ip - IP address which kea-dhcp6 should use to send requests to D2. + + + sender-ip - IP address which kea-dhcp6 should use to send requests to D2. The default value is blank which instructs kea-dhcp6 to select a suitable address. - - - sender-port - port which kea-dhcp6 should use to send requests to D2. The + + + sender-port - port which kea-dhcp6 should use to send requests to D2. The default value of 0 instructs kea-dhcp6 to select suitable port. - - - ncr-format - Socket protocol use when sending requests to D2. Currently - only UDP is supported. TCP may be available in an upcoming release. - - - ncr-protocol - Packet format to use when sending requests to D2. - Currently only JSON format is supported. Other formats may be available - in future releases. - - - max-queue-size - maximum number of requests allowed to queue waiting to + + + max-queue-size - maximum number of requests allowed to queue waiting to be sent to D2. This value guards against requests accumulating uncontrollably if they are being generated faster than they can be delivered. If the number of requests queued for transmission reaches this value, DDNS updating will be turned off until the queue backlog has been sufficiently reduced. The intent is allow kea-dhcp6 to continue lease operations. The default value is 1024. - - + + + ncr-format - Socket protocol use when sending requests to D2. Currently + only UDP is supported. TCP may be available in an upcoming release. + + + ncr-protocol - Packet format to use when sending requests to D2. + Currently only JSON format is supported. Other formats may be available + in future releases. + + By default, D2 is assumed to running on the same machine as kea-dhcp6, and all of the default values mentioned above should be sufficient. If, however, D2 has been configured to listen on a different address or @@ -1371,13 +1374,13 @@ should include options from the isc option space: When does kea-dhcp6 generate DDNS request - kea-dhcp6 follows the behavior prescribed for DHCP servers - in RFC 4704. It is important to keep in mind that kea-dhcp6 - provides the initial decision making of when and what to update - and forwards that information to D2 in the form of - NCRs. Carrying out the actual DNS updates and dealing with such - things as conflict resolution are the purview of D2 (). + kea-dhcp6 follows the behavior prescribed for DHCP servers in + RFC 4704. + It is important to keep in mind that kea-dhcp6 provides the initial + decision making of when and what to update and forwards that + information to D2 in the form of NCRs. Carrying out the actual + DNS updates and dealing with such things as conflict resolution + are the purview of D2 (). This section describes when kea-dhcp6 will generate NCRs and the @@ -1482,7 +1485,7 @@ should include options from the isc option space: "Dhcp6": { "dhcp-ddns": { - "override-client-update": true, + "override-client-update": "true", ... }, ... @@ -1502,7 +1505,7 @@ should include options from the isc option space: "Dhcp6": { "dhcp-ddns": { - "override-no-update": true, + "override-no-update": "true", ... }, ... @@ -1547,7 +1550,7 @@ should include options from the isc option space: "Dhcp6": { "dhcp-ddns": { - "replace-client-name": true, + "replace-client-name": "true", ... }, ... @@ -1573,7 +1576,7 @@ should include options from the isc option space: is no default value. To set its value simply set it to the desired string: -"Dhcp4": { +"Dhcp6": { "dhcp-ddns": { "qualifying-suffix": "foo.example.org", ...