Opened 7 years ago

Closed 7 years ago

#2305 closed defect (complete)

Document bindctl in the BIND 10 guide

Reported by: jreed Owned by: jelte
Priority: medium Milestone: Sprint-20121120
Component: ~bind-ctl (obsolete) Version:
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: Core Feature Depending on Ticket:
Estimated Difficulty: 7 Add Hours to Ticket: 0
Total Hours: 1.25 Internal?: no

Description

Add section to guide documenting the use, syntax, and behaviour of bindctl.

Subtickets

Change History (15)

comment:1 Changed 7 years ago by muks

  • Summary changed from document bindctl to Document bindctl in the BIND 10 guide

comment:2 Changed 7 years ago by jelte

  • Milestone changed from New Tasks to Sprint-20121106

comment:3 Changed 7 years ago by jelte

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

comment:4 Changed 7 years ago by jelte

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

expanded the chapter about bindctl (chapter 7).

Ready for review

comment:5 follow-up: Changed 7 years ago by jinmei

I've only gone through the text, performing sanity checks. I didn't
confirm whether each and every example actually works as documented by
hand, for example.

Specific comments:

  • I guess this change may be worth a changelog entry. But I'd leave it to you.
  • I suggest the documentation issue of #2449 is addressed within ticket, either in the new section 7 or as part of installation.
  • some concepts seem to be used before the definition, such as "named set".
  • 7.6 Configuration commands: "but similar to modules" should be "but similar to commands"?
  • 7.6.1. List of configuration commands: "must be (in JSON format)" why in parentheses? and it doesn't seem to parse well. Maybe "must be specified (in JSON format)"
  • 7.6.2. Configuration data types: the use of ';' and ',' is not consistent.
  • maps: it doesn't explain how to remove stuff from a map.
  • the example at the last of "named set" doesn't seem to make much sense.
  • 7.7.2. Notes on execute scripts: "However; as module" should be "However, as module"?
  • 7.7.2. Notes on execute scripts: I was not sure how the second paragraph relates to execute scripts.
  • there's a redundant space at the end of line:
    +Module  Boss   Master process 
    
    I'm not sure if this is an issue of XML or in the output of bindctl. In either case, the XML doc should be fixed. If it's also a bindctl issue it should also be fixed.

comment:6 Changed 7 years ago by jinmei

  • Owner changed from UnAssigned to jelte

comment:7 in reply to: ↑ 5 ; follow-up: Changed 7 years ago by jelte

  • Owner changed from jelte to jinmei

Replying to jinmei:

I've only gone through the text, performing sanity checks. I didn't
confirm whether each and every example actually works as documented by
hand, for example.

Specific comments:

  • I guess this change may be worth a changelog entry. But I'd leave it to you.

something simple like this ok? (not sure if i should add what the chapter contains)

[doc] jelte
Added a chapter about the use of the bindctl command tool to the BIND 10 guide.

  • I suggest the documentation issue of #2449 is addressed within ticket, either in the new section 7 or as part of installation.

oh right, added a note at the beginning

  • some concepts seem to be used before the definition, such as "named set".

hmm, yes, but switching them around would have the same problem... Added a few references to the section.

  • 7.6 Configuration commands: "but similar to modules" should be "but similar to commands"?

changed

  • 7.6.1. List of configuration commands: "must be (in JSON format)" why in parentheses? and it doesn't seem to parse well. Maybe "must be specified (in JSON format)"

oops, yes, added 'specified'

  • 7.6.2. Configuration data types: the use of ';' and ',' is not consistent.

changed ',' to ';'

  • maps: it doesn't explain how to remove stuff from a map.

