Kea Database Administration

Databases and Database Version Numbers @@@ -158,14 -153,14 +161,14 @@@ backend may be essential for success or failure of your deployment. - +

List of available backends - - - - - - + + + + + + Feature diff --cc doc/guide/agent.xml index 90dffee1c7,0a1f8ec77a..d8d5c5f470 --- a/doc/guide/agent.xml +++ b/doc/guide/agent.xml @@@ -1,13 -1,8 +1,16 @@@ - - - ]> - - ++ ++ + + Kea Control Agent -

Overview Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which exposes a RESTful control interface for managing Kea servers. The daemon @@@ -267,14 -262,9 +270,14 @@@ http organization which apply to this setup. + When you use an HTTP client without TLS support as + kea-shell you can use an HTTP/HTTPS translator such as stunnel + in client mode. A sample configuration is provided in the + doc/examples/https/shell/ directory +

Control Agent Limitations Control Agent is a new component, first released in Kea 1.2. In diff --cc doc/guide/classify.xml index 23009e98f5,e78fd404d2..c9ff02116c --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@@ -1,10 -1,5 +1,13 @@@ - - - ]> ++ + - + + Client Classification

diff --cc doc/guide/config.xml index 645ee9c9e5,809150c3a3..ac8965fa41 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@@ -1,9 -1,5 +1,13 @@@ - - - ]> - ++ ++ + + Kea Configuration Kea is using JSON structures to handle configuration. Previously diff --cc doc/guide/ctrl-channel.xml index 2b37e9660c,d590e93a58..02c593fb5d --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@@ -1,12 -1,5 +1,13 @@@ - - - - %version; - ]> - - ++ ++ + + Management API A classic approach to daemon configuration assumes that @@@ -557,43 -535,7 +557,43 @@@ $ curl -X POST -H "Content-Type: applic

+ dhcp-disable + + The dhcp-disable command globally disables the DHCP + service. The server continues to operate, but it drops all received DHCP + messages. This command is useful when the server's maintenance requires that + the server temporarily stops allocating new leases and renew existing leases. + It is also useful in failover like configurations during a synchronization of + the lease databases at startup or recovery after a failure. The optional parameter + max-period specifies the time in seconds after which the + DHCP service should be automatically re-enabled if the + dhcp-enable command is not sent before this time elapses. + + +{ + "command": "dhcp-disable", + "arguments": { + "max-period": 20 + } +} + +

+ +

+ dhcp-enable + + The dhcp-enable command globally enables the DHCP + service. + + +{ + "command": "dhcp-enable" +} + +

+ -

version-get The version-get command returns on the control diff --cc doc/guide/ddns.xml index 64b90f6f31,d2d384ff2a..dd99fd0290 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@@ -1,102 -1,50 +1,106 @@@ - - - ]> - - ++ ++ + + The DHCP-DDNS Server - - The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of - the DDNS protocol (defined in RFC 2136) - on behalf of the DHCPv4 and DHCPv6 - servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct - DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP - lease change events and then post these to D2. D2 attempts to match - each such request to the appropriate DNS server(s) and carry out the - necessary conversation with those servers to update the DNS data. - - - In order to match a request to the appropriate DNS servers, D2 must have a - catalog of servers from which to select. In fact, D2 has two such catalogs, - one for forward DNS and one for reverse DNS; these catalogs are referred - to as DDNS Domain Lists. Each list consists of one or more named DDNS - Domains. Further, each DDNS Domain has a list of one or more DNS - servers that publish the DNS data for that domain. - - - When conducting forward domain matching, D2 will compare the FQDN in - the request against the name of each forward DDNS Domain. The domain - whose name matches the longest portion of the FQDN is considered the - best match. For example, if the FQDN is "myhost.sample.example.com.", - and there are two forward domains in the catalog: "sample.example.com." - and "example.com.", the former is regarded as the best match. In some - cases, it may not be possible to find a suitable match. Given the same two - forward domains there would be no match for the FQDN, "bogus.net", so the - request would be rejected. Finally, if there are no forward DDNS Domains - defined, D2 will simply disregard the forward update portion of requests. - - - When conducting reverse domain matching, D2 constructs a reverse - FQDN from the lease address in the request and compare that against - the name of each reverse DDNS Domain. Again, the domain whose name matches - the longest portion of the FQDN is considered the best match. For instance, - if the lease address is "172.16.1.40" and there are two reverse domains in - the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the - former is the best match. As with forward matching, it is possible to not - find a suitable match. Given the same two domains, there would be no - match for the lease address, "192.168.1.50", and the request would be - rejected. Finally, if there are no reverse DDNS Domains defined, D2 will - simply disregard the reverse update portion of requests. ++ +

+ Overview + + The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts - the client side of the DDNS protocol (defined in - RFC 2136) ++ the client side of the DDNS protocol (defined in RFC 2136) + on behalf of the DHCPv4 and DHCPv6 servers (kea-dhcp4 and kea-dhcp6 + respectively). The DHCP servers construct DDNS update requests, known + as NameChangeRequests (NCRs), based upon DHCP lease change events and + then post these to D2. D2 attempts to match each such request to the + appropriate DNS server(s) and carry out the necessary conversation with + those servers to update the DNS data. -

+ DNS Server selection + + In order to match a request to the appropriate DNS servers, D2 must have a + catalog of servers from which to select. In fact, D2 has two such catalogs, + one for forward DNS and one for reverse DNS; these catalogs are referred + to as DDNS Domain Lists. Each list consists of one or more named DDNS + Domains. Further, each DDNS Domain has a list of one or more DNS + servers that publish the DNS data for that domain. + + + When conducting forward domain matching, D2 will compare the FQDN in + the request against the name of each forward DDNS Domain. The domain + whose name matches the longest portion of the FQDN is considered the + best match. For example, if the FQDN is "myhost.sample.example.com.", + and there are two forward domains in the catalog: "sample.example.com." + and "example.com.", the former is regarded as the best match. In some + cases, it may not be possible to find a suitable match. Given the same two + forward domains there would be no match for the FQDN, "bogus.net", so the + request would be rejected. Finally, if there are no forward DDNS Domains + defined, D2 will simply disregard the forward update portion of requests. + + + When conducting reverse domain matching, D2 constructs a reverse + FQDN from the lease address in the request and compare that against + the name of each reverse DDNS Domain. Again, the domain whose name matches + the longest portion of the FQDN is considered the best match. For instance, + if the lease address is "172.16.1.40" and there are two reverse domains in + the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the + former is the best match. As with forward matching, it is possible to not + find a suitable match. Given the same two domains, there would be no + match for the lease address, "192.168.1.50", and the request would be + rejected. Finally, if there are no reverse DDNS Domains defined, D2 will + simply disregard the reverse update portion of requests. + +

+ Conflict Resolution + + D2 implements the conflict resolution strategy prescribed by + RFC 4703. + Conflict resolution is intended to prevent different clients from + mapping to the same FQDN at the same time. To make this possible, the + RFC requires that forward DNS entries for a given FQDN must be + accompanied by a DHCID resource record (RR). This record contains a + client identifier that uniquely identifies the client to whom the name + belongs. Furthermore, any DNS updater who wishes to update or remove + existing forward entries for an FQDN may only do so if their client + matches that of the DHCID RR. + + + In other words, the DHCID RR maps an FQDN to the client to whom it + belongs and thereafter only changes to that mapping should only be + done by or at the behest of that client. + + + Currently, conflict detection is always performed. Future releases may + offer alternative behavior. + +

+ Dual Stack Environments + + RFC 4703, + sec. 5.2, describes issues that may arise with dual stack + clients. These are clients that wish to have have both IPv4 and IPv6 + mappings for the same FQDN. In order for this work properly, such + clients are required to embed ther IPv6 DUID within their IPv4 client + identifier option as described in + RFC 4703. + In this way, DNS upates for both IPv4 and IPv6 can be managed under + the same DHCID RR. Support for this does not yet exist in Kea but is + called for in the ticket, http://kea.isc.org/ticket/4519, which we + hope to include in a future release. + +

Starting and Stopping the DHCP-DDNS Server @@@ -977,4 -925,4 +981,4 @@@ corresponding values in the DHCP server

- - ++ diff --cc doc/guide/dhcp4-srv.xml index 95453e18a8,669e52eee1..83de4dadb9 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@@ -1,13 -1,8 +1,15 @@@ - - - ]> - - ++ + + The DHCPv4 Server -

Starting and Stopping the DHCPv4 Server @@@ -1447,8 -1369,8 +1446,8 @@@ It is merely echoed by the serve ipv4-addressIPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1) ipv6-addressIPv6 address in the usual colon notation (e.g. 2001:db8::1) ipv6-prefixIPv6 prefix and prefix length specified using CIDR notation, e.g. 2001:db8:1::/64. This data type is used to represent an 8-bit field conveying a prefix length and the variable length prefix value - psidPSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See RFC 7597 for the details about the PSID wire representation + psidPSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See RFC 7597 for the details about the PSID wire representation - recordStructured data that may comprise any types (except "record" and "empty") + recordStructured data that may be comprised of any types (except "record" and "empty"). The array flag applies to the last field only. stringAny text tupleA length encoded as a 8 (16 for DHCPv6) bit unsigned integer followed by a string of this length uint88 bit unsigned integer with allowed values 0 to 255 @@@ -1614,148 -1513,7 +1613,148 @@@

