Update Bind 9 backend and other documentation

Change-Id: I6b17eae84631f549371764e99de2d54cb2ac35e0

designate/backend/impl_bind9.py

@@ -13,6 +13,11 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations
 # under the License.
+
+"""
+Bind 9 backend. Create and delete zones by executing rndc
+"""
+
 import random
 
 import six
@@ -36,6 +41,7 @@ class Bind9Backend(base.Backend):
     def __init__(self, target):
         super(Bind9Backend, self).__init__(target)
 
+        # TODO(Federico): make attributes private, run _rndc_base at init time
         self.host = self.options.get('host', '127.0.0.1')
         self.port = int(self.options.get('port', 53))
         self.rndc_host = self.options.get('rndc_host', '127.0.0.1')
@@ -49,6 +55,9 @@ class Bind9Backend(base.Backend):
                                   self.options.get('clean_zonefile', 'false'))
 
     def create_zone(self, context, zone):
+        """Create a new Zone by executin rndc, then notify mDNS
+        Do not raise exceptions if the zone already exists.
+        """
         LOG.debug('Create Zone')
         masters = []
         for master in self.masters:
@@ -78,6 +87,9 @@ class Bind9Backend(base.Backend):
             self.retry_interval, self.max_retries, self.delay)
 
     def delete_zone(self, context, zone):
+        """Delete a new Zone by executin rndc
+        Do not raise exceptions if the zone does not exist.
+        """
         LOG.debug('Delete Zone')
         rndc_op = [
             'delzone',

designate/tests/test_backend/test_bind9.py

@@ -18,6 +18,8 @@ from designate import objects
 from designate.tests.test_backend import BackendTestCase
 from designate.backend.impl_bind9 import Bind9Backend
 
+# TODO(Federico): test execute() calls
+
 
 class Bind9BackendTestCase(BackendTestCase):
 

designate/utils.py

@@ -167,6 +167,8 @@ def render_template_to_file(template_name, output_path, makedirs=True,
 
 
 def execute(*cmd, **kw):
+    """Execute a command in a subprocess, blocking.
+    """
     root_helper = kw.pop('root_helper', cfg.CONF.root_helper)
     run_as_root = kw.pop('run_as_root', True)
     return processutils.execute(*cmd, run_as_root=run_as_root,

doc/source/backend.rst

@@ -12,7 +12,31 @@ Backend Base
     :undoc-members:
     :show-inheritance:
 
-Backend Dynect 
+Backend Akamai
+==============
+
+.. automodule:: designate.backend.impl_akamai
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Backend Bind9
+=============
+
+.. automodule:: designate.backend.impl_bind9
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Backend Designate
+=================
+
+.. automodule:: designate.backend.impl_designate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Backend Dynect
 ==============
 
 .. automodule:: designate.backend.impl_dynect
@@ -20,10 +44,18 @@ Backend Dynect
     :undoc-members:
     :show-inheritance:
 
-Backend Multi
-=============
+Backend Infoblox
+================
 
-.. automodule:: designate.backend.impl_multi
+.. automodule:: designate.backend.impl_infoblox
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Backend Nsd4
+============
+
+.. automodule:: designate.backend.impl_nsd4
     :members:
     :undoc-members:
     :show-inheritance:
@@ -36,4 +68,10 @@ Backend Fake
     :undoc-members:
     :show-inheritance:
 
+Backend Powerdns
+================
 
+.. automodule:: designate.backend.impl_powerdns
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/backends/bind9.rst

@@ -13,44 +13,40 @@
     License for the specific language governing permissions and limitations
     under the License.
 
-BIND9 Backend
+Bind9 Backend
 =============
 
-.. note::
-   The BIND9 backend, while functional, is lacking a solid process for
-   distributing zone files among multiple DNS servers. The soon to be introduced
-   concept of "Pools" will provide a foundation to fix this.
+This page documents using the Pool Manager Bind 9 backend.
+The backend uses the rndc utility to create and delete zones remotely.
+
+The traffic between rndc and Bind is authenticated with a key.
 
 Designate Configuration
 -----------------------
 
-Configuration Options required for BIND9 operation::
+Example configuration required for Bind9 operation. One section for each pool target::
 
-    [service:central]
-    state-path = /var/lib/designate
-    backend_driver = bind9
+    [pool_target:f26e0b32-736f-4f0a-831b-039a415c481e]
+    options = rndc_host: 192.168.27.100, rndc_port: 953, rndc_config_file: /etc/bind/rndc.conf, rndc_key_file: /etc/bind/rndc.key, port: 53, host: 192.168.27.100, clean_zonefile: false
+    masters = 192.168.27.100:5354
+    type = bind9
 
-    [backend:bind9]
-    rndc-host = 127.0.0.1
-    rndc-port = 953
-    rndc-config-file = /etc/bind9/rndc.conf  # If required by BIND9
-    rndc-key-file = /etc/bind/rndc.key
+The key and config files are relative to the host running Pool Manager (and can
+be different from the hosts running Bind)
 
-BIND9 Configuration
+Bind9 Configuration
 -------------------
 
-Include the Designate generated configuration in /etc/bind/named.conf.local::
+Ensure Bind can access the /etc/bind/rndc.conf and /etc/bind/rndc.key files and
+receive rndc traffic from Pool Manager.
 
-    include "/var/lib/designate/bind9/zones.config";
-
-Ensure BIND9 can access the above config, one way to achieve this is by
-disabling AppArmor::
-
-    $ touch /etc/apparmor.d/disable/usr.sbin.named
-    $ service apparmor reload
-    $ service bind9 restart
-
-To ensure rndc addzone/delzone functionality edit named.conf.options, or
-named.conf and add this line under options::
+Enable rndc addzone/delzone functionality by editing named.conf.options or named.conf and add this line under options::
 
     allow-new-zones yes;
+
+Example configuration of /etc/bind/rndc.key::
+
+    key "rndc-key" {
+        algorithm hmac-md5;
+        secret "<b64-encoded string>";
+    };

doc/source/mdns.rst

@@ -4,6 +4,13 @@
 MDNS
 ****
 
+MDNS Base
+=========
+.. automodule:: designate.mdns.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 MDNS Handler
 ============
 .. automodule:: designate.mdns.handler
@@ -11,15 +18,6 @@ MDNS Handler
     :undoc-members:
     :show-inheritance:
 
-
-MDNS Middleware
-===============
-.. automodule:: designate.mdns.middleware
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
 MDNS Notify
 ===========
 .. automodule:: designate.mdns.notify
@@ -27,7 +25,6 @@ MDNS Notify
     :undoc-members:
     :show-inheritance:
 
-
 MDNS RPC API
 ============
 .. automodule:: designate.mdns.rpcapi
@@ -35,11 +32,16 @@ MDNS RPC API
     :undoc-members:
     :show-inheritance:
 
-
 MDNS Service
-===============
+============
 .. automodule:: designate.mdns.service
     :members:
     :undoc-members:
     :show-inheritance:
 
+MDNS XFR
+========
+.. automodule:: designate.mdns.xfr
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/objects.rst

@@ -20,9 +20,9 @@ Objects Backlist
     :show-inheritance:
 
 
-Objects Domain
-==============
-.. automodule:: designate.objects.domain
+Objects Zone
+============
+.. automodule:: designate.objects.zone
     :members:
     :undoc-members:
     :show-inheritance: