|
|
# This document needs work to implement all the color-coding
|
|
|
|
|
|
# Kea Commands
|
|
|
|
... | ... | @@ -6,10 +7,12 @@ Kea provides a REST API (JSON structures sent of http) and a control channel (JS |
|
|
'''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 may be defined.
|
|
|
|
|
|
For easier understanding what is and what is not supported, the commands are color coded. The meaning is as follows:
|
|
|
- [[span(style=color:green, '''green''' is currently supported by either released or development version)]];
|
|
|
|
|
|
`RGB(0,255,0)` 'green' is currently supported by either released or development version);
|
|
|
- [[span(style=color:blue, '''blue''' is implemented and is part of the add-ons ISC is offering. Getting access to those extensions involves money. See http://isc.org/kea for details)]];
|
|
|
- [[span(style=color:orange, '''orange''' is planned for upcoming versions)]];
|
|
|
- '#F00', '''red''' is currently not implemented and there are no specific milestones (please contact ISC if you're interested in those commands and we can talk about how we could fund that development effort).
|
|
|
|
|
|
#F00 `red` is currently not implemented and there are no specific milestones (please contact ISC if you're interested in those commands and we can talk about how we could fund that development effort).
|
|
|
|
|
|
Often there are many ways how certain things can be achieved. Where appropriate, the text below explains the rationale that led to specific design choices.
|
|
|
|
... | ... | @@ -22,7 +25,7 @@ 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 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 [[span(style=color:green,'''shutdown''')]] command (supported since 0.9.2).
|
|
|
|
... | ... | @@ -92,9 +95,9 @@ Since the command channel is a powerful feature and can be used (intentionally o |
|
|
Kea should allow to test a new configuration to the possible extend 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 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 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.
|
|
|
|
... | ... | @@ -103,7 +106,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 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 causes lease state to change. Therefore this is the most dynamic data in the DHCP world.
|
|
|
|
... | ... | @@ -156,7 +159,7 @@ Those two commands would return all leases for a given IPv4 or IPv6 subnet. Sinc |
|
|
|
|
|
Those two commands would return information about leases for a given device, regardless of 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) up to fully static model (dynamic allocation is effectively disabled, all clients are known and have static reservations).
|
|
|
|
... | ... | @@ -229,7 +232,7 @@ Note that IPv4 or IPv6 address are used to identify the reservation. If found th |
|
|
|
|
|
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 '''config-get''' command before shutdown and make sure it is store somewhere before shutting down the server.
|
|
|
|
|
|
=== 2.4 Subnets management ===
|
|
|
### 2.4 Subnets management
|
|
|
|
|
|
Dedicated page: SubnetCommands.
|
|
|
|
... | ... | @@ -300,7 +303,7 @@ The issue here is similar to update-subnet. There are several possible strategie |
|
|
|
|
|
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 Kea User's Guide for examples of option definitions and option data.
|
... | ... | @@ -345,7 +348,7 @@ get-options4 and get-options6 command returns all option values defined for a gi |
|
|
|
|
|
delete-option4 and delete-option6 delete configuration value of an option. It requires 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 global option with specified code or name. If subnet-id is specified, 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: interface or interfaces refer to network interfaces present in the system. These are typically physical hardware network interfaces, but may as well be logical interfaces that represent a VLAN, a tunnel or other type of connection. These is 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. 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 interface that is reported by the OS as available will result in Kea configuration error.
|
|
|
|
... | ... | @@ -367,17 +370,17 @@ The get-interfaces command is a convenience method that returns all network inte |
|
|
|
|
|
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, PPP link may have gone down etc. 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, 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 API for this as the client classification is being worked 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:
|
|
|
|
... | ... | @@ -391,7 +394,7 @@ Kea is able to gather many run-time parameters called statistics. The following |
|
|
Calls R.1 - R.6 are already implemented in Kea 1.0 and are documented in Chapter 15 of the Kea User's Guide.
|
|
|
|
|
|
|
|
|
=== 2.10 Shared Networks Management ===
|
|
|
### 2.10 Shared Networks Management ###
|
|
|
|
|
|
Main page: SharedNetworkCommands.
|
|
|
|
... | ... | @@ -408,7 +411,7 @@ Main page: SharedNetworkCommands. |
|
|
- [[span(style=color:blue,'''network4-subnet-del''')]] command removes an existing IPv4 subnet that was part of existing shared IPv4 network from that network.
|
|
|
- [[span(style=color:blue,'''network4-subnet-del''')]] command removes an existing IPv6 subnet that was part of 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.
|
|
|
|
... | ... | |