wiki:Commands

Version 22 (modified by tomek, 3 years ago) (diff)

--

Control API Requirements

Kea provides a control channel that allows external entity send administrative commands to the server. This document is a requirements document. It describes what the implementation is expected to provide. Once the discussion on it is settled, an additional document will lay out the design and will provide more technical details. That design will be expected to meet the requirements laid out this in this document.

There are multiple ways how certain things can be achieved. The text below often explains the rationale that led to certain decisions.

WARNING: This document is a work in progress. Expect significant changes. Once this document is more mature, it will be discussed on kea-dev list.

At the time of writing this document (May 2016, i.e. post Kea 1.0, before Kea 1.1 release) several commands listed here are already supported. They're listed here in an effort to provide a complete overview of the desired capability of the Control API.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (https://tools.ietf.org/html/rfc2119).

The key words can also be used to roughly estimate priority for a given feature: MUST is P1 priority (i.e. it's mandatory part and the feature is considered dysfunctional without it), SHOULD being P2 (less important than MUST, but still much desired) and MAY being P3 (this is really an optional thing. Assuming infinite time we would implement all MAYs, but the reality makes it somewhat unlikely).

Administrative actions

  • A.1. Kea MUST support shutdown command (already supported since 0.9.2).

Supporting large command parameters and and responses is required for a number of scenarios: getting all leases from a subnet, getting statistics for multiple subnets when # of subnets is large etc. (This was never tested, it may work for commands bigger than 1500, but we do have a static buffer somewhere. Once the command parameters are larger than this buffer, we'll truncate the command first and then will reject it as malformed. We need to improve the code).

  • A.2. Control channel MUST support accepting commands and sending responses bigger than 1500 bytes.

Kea 1.0 already supports reload-config. It remembers the path to the config file used during start and can reload it if needed. This is sufficient in simple cases of a local config file that was edited. However, there are other scenarios that it does not address. In particular, there is no way to specify that the file location has changed. There are customers who built IPAM systems around ISC DHCP and they generate temporary config files, then restart isc dhcpd. Once dhcpd is restarted, that temporary file is removed. It seems logical to presume that similar model will be used with Kea.

  • A.3. Kea MUST support reload-config (Kea reloads its current configuration file from disk, already supported in 1.0).

This functionality is already supported in Kea 1.0, albeit not in its fully featured form. Current code simply allows to reload the same file, without providing an ability to change its location. Changing location is especially important for cases when Kea is integrated into IPAM or similar system: The system around Kea may generate a temporary config file, let Kea reload it and then the file is deleted.

  • A.4. Kea MUST support get-config (Kea sends back its current configuration in the response).

With the advance of Control API the ability to modify its configuration during run-time a new problem will emerge: how to ensure persistence of the configuration changes. It was suggested that perhaps Kea could try to overwrite its configuration file. This approach has several issues. First, we would have to ensure that whatever rewrite Kea does would not overwrite any existing information, including comments. Current Kea parser simply ignores comments. Kea code would have to remember it and then insert them back into the written file. This is more complex than it sounds as there are many commenting styles. People write their comments immediately before the clause, they may put sections in their config, add some comments for specific entries etc. Understanding which comment applies to which JSON entry is a difficult task. Have we chose to retain comments and write whole configuration, there would be cases of oddly misplaced comments.

Second argument against the approach of Kea rewriting its own configuration file is limiting use cases. There are deployments where the config file is stored on read-only filesystem (e.g. OpenWRT or systems where only /tmp and /var is writeable). It would also make difficult for IPAM-like systems built around Kea. We know of several systems developed around ISC DHCP. One of them keeps the configuration internally in XML. When configuration changes, this XML is processed to generate isc dhcpd's config written to a temporary file, the server is restarted and the temporary file removed. Rewriting this long deleted file would be meaningless.

Last, but not least the argument is about desired persistence of the changes. Users could experiment with their configuration and not necessarily keep the changes if they don't like the outcome. Therefore the "rewrite your own config" approach would require adding "bool persist" parameters to all configuration modification calls and then keep them internall in configuration manager. Furthermore, the configuration could possibly be internally inconsistent, e.g. sane with non-persistent elements, but insane without them. This would be an evergrowing complexity without good solutions in sight.

Therefore the proposal is to provide get-config method that would return current running configuration. It is up to the caller to do something with the response, e.g. store it externally, review it or write it to configuration file, possibly overwrite existing config if the user so desires. Also, it gives the best flexibility in the sense of discarding changes that are deemed not desired. The user would simply not call get-config, restart Kea and it would revert to its previous configuration.

  • A.5. Kea MUST support set-config (sysadmin specifies new configuration as parameter).

Currently we assume that Kea loads its configuration file from local file system. This will certainly remain the default behavior, but with simple modification we could add optional, additional source of configuration. The JSON configuration would be sent over command channel. One specific envisaged use case for this is the ability to boot many DHCP servers in data centers or large networks. There would be a VM image with just bare bones configuration covering logging destination and pointers to the database. Then once the VM is booted the actual configuration is deployed using set-config command.

Another envisaged use case for this call is the ability to push configuration. This could be useful in several scenarios. In large networks new configuration could be pushed to multiple servers at the same time. Another scenario would be to overwrite existing configuration without needing to restart the server.

Configuration management

Identifier types

There are several calls proposed below that refer to identifier-type and identifier, especially in leases and host reservations contexts. In a very simplified approach, the DHCPv4 client can be identified by its hardware/MAC address and DHCPv6 client can be identified by its client-id (which is a DUID). However, modern networks are often more complicated and so are the ways clients are identified. DHCPv4 clients may send client-id options, ISPs may not know the MAC addresses, but know the ports over which the clients will be connecting etc. The number of such identifiers that are used to identify a client are growing over time. Therefore Kea is currently being refactored to allow easy addition of extra identifiers in the future.

Kea 1.0 allowed the following identifier types: hardware/MAC addresses for DHCPv4 and DUID for DHCPv6. Kea 1.1 is expected to allow the following identifier types: hardware/MAC addresses, client-id (client-id option in DHCPv4), DUID (client-id option formatted according to RFC4361 in DHCPv4, client-id option in DHCPv6), remote-id (remote-id suboption inserted in option 82 by a DHCPv4 relay agent or remote-id option (37) inserted by a DHCPv6 relay agent) or circuit-id (circuit-id suboption inserted in option 82 by a DHCPv4 relay agent).

Additional identifier types are likely to be implemented in the future.

Leases management

After DHCP server assigns an address (or address or prefix in case of DHCPv6) it records the fact of the address being assigned to given client as a lease. This is the most important run-time piece of information for every DHCP server. The lease information tends to be updated frequently as most communications with any client causes lease state to change. Therefore this is the most dynamic data in the DHCP world.

The API must allow management of the leases. It should allow full CRUD methodology (Create, Retrieve, Update, Delete). Those changes MUST be applicable during run-time and MUST NOT require Kea to be restarted.

  • L.1. Kea MUST support add-lease4 command.
  • L.2. Kea MUST support add-lease6 command.

Kea is able to store leases in memfile (which is in-memory database that writes changes to a CSV file), MySQL, PostgreSQL. There's work in progress to also store leases in Cassandra nosql database. While it is possible to insert leases into the databases in some backends (MySQL and Postgres), this direct insertion approach has several flaws. In particular, it does not offer any sanity checks. The very basic checks (that the address is unique) are enforced by the database schema, but the more subtle are not. Three specific examples of such checks would be adding a lease for host A when the address is reserved for host B, adding a lease with invalid subnet ID and adding a lease for subnet X with an address Y where address Y does not belong to the subnet X. Another reason why using an API is better, because it behaves in the same way for every backend, so any solutions built around Kea could be migrated to a different backend if such a need arises.

  • L.3. Kea MUST support get-lease4 command that takes IPv4 address as a parameter.
  • L.4. Kea MUST support get-lease4 command that takes (identifier-type, identifier, subnet-id) as parameters.
  • L.5. Kea MUST support get-lease6 command that takes IPv6 address as a parameter.
  • L.6. Kea MUST support get-lease6 command that takes (identifier-type, identifier, subnet-id) as parameters.

identifier-type is hwaddr (hardware/MAC address of the client), client-id (content of the client-identifier option in DHCPv4), DUID (content of the client-identifier option in DHCPv6), remote-id (content of the remote-id sub-option inserted in option 82 by a relay agent), circuit-id (content of the circuit-id sub-option inserted in option 82 by a relay agent). More identifier types may be defined in the future.

Those two calls will be used to retrieve IPv4 or IPv6 lease information. For each call one of available two sets of parameters may be specified: either IP address or a tuple of (identifier-type, identifier, subnet-id). The first call type is pretty obvious. We know an IP address and want to check whether there's a lease for it. The second call type is somewhat more complex. Kea 1.0 supports MAC addresses in IPv4 leases and DUIDs in IPv6 leases. Kea 1.1 will support several identifier types, in particular we're working on adding support for client-id, remote-id and circuit-id options. It is envisaged that more identifier types may be added in the future. Therefore we chose the identifier-type + identifier approach, rather than provide specific calls for get-lease-by-hwaddr, get-lease-by-client-id etc. as the number of such calls would grow over time.

Q: Do we want to have a single query (e.g. get-lease4) with multiple parameter sets or do we want separate queries (get-lease4-by-ip-addr, get-lease4-by-identifier).

Q: Do we want to support multi-tenancy (i.e. having multiple hot spots, each with the same private IP address space)? If that is so, then (IP address only) parameter set must be extended with (IP address, subnet-id). The benefit would be to allow new deployment scenarios, but the downside would be to make usage more complicated (i.e. caller may simply don't know the subnet-id).

  • L.7. Kea MUST support update-lease4 command.
  • L.8. Kea MUST support update-lease6 command.

Those two calls allow updating all parameters of v4 or v6 lease. It is assumed that all parameters can change, except the IP address. Code processing this call MUST ensure that the data is consistent, e.g. verify that subnet-id are sane, that IP address range matches the subnet it belongs to, that hostname has valid format etc. For the call to succeed the lease for specified IP address must exist.

  • L.9. Kea MUST support delete-lease4 command.
  • L.10. Kea MUST support delete-lease6 command.

Those two call attempt to remove IPv4 and IPv6 leases. There will be only one mandatory parameter specified: IP address of the lease to be removed. There will be one optional parameter called mode. It will accept one of two values: remove (which simply remove the lease from the database), release (treat it as if Release packet was received. In particular, this would trigger additional steps, like cleaning up DNS entries if necessary). The default would be 'remove'.

Q: Do we want a way to delete all leases in a subnet? This could be useful when retiring/disconnecting the whole subnet.

Q: Do we want to delete all leases that belong to certain identifier? This could be useful for mobile clients that are not welcome in the network anymore (e.g. mobile device being retired, or subscriber terminated its contract).

Note: There are currently no plans to implement calls that retrieve multiple leases, e.g. all leases in a subnet. The reason why such an API was not designed is the stress on the API code. With subnets having potentially millions of leases, a call requesting all of them formatted as JSON structures would be a significant burden (potentially exploitable as a denial of service attack) to the server. We may revisit this if people come up with actual use cases for this.

Host Reservations (HR) management

Kea allows host reservations. HR is a mechanism that allows reserving a specific IPv4 address, IPv6 address, IPv6 prefix, specific hostname or set of options is reserved to a given client. Depending on the deployment there may be no host reservations at all (all leases assigned dynamically), there may be some reservations (mixed model, where most clients are assigned dynamically, but there is a subset of clients that have reserved parameters) up to fully static model (dynamic allocation is effectively disabled, all clients are known and have static reservations).

Currently (Kea 1.0) Kea allows storing host reservations in the configuration file and there's work in progress to allow storing HR in MySQL and PostgreSQL. Ultimately, the plan is to store this information in backends (for most backends except memfile). When the number of reservations is small and they are not updated frequently, it makes sense to store them in configuration file. However, with the number of HR getting large or being updated more frequently, it is increasingly compelling to store them in the database. The following calls provide ability to manipulate the HR information.

Note: for backends that provide ability to store HR (currently MySQL only, but this capability for PostgreSQL is planned for 1.1. There are also discussions about developing such capability for Cassandra in the upcoming releases, but no firm decisions have been made yet).

  • H.1. Kea MUST support add-reservation command that adds a reservation.
  • H.2. The add-reservation command MUST allow reserving an IPv4 address.
  • H.3. The add-reservation command MUST allow reserving at least one IPv6 address.
  • H.4. The add-reservation command MUST allow reserving at least one IPv6 prefix.
  • H.5. The add-reservation command MUST allow specifying a hostname.
  • H.6. The add-reservation command MUST allow specifying IPv4 options that will be sent for the host.
  • H.7. The add-reservation command MUST allow specifying IPv6 options that will be sent for that host.
  • H.8. The add-reservation command MUST allow reservations by hardware (MAC) address.
  • H.9. The add-reservation command MUST allow reservations by DUID.
  • H.10. The add-reservation command SHOULD allow reservations by client-id.
  • H.11. The add-reservation command MAY allow reservations by circuit-id.
  • H.12. The add-reservation command MAY allow reservations by remote-id.

This call will add a new reservation for a host. It will be possible to specify IPv4 address, IPv6 addresses (typically one, but eventually it will be possible to specify more), IPv6 prefixes (typically one, but eventually it will be possible to specify more), hostname, per host specific options, subnet-id (separate for IPv4 and IPv6 subnets) and an identifier. The identifier will be specified as (identifier-type, identifier) pair. The details are TBD, but it seems very likely that the initial implementation will allow specifying the following identifier types: hwaddr (hardware/MAC address), client-id (client-identifier option in DHCPv4), DUID (client-id option in DHCPv6), remote-id (remote-id sub-option in option 82), circuit-id (circuit-id sub-option in option 82). Additional identifier types are likely to be defined in the future.

Add-reservation call will ensure integrity of the data. In particular, it will refuse any data that fails sanity checks: IP address is already reserved to a different host, this identifier has already different reservation in this subnet, the IP address does not belong to the subnet represented by subnet-id parameter.

For backends that do not support storing reservations, this will create a memory entry in Host Manager. This will be lost upon shutdown or restart. To avoid loss of this information use get-config call before shutdown.

  • H.13. Kea MUST support get-reservation by IPv4 address command.
  • H.14. Kea MUST support get-reservation by IPv6 address command.
  • H.15. Kea MUST support get-reservation by IPv6 prefix command.
  • H.16. Kea SHOULD support get-reservation by (identifier-type, identifier, subnet-id).

An ability to retrieve existing reservations is useful for two broad ranges of scenarios. First is to check whether there is a reservation for given address or client. Second is to check the details of said reservation. Kea stores IPv4 and IPv6 reservations together in the same table to allow centralized point of authority for dual stack devices. It also makes managing the configuration to be consistent between IPv4 and IPv6 stacks easier.

There will be two ways to use get-reservation call. The first one is to specify an IP address. The second one it specify an identifier-type, identifier and a subnet in which the search should be conducted. See "Identifier types" Section above for details about identifier-type, identifier tuple.

  • H.17. Kea MUST support update-reservation command that modifies existing reservation.

This call will update existing host reservation. This call will have two groups of parameters. The first group will be used to select the reservation. It will have Identifier-type, identifier and subnet-id parameters specified (there will be a way to specify if the subnet-id is v4 or v6). Once the appropriate reservation is selected, it will be updated. The parameters for this are to be specified in the second group of parameters. This will include all parameters allowed in add-reservation call.

The implementation of this call will internally be split into two logical phases. The first is an attempt to retrieve the host, which is functionally equivalent to get-reservation(identifier-type, identifier, subnet-id) call. The second step is to update specified parameters.

For backends that do not support storing reservations, this will create a memory entry in Host Manager. This will be lost upon shutdown or restart. To avoid loss of this information use get-config call before shutdown.

Q: For IPv6 there may be multiple IPv6 addresses and/or prefixes reserved. There is no easy way to identify them. Do we want to define calls like add-ipv6-reservation, delete-ipv6-reservation that would add or delete a single entry for single IPv6 address or prefix, but keep the whole host reservation in place?

  • H.18. Kea MUST support delete-reservation by IPv4 address command.
  • H.19. Kea MUST support delete-reservation by IPv6 address command.

Those two calls will attempt to remove a reservation. It is recommended to understand how Kea works before deleting reservation for an active host. Once a request comes from a client that has matching HR, Kea will create a lease entry (or even multiple leases if the host has IPv4+IPv6 or multiple IPv6 addresses reserved). Removing the host reservation will not remove the leases, unless delete-leases parameter is specified.

It is not advisable to remove the lease, as it could have adverse consequences. In particular, after removing a lease for active client, the client will not immediately know that his lease was revoked and will continue using it until next renewal, which may be days in advance. The server, however, would consider the address unused and available for allocation and could assign it to a different client. This would cause two clients to attempt to use the same address, which would cause Decline procedures.

For backends that do not support storing reservations, this will create a memory entry in Host Manager. This will be lost upon shutdown or restart. To avoid loss of this information use get-config call before shutdown and make sure it is store somewhere before shutting down the server.

Q: Do we want to specify delete-reservation with (identifier-type, identifier, subnet-id)?

Subnets management

Existing (Kea 1.0) and upcoming (Kea 1.1) supports storing subnet information in the configuration file only. However, it was reported by several large scale existing and prospective users that their deployments use thousands of subnets. At this scale it makes sense to consider allowing storage of subnet information in the database. Subnet information is considered to be less frequently changing than host reservations and much less than lease information.

It should be noted that such a capabilty will always be in addition to config file. The ability to define configuration in a config file and don't need to run a database at all is and will remain to be supported.

Since IPv4 and IPv6 topologies may be different and the per subnet parameters are different in those protocols, Kea stores IPv4 and IPv6 subnets separately. Therefore there will be separate calls for IPv4 and IPv6 subnets.

  • S.1. Kea MUST support get-subnet4-count command.
  • S.2. Kea MUST support get-subnet6-count command.

Kea uses subnet-id parameter (an integer) to identify subnets. The only requirement for those identifier is that they must be unique for each family. In particular, they don't have to be consecutive, start from 1 or have increasing values. There is a very good reason for that. Imagine a case where there are 3 subnets with subnet-ids 1, 2 and 3. Now the topology has changed and subnet 2 was removed. The subnet ids are 1,3. That removed subnet then replaced by two subnets with ids 2 and 10 and added to the configuration. The subnet ids for configured subnets are 1,3,2,10. This simple example shows that we can't make any assumptions against the subnet-id. In particular the assumption that the biggest subnet-id equals to the number of subnets is false. Also, the assumption that we can get the subnet by querying subnet-ids in increasing (1,2,3,4,5,6...) order would return all subnets is false.

Therefore it's necessary to introduce the ability to query for the number of subnets. It will be then possible to query for a specific subnet, using the range 0...[index - 1], where index is the value returned by get-subnet4-count or get-subnet6-count.

If the user knows subnet-id values, this call can be skipped altogether.

  • S.3. MUST support get-subnet4 (by subnet-id) command.
  • S.4. MUST support get-subnet6 (by subnet-id) command.
  • S.5. MUST support get-subnet4 (by index) command.
  • S.6. MUST support get-subnet6 (by index) command.

The get-subnetX calls return subnet information, including subnet range and prefix (e.g. 192.0.2.0/24), subnet-id. Additional parameters (e.g. configured relay information, configured host reservation mode, configured T1, T2, preferred lifetime, valid lifetime, allowed client classes and subnet specific options) may also be returned. The exact scope of informations returned will be decided during design phase. This call will return all pools configured in the subnet.

  • S.7. Kea MUST support update-subnet4 command.
  • S.8. Kea MUST support update-subnet6 command.

Those two calls allow making changes to existing subnet: changing prefix, prefix length, T1, T2, preferred lifetime, valid lifetime timers, allowed client classes, subnet specific options and subnet-id values. It also allows modifying pools.

Sanity checks will be conducted to verify that the specified input parameters are sane.

Note: the typical workflow envisaged is to call get-subnetX first, tweak the response and send it back as parameters for update-subnetX. This approach allows adding, updating and removing pools. For example, if there are three existing pools and sysadmin wants to add fourth one, in the update-subnet4 call he should include all four (existing 3 and 1 new) pools.

Note: for backends that do not support storing subnet information (as of upcoming Kea 1.1 none of the backends will be able to store this information. There is a debate whether database storage for subnet information will be available in Kea 1.2), the update will only modify in-memory representation of the database. This will be lost upon shutdown or restart. To avoid loss of this information use get-config call before shutdown and store its response.

Note: Care should be taken when modifying a subnet or its pools to not abandon any leases. If the updated subnet or pool definition has smaller scope than before modification, it's possible to have leases that are outside of the current definitions.

TBD: What to do about it? There are several options:

  1. we could forcibly remove leases that are not in the subnet anymore. This has the advantage of having lease information consistent with the configuration. However, it means that after subnet reconfiguration there will be clients believing to have a lease, but the server would think the address is not used. This should be ok in most cases, as those addresses are out of subnet now, so the server wouldn't assign them to anyone else. However, in rare cases where existing subnet is split into two smaller ones, this logic could fail and thne the same address could be assigned twice.
  1. we could keep the leases and implement a check in allocation engine. Before very time an address is sent to the client, we could check if it belongs to a subnet it's claimed to be in (match by subnet-id) and that the address belongs in current definition of pools. This would mostly work, except the cases of having host reservations that use out-of-pool reservations. Also, adding extra checks in the assignment/renewal case would have some small performance implications.
  1. we could keep the leases as they are and do nothing. It would mean that after shrinking the subnet or pool, clients would remain using the address they got. It's the safest approach from the safety perspective, but it would mean a long tail of addresses being still in use after configuration has changed.
  1. we could add a parameter that would choose the behavior between 1,2 and 3.
  • S.9. Kea MUST support add-subnet4 command.
  • S.10. Kea MUST support add-subnet6 command.

Those two calls add new subnets. They will allow specifying all the subnet parameters as if the subnet definition were in a config file. Sanity checks will be conducted to verify that the specified input parameters are sane.

Note: for backends that do not support storing subnet information (as of upcoming Kea 1.1 none of the backends will be able to store this information. There is a debate whether database storage for subnet information will be available in Kea 1.2), the update will only modify in-memory representation of the database. This will be lost upon shutdown or restart. To avoid loss of this information use get-config call before shutdown and store its response.

  • S.11. Kea MUST support delete-subnet4 command.
  • S.12. Kea MUST support delete-subnet6 command.

Those two calls attempt to delete existing subnet definition. Removing existing subnet should be taken with care. If there are active devices in the subnet being removed from configuration, unexpected behaviors may observed.

Q: How do we want the subnet removal procedure to work? There are several possible options:

  1. Do gradual subnet retirement. First step would be to mark the subnet for removal. This means that no new address would assigned and existing leases would not be extended. Once all leases are released or expired, we could remove the subnet. This seems to be the cleanest way to remove a subnet. However, it takes time and in some cases it would be annoying to wait.
  1. Simply delete the subnet structure. The leases will be there, but during renewal, the server will not be able to pick them up because of subnet selection failing and a new lease will be assigned. After valid-lifetime all leases will be expired. This could potentially get messed up if a subnet is deleted and then a new subnet with the same subnet-id is added.

Options management

Kea allows specifying options in several scopes: global (all clients will get them), subnet (all clients connected to a given subnet will get them) and host (only a given host will get them). Kea allows option definitions on a global level. See Sections 7.2.9 of [[Kea User's Guide | http://git.kea.isc.org/~tester/kea/guide/kea-guide.html#dhcp4-std-options] for examples of option definitions and option data.

Option definitions allow defining standard options, custom options, vendor space options and nested options. See Sections 7.2.8, 7.2.9, 7.2.10 and 7.2.11.

  • O.1. Kea MUST support add-option4-def command that adds DHCPv4 option definition.
  • O.2. Kea MUST support add-option6-def command that adds DHCPv6 option definition.
  • O.3. Kea MUST support set-option4-def command that sets all DHCPv4 option definitions.
  • O.4. Kea MUST support set-option6-def command that sets all DHCPv6 option definitions.
  • O.5. Kea MUST support get-option4-def command that returns all DHCPv4 option definitions.
  • O.6. Kea MUST support get-option6-def command that returns all DHCPv6 option definitions.
  • O.7. Kea MUST support del-option4-def command that deletes a DHCPv4 option definition.
  • O.8. Kea MUST support del-option6-def command that deletes a DHCPv6 option definition.

add-optionX-def calls add one or more new option definitions. New options will be added to existing ones. Sanity check is done on input data. In particular, it is checked whether the option is internally consistent and do not conflict with existing standard or custom options (e.g. by attempting to define an option that is already defined).

set-optionX-def calls set all option definitiones. New options will replace whatever old definitions may have been there. Sanity check is done on input data. It is checked whether the new options are internally consistent (i.e. there are no options with duplicate names or duplicate codes). Also, since subnets may contain definitions of options, all of existing subnets are checked whether they are covered by new option definitions.

get-optionX-def calls return set of all option definitions.

del-optionX-def calls have 3 parameters: option-name, option-code and option-space. Only one of option-name or option-code is required, so the option being deleted can be referred either by name or by code. If option-space is not specified, it is assumed to be "dhcp4" for del-option4-def and "dhcp6" for del-option6-def.

  • O.9. Kea MUST support add-option4 command that adds value of DHCPv4 option.
  • O.10. Kea MUST support add-option6 command that adds value of DHCPv6 option.

Those two calls add new DHCPv4 or DHCPv6 option values. It is expected that only options that have definitions can be specified. This requires either the option to be standard or have custom definiton. See Table 7.1 in Section 7.2.8 and Table 8.1 in Section 8.2.8 of the Kea User's Guide for a list of currently defined standard options. This call would generally expect parameters as specified in Section 8.2.8, i.e. one of option-name or option-code being mandatory, option-space being optional with the default option space being "dhcp4" or "dhcp6" depending on which call was called, csv-format to be true. Option-data is mandatory for options that have any fields (most options have, except empty and container options).

Classification management

TODO: Do we need API calls to manage client classification?

Interfaces management

TODO: We will most likely need an API to manage interfaces (which interfaces to listen on and which addresses to bind).

Run-time operations

TODO: list all statistics related commands here.

Open questions

Q: What to do with the leases when removing pools/subnets? Available options:

  1. Keep them in the DB (useful when removal is temporary)
  2. Keep them, but don't allow the server to renew (that would keep the subnet/leases, but they would expire naturally)
  3. delete them instantly
  4. initiate reconfigure process and delete the leases/subnet afterwards