[kea-dev] Initial proposal for Kea Control API
Thomas Markwalder
tmark at isc.org
Thu May 26 20:01:44 UTC 2016
On 5/24/16 7:27 PM, Tomek Mrugalski wrote:
> Hi,
>
> I have just finished an initial proposal for Control API for Kea. The
> proposal is available here:
>
> http://kea.isc.org/wiki/ControlAPIRequirements
>
> I'm very eager to hear your opinions on this. If you're an existing or
> prospective user, can you also share your perceived priorities of those
> proposed calls? Sharing your opinion on kea-dev is the best way to
> respond, but sending your comments privately off the list is ok, too.
>
> The complete API is huge and there is no way ISC could implement all of
> it, at least not in one release. Therefore it's very useful to
> prioritize which calls should be implemented first.
>
> Note that ISC does not plan to make actual implementation of the API in
> Kea 1.1. We had preliminary discussions whether it would be a good
> leading topic for Kea 1.2, but we did not make any specific decisions yet.
>
> Tomek
> _______________________________________________
> kea-dev mailing list
> kea-dev at lists.isc.org
> https://lists.isc.org/mailman/listinfo/kea-dev
Hello Tomek:
This is a good first cut. My comments follow:
General:
--------
1. We have the command channel, across which we issue commands, yet you
refer to them frequently as "calls". As in the Kea Admin guide, we
should refer to them as "commands" throughout this document.
2. We need requirements that describe command channel security. You
cited large response sizes as a potential DOS vector. Actually, once
they have access to the command channel, the hammer can be dropped in
any number of ways. Making it secure is a vital aspect and needs to be
covered by requirements.
3. People may want an audit log of commands issued, so we should
consider adding requirements for this. These may be satisfied simply
by a dedicated logger but that's an implementation detail.
Since we are mostly focusing on content right now, I did not worry much
about grammar.
Administrative Management
--------------------------
1. The paragraph under A.1, "Supporting large command parameters end
and responses..."
Really this is part of the A.2 discussion and should be incorporated there.
2. A.5 - implies, but does not explicitly state, that content supplied
with set-confg would replace the entire existing, in memory
configuration. In other words, set-config is intended to supply a full
configuration, anything not supplied in it does not exist. We should
maybe state this explicitly.
3. One thing we might consider is to allow set-config to automatically
dump a successful configuration to a file for diagnostic purposes.
Somebody does a set-config, possibly from a remote box and no one
records the config. If Kea then crashes we would have no certain
knowledge of it's configuration at the time it went down. The file
could be saved to a time-based file name. This would not overwrite the
existing configuration, nor be reloaded at startup (though that has
interesting possibilities).
Lease Management
----------------
3. "Those two calls will be used to retrieve..." should be "These two
commands will be..."
4. "Q: Do we want to have a single query (e.g. get-lease4) with
multiple parameter sets or do we want separate queries..."0
Initially I thought, they should be be separate commands but I think
having a single ("overloaded") command is more flexible should we decide
to add variants in the future. I don't think the extra parameter logic
to deal with permutations would be significant. Whatever we do decide
here we should apply universally throughout the API. Either we
"overload" commands or we do not.
5. "Q: Do we want to support multi-tenancy..."
This seems like a broader question, than just at our command API level.
This is likely to have ramifications other places. In such a scenario
then, what would get-lease6(ip-addr) return if there were more than one
lease on different subnets? It could the first such lease we found OR a
collection of the leases.
We could decide now that all get commands return collections, just as
SQL selects return rows/result sets, giving us ample flexibility for any
number of future requirements.
6. Does update equate to replacing the entire lease with what is sent
with the update command? In other words, is an update equivalent to
delete/add? If so it implies that every value for the updated lease
must be in the JSON supplied to the update. I'm not saying this is a
bad thing, I'm simply looking for clarification.
7. Should we allow them to change the subnet id of lease? This might
come in handy for repairing some unseen situation but I'm not certain it
is good idea.
8. Do we not also have the multi-tenancy question with update and delete?
9. "Q: Do we want a way to delete all leases in a subnet? ..."
Yes, I think this is useful.
10. "Q: Do we want to delete all leases that belong to certain identifier?"
Are you talking about an identifier having leases in more than one subnet?
I imagine this could also be useful.
11. "Note: There are currently no plans to implement calls that retrieve
multiple leases..."
We could implement a row limit with some reasonable number, and maybe a
flag or parameter for overriding that limit.
As noted above under general comments, security is a bigger issue than
just this item. In theory only admins should be using this and
ultimately it is up to them to use the commands safely.
Host Reservation Management
-----------------------------
12. H.17, as with updating leases, is update-reservation equivalent to
delete/add?
13. "Q: For IPv6 there may be multiple IPv6 addresses and/or prefixes
reserved. There is no easy way to identify them..."
This question also applies to host options no? Users might find it
equally useful to add, update, or delete options without having to
updating the entire reservation. We could add these commands as "MAY"
support.
14. "Q: Do we want to specify delete-reservation with (identifier-type,
identifier, subnet-id)?"
Yes I think we should include this.
Subnet Management
-----------------
15. "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."
Needs rewording, how about:
"The ability to provide the configuration in a configuration file
without running a database will remain supported."
16. "TBD: What to do about subnets modification? There are several
options:..."
I think a mode parameter is a good idea, certainly one that allows
choosing between #1 and #3.
I'm not sure how we would implement #2's subnet validity check as a
parameter pertaining to a single update. These checks would have to
continue over time, rather than as part of the update processing. How
would one turn this off again? What we could do, if we are worried
about performance is make it a global level parameter, that admins turn
on or off, if we think the performance impact warrants this or it
prohibits some form of host reservation behavior.
17."Q: How do we want the subnet removal procedure to work? There are
several possible options:"
I do not believe #2 is viable because it introduces a violation of
referential integrity. This is true even though Memfile doesn't have
foreign key constraints and for RDBMS's they aren't mandatory.
As with the update, I think we should provide a delete "mode" parameter
that lets them pick either #1 or #3, "retire" or "immediate".
Under "retire", new subnets cannot have the same ID as a retiring
subnet, so there is no break in integrity.Retired subnets are deleted
only after their last lease is removed. Mode #3 avoids the issue
entirely by performing a cascading delete.
I think that #4, "reconfigure process", might actually be a subnet
command in itself. Wouldn't your use case be something like this:
1. Delete the current subnet
2. Add the new subnet
3. Tell clients of the subnet to reconfigure
Note that steps 1 and 2 might have been replaced with single step of
updating a subnet. It would also allow you to force all clients to do
it without having made any changes.
18. As an aside, for an eBay type setup, where they are going to delete
thousand of subnets and add thousands more, at some point the ID pool
runs out. We may need an administrative command for handling this.
Options management - Option Definition commands
-----------------------------------------------
19. "Kea allows specifying options in several scopes:..." Does not
mention client class as a scope.
20. The add-optionX-def commands appear to be the only add commands
which support adding multiple elements
- Why support multiples with this one and not others?
Consistency and clarity in APIs are important. We could decide, that
all add commands should accept a collection of objects. If I can add
one host reservation, why not ten? Or maybe we adopt a naming
convention such that add commands which add a list of one or objects
have plural names: add-option6-defs. I'm not advocating one position
over the other (yet) but I want to understand why option definitions
should be different from all the others.
- If we're going to support adding more than one at a time, what happens
if one of entries is invalid, does the whole addition "rollback" and fail?
21. "set-optionsX-def calls set all option definitions. New options will
replace whatever old definitions may have been there."
- Does this include the pre-defined "standard" option definitions or
does this only apply to custom options. I'm not sure I see the
usefulness of this command. Do you have use case in mind?
- If there is an option definition X and values for option X have been
specified by two subnets and three host reservations on X but the new
set of definitions does not define option X? Does the set command fail?
23. The delete command names abbreviate "delete" to "del". We need to
be consistent. Either always spell it out or always abbreviate it.
24. As with the set command, how do we handle a delete option definition
command that attempts to delete a definition that is in use?
25. "Q: Do we want also get-optionX-def which would return a single
option definition?"
Yes, I think we do.
Options management - Option commands
-----------------------------------------------
26. "Kea allow option specification on global and per subnet level. Both
can be manipulated using the same call. There will be an optional
parameter subnet-id. If it's not specified, the code applies to global
level. If there is subnet-id specified, the change applies to specific
subnet. The same rule applies to all call related to options."
Actually they can be set at global, subnet, host and eventually class
level. Are these commands intended only to address the global and
subnet scopes, while options for hosts or classes will be handled under
object specific commands?
27. "add-option4 and add-option6 add new DHCPv4 or DHCPv6 option values."
Do these commands one option specification or a collection of one or
more? It's not clear.
29. "set-options4 and set-options6 set all option values for a given
scope...."
30. "get-options4 and get-options6 command returns all option values
defined for a given scope. It has one optional parameter: subnet-it. If
it's defined, all global options are returned. If it's defined, only
options for a given scope are returned."
This has a few issue, first is "subnet-it" you mean "subnet-id". And I
think you mean if it is not defined, global options will be returned, if
it is defined..."
Interfaces Management
---------------------
31. "Q: Do we want those calls at all? ...."
I think we probably do want these eventually. You could change them
from MUST to MAY. But I could see somebody having everything else
correct but forgetting an interface name or something. Certainly, I can
see them wanting the redetect-interfaces.
Client Classification
---------------------
32. You don't think we know enough about them to write the
requirements? I won't press the issue but I think we do.
Runtime Operations
------------------
33. Since these are only statistics commands, you could maybe rename
this section.
Thomas
More information about the kea-dev
mailing list