BIND 10 #2642: Update DHCP documentation in BIND 10 guide

[BIND 10 Development]

#2642: Update DHCP documentation in BIND 10 guide
-------------------------------------+-------------------------------------
            Reporter:  stephen       |                        Owner:  tomek
                Type:  task          |                       Status:
            Priority:  medium        |  reviewing
           Component:                |                    Milestone:
  documentation                      |  Sprint-DHCP-20130122
            Keywords:                |                   Resolution:
           Sensitive:  0             |                 CVSS Scoring:
         Sub-Project:  DHCP          |              Defect Severity:  N/A
Estimated Difficulty:  0             |  Feature Depending on Ticket:
         Total Hours:  0             |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------
Changes (by stephen):

 * owner:  stephen => tomek


Comment:

 '''Chapter 16'''[[BR]]
 > 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.
 Changed.


 '''Section 16.1'''[[BR]]
 > "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.
 I've changed the text to give a similar meaning.

 > "...if MySQL was installed in the default location"
 > Is there such a thing as default location? ...
 Not with the distros, but I think it may be possible: for example, you may
 want to install a later version of MySQL on a machine for test purposes.
 At any rate, the reference to "location" is because the installation
 procedure looks for the mysql_config program in a particular place.  If
 the location is non-standard, --with-dhcp-mysql can be used to specify the
 location.

 '''Subsection 16.1.3 "Create MySQL database and bind10 user"'''[[BR]]
 > The text should mention something about the default values.
 The default values were hardcoded pending the merging of #2559, which
 allows the database access information to be set in the BIND 10
 configuration database.  That was merged late on 21 Jan 2013, so your
 tests would have been using the temporary code.

 '''Subsection 17.2.1'''[[BR]]
 > Note: "databases used by the server need not be the same."
 Rewritten.

 > "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.
 Decoloned.

 > There are no option examples for DHCPv4. We definitely need some!
 Awaiting Marcin's input here...

 '''Section 17.3'''[[BR]]
 > RFC 2131: Please add RELEASE and NAK to supported messages list.
 Added.

 '''Section 17.4'''[[BR]]
 > 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.
 Agreed - removed.

 '''Section 18.1'''[[BR]]
 > "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.
 Changed as suggested.


 > "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.
 Removed.

 > "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.
 I've removed this, although I think we need to discuss privilege with the
 DNS team: do we use the privileged socket creator to open the privileged
 ports?


 '''Section 18.2'''[[BR]]
 > 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.
 The listing has been changed.  As to a default password, I don't think it
 would be useful: the creation of the MySQL database and authorization of
 the username under which it is accessed is wholly under control of the
 user.  The aim is to get the information in the BIND 10 configuration
 matching that entered when the database and the database user were
 created.

 '''Subsection 18.2.1'''[[BR]]
 > "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.
 Mentioned in a footnote.

 > "The usual state of affairs will be to have the database on the same
 machine as the DHCPv4 server."
 > DHCPv4 => DHCPv6.
 Changed.


 '''Subsection 18.2.2'''[[BR]]
 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.
 It was a paste error - corrected.

 > 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).
 Agree to all - that bit is up to Marcin.

 > 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.
 I don't think it's needed here - the following paragraph explains that the
 text should be entered on one line.  Adding a backslash could confuse
 things - should that be entered as well?


 >  "all the string"
 > "the whole string"
 Corrected.

 '''Subsection 18.2.3'''[[BR]]
 > We should add a note that relay traffic is not currently supported and
 add a link to 18.4.
 Done.

 '''Section 18.3'''[[BR]]
 > 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.
 Updated message list and removed option list - that will be covered by
 Marcin.


 '''Section 18.4'''[[BR]]
 > 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.
 Removed this bullet.

 > 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.
 I think this limitation is still here.  Let's not this and check when we
 do the testing.

 > 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.
 Removed.

 > We do support RENEW and RELEASE. Please update 8th bullet.
 Updated.

 '''Chapter 19'''[[BR]]
 > I think there should be a colon after "including" in the first line.
 Agree - added.

 > "While this library is currently used by b10-dhcp4 and b10-dhcp6 only"
 > Not true. Perfdhcp uses it as well.
 Generalised to "currently used by BIND 10 DHCP".

 > There is no chapter about libdhcpsrv.
 I don't think there should be - it is internal to BIND 10 and not designed
 for external use.

-- 
Ticket URL: <http://bind10.isc.org/ticket/2642#comment:7>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development