[kea-dev] Initial proposal for Kea Control API

Tomek Mrugalski tomasz at isc.org
Thu Jul 14 13:20:13 UTC 2016

On 07.06.2016 22:44, Shawn Routhier wrote:
>> On May 24, 2016, at 4:27 PM, Tomek Mrugalski <tomasz at isc.org> wrote:
> 1) Adding numbers to the questions would make it easier to reference them
> in the discussion.
Note taken. There are currently 3 outstanding questions, so I numbered
them. If we need to add any additional questions, will make sure they'll
be numbered too.

> 2) I second Thomas’s comments about security.  I don’t think we need encryption
> but we will want authentication and data integrity.  If the control channel can only
> be accessed from the local host we may be able to defer this for a bit, but it may
> be easier to include it at the start.
Added requirements A.8, A.8.1 and A.8.2 for this. Let me know if it's
suitable. If not, providing extra text would be appreciated.

> 3) My current understanding of multi-tenancy is that each tenant would see what
> looks like their own server with (potentially) different configurations.  Following this
> model it would seem best to have the tenant selector be at a fairly high level so that
> each command could only affect one tenant at a time (or maybe even an entire
> connection would be for a single tenant).  If others have a different understanding
> of multi-tenancy, perhaps we need to discuss and define that as well?
I like that idea. AIUI it's similar to views in bind. It would an
interesting experiment to try to implement it in practice. We would have
to lift the restriction on lease address being unique. Instead we would
put a requirement of global uniqueness of subnet-ids. As a result the
tuple (address, subnet-id) would become unique. Anyway, I think this is
clearly out of scope for this discussion, so I removed all references to
multi-tenancy for now. If we decide to do it, then it would be a good
time to update the control api requirements.

> 4) Thomas’s idea of audit logs is also something that I think is useful.
Added A.9 requirement for it.

> 5) I would find a table at the end to collect all the requirements together useful.  I’m
> not sure if it would be useful enough to spend the time organizing it and updating
> it as the rest of the document changes.
We may do it at the very end when the document is stable. At this stage
of the game I can't see how one could keep it consistent. I'm against
reorganizing the text to move all requirements to the end and then cramp
up the text together. Those paragraphs only make sense along the
requirements they explain.

> 6) From a practical perspective if we can get an update effect by doing a delete followed
> by an add we may decide that all of the updates can be deferred.  This will make
> it harder to do certain things via the command channel but it also may allow the
> first round of the work to be completed earlier.
That's true in the initial approach, but there are benefits in having
update command. For example you'd like to update only options for host
reservation. With update you pdate only that. With delete/add, you
really need to do get to retrieve all the other details that you don't
want to change, then call delete, then add with the change applied.
But I agree. The functionality can be achieved, so I lowered the
priority of all update commands from MUST to MAY.

> 7) In Bind’s RNDC there is the concept of freezing the server such that the
> configuration can be updated while it is still “running” but not “serving”.  This
> is useful if the admin wants to make a number of changes that should be
> somewhat atomic as seen from the outside.  Do we think that such a feature
> would be useful?  perhaps in the future and for now any such changes would
> be done be replacing the entire configuration?
We can certainly consider such a feature, but I think it's out of scope
for this ticket. The goal was to write requirements for manipulation API
for leases, hosts, subnets and options. But in general I like the idea
and wouldn't want it to get lost. Added a new section with future ideas
and enhancements.

> 8) Should there be some sort of version or time stamp on the configuration to
> allow an admin to see if anything has been changed?  I’m thinking of the case
> of an admin trying to synchronize the configuration with an external source
> and being able to confirm that the version or time stamp is the same as when
> the external source last updated the configuration could avoid having to
> retrieve and compare the entire configuration.
We're talking about two independent aspects. If I set the same
configuration 10 times, I would get 10 different timestamps, so it would
be useless to determine if the configuration is the same or not. Version
on the other hand would say how many time a configuration has changed.
If there's configuration 1, a subnet is added and then removed, version
would be 3, but it would be exactly the same as 1. Finally, there's
third alternative here. We could implement a sort of a digest of the
whole configuration. If the configuration changes the digest would
change. This would have 2 benefits. First, you can check if the
configuration is matching what is expected, but without retrieving the
whole configuration. Second, you could detect any changes, for example
attacker updating your router configuration as a stage for MITM attack.

Anyway, added ideas #2, #3 and #4.

> Administrative Actions
> 9) A4 - get-config
> While I won’t argue for it strongly I think have a write-config command would be
> convenient for the admins.  While I agree over-writing the config file on all changes
> would be inappropriate I think having a command to do so would eliminate some
> work for a basic set up.  The admin would understand that they would lose any
> extra data in the config file but they might find that acceptable in some cases.
I was initially reluctant to have such a call and added A.5.1 (a 'write'
flag in set-config call), but since there are two voices supporting it
now, I added write-config command as A.5.2.

> 10) As Thomas pointed out getting a copy of the config file is going to be useful
> for debugging purposes.  Either having the file saved to a diagnostic file or providing
> the admin a way to save the file would seem to be useful.
See above. A.5.2 should address this comment.

