Opened 6 years ago

Closed 5 years ago

#3418 closed enhancement (complete)

Update Kea Guide (file based config, remove refs to BIND10 framework, renames)

Reported by: tomek Owned by: tomek
Priority: medium Milestone: Kea0.9
Component: documentation Version:
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

Make sure that:

  • the new documentation explains file-based configuration procedure
  • that all references to BIND 10 are gone
  • all names are updated appropriately (e.g. libb10-* => libkea-*)

Subtickets

Change History (9)

comment:1 Changed 5 years ago by tomek

  • Summary changed from Update Kea Guide for 0.9 release to Update Kea Guide (file based config, remove refs to BIND10 framework, renames)

comment:2 Changed 5 years ago by tomek

There is a follow-up ticket (#3429) which should be done shortly before 0.9 is completed.

comment:3 Changed 5 years ago by tomek

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

comment:4 Changed 5 years ago by tomek

  • Owner changed from tomek to UnAssigned
  • Status changed from assigned to reviewing

I reorganized the general parts of the guide and converted DHCPv4 section to use JSON format. The outstanding things to do are:

  • DHCPv6, DDNS sections (will be covered in newly created #3468)
  • starting/stopping the servers (will be covered in #3466)
  • logging configuration (will be covered in #3427)

I decided to push Kea6,D2 rewrites to separate ticket, because I'd like to get feedback before going into repetitive stuff (over 100 instances to convert in Kea6,D2 sections).

Major changes done:

  • Reorganized the whole guide
  • Split the doc into several smaller ones (usually 1 chapter = 1 file)
  • Renamed to Kea Administrator Reference Manual (to follow BIND9 naming convention)
  • Removed many BIND10 specific sections
  • Converted all configuration examples in DHCPv4 section.
  • Reorganized installation section

Please review. Keep in mind that the intention here never was to convert everything as there are outstanding tickets that cover those missing gaps. Also, once all intended changes are done, there's final proofreading task planned (#3429).

comment:5 Changed 5 years ago by stephen

  • Owner changed from UnAssigned to stephen

comment:6 follow-up: Changed 5 years ago by stephen

  • Owner changed from stephen to tomek

Reviewed commit 61558be1eafa20d040c9ed8e3b361cb2ec29ed28

I had a number of small corrections and suggested changes to wording. Rather than document here, I've editing the files and pushed. Please pull them and review. Some more substantive issues (which I've not touched) are listed here.

quickstart.xml
A comment in this talks about the need to replace the description of checking out from the git repository with a link to a downloadable tarball. I suggest that the main description includes a step that describes how to download and unpack the tarball (with a link if possible). But that step should have a footnote explaining how to clone the git repository and run autoreconf to create the configure script. In this way, we cover both building the released version and builing the latest snapshot.

The text talks about examples in an example directory (and refers to a "doc" directory). Is that installed with Kea?

config.xml
As the aim is to remove the BIND 10 configuration mechanism completely, is there any need to document it. Why not ignore it and aim the documentation to Kea 0.9?

dhcp4-srv.xml
The example configuration in 5.2 does not specify the location of the CSV file, although the text talks about information being stored in one.

The limitations section says that BOOTP is not supported. This is a permanent limitation, not one that we are likely to crrect soon. It may be better put elsewhere.

ChangeLog
This seems OK.

comment:7 in reply to: ↑ 6 Changed 5 years ago by tomek

  • Owner changed from tomek to stephen

Replying to stephen:

Reviewed commit 61558be1eafa20d040c9ed8e3b361cb2ec29ed28

I had a number of small corrections and suggested changes to wording. Rather than document here, I've editing the files and pushed. Please pull them and review. Some more substantive issues (which I've not touched) are listed here.

Thank you. Your changes are fine.

quickstart.xml
A comment in this talks about the need to replace the description of checking out from the git repository with a link to a downloadable tarball. I suggest that the main description includes a step that describes how to download and unpack the tarball (with a link if possible). But that step should have a footnote explaining how to clone the git repository and run autoreconf to create the configure script. In this way, we cover both building the released version and builing the latest snapshot.

We do not build daily tarballs. It is questionable whether building them on a daily basis would add much value. If someone is adventurous enough to run daily snapshots, we prefer he'd use git directly as this will make updates easier. Especially that people running snapshots are likely to report bugs and then try our fixes once they become available.

We'll discuss this on the next Kea call. If we decide that tarballs are useful, we can then update this section.

The text talks about examples in an example directory (and refers to a "doc" directory). Is that installed with Kea?

Excellent question. They weren't, but they are now.

config.xml
As the aim is to remove the BIND 10 configuration mechanism completely, is there any need to document it. Why not ignore it and aim the documentation to Kea 0.9?

I'm not so sure about that. Currently the Bundy mechanism is limited to bundy_controller.cc files in dhcp{4,6}. I was planning to leave those files. Obviously, the whole framework will go as soon as #3413 is merged, so the Bundy mechanism will be dysfunctional. It will have the capability to connect to msgq, but there won't by anything to connect to. That's ok. The idea (hope) is that Bundy guys will pick this up and integrate with their framework. I'm not sure if or when it will happen, but for us keeping 2 files (around 230 lines each) is not a problem.

dhcp4-srv.xml
The example configuration in 5.2 does not specify the location of the CSV file, although the text talks about information being stored in one.

Added persistent and name parameters.

The limitations section says that BOOTP is not supported. This is a permanent limitation, not one that we are likely to crrect soon. It may be better put elsewhere.

There's no other section that would be a good fit. I thought that from user's perspective, average sysadmin does not pay attention for the reasons why certain limitation exists, he just want to know the limitations. So I kept it in the section, but added a bit of explanation that it's a result of design choice.

comment:8 Changed 5 years ago by stephen

  • Owner changed from stephen to tomek

Reviewed commit 73e6019d83760f0500890240e2e187dcd5e1e14c

All OK, please merge.

This is a visible change so would normally require a ChangeLog entry. However, I suggest adding a single entry to cover all the documentation tickets mentioned above.

comment:9 Changed 5 years ago by tomek

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

Merged. Thanks for the review.

Note: See TracTickets for help on using tickets.