Kea Administrator Reference Manual question

Thomas Markwalder tmark at isc.org
Wed Jun 11 17:58:28 UTC 2014


On 6/11/14, 12:24 PM, Tomek Mrugalski wrote:
> I'm working on a ticket #3418 that updates Kea User's Guide (formerly
> also known as BIND10 Guide or Administrator Reference for BIND10/Kea).
> Major part of that work is to convert all bindctl examples to JSON
> format. I did convert couple sections and would like to ask for your
> feedback.
>
> You can either get the code from trac3418 or use that generated file:
> http://git.kea.isc.org/~tomek/kea/kea-guide.html
>
> In particular, please note sections 4. (general overview of the
> configuration) and sections 5.2 (example config for Kea4) and 5.2.1
> Default storage for leases. I'm particularly interested in your comments
> on this one. It lists a number of parameters, but each of them is
> presented in slightly different way. Let me know which of those formats
> is easiest to read.
> Couple random comments:
> Section 5.2 includes an example that has line numbers. The obvious
> advantage is that it's easier to reference them. The disadvantages are
> that it's not possible to copy/paste the example and it's awkward to
> maintain (e.g. when you need to add a line somewhere at the beginning).
The example file is actually rather cluttered.  Between the line numbers
and the comments
you can't see the file structure and syntax.  Maybe try thinning it out:


*{ **
**# start Dhcp4 **
**"Dhcp4": {**
**
**# First we set up global values**
**
**    interfaces": [ "eth0" ],**
**    "valid-lifetime": 4000,**
**    "renew-timer": 1000,**
**    "rebind-timer": 2000,**
**
**# Next we, specify the type of lease database  **
**
**    "lease-database": {**
**        "type": "memfile"**
**    },**
**
**# Finally, we List the subnets from which we will be leasing.**
**
**    "subnet4": [ **
**        {   **
**            "subnet": "192.0.2.0/24"**,
**            "pool": [ "192.0.2.1 - 192.0.2.200" ]**
**        }   **
**    ]**
**} **
**}*

Thinning out the comments should make it a lot easier to discuss each
'section' without using line numbers.

Also,  notice that you can rearrange the order of the entries so they
make more sense naturally.  You are showing them in the order they would
have as Elements which is lexical based on Element name and also
influenced by Element type.  There is nothing stopping us from putting
them in logical order.   It makes the file much easier to discuss and
follow.

Just as your example farther on, if you simply swap the order of pool
and subnet, it reads much better:

*    "subnet4": [**
**    {   "subnet": "192.0.2.0/24", **
**        "pool": [ "192.0.2.1 - 192.0.2.200" ]**
**    },**
**    {   "subnet": "192.0.3.0/24", **
**        "pool": [ "192.0.3.100 - 192.0.3.200" ]**
**    },**
**    {   "subnet": "192.0.4.0/24",**
**        "pool": [ "192.0.4.1 - 192.0.4.254" ]**
**    }]*

and it will parse just fine.

The existing example also shows rebind-timer and renew-timer "commented
out"  which I assume implies they
would have a default value which gives the behavior described in the
comments.   First, this won't currently work because we don't
automatically fill in default values.   If we did, I think using that in
the first example file shown
is clutter.   I think that is something that can be described in the
reference section.

Until we resolve the defaults issue, our examples should probably show
what's required to work.  I'm guessing the
example shown would probably get rejected as lease-database does not
have all its values and the two timers
already mentioned.

> Section 4.2.2 explains the notation that is used throughout the doc. It
> was a directly applicable in bindctl, but I think it's convenient to
> keep it after migration to JSON, even though it won't be directly usable
> any more.

I would suggest perhaps replacing the word "array" with the word "list". 
When people are writing configuration files they tend to think "list"
not "array".
I know if I were discussing the pools in a subnet, I  would refer to it
as "the list of
pools in the subnet".

>
> I'm adding many <!-- @todo --> comments in the XML file. We expect parts
> of the guide to be rewritten once their respective tickets are done
> (e.g. start/stop after #3422 script is implemented).
>
> I've removed a lot of sections that were related to BIND10 framework.
>
> The guide is now split into a number of XML files, rather than one large
> XML. I think it will be easier to maintain, as finding something in 7k
> lines file was increasingly awkward.
>
> Thoughts? Comments?
>
> Tomek
>
>
> _______________________________________________
> kea-dev mailing list
> kea-dev at lists.isc.org
> https://lists.isc.org/mailman/listinfo/kea-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.isc.org/pipermail/kea-dev/attachments/20140611/87725c69/attachment.html>


More information about the kea-dev mailing list