Send kea-dev mailing list submissions to
[email protected]
To subscribe or unsubscribe via the World Wide Web, visit
https://lists.isc.org/mailman/listinfo/kea-dev
or, via email, send a message with subject or body 'help' to
[email protected]
You can reach the person managing the list at
[email protected]
When replying, please edit your Subject line so it is more specific
than "Re: Contents of kea-dev digest..."
Today's Topics:
1. Kea Administrator Reference Manual question (Tomek Mrugalski)
2. Re: Kea Administrator Reference Manual question (Marcin Siodelski)
3. Re: Kea Administrator Reference Manual question
(Thomas Markwalder)
----------------------------------------------------------------------
Message: 1
Date: Wed, 11 Jun 2014 18:24:38 +0200
From: Tomek Mrugalski <[email protected]>
To: [email protected]
Subject: Kea Administrator Reference Manual question
Message-ID: <[email protected]>
Content-Type: text/plain; charset=ISO-8859-1
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).
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'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
------------------------------
Message: 2
Date: Wed, 11 Jun 2014 18:56:29 +0200
From: Marcin Siodelski <[email protected]>
To: Tomek Mrugalski <[email protected]>, [email protected]
Subject: Re: Kea Administrator Reference Manual question
Message-ID: <[email protected]>
Content-Type: text/plain; charset=ISO-8859-1
I would keep the config examples *without* line numbers, for the
following major reasons:
- It is difficult to maintain
- As a novice in using Kea I want to copy-paste the configuration and I
get irritated if I have to remove extra content which I even don't know
whether should be removed or left untouched.
I think the examples will be sufficiently small (can't be large if
pasted into the user guide) that we can refer to the certain portions of
the configuration using the BIND10 notation described in 4.2.2. If you
really have to focus the reader on some portion of the configuration you
can extract this portion from the big chunk of configuration and paste
it into the text once again.
Marcin
On 11/06/14 18:24, 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).
>
> 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'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
> [email protected]
> https://lists.isc.org/mailman/listinfo/kea-dev
>
------------------------------
Message: 3
Date: Wed, 11 Jun 2014 13:58:28 -0400
From: Thomas Markwalder <[email protected]>
To: Tomek Mrugalski <[email protected]>, Kea Dev List
<[email protected]>
Subject: Re: Kea Administrator Reference Manual question
Message-ID: <[email protected]>
Content-Type: text/plain; charset="iso-8859-1"
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
> [email protected]
> 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-0001.html>
------------------------------
_______________________________________________
kea-dev mailing list
[email protected]
https://lists.isc.org/mailman/listinfo/kea-dev
End of kea-dev Digest, Vol 3, Issue 4
*************************************