That's because you can't :) (a map's possible entries are pre-defined by the spec file, they may be optional and have no value, but they cannot be removed completely, at least not by the user).

Changed a bit in the wording, and added a small paragraph to make this more clear

  • the example at the last of "named set" doesn't seem to make much sense.

oh hadn't noticed the bad formatting there. Updated (And added why these commands are shown)

  • 7.7.2. Notes on execute scripts: "However; as module" should be "However, as module"?

yup, changed

  • 7.7.2. Notes on execute scripts: I was not sure how the second paragraph relates to execute scripts.

ah, that was some old text that should've been removed. Removed now.

  • there's a redundant space at the end of line:
    +Module  Boss   Master process 
    
    I'm not sure if this is an issue of XML or in the output of bindctl. In either case, the XML doc should be fixed. If it's also a bindctl issue it should also be fixed.

Yup, it was in the original output (due to the python syntax used)

fixed both

comment:8 in reply to: ↑ 7 Changed 7 years ago by jinmei

Replying to jelte:

something simple like this ok? (not sure if i should add what the chapter contains)

[doc] jelte
Added a chapter about the use of the bindctl command tool to the BIND 10 guide.

Works for me.

  • there's a redundant space at the end of line:
    +Module  Boss   Master process 
    
    I'm not sure if this is an issue of XML or in the output of bindctl. In either case, the XML doc should be fixed. If it's also a bindctl issue it should also be fixed.

Yup, it was in the original output (due to the python syntax used)

I suggest checking (if you didn't) this doesn't break lettuce tests.

Other than that the branch looks okay for merge. You may want to get
review by Jeremy, though.

comment:9 Changed 7 years ago by jinmei

  • Owner changed from jinmei to jelte
  • Total Hours changed from 0 to 1.25

comment:10 follow-up: Changed 7 years ago by jreed

I made a variety of minor changes. See commit 3d71b86e777c7280043a1191bbeb0bb115f88078 -- please review the content changes in the diff.

I also have a few comments:

In the bindctl_command_arguments section, maybe write about it before examples. (Currently it just uses examples to explain it.)

", to add and remove elements." (line 1686) what is this for? Reads strange or maybe is missing some content?

Are the brackets in the list examples [value] required or optional? (See around line 1683)

Also the boss chapter examples are shown before bindctl is taught. Maybe split the boss chapter up into two chapters?

comment:11 in reply to: ↑ 10 Changed 7 years ago by jelte

  • Owner changed from jelte to jreed

Replying to jreed:

I made a variety of minor changes. See commit 3d71b86e777c7280043a1191bbeb0bb115f88078 -- please review the content changes in the diff.

look good, thanks.

I noticed one more small issue there; in the section about default_user.csv, it said 'stores username and password for logging in a file', which would suggest it would be something about logfiles. Changed it to 'for logging in in a file' (i.e. double in).

I also have a few comments:

In the bindctl_command_arguments section, maybe write about it before examples. (Currently it just uses examples to explain it.)

changed that section, is this better?

", to add and remove elements." (line 1686) what is this for? Reads strange or maybe is missing some content?

reworded.

Are the brackets in the list examples [value] required or optional? (See around line 1683)

also reworded (and some more in that paragraph)

Also the boss chapter examples are shown before bindctl is taught. Maybe split the boss chapter up into two chapters?

Yes, but maybe we should discuss that a bit (i'm thinking that initially we should only talk about boss as some component that runs the rest, and how to start the entire system. Then discuss Boss as a module in a separate chapter (i.e. perhaps simply make 3.2 its own chapter to be put either after chapter 7 or 8)

comment:12 Changed 7 years ago by jreed

Thanks for the improvements.

Please merge the changes to master. Note I made some more very few very minor changes to the branch.

I agree we should move 3.2 to its own chapter (after common configurations and before auth chapter). We can do that after this merge if you'd like or before. I think it would only need quick review via jabber is fine.

comment:13 Changed 7 years ago by jreed

Also please include a brief changelog entry. Thanks!

comment:14 Changed 7 years ago by jreed

  • Owner changed from jreed to jelte

comment:15 Changed 7 years ago by jelte

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

thanks, merged, closing ticket

(we'll do the move separately)

Note: See TracTickets for help on using tickets.