+ DHCPv4 Private Options + + Options with code between 224 and 254 are reserved for private use. + They can be defined at the global scope or at client class local + scope: this allows to use option definitions depending on context + and to set option data accordingly. For instance to configure + an old PXEClient vendor: + +"Dhcp4": { + "client-class": [ + { + "name": "pxeclient", + "test": "option[vendor-class-identifier].text == 'PXEClient'", + "option-def": [ + { + "name": "configfile", + "code": 209, + "type": "string" + } + ], + ... + }, ... + ], + ... +} + + + + As the Vendor Specific Information option (code 43) has vendor + specific format, i.e. can carry either raw binary value or + sub-options, this mechanism is available for this option too. + + + In the following example taken from a real configuration two vendor + classes use the option 43 for different and incompatible purposes: + +"Dhcp4": { + "option-def": [ + { + "name": "cookie", + "code": 1, + "type": "string", + "space": "APC" + }, + { + "name": "mtftp-ip", + "code": 1, + "type": "ipv4-address", + "space": "PXE" + }, + ... + ], + "client-class": [ + { + "name": "APC", + "test": "(option[vendor-class-identifier].text == 'APC'", + "option-def": [ + { + "name": "vendor-encapsulated-options", + "type": "empty", + "encapsulate": "APC" + } + ], + "option-data": [ + { + "name": "cookie", + "space": "APC", + "data": "1APC" + }, + { + "name": "vendor-encapsulated-options" + }, + ... + ], + ... + }, + { + "name": "PXE", + "test": "(option[vendor-class-identifier].text == 'PXE'", + "option-def": [ + { + "name": "vendor-encapsulated-options", + "type": "empty", + "encapsulate": "PXE" + } + ], + "option-data": [ + { + "name": "mtftp-ip", + "space": "PXE", + "data": "0.0.0.0" + }, + { + "name": "vendor-encapsulated-options" + }, + ... + ], + ... + }, + ... + ], + ... +} + + + + The definition used to decode a VSI option is: + + + The local definition of a client class the incoming packet belongs to + + + If none, the global definition + + + If none, the last resort definition described in the next section + (backward compatible with + previous Kea versions). + + + + + + This last resort definition for the Vendor Specific Information + option (code 43) is not compatible with a raw binary value. + So when there are some known cases where a raw binary value + will be used, a client class must be defined with a classification + expression matching these cases and an option definition for + the VSI option with a binary type and no encapsulation. + + + + + Option definitions in client classes is allowed only for these + limited option set (codes 43 and from 224 to 254), and only + for DHCPv4. + + +

+ -

DHCPv4 Vendor Specific Options Currently there are two option spaces defined for the DHCPv4 daemon: @@@ -1825,14 -1583,9 +1824,14 @@@ ... } + + + Another possibility, added in Kea 1.3, is to redefine the option, + see . +

Nested DHCPv4 Options (Custom Option Spaces) It is sometimes useful to define a completely new option @@@ -2653,10 -2402,9 +2652,10 @@@ myhost-172-16-1-10.example.com. +

Next Server (siaddr) In some cases, clients want to obtain configuration from a TFTP server. Although there is a dedicated option for it, some devices may use the siaddr field @@@ -3389,22 -3124,30 +3386,25 @@@ with classification using expressions.

- Storing Host Reservations in MySQL or PostgreSQL +

+ Storing Host Reservations in MySQL, PostgreSQL or Cassandra - It is possible to store host reservations in MySQL or PostgreSQL database. See - for information on how to configure Kea to use - reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated - tools for managing reservations in a database. The Kea wiki http://kea.isc.org/wiki/HostReservationsHowTo provides detailed - information and examples of how reservations can be inserted into the - database. + It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See + for information on how to configure Kea to use + reservations stored in MySQL, PostgreSQL or Cassandra. Kea provides dedicated hook for + managing reservations in a database, section provide - detailed information. ++ detailed information. http://kea.isc.org/wiki/HostReservationsHowTo ++ provides some examples how to conduct common host reservation operations. - In Kea 1.1.0 maximum length of an option specified per host is + In Kea maximum length of an option specified per host is arbitrarily set to 4096 bytes.

- Storing host reservations in CQL (Cassandra) - Kea currently does not support storing reservations in - Cassandra (CQL). -

- - +

Fine Tuning DHCPv4 Host Reservation The host reservation capability introduces additional restrictions for the @@@ -3512,456 -3255,15 +3512,456 @@@ If not specified, the default value is src/lib/dhcpsrv/cfg_host_operations.cc --> +

+ -

+ + +

