wiki:Commands

Version 5 (modified by tomek, 4 years ago) (diff)

--

Control API Requirements

Kea provides a control channel that allows external entity send administrative commands to the server. This document explains rationale that led to certain decisions and enumerates desired capabilities.

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 (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.

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.4. Kea MUST support reload-config (Kea reloads its current configuration file from disk, already supported in 1.0).
  • A.3. Kea MUST support get-config (Kea sends back its current configuration in the response).
  • A.5. Kea MUST support set-config (sends new configuration as parameter).

Run-time operations

  1. Kea MUST support (TODO: list all statistics related commands here).

Configuration management

Leases management

  1. Kea MUST support add-lease4 command.
  2. Kea MUST support add-lease6 command.
  3. Kea MUST support get-lease4 command. Available parameters:
    • (v4 address), (hwaddr, subnet-id), (client-id, subnet-id)
  4. Kea MUST support get-lease6 command. Available parameters:
    • (v6 address), (duid, subnet-id)
  5. Kea MUST support update-lease4 command.
  6. Kea MUST support update-lease6 command.
  7. Kea MUST support delete-lease4 command.
  8. Kea MUST support delete-lease6 command.

Reservations management

  1. Kea MUST support add-reservation command that includes IPv4 reservation.
  2. Kea MUST support add-reservation command that includes IPv6 reservation.
  3. Kea MUST support add-reservation command that makes reservation for a hostname.
  4. Kea MUST support add-reservation command that makes reservation based on hardware address.
  5. Kea MUST support add-reservation command that makes reservation based on DUID.
  6. Kea SHOULD support add-reservation command that makes reservation based on remote-id.
  7. Kea SHOULD support add-reservation command that makes reservation based on subscriber-id.
  8. Kea MAY support add-reservation command that makes reservation based on client-id.
  9. Kea SHOULD support add-reservation command that reserves certain v4 options for a client.
  10. Kea SHOULD support add-reservation command that reserves certain v6 options for a client.
  1. get-reservation by IPv4 address
  2. get-reservation by IPv6 address
  3. get-reservation by hwaddress, subnet-id
  4. get-reservation by duid, subnet-id
  5. update-reservation
  6. delete-reservation by IPv4 address
  7. delete-reservation by IPv6 address
  8. MAY delete-reservation by hwaddress, subnet-id
  9. MAY delete-reservation by DUID, subnet-id

Subnets management

  1. MUST support get-subnet4-count
  2. MUST support get-subnet6-count
  3. MUST support get-subnet4 (by subnet-id), (by index)
  4. MUST support get-subnet6 (by subnet-id), (by index)
  5. MUST support update-subnet4
  6. MUST support update-subnet6
  7. MUST support add-subnet4
  8. MUST support add-subnet6
  9. MUST support delete-subnet4
  10. MUST support delete-subnet6

TODO: Hmmm, how do we want to refer to specific pools. We currently don't have any indexes.

  1. MUST support get-pools4-count (returns a number of subnets in a given v4 subnet)
  2. MUST support get-pools6-count (returns a number of subnets in a given v4 subnet)
  3. MUST support add-pool4
  4. MUST support add-pool6
  5. MUST support get-pool4
  6. MUST support get-pool6
  7. MUST support delete-pool4
  8. MUST support delete-pool6

Options management

Need API calls to manage assigned global and per subnet options.

Classification management

Do we need API calls to manage client classification?

Interfaces management

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

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