#5613 closed defect (fixed)

The documentation on where to install hooks needs to be clearer

Reported by: cathya Owned by: marcin
Priority: medium Milestone: Kea1.4-final
Component: documentation Version: git
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DHCP Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

The Kea guide explains how to configure to load hooks libraries - both for the various services (kea-dhcp4, kea-dhcp6 etc) and for the Kea Control Agent (kea-ctrl-agent), showing the syntax for each.

This is fine, because in Kea there is great flexibility, and it might well be that in the future it makes a lot of sense to have a hook loaded and operated by the CA versus one of the services. In fact the Kea guide even alludes to a situation where that could be desirable.

But currently, ISC does not distribute or sell any hooks that are intended to be installed/loaded by the CA - but this is not at all clear in the documentation and there have been at least two instances now (to my knowledge, there may be more) where a new user of a hooks libraries have either loaded them on the CA, or on both the CA and kea-dhcp4 or kea-dhcp6.

When they do this, because of the order of precedence applied by the CA, the commands (even with service properly specified) never get to the service they're intended for and are consumed locally - this causes a lot of bafflement and wasted time troubleshooting why the hook doesn't appear to work, even when the commands issued specify the service that they're intended for.

Needed:

  1. Better clarification on where hooks can be installed and why this gives such great flexibility to Kea DHCP
  1. Update the lists and details for current (and future) hooks to indicate where they can/should be installed

(Future work - this is just a request for documentation improvements - could make it impossible to load a hook in the wrong service/CA).

Subtickets

Change History (9)

comment:1 Changed 17 months ago by tomek

Note there is now a description, see here for our nightly builds (to be included in 1.4.0-beta):

https://jenkins.isc.org/job/Kea_doc/guide/kea-guide.html#idp1380439068

Also, when configure is run, it prints the following:

Package:
  Name:              kea
  Version:           1.4.0-beta
  Extended version:  1.4.0-beta (tarball)
  OS Family:         Linux

  Hooks directory:   /usr/local/lib/hooks
  Premium hooks:     no

Note the hooks directory.

Last edited 17 months ago by tomek (previous) (diff)

comment:2 Changed 17 months ago by tomek

  • Milestone changed from Kea-proposed to Kea1.4-final

comment:3 Changed 17 months ago by marcin

  • Owner set to marcin
  • Status changed from new to accepted

comment:4 Changed 17 months ago by marcin

  • Owner changed from marcin to UnAssigned
  • Status changed from accepted to reviewing

I updated user's guide in a couple places to highlight that libs should be loaded to the DHCP servers rather then than CA, etc.

Proposed ChangeLog entry:

14XX.	[doc]		marcin
	List of hooks libraries provided by ISC includes an
	information which Kea servers the libraries can be attached
	to. The detailed description of each supported hooks library
	also contains this information.
	(Trac #5613, git cafe)

comment:5 Changed 17 months ago by tmark

  • Owner changed from UnAssigned to tmark

comment:6 Changed 17 months ago by tmark

  • Owner changed from tmark to marcin

I doctored the wording in hooks.xml a little. One thing I noticed though is hooks.xml describes "loading" libraries (btw it should be "load by" not "load to"), but the changes in individual hook lib XML uses phrasing "....library may only be attached...".

I think you should change those to be "library may only be loaded by ...". From what I can see we use "load" and "unload" in our doc and logs almost entirely.

comment:7 Changed 17 months ago by marcin

  • Owner changed from marcin to tmark

Thanks for your corrections. I changed "attached to" to "loaded by" per your suggestion.

comment:8 Changed 17 months ago by tmark

  • Owner changed from tmark to marcin

Changes are good, please merge.

comment:9 Changed 17 months ago by marcin

  • Resolution set to fixed
  • Status changed from reviewing to closed

Merged with commit 9d6f8de3d988c42c413a7d628e31854e9c80d8c9

Note: See TracTickets for help on using tickets.