BIND 10 #2642: Update DHCP documentation in BIND 10 guide
BIND 10 Development
do-not-reply at isc.org
Mon Jan 21 18:43:54 UTC 2013
#2642: Update DHCP documentation in BIND 10 guide
-------------------------------------+-------------------------------------
Reporter: stephen | Owner:
Type: task | stephen
Priority: medium | Status:
Component: | reviewing
documentation | Milestone:
Keywords: | Sprint-DHCP-20130122
Sensitive: 0 | Resolution:
Sub-Project: DHCP | CVSS Scoring:
Estimated Difficulty: 0 | Defect Severity: N/A
Total Hours: 0 | Feature Depending on Ticket:
| Add Hours to Ticket: 0
| Internal?: 0
-------------------------------------+-------------------------------------
Changes (by tomek):
* owner: tomek => stephen
Comment:
'''Chapter 16'''
BIND 10 offers server implementations, one for DHCPv4 and one for DHCPv6.
=>
BIND 10 offers two server implementations, one for DHCPv4 and one for
DHCPv6.
'''Section 16.1'''
> "The current version of BIND 10 DHCP stores lease information in a MySQL
database."
The default (./configure && make) does not use MySQL at all, so this
statement was not always true. I would add a bit of clarification here:
BIND 10 DHCP provides an interface for supporting several database
backend. The current version of BIND 10 DHCP stores lease information in a
MySQL database if configured to do so.
> "...if MySQL was installed in the default location"
Is there such a thing as default location? I think you meant "...if MySQL
tools are installed and available in configured PATH" or something
similar.
'''Subsection 16.1.3 "Create MySQL database and bind10 user"'''
The text should mention something about the default values. When testing
DHCPv6 server, I did not do steps explained in 18.2.1 and it all worked
for default kea/kea/kea. Perhaps the code I was using did not have the
latest changes merged, but I seriously doubt it. I did my tests on lastest
master on last Friday (Jan. 18th).
I think we should mention the defaults here.
'''Subsection 17.2.1'''
> Note: "databases used by the server need not be the same."
I would rewrite it differently as it may be understood as "must not". I
would rewrite it as "both server may store their information in one common
or two separate databases".
> "the database host name must also be specified: note however that this
configuration may have a severe impact on server performance:".
Too many colons here.
There are no option examples for DHCPv4. We definitely need some!
'''Section 17.3'''
RFC 2131: Please add RELEASE and NAK to supported messages list.
'''Section 17.4'''
The text lists RELEASE as not supported. That is not true anymore. Also,
there is no such thing as CONFIRM in DHCPv4.
I'm not sure why DNS Update is listed. This is not an essential feature.
If we want to the list to be so detailed, we should also add that
failover, leasequery, client reservations, client classification, multi
cores, and hooks are not supported as well. I think the better way forward
here would be to simply remove DNS Update from the list.
'''Section 18.1'''
> "After starting BIND 10 and entering bindctl, the first step in
configuring the server is to add it to the list of running BIND 10
services".
Please format bindctl to use bold. I think it would read better if
"entering" would be replaced with "starting". Replacing "it" with
b10-dhcp6 would help as well.
> "The currently supported client messages are SOLICIT and REQUEST. The
server will respond to them with ADVERTISE and REPLY, respectively."
This list is no longer complete. We support RENEW and RELEASE as well. I
think the best way forward would be to remove those two sentences. We have
too many places to update once we add support for new packets.
> "Since the DHCPv6 server opens privileged ports, it requires root
access. Make sure you run this daemon as root."
Does this make sense anymore? bind10 is started as root, and so are all
its daemons. It was useful remark when b10-dhcp6 was stand-alone.
'''Section 18.2'''
Second listing has some values for v6 database name and user, but the v4
counterpart does not. I think it would be easier to deploy if we had
defined some defaults. I understand the dangers of having default password
set, but still these are early days, so tradeoff for easier deployment
outweights security concerns.
We should probably add a check later that if the password is 'kea', then a
big warning is printed urging user to not use default passwords. It is
much better than a user who spend an hour trying to figure out how to
configure his database, gets bored and uses some other server.
'''Subsection 18.2.1'''
> "Currently, the only supported database is MySQL, and so the server must
be configured to access the correct database with the appropriate
credentials.".
We should probably mention here that the other alternative - memfile - is
not usable yet and is used for internal tests only. We should mention
this, because user who does ./configure && make will be confused - his
installation will say that the type is memfile, but the documentation will
claim that the only supported type is MySQL.
> "The usual state of affairs will be to have the database on the same
machine as the DHCPv4 server."
DHCPv4 => DHCPv6.
'''Subsection 18.2.2'''
Second paragraph after first example (the one staring with "It is
possible...") contains something that looks like example that is mangled
into regular text. I looked at the text, but it seems that it was an
accidental paste error. The text should read "It could be written as
2001:db8:1:0:5:: - 2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's
is cumbersome.
Options configuration definitely deserve a separate subsection (18.2.X).
Even if you think that it's part of the subnet configuration, there will
be people who will look at table of contents and will try to locate that
information. Having it separated will make it easier.
There should be a list (or at least a range) of options that we currently
support out of the box.
Do we support content-specific option defintion, e.g. specifying a simple
address for DNS Servers option? If yes, we definitely should show how such
a thing can be achieved. Current example is cryptic and requires deep
knowledge of the RFCs (user has to know option codes and option formats).
Both option examples should end a line with backslash. That's a typical
convention for wrapping too long lines that is used in the rest of this
documentation.
> "all the string"
"the whole string"
'''Subsection 18.2.3'''
We should add a note that relay traffic is not currently supported and add
a link to 18.4.
'''Section 18.3'''
We do support RENEW and RELEASE as well. We now support ORO and
STATUS_CODE options in allocation engine. I'm sure we are supporting other
options as well, but we have to ask Marcin about specific list.
'''Section 18.4'''
The first bullet mentions that the server has been tested on Debian only.
That is not true. I was able to successfully handle a lease to a client on
CentOS 6.3 64bit. We also run unit-tests on many systems.
Third bullet suggest an ugly kludge for working around the problems in
session control. With Marcin's fixes (or bit cleaner workarounds, as the
underlying issue in session control object are not fixed) in #2637, this
should be removed.
Fourth bullet discusses a limitation about supporting multiple interfaces.
This code is implemented and believed to be working properly. The whole
bullet should be removed.
Fifth bullet (ORO) is no longer valid. We do support ORO. Please remove
this bullet.
We do support RENEW and RELEASE. Please update 8th bullet.
'''Chapter 19'''
I think there should be a colon after "including" in the first line.
> "While this library is currently used by b10-dhcp4 and b10-dhcp6 only"
Not true. Perfdhcp uses it as well.
There is no chapter about libdhcpsrv.
----
I think the documentation reads better after the update. There's still a
lot of work to do, but the text starts to be really usable.
--
Ticket URL: <http://bind10.isc.org/ticket/2642#comment:6>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development
More information about the bind10-tickets
mailing list