|
|
## Kea Commands
|
|
|
## Kea Commands
|
|
|
|
|
|
Kea provides a REST API (JSON structures sent via http) and a control channel (JSON structures sent via Unix domain socket) that allows an external entity to send administrative commands to the server. This is a requirements document that describes what the implementation is expected to provide. Many of the commands listed here are already implemented. See below for color coding.
|
|
|
|
|
|
**WARNING:** This is a living document that is expected to evolve over multiple Kea releases. As a result, the requirements numbering may not be continuous, as obsolete requirements may be removed or new ones may be defined.
|
|
|
|
|
|
For easier understanding of what is and what is not supported, the commands are color coded. (We apologize for the inelegant color coding; if you can make it work correctly, we invite you to fix it.) The meaning is as follows:
|
|
|
For easier understanding of what is and what is not supported, the commands are color coded. (We apologize for the inelegant color coding; if you can make it work correctly, we invite you to fix it.) The meaning is as follows:
|
|
|
|
|
|
- `#39e21f`Green is currently supported by either released or development version;
|
|
|
- `#1221cc`Blue is implemented and is part of the add-ons ISC is offering. Getting access to those extensions involves money. See https://isc.org/kea for details;
|
... | ... | @@ -21,8 +21,8 @@ Each requirement has an X.Y designation, which can be used for reference. |
|
|
|
|
|
The key words can also be used to roughly estimate priority for a given feature: MUST is P1 priority (i.e. it's a 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).
|
|
|
|
|
|
|
|
|
### 1. Administrative actions
|
|
|
|
|
|
### 1. Administrative actions
|
|
|
|
|
|
- A.1. Kea MUST support the `#39e21f` ```shutdown``` command. (supported since 0.9.2)
|
|
|
|
... | ... | @@ -30,13 +30,13 @@ It must be possible to terminate Kea programmatically. Since Kea is the process |
|
|
|
|
|
- A.2. Control channel MUST support incoming commands and sending responses of any size (larger than 64K bytes).
|
|
|
|
|
|
Supporting large command parameters 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.
|
|
|
Supporting large command parameters 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.
|
|
|
|
|
|
Since some existing and prospective deployments talk about having over 10k subnets and 2M devices, it seems natural that some of the commands (e.g. ```subnetX-list```) will generate large responses. Also, ```config-set``` and ```config-get``` commands will operate on the whole configuration, which can clearly be larger than 1500 bytes. With Kea 1.1 and 1.2 we tried to limit the maximum size to 64K, but that restriction is going to be removed in Kea 1.3.
|
|
|
|
|
|
- A.3. Kea MUST support `#39e21f` ```config-reload``` to reload configuration from a file. (supported since 1.2.0)
|
|
|
|
|
|
Kea 1.2.0 already supports ```config-reload```. It remembers the path to the JSON config file used during start and can reload it if needed. This is sufficient in use cases where a local configuration file was edited.
|
|
|
Kea 1.2.0 already supports ```config-reload```. It remembers the path to the JSON config file used during start and can reload it if needed. This is sufficient in use cases where a local configuration file was edited.
|
|
|
|
|
|
- A.3.1. Kea SHOULD support `#FF0000` ```filename parameter``` in ```config-reload``` to reload configuration from a different file than when it initially started.
|
|
|
|
... | ... | @@ -64,7 +64,7 @@ The ```config-set``` command will replace the existing configuration in memory. |
|
|
|
|
|
The ```config-set``` command may also optionally provide updated logging configuration.
|
|
|
|
|
|
The ```config-write``` command allows writing of the current configuration to a file. The file location MUST be somehow limited; otherwise, a compromising DHCP server would allow escalation to write to an arbitrary place on disk.
|
|
|
The ```config-write``` command allows writing of the current configuration to a file. The file location MUST be somehow limited; otherwise, a compromising DHCP server would allow escalation to write to an arbitrary place on disk.
|
|
|
|
|
|
- A.6. Kea MUST support the `#39e21f` ```leases-reclaim``` command to trigger expiration of expired leases. (supported since 1.1.0)
|
|
|
|
... | ... | @@ -91,9 +91,9 @@ Since the command channel is a powerful feature and can be used (intentionally o |
|
|
|
|
|
Kea should allow testing of a new configuration without actually applying it. It is understood that certain aspects can't be really validated or the validation is temporary. For example, database connection or opening sockets is something that could work during verification, but could fail during the actual configuration commit.
|
|
|
|
|
|
## 2. Configuration management
|
|
|
## 2. Configuration management
|
|
|
|
|
|
### 2.1 Identifier types
|
|
|
### 2.1 Identifier types
|
|
|
|
|
|
There are several commands 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 the 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 is growing over time. Therefore Kea is currently being refactored to allow easy addition of extra identifiers in the future.
|
|
|
|
... | ... | @@ -102,7 +102,7 @@ Kea 1.1 is expected to allow the following identifier types: hardware/MAC addres |
|
|
|
|
|
Additional identifier types are likely to be implemented in the future.
|
|
|
|
|
|
### 2.2 Leases management
|
|
|
### 2.2 Leases management
|
|
|
|
|
|
After the DHCP server assigns an address (or address or prefix in case of DHCPv6), it records the fact of the address being assigned to a 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 cause the lease state to change. Therefore this is the most dynamic data in the DHCP world.
|
|
|
|
... | ... | @@ -155,7 +155,7 @@ These two commands would return all leases for a given IPv4 or IPv6 subnet. Sinc |
|
|
|
|
|
These two commands would return information about leases for a given device, regardless of the subnet it is connected to. This call could potentially return multiple leases for a mobile device that visited multiple subnets.
|
|
|
|
|
|
### 2.3 Host Reservations (HR) management
|
|
|
### 2.3 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 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), or there may be a fully static model (dynamic allocation is effectively disabled, all clients are known and have static reservations).
|
|
|
|
... | ... | @@ -227,7 +227,7 @@ Note that IPv4 or IPv6 addresses are used to identify the reservation. If found, |
|
|
|
|
|
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 the ```config-get``` command before shutdown and make sure it is stored somewhere before shutting down the server.
|
|
|
|
|
|
### 2.4 Subnets management
|
|
|
### 2.4 Subnets management
|
|
|
|
|
|
Dedicated page: SubnetCommands.
|
|
|
|
... | ... | @@ -240,7 +240,7 @@ Since IPv4 and IPv6 topologies may be different and the per-subnet parameters ar |
|
|
- S.1. Kea MUST support the `#ea8920` ```subnet4-list``` command (planned for 1.3.0).
|
|
|
- S.2. Kea MUST support the `#ea8920` ```subnet6-list``` command (planned for 1.3.0).
|
|
|
|
|
|
Kea uses the subnet-id parameter (an integer) to identify subnets. The only requirement for those identifiers 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 and 3. That removed subnet is then replaced by two subnets with ids 2 and 10, which are added to the configuration. The subnet ids for the configured subnets are now 1, 3, 2, 10. This simple example shows that we can't make any assumptions about the subnet-id. In particular, the assumption that the biggest subnet-id equals the number of subnets is false. Also, the assumption that we can get all subnets by querying subnet-ids in increasing (1,2,3,4,5,6...) order is false.
|
|
|
Kea uses the subnet-id parameter (an integer) to identify subnets. The only requirement for those identifiers 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 and 3. That removed subnet is then replaced by two subnets with ids 2 and 10, which are added to the configuration. The subnet ids for the configured subnets are now 1, 3, 2, 10. This simple example shows that we can't make any assumptions about the subnet-id. In particular, the assumption that the biggest subnet-id equals the number of subnets is false. Also, the assumption that we can get all subnets by querying subnet-ids in increasing (1,2,3,4,5,6...) order is false.
|
|
|
|
|
|
```subnetX-list``` will return a list of all subnets. Each subnet will be represented as a single subnet-id value and no other value. This terse notation is useful when you have many subnets and returning detailed information about all of them could easily slow down the server. If you are interested in a particular subnet, please use the ```subnetX-get(subnet-id)``` call.
|
|
|
|
... | ... | @@ -256,7 +256,7 @@ The ```subnetX-get``` commands return subnet information, including subnet range |
|
|
- S.7. Kea MAY support the `#FF0000` ```subnet4-update``` command.
|
|
|
- S.8. Kea MAY support the `#FF0000` ```subnet6-update``` command.
|
|
|
|
|
|
Those two commands allow making changes to an 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.
|
|
|
Those two commands allow making changes to an 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.
|
|
|
|
... | ... | @@ -298,7 +298,7 @@ The issue here is similar to ```update-subnet```. There are several possible str |
|
|
|
|
|
We will likely implement a parameter that will cause Kea to proceed using one of the strategies above.
|
|
|
|
|
|
### 2.5 Options management
|
|
|
### 2.5 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), class (only clients belonging to specific class 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 the Kea User's Guide for examples of option definitions and option data.
|
|
|
|
... | ... | @@ -342,7 +342,7 @@ The ```get-options4``` and ```get-options6``` commands return all option values |
|
|
|
|
|
```delete-option4``` and ```delete-option6``` delete the configuration value of an option. They require either option-name or option-code to be specified and optionally subnet-id. If subnet-id is not specified, it is interpreted as a command to delete the global option with the specified code or name. If subnet-id is specified, the option value in that subnet is deleted.
|
|
|
|
|
|
### 2.6 Interfaces management
|
|
|
### 2.6 Interfaces management
|
|
|
|
|
|
In DHCP it is essential to control how the server receives and transmits packets to and from clients. The important distinction should be kept in mind here: an interface or interfaces refer to network interfaces present in the system. These are typically physical hardware network interfaces, but may also be logical interfaces that represent a VLAN, a tunnel, or another type of connection. They are something that the OS reports are a possible communication channel. Kea servers can only read that information from the system, but can't change anything about them. On top of that there is a list of interfaces that Kea is configured to listen on and handle traffic from. This is a part of Kea configuration. This list can be updated, i.e. entries can be added and removed from that list at any time. Currently (Kea 1.2.0), an attempt to configure an interface that is reported by the OS as available will result in a Kea configuration error.
|
|
|
|
... | ... | @@ -363,17 +363,17 @@ The ```get-interfaces``` command is a convenience method that returns all networ |
|
|
|
|
|
It should be noted that Kea detects interfaces reported by the OS during startup and assumes that they have not changed. This may not always be true, e.g. new USB or PPP interfaces may have been added, a PPP link may have gone down, etc. The ```redetect-interfaces``` command tells Kea to redo the interface procedure.
|
|
|
|
|
|
### 2.7 Classification management
|
|
|
### 2.7 Classification management
|
|
|
|
|
|
Kea supports client classification. It is a set of expressions that are evaluated for each incoming packet. Depending on the result of such evaluation, the packet may be assigned to zero or more classes. This mechanism is explained in Section 12 of the Kea User's Guide.
|
|
|
|
|
|
Q3: Do we need API commands to manage client classification? The answer is likely yes, but it's a bit premature to define an API for this as the client classification is being worked on right now (Kea 1.1).
|
|
|
|
|
|
### 2.8 Hooks management
|
|
|
### 2.8 Hooks management
|
|
|
|
|
|
At this time we do not plan separate commands for hook management, but we may design them once hooks usage becomes more popular.
|
|
|
|
|
|
### 2.9 Run-time operations
|
|
|
### 2.9 Run-time operations
|
|
|
|
|
|
Kea is able to gather many run-time parameters called statistics. The following commands are currently supported in Kea 1.0:
|
|
|
|
... | ... | @@ -403,7 +403,7 @@ Main page: SharedNetworkCommands. |
|
|
- The `#1221cc` ```network4-subnet-del``` command removes an existing IPv4 subnet that was part of an existing shared IPv4 network from that network.
|
|
|
- The `#1221cc` ```network4-subnet-del``` command removes an existing IPv6 subnet that was part of an existing shared IPv4 network from that network.
|
|
|
|
|
|
## 3. Future enhancements and ideas
|
|
|
## 3. Future enhancements and ideas
|
|
|
|
|
|
This section lists ideas and potential features that are currently out of scope. We keep them to solicit feedback and comments.
|
|
|
|
... | ... | @@ -421,4 +421,4 @@ This section lists ideas and potential features that are currently out of scope. |
|
|
|
|
|
7. Normen mentioned: there should be more server configuration parameters, like interface names, logging, and database configuration.
|
|
|
|
|
|
8. Thomas: At some point we had requirements to address an audit trail/log of commands received/executed. Not sure when they fell out but we should add them. |
|
|
\ No newline at end of file |
|
|
8. Thomas: At some point we had requirements to address an audit trail/log of commands received/executed. Not sure when they fell out but we should add them. |