Opened 4 years ago

Closed 3 years ago

#4511 closed task (fixed)

Generate user documentation for Legal Log Hooks library

Reported by: tmark Owned by: UnAssigned
Priority: medium Milestone: Kea1.1
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: 12 Add Hours to Ticket: 0
Total Hours: 9 Internal?: no

Description

The Legal Log Hooks library is to be distributable as a separate producet from Kea proper and therefore it's user document needs to standalone as well. This ticket calls for the creation of such a document. For components of Kea, we usually create a <component>.dox file which is referred to as a subpage within the Kea admin guide. In this case, the dox would need to be made into a self-contained mini-guide.

Subtickets

Change History (18)

comment:1 Changed 4 years ago by tmark

  • Type changed from defect to task

comment:2 Changed 4 years ago by tmark

As of this writing the legal log source is not being merged into master, therefore this ticket should be done under the branch containing it. Currently that branch is trac4298.

comment:3 Changed 4 years ago by hschempf

  • Milestone changed from Kea-proposed to Kea1.1

Per team meeting on 2 June, accept 1.1 with estimate of 1.5 days

comment:4 Changed 3 years ago by fdupont

  • Owner set to fdupont
  • Status changed from new to assigned

comment:5 Changed 3 years ago by fdupont

  • Owner changed from fdupont to UnAssigned
  • Status changed from assigned to reviewing
  • Total Hours changed from 0 to 4

Done. IMHO there should be more about how it was programmed, at least for the hook and callout stuff.
Anyway it is at a point where comments are welcomed so I put it under review.

comment:6 Changed 3 years ago by fdupont

  • Total Hours changed from 4 to 6

Added a detailed design section in the .dox file.

comment:7 Changed 3 years ago by sar

  • Owner changed from UnAssigned to sar

comment:8 follow-up: Changed 3 years ago by sar

  • Total Hours changed from 6 to 9

There are several high level questions
1) I read the ticket as requesting an admin type document similar to the kea-guide rather than the developers documentation. Probably we should have both.
2) As we add more hook libraries we may want to have all of them described in a single guide. I don't think that is necessary in this ticket or for 1.1 but we should decide if each hook library will be separate or if there will be a guide for all of them.
3) Do we need links from the main documentation to these guides? Or to think of another way - how will a user find this guide?

I've made some changes to the comments to try and tidy things up and make them more consistent. Please do a pull and verify they are reasonable.

In src/hooks/dhcp/legal_log/rotating_file.h the path and base_name variables are in bold. In src/hooks/dhcp/legal_log/load_unload.cc they are in double quotes (lines 39 & 42). I think it would be best to be consistent and to use bold for both.

Log Files ==

There should be a pointer to the section on configuring the library so that the path and base_name are described.

Configuring the DHCP Modules

There should be a brief discussion about what happens if the two servers use the same name. It appears that they can both write to the same file and the v4 and v6 entires will be mixed, this is okay but should be described to allow the user to choose to use the same name or to have two different names to split the v4 and v6 entries.

comment:9 Changed 3 years ago by sar

  • Owner changed from sar to fdupont

comment:10 in reply to: ↑ 8 ; follow-up: Changed 3 years ago by fdupont

  • Owner changed from fdupont to sar

Replying to sar:

There are several high level questions
1) I read the ticket as requesting an admin type document similar to the kea-guide rather than the developers documentation. Probably we should have both.

=> I don't think the legal log is supposed to be used as it: first laws about what must be logged are not likely the same so the code should be adapted for all particular cases, second log files are not the best way for an ISP to keep legal logs. So I read the ticket as documenting a stand alone sample code.

2) As we add more hook libraries we may want to have all of them described in a single guide. I don't think that is necessary in this ticket or for 1.1 but we should decide if each hook library will be separate or if there will be a guide for all of them.
3) Do we need links from the main documentation to these guides? Or to think of another way - how will a user find this guide?

I've made some changes to the comments to try and tidy things up and make them more consistent. Please do a pull and verify they are reasonable.

=> they are! Thanks!

In src/hooks/dhcp/legal_log/rotating_file.h the path and base_name variables are in bold. In src/hooks/dhcp/legal_log/load_unload.cc they are in double quotes (lines 39 & 42). I think it would be best to be consistent and to use bold for both.

=> done

Log Files ==

There should be a pointer to the section on configuring the library so that the path and base_name are described.

=> I agree but I don't know how to put an internal pointer to something which is not a section... Please add it if you know?

Configuring the DHCP Modules

There should be a brief discussion about what happens if the two servers use the same name. It appears that they can both write to the same file and the v4 and v6 entires will be mixed, this is okay but should be described to allow the user to choose to use the same name or to have two different names to split the v4 and v6 entries.

