[3036] Added a doxygen section about DNS Updates in bind10-dhcp6.

src/bin/dhcp6/dhcp6.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2012  Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC")
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted, provided that the above
@@ -90,6 +90,82 @@
  simple as possible. In fact, currently the code has to call Subnet6->getT1() and
  do not implement any fancy inheritance logic.
 
+@section dhcpv6DDNSIntegration DHCPv6 Server Support for the Dynamic DNS Updates
+
+The DHCPv6 server supports processing of the DHCPv6 Client FQDN Option described in
+the RFC4307. This Option is sent by the DHCPv6 client to instruct the server to
+update the DNS mappings for the acquired lease. A client may send its fully
+qualified domain name, a partial name or it may choose that server will generate
+the name. In the last case, the client sends an empty domain-name field in the
+DHCPv6 Client FQDN Option.
+
+As described in RFC4307, client may choose that the server delegates the forward
+DNS update to the client and that the server performs the reverse update only. Current
+version of the DHCPv6 server does not support delegation of the forward update
+to the client. The implementation of this feature is planned for the future releases.
+
+The bind10-d2 process is responsible for the actual communication with the DNS
+server, i.e. to send DNS Update messages. The bind10-dhcp6 module is responsible
+for generating so called @ref isc::d2::NameChangeRequest and sending it to the
+bind10-d2 module. The @ref isc::d2::NameChangeRequest object represents changes to the
+DNS bindings, related to acquisition, renewal or release of the lease. The bind10-dhcp6
+module implements the simple FIFO queue of the NameChangeRequest objects. The module
+logic, which processes the incoming DHCPv6 Client FQDN Options puts these requests
+into the FIFO queue.
+
+@todo Currently the FIFO queue is not processed after the NameChangeRequests are
+generated and added to it. In the future implementation steps it is planned to create
+a code which will check if there are any outstanding requests in the queue and
+send them to the bind10-d2 module when server is idle waiting for DHCP messages.
+
+Depending on the message type, a DHCPv6 server may generate 0, 1 or 2 NameChangeRequests
+during single message processing. Server generates no NameChangeRequests if it is
+not configured to update DNS or it rejects the DNS update for any other reason.
+
+Server may generate 1 NameChangeRequests in a situation when a client acquires a
+new lease or it releases an existing lease. In the former case, the NameChangeRequest
+type is CHG_ADD, which indicates that the bind10-d2 module should add a new DNS
+binding for the client, and it is assumed that there is no DNS binding for this
+client already. In the latter case, the NameChangeRequest type is CHG_REMOVE to
+indicate to the bind10-d2 module that the existing DNS binding should be removed
+from the DNS. The binding consists of the forward and reverse mapping.
+A server may only remove the mapping which it had added. Therefore, the lease database
+holds an information which updates (no update, reverse only update, both reverse and
+forward update) have been performed when the lease was acquired. Server checks
+this information to make a decision which mapping it is supposed to remove when
+a lease is released.
+
+Server may generate 2 NameChangeRequests in case the client is renewing a lease and
+it already has a DNS binding for that lease. Note, that renewal may be triggered
+as a result of sending a RENEW message as well as the REQUEST message. In both cases
+DHCPv6 server will check if there is an existing lease for the client which has sent
+a message, and if there is it will check in the lease database if the DNS Updates had
+been performed for this client. If the notion of client's FQDN changes comparing to
+the information stored in the lease database, the DHCPv6 has to remove an existing
+binding from the DNS and then add a new binding according to the new FQDN information
+received from the client. If the FQDN sent in the message which triggered a renewal
+doesn't change (comparing to the information in the lease database) the NameChangeRequest
+is not generated.
+
+@todo The decision about not generating the NameChangeRequest for the client which
+renews the lease but doesn't change its FQDN may be wrong in case it is necessary
+to inform the bind10-d2 module that the lease has been extended. However, the
+house keeper process (which removes DNS bindings for expired leases) will be
+implemented within the bind10-dhcp6 module (not the bind10-d2), so there is no
+need to store lease lifetime information in the bind10-d2 and thus send it there.
+
+The DHCPv6 Client FQDN Option is comprises "NOS" flags which communicate to the
+server what updates (if any), client expects the server to perform. Server
+may be configured to obey client's preference or do FQDN processing in a
+different way. If the server overrides client's preference it will communicate it
+by sending the DHCPv6 Client FQDN Option in its responses to a client, with
+appropriate flags set.
+
+@todo Note, that current implementation doesn't allow configuration of the server's behaviour
+with respect to DNS Updates. This is planned for the future. The default behaviour is
+constituted by the set of constants defined in the (upper part of) dhcp6_srv.cc file.
+Once the configuration is implemented, these constants will be removed.
+
  @todo Add section about setting up options and their definitions with bindctl.
 
  */