+ Shared networks in DHCPv4 + + DHCP servers use subnet information in two ways. First, it is used + to determine the point of attachment, or simply put, where the client is + connected to the network. Second, the subnet information is used to group + information pertaining to specific location in the network. This approach + works well in general case, but the are scenarios where the boundaries are + blurred. Sometimes it is useful to have more than one logical IP subnet + being deployed on the same physical link. The need to understand + that two or more subnets are used on the same link requires additional logic + in the DHCP server. This capability has been added in Kea 1.3.0. It is + called "shared networks" in Kea and ISC DHCP projects. It is sometimes also + called "shared subnets". In Microsoft's nomenclature it is called "multinet". + + + There are many use cases where the feature is useful. This paragraph + explains just a handful of the most common ones. The first and by far the most + common use case is an existing network that has grown and is running out of + available address space. Rather than migrating all devices to a new, larger + subnet, it is easier to simply configure additional subnet on top of the + existing one. Sometimes, due to address space fragmentation (e.g. only many + disjoint /24s are available) this is the only choice. Also, configuring + additional subnet has the advantage of not disrupting the operation of + existing devices. + + Another very frequent use case comes from cable networks. There are two types + of devices in cable networks: cable modems and the end user devices behind + them. It is a common practice to use different subnet for cable modems to + prevent users from tinkering with their cable modems. In this case, the + distinction is based on the type of device, rather than address space + exhaustion. + + A client connected to a shared network may be assigned an address from + any of the address pools defined within the subnets belonging to the shared + network. Internally, the server selects one of the subnets belonging to a + shared network and tries to allocate an address from this subnet. If the + server is unable to allocate an address from the selected subnet (e.g. due + to address pools exhaustion) it will use another subnet from the same shared + network and try to allocate an address from this subnet etc. Therefore, in the + typical case, the server will allocate all addresses available for a given + subnet before it starts allocating addresses from other subnets belonging to + the same shared network. However, in certain situations the client can be + allocated an address from the other subnets before the address pools in the + first subnet get exhausted, e.g. when the client provides a hint that + belongs to another subnet or the client has reservations in a different than + default subnet. + + + + It is strongly discouraged for the Kea deployments to assume that the + server doesn't allocate addresses from other subnets until it uses all + the addresses from the first subnet in the shared network. Apart from the + fact that hints, host reservations and client classification affect subnet + selection, it is also foreseen that we will enhance allocation strategies + for shared networks in the future versions of Kea, so as the selection + of subnets within a shared network is equally probable (unpredictable). + + + In order to define a shared network an additional configuration scope + is introduced: + +{ +"Dhcp4": { + "shared-networks": [ + { + // Name of the shared network. It may be an arbitrary string + // and it must be unique among all shared networks. + "name": "my-secret-lair-level-1", + + // Subnet selector can be specifed on the shared network level. + // Subnets from this shared network will be selected for directly + // connected clients sending requests to server's "eth0" interface. + "interface": "eth0", + + // This starts a list of subnets in this shared network. + // There are two subnets in this example. + "subnet4": [ + { + "subnet": "10.0.0.0/8", + "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], + }, + { + "subnet": "192.0.2.0/24", + "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ] + } + ], + } ], // end of shared-networks + + // It is likely that in your network you'll have a mix of regular, + // "plain" subnets and shared networks. It is perfectly valid to mix + // them in the same config file. + // + // This is regular subnet. It's not part of any shared-network. + "subnet4": [ + { + "subnet": "192.0.3.0/24", + "pools": [ { "pool": "192.0.3.1 - 192.0.3.200" } ], + "interface": "eth1" + } + ] + +} // end of Dhcp4 +} + + + As you see in the example, it is possible to mix shared and regular + ("plain") subnets. Each shared network must have a unique name. This is + similar to ID for subnets, but gives you more flexibility. This is used + for logging, but also internally for identifying shared networks. + + In principle it makes sense to define only shared networks that + consist of two or more subnets. However, for testing purposes it is allowed + to define a shared network with just one subnet or even an empty one. This + is not a recommended practice in production networks, as the shared network + logic requires additional processing and thus lowers server's performance. + To avoid unnecessary performance degradation the shared subnets should only + be defined when required by the deployment. + + + Shared networks provide an ability to specify many parameters in + the shared network scope that will apply to all subnets within it. If + necessary, you can specify a parameter on the shared network scope and then + override its value in the subnet scope. For example: + +"shared-networks": [ + { + "name": "lab-network3", + + "interface": "eth0", + + // This applies to all subnets in this shared network, unless + // values are overridden on subnet scope. + "valid-lifetime": 600, + + // This option is made available to all subnets in this shared + // network. + "option-data": [ { + "name": "log-servers", + "data": "1.2.3.4" + } ], + + "subnet4": [ + { + "subnet": "10.0.0.0/8", + "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], + + // This particular subnet uses different values. + "valid-lifetime": 1200, + "option-data": [ + { + "name": "log-servers", + "data": "10.0.0.254" + }, + { + "name": "routers", + "data": "10.0.0.254" + } ] + }, + { + "subnet": "192.0.2.0/24", + "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ], + + // This subnet does not specify its own valid-lifetime value, + // so it is inherited from shared network scope. + "option-data": [ + { + "name": "routers", + "data": "192.0.2.1" + } ] + } + ] + } ] + In this example, there is a log-servers option defined that is available to + clients in both subnets in this shared network. Also, a valid lifetime is + set to 10 minutes (600s). However, the first subnet overrides some of the values + (valid lifetime is 20 minutes, different IP address for log-servers), but + also adds its own option (router address). Assuming a client asking for + router and log servers options is assigned a lease from this subnet, he will + get a lease for 20 minutes and log-servers and routers value of 10.0.0.254. + If the same client is assigned to the second subnet, he will get a 10 + minutes long lease, log-servers value of 1.2.3.4 and routers set to 192.0.2.1. + + +

+ Local and relayed traffic in shared networks + + It is possible to specify interface name in the shared network scope to + tell the server that this specific shared network is reachable directly (not + via relays) using local network interface. It is sufficient to specify + it once on the shared network level. As all subnets in a shared network are + expected to be used on the same physical link, it is a configuration error + to attempt to define a shared network using subnets that are reachable over + different interfaces. It is allowed to specify interface parameter on each + subnet, although its value must be the same for each subnet. Thus it's + usually more convenient to specify it once on the shared network level. + +"shared-networks": [ + { + "name": "office-floor-2", + + // This tells Kea that the whole shared networks is reachable over + // local interface. This applies to all subnets in this network. + "interface": "eth0", + + "subnet4": [ + { + "subnet": "10.0.0.0/8", + "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], + "interface": "eth0" + }, + { + "subnet": "192.0.2.0/24", + "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ] + + // Specifying a different interface name is configuration + // error: + // "interface": "eth1" + } + ] + } ] + + + +Somewhat similar to interface names, also relay IP addresses can be +specified for the whole shared network. However, depending on your relay +configuration, it may use different IP addresses depending on which subnet +is being used. Thus there is no requirement to use the same IP relay address +for each subnet. Here's an example: + + +"shared-networks": [ + {" + "name": "kakapo", + "relay": { + "ip-address": "192.3.5.6" + }, + "subnet4": [ + { + "subnet": "192.0.2.0/26", + "relay": { + "ip-address": "192.1.1.1" + }, + "pools": [ { "pool": "192.0.2.63 - 192.0.2.63" } ] + }, + { + "subnet": "10.0.0.0/24", + "relay": { + "ip-address": "192.2.2.2" + }, + "pools": [ { "pool": "10.0.0.16 - 10.0.0.16" } ] + } + ] + } +] +In this particular case the relay IP address specified on network level doesn't +have much sense, as it is overridden in both subnets, but it was left there +as an example of how one could be defined on network level. Note that the +relay agent IP address typically belongs to the subnet it relays packets from, +but this is not a strict requirement. Therefore Kea accepts any value here +as long as it is valid IPv4 address. + +

+ Client classification in shared networks + + Sometimes it is desired to segregate clients into specific subnets + based on some properties. This mechanism is called client classification + and is described in . Client classification + can be applied to subnets belonging to shared networks in the same way + as it is used for subnets specified outside of shared networks. + It is important to understand how the server selects subnets for + the clients when client classification is in use, to assure that the + desired subnet is selected for a given client type. + + If a subnet is associated with some classes, only the clients + belonging to any of these classes can use this subnet. If there are no + classes specified for a subnet, any client connected to a given shared + network can use this subnet. A common mistake is to assume that the + subnet including client classes is preferred over subnets without + client classes. Consider the following example: + + +{ + "client-classes": [ + { + "name": "b-devices", + "test": "option[93].hex == 0x0002" + } + ], + "shared-networks": [ + { + "name": "galah", + "interface": "eth0", + "subnet4": [ + { + "subnet": "192.0.2.0/26", + "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ], + }, + { + "subnet": "10.0.0.0/24", + "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ], + "client-class": "b-devices" + } + ] + } + ] +} + + + If the client belongs to "b-devices" class (because it includes option + 93 with a value of 0x0002) it doesn't guarantee that the subnet 10.0.0.0/24 + will be used (or preferred) for this client. The server can use any of + the two subnets because the subnet 192.0.2.0/26 is also allowed for + this client. The client classification used in this case should be pereceived + as a way to restrict access to certain subnets, rather than a way to express + subnet preference. For example, if the client doesn't belong to the + "b-devices" class it may only use the subnet 192.0.2.0/26 and will + never use the subnet 10.0.0.0/24. + + + A typical use case for client classification is in the cable network, + where cable modems should use one subnet and other devices should use + another subnet within the same shared network. In this case it is required + to apply classification on all subnets. The following example defines two + classes of devices. The subnet selection is made based on option 93 values. + +{ + "client-classes": [ + { + + "name": "a-devices", + "test": "option[93].hex == 0x0001" + }, + { + "name": "b-devices", + "test": "option[93].hex == 0x0002" + } + ], + "shared-networks": [ + { + "name": "galah", + "interface": "eth0", + "subnet4": [ + { + "subnet": "192.0.2.0/26", + "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ], + "client-class": "a-devices" + }, + { + "subnet": "10.0.0.0/24", + "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ], + "client-class": "b-devices" + } + ] + } + ] +} + +In this example each class has its own restriction. Only clients that belong to +class "a-devices" will be able to use subnet 192.0.2.0/26 and only clients +belonging to b-devices will be able to use subnet 10.0.0.0/24. Care should be +taken to not define too restrictive classification rules, as clients that are +unable to use any subnets will be refused service. Although, this may be a +desired outcome if one desires to service only clients of known properties +(e.g. only VoIP phones allowed on a given link). + + + Note that it is possible to achieve similar effect as presented in this + section without the use of shared networks. If the subnets are placed in + the global subnets scope, rather than in the shared network, the server + will still use classification rules to pick the right subnet for a given + class of devices. The major benefit of placing subnets within the + shared network is that common parameters for the logically grouped + subnets can be specified once, in the shared network scope, e.g. + "interface" or "relay" parameter. All subnets belonging to this shared + network will inherit those parameters. + + +

+ +

+ Host reservations in shared networks + + + Subnets being part of a shared network allow host reservations, similar to + regular subnets: + +{ + "shared-networks": [ + { + "name": "frog", + "interface": "eth0", + "subnet4": [ + { + "subnet": "192.0.2.0/26", + "id": 100, + "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ], + "reservations": [ + { + "hw-address": "aa:bb:cc:dd:ee:ff", + "ip-address": "192.0.2.28" + } + ] + }, + { + "subnet": "10.0.0.0/24", + "id": 101, + "pools": [ { "pool": "10.0.0.1 - 10.0.0.254" } ], + "reservations": [ + { + "hw-address": "11:22:33:44:55:66", + "ip-address": "10.0.0.29" + } + ] + } + ] + } + ] +} + + +It is worth noting that Kea conducts additional checks when processing a +packet if shared networks are defined. First, instead of simply checking if +there's a reservation for a given client in his initially selected subnet, it +goes through all subnets in a shared network looking for a reservation. This is +one of the reasons why defining a shared network may impact performance. If +there is a reservation for a client in any subnet, that particular subnet will +be picked for the client. Although it's technically not an error, it is +considered a bad practice to define reservations for the same host in multiple +subnets belonging to the same shared network. + +While not strictly mandatory, it is strongly recommended to use explicit +"id" values for subnets if you plan to use database storage for host +reservations. If ID is not specified, the values for it be autogenerated, +i.e. it will assign increasing integer values starting from 1. Thus, the +autogenerated IDs are not stable across configuration changes. +

- -

Server Identifier in DHCPv4 The DHCPv4 protocol uses a "server identifier" to allow clients @@@ -3971,34 -3273,14 +3971,34 @@@ received. A single server instance will use multiple server identifiers if it is receiving queries on multiple interfaces. + - Currently there is no mechanism to override the default server identifiers - by an administrator. In the future, the configuration mechanism will be used - to specify the custom server identifier. + It is possible to override default server identifier values by specifying + "dhcp-server-identifier" option. This option is only supported on the + global, shared network and subnet level. It must not be specified + on client class and host reservation level. + + + The following example demonstrates how to override server identifier for + a subnet: + +"subnet4": [ + { + "subnet": "192.0.2.0/24", + "option-data": [ + { + "name": "dhcp-server-identifier", + "data": "10.2.5.76" + } + ], + ... + } +] +

How the DHCPv4 Server Selects a Subnet for the Client The DHCPv4 server differentiates between the directly connected clients, diff --cc doc/guide/dhcp6-srv.xml index 492f384229,917513f4a0..f5e1ae340e --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@@ -1,13 -1,8 +1,15 @@@ - - - ]> - - ++ + + The DHCPv6 Server -

Starting and Stopping the DHCPv6 Server @@@ -599,7 -581,8 +600,7 @@@ 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 @@@ -1228,14 -1208,15 +1227,14 @@@ temporarily override a list of interfac no means to validate the format at the moment. - -

List of Standard DHCPv6 Options - - - - - + + + + + NameCodeTypeArray? @@@ -1264,10 -1245,10 +1263,10 @@@ vendor-opts17uint32false - --> + --> sip-server-dns21fqdntruesip-server-addr22ipv6-addresstruedns-servers23ipv6-addresstrue @@@ -1359,188 -1314,7 +1358,188 @@@ +

+ Common Softwire46 Options + + Softwire46 options are involved in IPv4 over IPv6 provisioning by + means of tunneling or translation as specified in the + RFC 7598. + The following sections provide configuration examples of these + options. + + +

+ Softwire46 Container Options + + S46 container options group rules and optional port parameters + for a specified domain. There are three container options specified + in the "dhcp6" (top level) option space: MAP-E Container option, + MAP-T Container option and S46 Lightweight 4over6 Container option. + These options only contain encapsulated options specified below. + They do not include any data fields. + + + + In order to configure the server to send specific container option + along with all encapsulated options, the container option must be + included in the server configuration as shown below: + +"Dhcp6": { + ... + "option-data": [ + { + "name": "s46-cont-mape" + } ], + ... +} + + + This configuration will cause the server to include MAP-E Container + option to the client. Use "s46-cont-mapt" or "s46-cont-lw" for the + MAP-T Container and S46 Lightweight 4over6 Container options + respectively. + + + + All remaining softwire options described below are included in one + of the container options. Thus, they have to be included in appropriate + option spaces by selecting a "space" name, which specifies in which + option they are supposed to be included. + +

+ +

+ S46 Rule Option + + The S46 Rule option is used for conveying the Basic Mapping Rule (BMR) + and Forwarding Mapping Rule (FMR). + +{ + "space": "s46-cont-mape-options", + "name": "s46-rule", + "data": "128, 0, 24, 192.0.2.0, 2001:db8:1::/64" +} + + Other possible "space" value is "s46-cont-mapt-options". + + + + The S46 Rule option conveys a number of parameters: + + + + flags, an unsigned 8 bits integer, with + currently only the most significant bit specified. It denotes whether + the rule can be used for forwarding (128) or not (0). + + + + + ea-len, an 8 bits long Embedded Address length. Allowed values + range from 0 to 48. + + + + IPv4 prefix length, 8 bits long; expresses the prefix length of the + Rule IPv4 prefix specified in the ipv4-prefix field. Allowed + values range from 0 to 32. + + + + IPv4 prefix, a fixed-length 32-bit field that specifies the IPv4 + prefix for the S46 rule. The bits in the prefix after prefix4-len + number of bits are reserved and MUST be initialized to zero by the + sender and ignored by the receiver. + + + + IPv6 prefix in prefix/length notation that specifies the IPv6 domain + prefix for the S46 rule. The field is padded on the right with zero + bits up to the nearest octet boundary when prefix6-len is not evenly + divisible by 8. + + + + +

+ S46 BR Option + + The S46 BR option is used to convey the IPv6 address of the + Border Relay. This option is mandatory in the MAP-E + Container option and not permitted in the MAP-T and + S46 Lightweight 4over6 Container options. + +{ + "space": "s46-cont-mape-options", + "name": "s46-br", + "data": "2001:db8:cafe::1", +} + + Other possible "space" value is "s46-cont-lw-options". + +

+ +

+ S46 DMR Option + + The S46 DMR option is used to convey values for the Default + Mapping Rule (DMR). This option is mandatory in the MAP-T + container option and not permitted in the MAP-E and S46 + Lightweight 4over6 Container options. + +{ + "space": "s46-cont-mapt-options", + "name": "s46-dmr", + "data": "2001:db8:cafe::/64", +} + + This option must not be included in other containers. + +

+ +

+ S46 IPv4/IPv6 Address Binding option. + + The S46 IPv4/IPv6 Address Binding option may be used to specify + the full or shared IPv4 address of the Customer Edge (CE). + The IPv6 prefix field is used by the CE to identify the + correct prefix to use for the tunnel source. + +{ + "space": "s46-cont-lw", + "name": "s46-v4v6bind", + "data": "192.0.2.3, 2001:db8:1:cafe::/64" +} + + This option must not be included in other containers. + +

+ S46 Port Parameters + + The S46 Port Parameters option specifies optional port set + information that MAY be provided to CEs + +{ + "space": "s46-rule-options", + "name": "s46-portparams", + "data": "2, 3/4", +} + + Other possible "space" value is "s46-v4v6bind" to include + this option in the S46 IPv4/IPv6 Address Binding option. + + + Note that the second value in the example above specifies the + PSID and PSID length fields in the format of PSID/PSID length. + This is equivalent to the values of PSID-len=4 and + PSID=12288 conveyed in the S46 Port Parameters option. + +

+ -

Custom DHCPv6 Options It is possible to define options in addition to the standard ones. Assume that we want to define a new DHCPv6 option called "foo" which will have @@@ -2327,7 -2063,8 +2326,7 @@@ should include options from the isc opt -

- +

DHCP-DDNS Server Connectivity In order for NCRs to reach the D2 server, kea-dhcp6 must be able @@@ -3108,22 -2843,28 +3105,26 @@@ with classification using expressions.

- Storing Host Reservations in MySQL or PostgreSQL +

+ Storing Host Reservations in MySQL, PostgreSQL or Cassandra - It is possible to store host reservations in MySQL or PostgreSQL. See for information on how to configure Kea to use - reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated - tools for managing reservations in a database. The Kea wiki http://kea.isc.org/wiki/HostReservationsHowTo provides detailed - information and examples of how reservations can be inserted into the - database. + It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See + for information on how to configure Kea to use + reservations stored in MySQL, PostgreSQL or Cassandra. Kea provides dedicated hook for + managing reservations in a database, section provide - detailed information. ++ detailed information. The Kea wiki http://kea.isc.org/wiki/HostReservationsHowTo ++ provides some examples how to conduct some common operations ++ on host reservations. - In Kea 1.1.0 maximum length of an option specified per host is + In Kea maximum length of an option specified per host is arbitrarily set to 4096 bytes.

- Storing Host Reservations in CQL (Cassandra) - Kea currently does not support storing reservations in - Cassandra (CQL). -

- +

Fine Tuning DHCPv6 Host Reservation The host reservation capability introduces additional restrictions for the @@@ -3238,474 -2979,7 +3239,474 @@@ If not specified, the default value is

+ +

+ Shared networks in DHCPv6 + + DHCP servers use subnet information in two ways. First, it is used + to determine the point of attachment, or simply put, where the client is + connected to the network. Second, the subnet information is used to group + information pertaining to specific location in the network. This approach + works well in general case, but the are scenarios where the boundaries are + blurred. Sometimes it is useful to have more than one logical IP subnet + being deployed on the same physical link. The need to understand + that two or more subnets are used on the same link requires additional logic + in the DHCP server. This capability has been added in Kea 1.3.0. It is + called "shared networks" in Kea and ISC DHCP projects. It is sometimes also + called "shared subnets". In Microsoft's nomenclature it is called "multinet". + + + There are many use cases where the feature is useful. The most common + example in the IPv4 case is when the server is running out of available + addresses in a subnet. This is less common in IPv6, but the shared networks + are still useful in IPv6. One of the use cases is an exhaustion of IPv6 + delegated prefixes within a subnet. Another IPv6 specific example + is an experiment with addressing scheme. With the advent of IPv6 deployment + and vast address space, many organizations split the address space into + subnets, then deploy it and after a while discover that they want to split it + differently. In the transition period they want both old and new addressing + to be available. Thus the need for more than one subnet on the same physical + link. + + Finally, the case of cable networks is directly applicable in + IPv6. There are two types of devices in cable networks: cable modems and the + end user devices behind them. It is a common practice to use different + subnet for cable modems to prevent users from tinkering with their cable + modems. In this case, the distinction is based on the type of device, rather + than coming out of running out address space. + + A client connected to a shared network may be assigned a lease (address + or prefix) from any of the pools defined within the subnets belonging to the + shared network. Internally, the server selects one of the subnets belonging to the + shared network and tries to allocate a lease from this subnet. If the + server is unable to allocate a lease from the selected subnet (e.g. due + to pools exhaustion) it will use another subnet from the same shared + network and try to allocate a lease from this subnet etc. Therefore, in the + typical case, the server will allocate all leases available in a given + subnet before it starts allocating leases from other subnets belonging to + the same shared network. However, in certain situations the client can be + allocated a lease from the other subnets before the pools in the first + subnet get exhausted, e.g. when the client provides a hint that belongs + to another subnet or the client has reservations in a different than + default subnet. + + + + It is strongly discouraged for the Kea deployments to assume that the + server doesn't allocate leases from other subnets until it uses all + the leases from the first subnet in the shared network. Apart from the + fact that hints, host reservations and client classification affect subnet + selection, it is also foreseen that we will enhance allocation strategies + for shared networks in the future versions of Kea, so as the selection + of subnets within a shared network is equally probable (unpredictable). + + + In order to define a shared network an additional configuration scope + is introduced: + +{ +"Dhcp6": { + "shared-networks": [ + { + // Name of the shared network. It may be an arbitrary string + // and it must be unique among all shared networks. + "name": "ipv6-lab-1", + + // Subnet selector can be specifed on the shared network level. + // Subnets from this shared network will be selected for clients + // communicating via relay agent having the specified IP address. + "relay": { + "ip-address": "2001:db8:2:34::1" + }, + + // This starts a list of subnets in this shared network. + // There are two subnets in this example. + "subnet6": [ + { + "subnet": "2001:db8::/48", + "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ] + }, + { + "subnet": "3ffe:ffe::/64", + "pools": [ { "pool": "3ffe:ffe::/64" } ] + } + ] + } ], // end of shared-networks + + // It is likely that in your network you'll have a mix of regular, + // "plain" subnets and shared networks. It is perfectly valid to mix + // them in the same config file. + // + // This is regular subnet. It's not part of any shared-network. + "subnet6": [ + { + "subnet": "2001:db9::/48", + "pools": [ { "pool": "2001:db9::/64" } ], + "relay": { + "ip-address": "2001:db8:1:2::1" + } + } + ] + +} // end of Dhcp6 +} + + + As you see in the example, it is possible to mix shared and regular + ("plain") subnets. Each shared network must have a unique name. This is a + similar concept to ID for subnets, but it offers more flexibility. This is used + for logging, but also internally for identifying shared networks. + + In principle it makes sense to define only shared networks that + consist of two or more subnets. However, for testing purposes it is allowed + to define a shared network with just one subnet or even an empty one. This + is not a recommended practice in production networks, as the shared network + logic requires additional processing and thus lowers server's performance. + To avoid unnecessary performance degradation the shared subnets should only + be defined when required by the deployment. + + + Shared networks provide an ability to specify many parameters in + the shared network scope that will apply to all subnets within it. If + necessary, you can specify a parameter in the shared network scope and then + override its value on the subnet scope. For example: + +"shared-networks": [ + { + "name": "lab-network3", + "relay": { + "ip-address": "2001:db8:2:34::1" + }, + + // This applies to all subnets in this shared network, unless + // values are overridden on subnet scope. + "valid-lifetime": 600, + + // This option is made available to all subnets in this shared + // network. + "option-data": [ { + "name": "dns-servers", + "data": "2001:db8::8888" + } ], + + "subnet6": [ + { + "subnet": "2001:db8:1::/48", + "pools": [ { "pool": "2001:db8:1::1 - 2001:db8:1::ffff" } ], + + // This particular subnet uses different values. + "valid-lifetime": 1200, + "option-data": [ + { + "name": "dns-servers", + "data": "2001:db8::1:2" + }, + { + "name": "unicast", + "data": "2001:abcd::1" + } ] + }, + { + "subnet": "2001:db8:2::/48", + "pools": [ { "pool": "2001:db8:2::1 - 2001:db8:2::ffff" } ], + + // This subnet does not specify its own valid-lifetime value, + // so it is inherited from shared network scope. + "option-data": [ + { + "name": "dns-servers", + "data": "2001:db8:cafe::1" + } ] + } + ], + } ] + + In this example, there is a dns-servers option defined that is available to + clients in both subnets in this shared network. Also, a valid lifetime is + set to 10 minutes (600s). However, the first subnet overrides some of the values + (valid lifetime is 20 minutes, different IP address for dns-servers), but + also adds its own option (unicast address). Assuming a client asking for a + server unicast and dns servers options is assigned a lease from this subnet, + he will get a lease for 20 minutes and dns-servers and be allowed to use + server unicast at address 2001:abcd::1. If the same client is assigned to + the second subnet, he will get a 10 minutes long lease, dns-servers value of + 2001:db8:cafe::1 and no server unicast. + + + Some parameters must be the same in all subnets in the same shared + network. This restriction applies to interface and + rapid-commit settings. The most convenient way is to + define them on shared network scope, but you may specify them for each + subnet. However, care should be taken for each subnet to have the same + value. + +

+ Local and relayed traffic in shared networks + + It is possible to specify interface name in the shared network scope to + tell the server that this specific shared network is reachable directly (not + via relays) using local network interface. It is sufficient to specify + it once in the shared network level. As all subnets in a shared network are + expected to be used on the same physical link, it is a configuration error + to attempt to make a shared network out of subnets that are reachable over + different interfaces. It is allowed to specify interface parameter on each + subnet, although its value must be the same for each subnet. Thus it's + usually more convenient to specify it once on the shared network level. + +"shared-networks": [ + { + "name": "office-floor-2", + + // This tells Kea that the whole shared networks is reachable over + // local interface. This applies to all subnets in this network. + "interface": "eth0", + + "subnet6": [ + { + "subnet": "2001:db8::/64", + "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ], + "interface": "eth0" + }, + { + "subnet": "3ffe:abcd::/64", + "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ] + + // Specifying a different interface name is configuration + // error: + // "interface": "eth1" + } + ], + } ] + + + +Somewhat similar to interface names, also relay IP addresses can be +specified for the whole shared network. However, depending on your relay +configuration, it may use different IP addresses depending on which subnet +is being used. Thus there is no requirement to use the same IP relay address +for each subnet. Here's an example: + + +"shared-networks": [ + {" + "name": "kakapo", + "relay": { + "ip-address": "2001:db8::abcd" + }, + "subnet6": [ + { + "subnet": "2001:db8::/64", + "relay": { + "ip-address": "2001:db8::1234" + }, + "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ] + }, + { + "subnet": "3ffe:abcd::/64", + "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ], + "relay": { + "ip-address": "3ffe:abcd::cafe" + } + } + ] + } +] +In this particular case the relay IP address specified on network level doesn't +have much sense, as it is overridden in both subnets, but it was left there +as an example of how one could be defined on network level. Note that the +relay agent IP address typically belongs to the subnet it relays packets from, +but this is not a strict requirement. Therefore Kea accepts any value here +as long as it is valid IPv6 address. + +

+ Client classification in shared networks + + Sometimes it is desired to segregate clients into specific subnets + based on some properties. This mechanism is called client classification + and is described in . Client classification + can be applied to subnets belonging to shared networks in the same way + as it is used for subnets specified outside of shared networks. + It is important to understand how the server selects subnets for + the clients when client classification is in use, to assure that the + desired subnet is selected for a given client type. + + If a subnet is associated with some classes, only the clients + belonging to any of these classes can use this subnet. If there are no + classes specified for a subnet, any client connected to a given shared + network can use this subnet. A common mistake is to assume that the + subnet including client classes is preferred over subnets without + client classes. Consider the following example: + + +{ + "client-classes": [ + { + "name": "b-devices", + "test": "option[1234].hex == 0x0002" + } + ], + "shared-networks": [ + { + "name": "galah", + "relay": { + "ip-address": "2001:db8:2:34::1" + }, + "subnet6": [ + { + "subnet": "2001:db8:1::/64", + "pools": [ { "pool": "2001:db8:1::20 - 2001:db8:1::ff" } ], + }, + { + "subnet": "2001:db8:3::/64", + "pools": [ { "pool": "2001:db8:3::20 - 2001:db8:3::ff" } ], + "client-class": "b-devices" + } + ] + } + ] +} + + + If the client belongs to "b-devices" class (because it includes option + 1234 with a value of 0x0002) it doesn't guarantee that the subnet 2001:db8:3::/64 + will be used (or preferred) for this client. The server can use any of + the two subnets because the subnet 2001:db8:1::/64 is also allowed for + this client. The client classification used in this case should be pereceived + as a way to restrict access to certain subnets, rather than a way to express + subnet preference. For example, if the client doesn't belong to the + "b-devices" class it may only use the subnet 2001:db8:1::/64 and will + never use the subnet 2001:db8:3::/64. + + + A typical use case for client classification is in the cable network, + where cable modems should use one subnet and other devices should use + another subnet within the same shared network. In this case it is required + to apply classification on all subnets. The following example defines two + classes of devices. The subnet selection is made based on option 1234 values. + +{ + "client-classes": [ + { + + "name": "a-devices", + "test": "option[1234].hex == 0x0001" + }, + { + "name": "b-devices", + "test": "option[1234].hex == 0x0002" + } + ], + "shared-networks": [ + { + "name": "galah", + "relay": { + "ip-address": "2001:db8:2:34::1" + }, + "subnet6": [ + { + "subnet": "2001:db8:1::/64", + "pools": [ { "pool": "2001:db8:1::20 - 2001:db8:1::ff" } ], + "client-class": "a-devices" + }, + { + "subnet": "2001:db8:3::/64", + "pools": [ { "pool": "2001:db8:3::20 - 2001:db8:3::ff" } ], + "client-class": "b-devices" + } + ] + } + ] +} + +In this example each class has its own restriction. Only clients that belong to +class a-devices will be able to use subnet 2001:db8:1::/64 and only clients +belonging to b-devices will be able to use subnet 2001:db8:3::/64. Care should +be taken to not define too restrictive classification rules, as clients that are +unable to use any subnets will be refused service. Although, this may be +desired outcome if one desires to service only clients of known properties +(e.g. only VoIP phones allowed on a given link). + + + Note that it is possible to achieve similar effect as presented in this + section without the use of shared networks. If the subnets are placed in + the global subnets scope, rather than in the shared network, the server + will still use classification rules to pick the right subnet for a given + class of devices. The major benefit of placing subnets within the + shared network is that common parameters for the logically grouped + subnets can be specified once, in the shared network scope, e.g. + "interface" or "relay" parameter. All subnets belonging to this shared + network will inherit those parameters. + + +

+ +

+ Host reservations in shared networks + + + Subnets being part of a shared network allow host reservations, similar to + regular subnets: + +{ + "shared-networks": [ + { + "name": "frog", + "relay": { + "ip-address": "2001:db8:2:34::1" + }, + "subnet6": [ + { + "subnet": "2001:db8:1::/64", + "id": 100, + "pools": [ { "2001:db8:1::1 - 2001:db8:1::64" } ], + "reservations": [ + { + "duid": "00:03:00:01:11:22:33:44:55:66", + "ip-addresses": [ "2001:db8:1::28" ] + } + ] + }, + { + "subnet": "2001:db8:3::/64", + "id": 101, + "pools": [ { "pool": "2001:db8:3::1 - 2001:db8:3::64" } ], + "reservations": [ + { + "duid": "00:03:00:01:aa:bb:cc:dd:ee:ff", + "ip-addresses": [ "2001:db8:2::28" ] + } + ] + } + ] + } + ] +} + + +It is worth noting that Kea conducts additional checks when processing a +packet if shared networks are defined. First, instead of simply checking if +there's a reservation for a given client in his initially selected subnet, it +goes through all subnets in a shared network looking for a reservation. This is +one of the reasons why defining a shared network may impact performance. If +there is a reservation for a client in any subnet, that particular subnet will +be picked for the client. Although it's technically not an error, it is +considered a bad practice to define reservations for the same host in multiple +subnets belonging to the same shared network. + +While not strictly mandatory, it is strongly recommended to use explicit +"id" values for subnets if you plan to use database storage for host +reservations. If ID is not specified, the values for it be autogenerated, +i.e. it will assign increasing integer values starting from 1. Thus, the +autogenerated IDs are not stable across configuration changes. + +

+ +

+ + + -

Server Identifier in DHCPv6 The DHCPv6 protocol uses a "server identifier" (also known as a DUID) for clients to be able to discriminate between several @@@ -4941,17 -4179,10 +4942,17 @@@ Issues and Recommendations with Multiple Stateful DHCPv6 Options, - RFC - 7550: All recommendations related to the DHCPv6 server + RFC + 7550: All recommendations related to the DHCPv6 server operation are supported. + + DHCPv6 Options for Configuration of Softwire + Address and Port-Mapped Clients, + RFC + 7598: All options specified in this specification are + supported by the DHCPv6 server. +

diff --cc doc/guide/faq.xml index 66157bf292,f638bfaf71..c58d35fd07 --- a/doc/guide/faq.xml +++ b/doc/guide/faq.xml @@@ -1,10 -1,5 +1,13 @@@ - - - ]> - - ++ ++ + + Frequently Asked Questions This chapter contains a number of frequently asked questions and diff --cc doc/guide/hooks.xml index 69f81021c9,b8bce1224e..50115e3106 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@@ -1,12 -1,7 +1,14 @@@ - - - ]> - - ++ + + Hooks Libraries -

Introduction Although Kea offers a lot of flexibility, there may be cases where @@@ -592,62 -507,9 +591,62 @@@ DUID: 17:34:e2:ff:09:92:54 and hardwar link address: 3001::1, hop count: 1, identified by remote-id: 01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f - + + + In addition to logging lease activity driven by DHCPv6 client traffic, it also + logs entries for the following lease management control channel commands: + lease6-add, lease6-update, and lease6-del. Each entry is a single string + with no embedded end-of-line markers and they will typically have the following + forms: + + + lease6-add: + + Administrator added a lease of address: *address* to a device with DUID: *DUID* + + Dependent on the arguments of the add command, it may also include the hardware address and duration. + + + Example: + +Administrator added a lease of address: 2001:db8::3 to a device with DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24 for 1 days 0 hrs 0 mins 0 secs + + + + lease6-update: + +Administrator updated information on the lease of address: *address* to a device with DUID: *DUID* + + Dependent on the arguments of the update command, it may also include the hardware address and lease duration. + + + Example: + +Administrator updated information on the lease of address: 2001:db8::3 to a device with DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24, hardware address: 1a:1b:1c:1d:1e:1f + + + + lease6-del: + Deletes have two forms, one by address and one by identifier and identifier type: + +Administrator deleted the lease for address: *address* + + or + +Administrator deleted a lease for a device identified by: *identifier-type* of *identifier* + + Currently only a type of DUID is supported. + + +Examples: + +Administrator deleted the lease for address: 2001:db8::3 + +Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24 + +

Configuring the Forensic Log Hooks To use this functionality the hook library must be included in the @@@ -894,112 -700,9 +892,112 @@@ ] } + + + When "replace-client-id" is set to false (which is the default setting), + the flex-id hook library uses evaluated flexible identifier solely for + identifying host reservations, i.e. searching for reservations within a + database. This is a functional equivalent of other identifiers, + similar to hardware address or circuit-id. However, + this mode of operation has an implication that if a client device is + replaced, it may cause a conflict between an existing lease (allocated + for old device) and the new lease being allocated for the new device. The + conflict arises because the same flexible identifier is computed for the + replaced device and the server will try to allocate the same lease. The + mismatch between client identifiers sent by new device and old device causes + the server to refuse this new allocation until the old lease expires. + A manifestation of this problem is dependant on specific expression + used as flexible identifier and is likely to appear if you only use options + and other parameters that are identifying where the device is + connected (e.g. circuit-id), rather than the device identification + itself (e.g. MAC address). + + + + The flex-id library offers a way to overcome the problem with lease conflicts + by dynamically replacing client identifier (or DUID in DHCPv6 case) with a + value derived from flexible identifier. The server processes the client's + query as if flexible identifier was sent in the client identifier (or DUID) + option. This guarantees that returning client (for which the same flexible + identifier is evaluated) will be assigned the same lease despite the client + identifier and/or MAC address change. + + + + The following is a stub configuration that enables this behavior: + +"Dhcp4": { + "hooks-libraries": [ + { + "library": "/path/libdhcp_flex_id.so", + "parameters": { + "identifier-expression": "expression", + "replace-client-id": "true" + } + }, + ... + ] +} + + + + + In the DHCPv4 case, the value derived from the flexible identifier is formed + by prepending 1 byte with a value of zero to flexible identifier. In the IPv6 + case, it is formed by prepanding two zero bytes before the flexible identifier. + + + + Note that for this mechanism to take effect, the DHCPv4 server must be configured + to respect the client identifier option value during lease allocation, i.e. + "match-client-id" must be set to true. See + for details. No additional settings + are required for DHCPv6. + + + If "replace-client-id" option is set to true, the value of "echo-client-id" + parameter (that governs whether to send back a client-id option or + not) is ignored. + + + + The section describes commands used to retrieve, + update and delete leases using various identifiers, e.g. "hw-address", + "client-id". The lease_cmds library doesn't natively support querying for + leases by flexible identifier. However, when "replace-client-id" is set to + true, it makes it possible to query for leases using a value derived from + the flexible identifier. In the DHCPv4 case, the query will look similar to this: + +{ + "command": "lease4-get", + "arguments": { + "identifier-type": "client-id", + "identifier": "00:54:64:45:66", + "subnet-id": 44 + } +} + + + where hexadecimal value of "54:64:45:66" is a flexible identifier computed + for the client. + + + + In the DHCPv6 case, the corresponding query will look similar to this: + +{ + "command": "lease6-get", + "arguments": { + "identifier-type": "duid", + "identifier": "00:00:54:64:45:66", + "subnet-id": 10 + } +} + +

host_cmds: Host Commands This section describes a hook application that offers a number of new @@@ -2386,318 -1941,10 +2382,318 @@@ If the subnet exists the response will

+ network4-list, network6-list commands + + These commands are used to retrieve full list of currently configured + shared networks. The list contains only very basic information about + each shared network. If more details are needed, please use + network4-get or network6-get to + retrieve all information available. This command does not require any + parameters and its invocation is very simple: + +{ + "command": "network4-list" +} + +An example response for network4-list looks as follows: + +{ + "arguments": { + "shared-networks": [ + { "name": "floor1" }, + { "name": "office" } + ] + }, + "result": 0, + "text": "2 IPv4 network(s) found" +} +network6-list follows exactly the same syntax for +both the query and the response. + +

+ +

+ network4-get, network6-get commands + + These commands are used to retrieve detailed information + about shared networks, including subnets currently + being part of a given network. Both commands take one + mandatory parameter name, which specify + the name of shared network. An example command to retrieve + details about IPv4 shared network with a name "floor13" + looks as follows: + +{ + "command": "network4-get", + "arguments": { + "name": "floor13" + } +} +An example response could look as follows: + +{ + "result": 0, + "text": "Info about IPv4 shared network 'floor13' returned", + "arguments": { + "shared-networks": [ + { + "match-client-id": true, + "name": "floor13", + "option-data": [ ], + "rebind-timer": 90, + "relay": { + "ip-address": "0.0.0.0" + }, + "renew-timer": 60, + "reservation-mode": "all", + "subnet4": [ + { + "subnet": "192.0.2.0/24", + "id": 5, + // many other subnet specific details here + }, + { + "id": 6, + "subnet": "192.0.3.0/31", + // many other subnet specific details here + } + ], + "valid-lifetime": 120 + } + ] + } +} + +Note that actual response contains many additional fields that are +omitted here for clarity. The response format is exactly the same as +used in config-get, just is limited to returning +shared networks information. +

+ +

+ network4-add, network6-add commands + + These commands are used to add a new shared network. New + network has to have unique name. This command requires one parameter + shared-networks, which is a list and + should contain exactly one entry that defines the + network. The only mandatory element for a network is its + name. Although it does not make operational sense, it is + allowed to add an empty shared network that does not have + any subnets in it. That is allowed for testing purposes, but + having empty networks (or with only one subnet) is + discouraged in production environments. For details regarding + syntax, see and . + + As opposed to parameter inheritance during full + new configuration processing, this command does not fully handle + parameter inheritance and any missing parameters will be + filled with default values, rather than inherited from + global scope. + + An example that showcases how to add a new IPv4 shared network looks + as follows: + +{ + "command": "network4-add", + "arguments": { + "shared-networks": [ { + "name": "floor13", + "subnet4": [ + { + "id": 100, + "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ], + "subnet": "192.0.2.0/24", + "option-data": [ + { + "name": "routers", + "data": "192.0.2.1" + } + ] + }, + { + "id": 101, + "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ], + "subnet": "192.0.3.0/24", + "option-data": [ + { + "name": "routers", + "data": "192.0.3.1" + } + ] + } ] + } ] + } +} + +Assuming there was no shared network with a name floor13 and no subnets with id +100 and 101 previously configured, the command will be successful and will +return the following response: + +{ + "arguments": { + "shared-networks": [ { "name": "floor13" } ] + }, + "result": 0, + "text": "A new IPv4 shared network 'floor13' added" +} + +The network6-add uses the same syntax for both the query and +the response. However, there are some parameters that are IPv4-only +(e.g. match-client-id) and some are IPv6-only (e.g. interface-id). The same +applies to subnets within the network. + +

+ network4-del, network6-del commands + + These commands are used to delete existing shared networks. Each + subnet within the network being removed will be demoted to a plain + subnet. If you want to completely remove the subnets, please use + subnet4-del or subnet6-del + commands. Both commands take exactly one parameter 'name' that + specifies the name of the network to be removed. An example invocation + of network4-del command looks as follows: + +{ + "command": "network4-del", + "arguments": { + "name": "floor13" + } +} + +Assuming there was such a network configured, the response will look similar to +the following: + +{ + "arguments": { + "shared-networks": [ + { + "name": "floor1" + } + ] + }, + "result": 0, + "text": "IPv4 shared network 'floor13' deleted" +} +The network6-del command uses exactly the same syntax for +both the command and the response. + + +

+ network4-subnet-add, network6-subnet-add commands + + These commands are used to add existing subnets to existing shared + networks. There are several ways to add new shared network. System + administrator can add the whole shared network at once, either by + editing a configuration file or by calling + network4-add or network6-add + commands with desired subnets in it. This approach works better for completely + new shared subnets. However, there may be cases when an existing + subnet is running out of addresses and needs to be extended with + additional address space. In other words another subnet has to be + added on top of it. For this scenario, a system administrator can use + network4-add or network6-add and + then add existing subnet to this newly created shared network using + network4-subnet-add or + network6-subnet-add. + + + The network4-subnet-add and + network6-subnet-add commands take two parameters: + id, which is an integer and specifies subnet-id of existing subnet to + be added to a shared network; and name, which + specifies name of the shared network the subnet will be added to. The + subnet must not belong to any existing network. In case you want to + reassign a subnet from one shared network to another, please use + network4-subnet-del or + network6-subnet-del commands first. + + + An example invocation of network4-subnet-add + command looks as follows: + +{ + "command": "network4-subnet-add", + "arguments": { + "name": "floor13", + "id": 5 + } +} +Assuming there is a network named 'floor13', there is a subnet with subnet-id 5 +and it is not a part of existing network, the command will return a response +similar to the following: + +{ + "result": 0, + "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'" +} + The network6-subnet-add command uses exactly the same syntax for +both the command and the response. + + + As opposed to parameter inheritance during full + new configuration processing or when adding a new shared network with + new subnets, this command does not fully handle + parameter inheritance and any missing parameters will be + filled with default values, rather than inherited from + global scope or from the shared network. +

+ network4-subnet-del, network6-subnet-del commands + + These commands are used to remove a subnet that is part of existing shared + network and demote it to a plain, stand-alone subnet. If you want to + remove a subnet completely, use subnet4-del or + subnet6-del commands instead. + The network4-subnet-del and + network6-subnet-del commands take two parameters: + id, which is an integer and specifies subnet-id of + existing subnet to be removed from a shared network; and + name, which specifies name of the shared network + the subnet will be removed from. + + An example invocation of the + network4-subnet-del command looks as follows: + + { + "command": "network4-subnet-del", + "arguments": { + "name": "floor13", + "id": 5 + } + } + Assuming there was a subnet with subnet-id equal to 5 that was part of a shared + network named 'floor13', the response would look similar to the following: + +{ + "result": 0, + "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'" +} +The network6-subnet-del command uses exactly the same syntax for +both the command and the response. + +

+ +

+ libdhcp_ha: High Availability + + This section will describe the libdhcp_ha hook library + being developed for the Kea 1.4.0 release. + +

+ +

+ + -

User contexts Hook libraries can have their own configuration parameters. That is convenient if the parameter applies to the whole library. However, @@@ -2736,4 -1966,4 +2732,4 @@@ - - ++ diff --cc doc/guide/install.xml index a3f8c33e97,aac13ba598..27236656cb --- a/doc/guide/install.xml +++ b/doc/guide/install.xml @@@ -1,13 -1,8 +1,16 @@@ - - - ]> ++ + - + + Installation -

Packages @@@ -112,11 -106,11 +114,11 @@@ on the system: - Boost build-time headers + Boost C++ Libraries - (). + (http://www.boost.org/). - At least Boost version 1.41 is required. - When header-only Boost error code is not available or wanted, the - Boost system library is required too. + The oldest Boost version used for testing is 1.57 (it may work with + older versions). Boost system library is required. Building boost + header only is no longer recommended. @@@ -194,9 -189,15 +196,14 @@@ Debian and Ubuntu + + Visit the user-contributed wiki at - http://kea.isc.org/wiki/SystemSpecificNotes ++ http://kea.isc.org/wiki/Install + for system-specific installation tips. + -

Installation from Source Kea is open source software written in C++. It is freely available in @@@ -264,10 -264,10 +270,10 @@@ are a developer planning to contribute to Kea, please fork our Github repository and use the "pull request" mechanism to request integration of your code. Please consult - for help on + https://help.github.com/articles/fork-a-repo/ for help on how to fork a Github repository. - The Kea - Developer's Guide contains more information about the process, as - The Kea ++ The Kea + Developer's Guide contains more information about the process, as well as describing the requirements for contributed code to be accepted by ISC. @@@ -439,22 -439,22 +445,22 @@@ 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 ++ ++

@@@ -474,11 -474,12 +480,11 @@@ JSON - JSON is the default configuration backend - JSON is the new default configuration backend -- that allows Kea to read JSON configuration files from -- disk. It does not require any framework and thus is - considered more lightweight. It allows dynamic on-line - considered more lightweight. It will allow dynamic - on-line reconfiguration, but lacks remote capabilities - (i.e. no RESTful API). ++ JSON is the default configuration backend ++ that allows Kea to read JSON configuration files from ++ disk. It does not require any framework and thus is ++ considered more lightweight. It allows dynamic on-line + reconfiguration using Kea API. @@@ -521,7 -522,7 +527,7 @@@ "configure" step (see ), the --with-dhcp-mysql switch should be specified: ./configure [other-options] --with-dhcp-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-dhcp-mysql=path-to-mysql_config @@@ -543,7 -544,7 +549,7 @@@ "configure" step (see ), the --with-dhcp-pgsql switch should be specified: ./configure [other-options] --with-dhcp-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-dhcp-pgsql=path-to-pg_config diff --cc doc/guide/intro.xml index b2e433b155,10461c0b74..b857c72845 --- a/doc/guide/intro.xml +++ b/doc/guide/intro.xml @@@ -1,12 -1,5 +1,18 @@@ - - - - %version; - ++ ++ ++ ++ ++%keaversion; +]> + - + Introduction Kea is the next generation of DHCP software developed by ISC. @@@ -22,7 -15,7 +28,7 @@@ - This guide covers Kea version &__VERSION__;. - This guide covers Kea version . ++ This guide covers Kea version &keaversion;.

@@@ -162,17 -156,9 +168,17 @@@ + + - kea-ctrl-agent — ++ kea-ctrl-agent â + Kea Control Agent (CA) is a daemon exposes a RESTful control + interface for managing Kea servers. + + + - perfdhcp — + perfdhcp â A DHCP benchmarking tool which simulates multiple clients to test both DHCPv4 and DHCPv6 server performance. diff --cc doc/guide/kea-guide.xml index 9baa8d13a6,a336cc3537..a8c02aaaf2 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@@ -1,23 -1,8 +1,23 @@@ - - - - %version; - ]> - ++ + + - ++ ++ ++%keaversion; ++]> ++ + + - + <inlinemediaobject> @@@ -28,12 -13,11 +28,11 @@@ Kea Administrator Reference Manual -- This is the reference guide for Kea version - &__VERSION__;. - . ++ This is the reference guide for Kea version &keaversion;. - 2010-2017Internet Systems Consortium, Inc. + 2010-2017 + Internet Systems Consortium, Inc. ("ISC") @@@ -45,91 -29,89 +44,92 @@@ - This is the reference guide for Kea version &__VERSION__;. - This is the reference guide for Kea version . ++ This is the reference guide for Kea version &keaversion;. The most up-to-date version of this document (in PDF, HTML, and plain text formats), along with other documents for - Kea, can be found at . + Kea, can be found at http://kea.isc.org/docs. - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - ++ Acknowledgments - Kea is primarily designed, developed, and maintained by - Internet Systems Consortium, Inc. It is an open source project - and contributions are welcomed. - - Support for the development of the DHCPv4, DHCPv6 and - DHCP-DDNS components was provided by - Comcast. + Kea is an open source project designed, developed, and maintained by Internet Systems + Consortium, Inc, a 501(c)3 non-profit organization. ISC is primarily funded by revenues from + support subscriptions for our open source and we encourage all professional users to consider + this option. To learn more, see âhttps://www.isc.org/support/. - Kea was initially implemented as a collection of applications - within the BIND 10 framework. Hence, Kea development would not be - possible without the generous support of past BIND 10 project sponsors. + If you would like to contribute to ISC to assist us in continuing to make quality open + source software, please visit our donations page at âhttp://www.isc.org/donate/. - - JPRS and - CIRA were Patron Level - BIND 10 sponsors. + We thank all the organizations and individuals who have helped to make Kea - possible. Comcast and the Comcast Innovation Fund provided major support for the development ++ possible. Comcast ++ and the Comcast Innovation Fund provided major support for the development + of Kea's DHCPv4, DHCPv6 and DDNS modules. Mozilla funded initial work on the REST API via a + MOSS award. - - AFNIC, + Kea was initially implemented as a collection of applications + within the BIND 10 framework. We thank the founding sponsors of the BIND10 project: - Afilias, - IIS.SE, - Nominet, and - SIDN; BIND10 patrons - JPRS and - CIRA; and additional sponsors - AFNIC, - CNNIC, - CZ.NIC, - DENIC eG, - Google, - RIPE NCC, - Registro.br, - .nz Registry Services, and - Technical Center of Internet. ++ Afilias, ++ IIS.SE, ++ Nominet, ++ SIDN, ++ JPRS, ++ CIRA; and additional sponsors ++ AFNIC, + CNNIC, + CZ.NIC, + DENIC eG, + Google, + RIPE NCC, + Registro.br, + .nz Registry Services, and + Technical Center of Internet - were past BIND 10 sponsors. - - Afilias, - IIS.SE, - Nominet, and - SIDN were founding - sponsors of the BIND 10 project. ++ . diff --cc doc/guide/keactrl.xml index 7e0aa4aa8d,76af644cd9..503372685a --- a/doc/guide/keactrl.xml +++ b/doc/guide/keactrl.xml @@@ -1,13 -1,8 +1,16 @@@ - - - ]> ++ + - + + Managing Kea with keactrl -

Overview keactrl is a shell script which controls the startup, shutdown and reconfiguration of the Kea servers (kea-dhcp4, diff --cc doc/guide/lease-expiration.xml index abca79b0f3,171c2d740f..4b7c5c8248 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@@ -1,9 -1,5 +1,13 @@@ - - - ]> - ++ ++ + + Lease Expiration in DHCPv4 and DHCPv6 The primary role of the DHCP server is to assign addresses and/or diff --cc doc/guide/lfc.xml index f6580e83fa,14dd477bf1..e689bde5aa --- a/doc/guide/lfc.xml +++ b/doc/guide/lfc.xml @@@ -1,13 -1,8 +1,16 @@@ - - - ]> ++ + - + + The LFC process -

Overview kea-lfc is a service process that removes redundant information from the files used to provide persistent storage diff --cc doc/guide/libdhcp.xml index 851c87469f,14441dae0b..9e192eeb29 --- a/doc/guide/libdhcp.xml +++ b/doc/guide/libdhcp.xml @@@ -1,10 -1,5 +1,13 @@@ - - - ]> ++ + - + + The libdhcp++ Library libdhcp++ is a library written in C++ that handles diff --cc doc/guide/logging.xml index 1806982a17,aed25ec42f..412b0f0c72 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@@ -1,22 -1,5 +1,13 @@@ - - - ]> - - - - ++ ++ + + Logging

diff --cc doc/guide/quickstart.xml index c632dd0dd2,9001bce995..07e09b2cfa --- a/doc/guide/quickstart.xml +++ b/doc/guide/quickstart.xml @@@ -1,12 -1,5 +1,22 @@@ - - - - %version; ++ ++ ++ ++ ++%keaversion; +]> + - + - ++ ++ ++ Quick Start @@@ -36,13 -28,13 +45,13 @@@ Extract the tarball. For example: - $ tar xvzf kea-&__VERSION__;.tar.gz - $ tar xvzf kea-.tar.gz ++ $ tar xvzf kea-&keaversion;.tar.gz Go into the source directory and run the configure script: - $ cd kea-&__VERSION__; - $ cd kea- ++ $ cd kea-&keaversion; $ ./configure [your extra parameters] diff --cc doc/guide/shell.xml index 1c470cada8,971489d00e..9396130a0f --- a/doc/guide/shell.xml +++ b/doc/guide/shell.xml @@@ -1,13 -1,8 +1,15 @@@ - - - ]> - - ++ + + The Kea Shell -

Overview Kea 1.2.0 introduced the Control Agent (CA, see ) that provides a RESTful control interface over HTTP. That API is typically expected to be used by diff --cc doc/guide/stats.xml index 17164c4df6,83fbc900ec..445cddf068 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@@ -1,10 -1,5 +1,12 @@@ - - - ]> - - ++ + + Statistics

diff --cc src/bin/admin/kea-admin.xml index edd15c865b,83e9177ddd..379014c920 --- a/src/bin/admin/kea-admin.xml +++ b/src/bin/admin/kea-admin.xml @@@ -1,21 -1,10 +1,18 @@@ - ]> + + - - + + + ISC Kea - Oct. 27, 2017 - 1.3.0 - - The Kea software has been written by a number of + Sep. 28, 2016 + 1.1.0 + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the diff --cc src/bin/agent/kea-ctrl-agent.xml index 267f2c345a,38926a99a0..cae562925d --- a/src/bin/agent/kea-ctrl-agent.xml +++ b/src/bin/agent/kea-ctrl-agent.xml @@@ -1,22 -1,11 +1,20 @@@ - ]> + + - + + - + ISC Kea - Sep. 28, 2016 - 1.1.0 - The Kea software has been written by a number of + Oct. 27, 2017 + 1.3.0 + + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the @@@ -217,8 -204,4 +213,4 @@@ - - ++ diff --cc src/bin/d2/kea-dhcp-ddns.xml index 04e88487b0,2cc67f1248..62fc109960 --- a/src/bin/d2/kea-dhcp-ddns.xml +++ b/src/bin/d2/kea-dhcp-ddns.xml @@@ -1,22 -1,11 +1,19 @@@ - ]> + + + - - - + ISC Kea - Sep. 28, 2016 - 1.1.0 - The Kea software has been written by a number of + Oct. 27, 2017 + 1.3.0 + + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the @@@ -219,8 -206,4 +214,4 @@@ - - ++ diff --cc src/bin/dhcp4/kea-dhcp4.xml index e2a3531e12,4860ec6004..73ef11ea77 --- a/src/bin/dhcp4/kea-dhcp4.xml +++ b/src/bin/dhcp4/kea-dhcp4.xml @@@ -1,22 -1,11 +1,19 @@@ - ]> + + + - - - + ISC Kea - Sep. 28, 2016 - 1.1.0 - The Kea software has been written by a number of + Oct. 27, 2017 + 1.3.0 + + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the @@@ -224,8 -211,4 +219,4 @@@ - - ++ diff --cc src/bin/dhcp6/kea-dhcp6.xml index 27b81377d0,cf175a10f3..4291cbbbc1 --- a/src/bin/dhcp6/kea-dhcp6.xml +++ b/src/bin/dhcp6/kea-dhcp6.xml @@@ -1,22 -1,11 +1,18 @@@ - ]> - + + - - - + ISC Kea - Sep. 28, 2016 - 1.1.0 - The Kea software has been written by a number of + Oct. 27, 2017 + 1.3.0 + + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the @@@ -225,8 -212,4 +219,4 @@@ - - ++ diff --cc src/bin/keactrl/keactrl.xml index 5937dfb79e,227d5adaa6..6b19be5b87 --- a/src/bin/keactrl/keactrl.xml +++ b/src/bin/keactrl/keactrl.xml @@@ -1,21 -1,10 +1,19 @@@ - ]> - + + - - + + ISC Kea - Sep. 28, 2016 - 1.1.0 - The Kea software has been written by a number of + Oct. 27, 2017 + 1.3.0 + ++ + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the diff --cc src/bin/lfc/kea-lfc.xml index 02e2843c70,fa1d916831..3aa3cff9de --- a/src/bin/lfc/kea-lfc.xml +++ b/src/bin/lfc/kea-lfc.xml @@@ -1,22 -1,11 +1,19 @@@ - ]> + + - + + - + ISC Kea - Sep. 28, 2016 - 1.1.0 + Oct. 27, 2017 + 1.3.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the @@@ -283,8 -270,4 +278,4 @@@ - - ++ diff --cc src/bin/perfdhcp/perfdhcp.xml index 568a4cdb09,6f0a0d792c..585be89944 --- a/src/bin/perfdhcp/perfdhcp.xml +++ b/src/bin/perfdhcp/perfdhcp.xml @@@ -1,22 -1,11 +1,20 @@@ - ]> - + + - + - + ISC Kea - Sep. 28, 2016 - 1.1.0 - The Kea software has been written by a number of + Oct. 27, 2017 + 1.3.0 + ++ + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the diff --cc src/bin/shell/kea-shell.xml index 101e6d3a50,598012f9c4..24e8d0f0f1 --- a/src/bin/shell/kea-shell.xml +++ b/src/bin/shell/kea-shell.xml @@@ -1,22 -1,11 +1,19 @@@ - ]> - + + - + - + ISC Kea - 0008-03-2017 - 1.2.0 - The Kea software has been written by a number of + Oct. 28, 2017 + 1.3.0 + + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the @@@ -46,16 -33,15 +41,16 @@@ - + kea-shell - - - - - - - - + + + + ++ + + + @@@ -240,8 -217,4 +235,4 @@@ - - ++ diff --cc src/bin/sockcreator/kea-sockcreator.xml index 53dc13f39d,0b1c9a81f8..591cd46761 --- a/src/bin/sockcreator/kea-sockcreator.xml +++ b/src/bin/sockcreator/kea-sockcreator.xml @@@ -1,32 -1,10 +1,33 @@@ - ]> - + + - + + + ISC Kea + Oct. 27, 2017 + 1.3.0 + + The Kea software has been written by a number of + engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin + Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, + Wlodek Wencel and Shawn Routhier. That list is roughly in the + chronological order in which the authors made their first + contribution. For a complete list of authors and + contributors, see AUTHORS file. + Internet Systems Consortium, Inc. + + + + + 2014-07-01 + + kea-sockcreator 8 @@@ -88,8 -66,4 +89,4 @@@ - - ++