=> it is more common sense than anything else... do you have a text to propose?

comment:11 in reply to: ↑ 10 Changed 3 years ago by sar

  • Owner changed from sar to fdupont

Replying to fdupont:

Replying to sar:

There are several high level questions
1) I read the ticket as requesting an admin type document similar to the kea-guide rather than the developers documentation. Probably we should have both.

=> I don't think the legal log is supposed to be used as it: first laws about what must be logged are not likely the same so the code should be adapted for all particular cases, second log files are not the best way for an ISP to keep legal logs. So I read the ticket as documenting a stand alone sample code.

The consensus is that we should add a section into the main Admin guide to describe how to set up the hooks. The code for the hooks will be distributed as a separate item. The configuration description should mention that but then proceed to describe how they can be configured. I'm thinking of this as a new chapter in the admin guide that will expand as more hook libraries are developed. So a new file in kea/doc/guide and updates to the base admin file to include the new chapter.

The actual configuration content will probably be only a couple of pages as there aren't that many configuration options.

I think the assumption is that this may be sufficient for some ISPs and for them they can just use it. For others that have other requirements they (or we) may need to update the code or create a new version.

Do you want to write the admin portion or shall I? I think a lot of it can be copied from the developers guide but there is some extra text to add as well.

2) As we add more hook libraries we may want to have all of them described in a single guide. I don't think that is necessary in this ticket or for 1.1 but we should decide if each hook library will be separate or if there will be a guide for all of them.
3) Do we need links from the main documentation to these guides? Or to think of another way - how will a user find this guide?

I've made some changes to the comments to try and tidy things up and make them more consistent. Please do a pull and verify they are reasonable.

=> they are! Thanks!

In src/hooks/dhcp/legal_log/rotating_file.h the path and base_name variables are in bold. In src/hooks/dhcp/legal_log/load_unload.cc they are in double quotes (lines 39 & 42). I think it would be best to be consistent and to use bold for both.

=> done

Log Files ==

There should be a pointer to the section on configuring the library so that the path and base_name are described.

=> I agree but I don't know how to put an internal pointer to something which is not a section... Please add it if you know?

I don't know offhand - if determine how to do so I'll update things.

Configuring the DHCP Modules

There should be a brief discussion about what happens if the two servers use the same name. It appears that they can both write to the same file and the v4 and v6 entires will be mixed, this is okay but should be described to allow the user to choose to use the same name or to have two different names to split the v4 and v6 entries.

=> it is more common sense than anything else... do you have a text to propose?

I'll look into this after we figure out who is doing the admin guide stuff.

comment:12 Changed 3 years ago by sar

I've now created the admin guide page for the legal log library. It is on trac4511. As there was already a chapter for hooks I added it there and expect that as we create more hook libraries they can be added there as well.

comment:13 Changed 3 years ago by stephen

  • Owner changed from fdupont to stephen

comment:14 Changed 3 years ago by stephen

  • Owner changed from stephen to sar

Reviewed commit 8fd967a483297c313945c5162863e14b98a0a331

Looks OK, but a few points:

  • The article needs a reason why such information is not automatically logged through the logging system (e.g. too slow for high-volume logging / information logged could not be changed without editing Kea itself).
  • The DHCPv4 entry is based on the REQUEST message, but the DHCPv6 one is not based on SOLICIT. Why is that? (The documentation does not need to state it, I'm just curious.)
  • Alignment of braces in the example configurations should be the same as in other examples, i.e. closing brace of "parameters" below the leading quote of the "parameters" string, and closing brace of the first "hooks-libraries" element below the opening brace.

comment:15 Changed 3 years ago by sar

I've merged the legal log hooks description for the admin guide into the master branch.

Now it's time to go back and finish off the developers guide items.

comment:16 Changed 3 years ago by sar

  • Owner changed from sar to fdupont

I've updated the dox file a bit to remove some of the descriptions of the code as example as it may be used directly if it records the correct information and added a note that the kea4 and kea6 servers should have different log files.

When we add more hook libraries we should revisit this documentation to add them as appropriate, but there is no need to do that now.

Ready for review

comment:17 Changed 3 years ago by fdupont

  • Owner changed from fdupont to UnAssigned

Reviewed. I suggest to leave this to Stephen (or a volunteer who has English as his/her mother language).

comment:18 Changed 3 years ago by sar

  • Component changed from Unclassified to documentation
  • Resolution set to fixed
  • Status changed from reviewing to closed

Thomas reviewed my last set of changes and they have been accepted.

So I'm closing this ticket as the documentation for the library has now been completed.

Note: See TracTickets for help on using tickets.