> Lease Management
> 11) Q: Do we want to have a single query?
> I think a single query with multiple parameters is a better choice.
Updated. I hope I caught all instances. Let me know if I skipped any.

> 13) L.7 and L.8
> See item (6) above, I think these could be moved to SHOULD rather than MUST
> as their functionality could be handled by a delete and add.
Moved to MAY.

> 14) Q: Do we want a way to delete all leases in a subnet?
> Probably
See new L.11 and L.12 requirements.

> 15) Q: Do we want to delete all leases that belong to a certain identifier?
> This could be useful but if we add it we should also probably add an option to get-leaseX
> to get all of the leases. I currently read the text as saying we only support getting the
> lease by identifier for a given subnet.  (Or if the subnet-id is optional that should be
> made clearer in the text).  If we have a command to get all the leases then I would
> make a command to delete all the leases lower priority as the admin could simply
> do the get and then walk through the resulting list.
I would rather skip it for now. A good design is not when there's
nothing to add, but when there's nothing left to take away. We can
consider implementing such a call when we have the calls planned right
now implemented and someone comes to us saying why those are not enough.

> Host reservation
> 16) H.16 - Kea Should support get-reservation by id
> This is inconsistent with H.17 which is a MUST and allows the admin to update the reservation
> by selecting it via id.  I think H.16 needs to be a MUST if H.17 is a MUST (but see my
> general comment and H.17 as  SHOULD or MAY).
Now H.16 is MUST, H.17 is MAY. Would that work?
> 17) Q: For IPv6 there may be multiple addresses …
> As with Thomas I think this is a bit more general than just addresses and prefixes for host
> reservations.  I think that eventually adding commands to add new addresses and prefixes
> is useful, but I think it can be deferred.  The alternative is to have the admins do a
> get command followed by editing the response and then an update.  This puts more effort
> on the admin (or the tool they use to connect to Kea) but is also likely to produce more
> consistent structures.
Agree. So let's stick with commands that operate on whole reservations.
I have added requirements H.17.1 and H.17.2 to clarify that
update-reservation must be able to update IPv6 reservations and v4/v6
options. Note that the call is MAY, but once it's implemented it MUST
support those.

> 18) Q: Do we want to specify delete-reservation with ids?
> Don’t we have to support this to be complete?  If we have a host reservation that only
> has options but doesn’t have an ip address how else could it be deleted?
Ok. Added H.20.

> Subnets Management
> 19) Should there be support for get-subnetX by prefix/prefix length?
> If so and continuing with the general rule that we don’t need to add convenience
> commands in the first round this would probably be a MAY.
Ok, I'm not a fan of extending this list, unless there's a good reason
for it. The list is already depressingly long.

> 20) One note describes the expected workflow of get-subnet, edit response, update-subnet.
> If we choose this style we should choose it for all of the update commands (perhaps
> that is already your thinking?)  If so it should be made as a general statement to cover
> all of the document.
Since we decided to lower priority of the update commands, I think this
note is no longer appropriate, so I removed it.

> 21) I think the TBD and Q about subnet modification and subnet removal
> need to be handled in the same fashion (whatever we choose).  Adding a parameter
> to choose does allow the admin the flexibility to do what they think is correct.  One
> of the options should be keep the leases around until they expire as the client does
> still think it owns the address and there will be problems if it gets reused.
The approach is that add, get and delete are MUST, so they will be
implemented first. update is MAY, so it will be available later. I hope
the new text reflects that.

> We may also want to consider the idea of before and after from ISC DHCP.  With
> these options one can specify that a given subnet is to only to be used until a certain
> date or only after a certain date.  Such a feature would require changes in the allocation
> code as well but it would make adding, removing or updating subnet information
> more convenient.  An example of how this could work is that an IPv6 subnet is being
> renumbered and the old prefix should stop at midnight tonight while the new prefix
> can be used after midnight.  The server would hand out shorter and shorter leases
> up till midnight such that all the leases would expire at midnight when the old prefix
> is no longer used.  Exact details of how to implement this would need to be discussed
> and again this is likely to be deferred till later.
Added to ideas and suggestion section.

> Options management
> 22) Do we want get-optionX-def which would return a single option definition
> Eventually yes, but I think it would be a MAY
Added O.17 and O.18 as MAY.

> 23) Thomas asks about what to do if one of several options in a request is invalid.
> I think we want to fail the entire set.  I don’t like the term rollback as it implies that
> we started setting the others and then un-did those sets.  I would prefer the code
> to have validated all of the options before trying to “commit” any of them but that
> is an implementation detail.
Yes. This type of details does not belong in the requirements doc.

> Interfaces Management
> 24) I agree with changing it from a MUST to a MAY
It's MAY then.

> Other
> 25) can we update the logging information while running?  It would be useful to
> modify the severity and debug level at least.
Yes, we can. Added clarification text to the set-config command that can
also set logging. Actually, there's experimental code for the upcoming
hackathon that already supposedly does that. Supposedly, because I
haven't tested it yet.

> 26) can we usefully display hooks information?  perhaps a MAY?
See above. Also, added item #6 in future idea.

Ok, that's it.


More information about the kea-dev mailing list