Merge "Edits to dev guide, juno guide, and kilo guide"

doc/source/examples/basic-config-sample-kilo.conf

@@ -0,0 +1,142 @@
+[DEFAULT]
+########################
+## General Configuration
+########################
+# Show more verbose log output (sets INFO log level output)
+verbose = True
+
+# Show debugging output in logs (sets DEBUG log level output)
+debug = True
+
+# Top-level directory for maintaining designate's state.
+state_path = $pybasedir/state
+
+# Log directory
+logdir = $pybasedir/log
+
+# Driver used for issuing notifications
+notification_driver = messaging
+
+# Use "sudo designate-rootwrap /etc/designate/rootwrap.conf" to use the real
+# root filter facility.
+# Change to "sudo" to skip the filtering and just run the comand directly
+# root_helper = sudo
+
+# RabbitMQ Config
+rabbit_userid = designate
+rabbit_password = designate
+#rabbit_virtual_host = /
+#rabbit_use_ssl = False
+#rabbit_hosts = 127.0.0.1:5672
+
+########################
+## Service Configuration
+########################
+#-----------------------
+# Central Service
+#-----------------------
+[service:central]
+# Maximum domain name length
+#max_domain_name_len = 255
+
+# Maximum record name length
+#max_record_name_len = 255
+
+#-----------------------
+# API Service
+#-----------------------
+[service:api]
+# Address to bind the API server
+api_host = 0.0.0.0
+
+# Port to bind the API server
+api_port = 9001
+
+# Authentication strategy to use - can be either "noauth" or "keystone"
+auth_strategy = noauth
+
+# Enable API Version 1
+enable_api_v1 = True
+
+# Enabled API Version 1 extensions
+enabled_extensions_v1 = diagnostics, quotas, reports, sync, touch
+
+# Enable API Version 2
+enable_api_v2 = True
+
+# Enabled API Version 2 extensions
+enabled_extensions_v2 = quotas, reports
+
+#-----------------------
+# mDNS Service
+#-----------------------
+[service:mdns]
+#workers = None
+#host = 0.0.0.0
+#port = 5354
+#tcp_backlog = 100
+
+#-----------------------
+# Pool Manager Service
+#-----------------------
+[service:pool_manager]
+pool_id = 794ccc2c-d751-44fe-b57f-8894c9f5c842
+#workers = None
+#threshold_percentage = 100
+#poll_timeout = 30
+#poll_retry_interval = 2
+#poll_max_retries = 3
+#poll_delay = 1
+#periodic_recovery_interval = 120
+#periodic_sync_interval = 300
+#periodic_sync_seconds = None
+#cache_driver = sqlalchemy
+
+#####################
+## Pool Configuration
+#####################
+[pool:794ccc2c-d751-44fe-b57f-8894c9f5c842]
+nameservers = f02a0c72-c701-4ec2-85d7-197b30992ce8
+targets = f02a0c72-c701-4ec2-85d7-197b30992ce9
+
+[pool_nameserver:f02a0c72-c701-4ec2-85d7-197b30992ce8]
+host = 127.0.0.1
+port = 53
+
+[pool_target:f02a0c72-c701-4ec2-85d7-197b30992ce9]
+masters = 127.0.0.1:5354
+type = bind9
+options = port: 53, host: 127.0.0.1
+
+###################################
+## Pool Manager Cache Configuration
+###################################
+#-----------------------
+# SQLAlchemy Pool Manager Cache
+#-----------------------
+[pool_manager_cache:sqlalchemy]
+connection = mysql://root:password@127.0.0.1/designate_pool_manager
+#connection_debug = 100
+#connection_trace = False
+#sqlite_synchronous = True
+#idle_timeout = 3600
+#max_retries = 10
+#retry_interval = 10
+
+########################
+## Storage Configuration
+########################
+#-----------------------
+# SQLAlchemy Storage
+#-----------------------
+[storage:sqlalchemy]
+# Database connection string - to configure options for a given implementation
+# like sqlalchemy or other see below
+connection = mysql://root:password@127.0.0.1/designate
+#connection_debug = 100
+#connection_trace = True
+#sqlite_synchronous = True
+#idle_timeout = 3600
+#max_retries = 10
+#retry_interval = 10
+

doc/source/examples/basic-config-sample.conf

@@ -58,12 +58,12 @@ auth_strategy = noauth
 # Enable API Version 1
 enable_api_v1 = True
 
-# Enable API Version 2
-enable_api_v2 = True
-
 # Enabled API Version 1 extensions
 enabled_extensions_v1 = diagnostics, quotas, reports, sync, touch
 
+# Enable API Version 2
+enable_api_v2 = True
+
 # Enabled API Version 2 extensions
 enabled_extensions_v2 = quotas, reports
 
@@ -80,9 +80,8 @@ enabled_extensions_v2 = quotas, reports
 # Pool Manager Service
 #-----------------------
 [service:pool_manager]
-backends = bind9
-#workers = None
 pool_id = 794ccc2c-d751-44fe-b57f-8894c9f5c842
+#workers = None
 #threshold_percentage = 100
 #poll_timeout = 30
 #poll_retry_interval = 2
@@ -93,6 +92,37 @@ pool_id = 794ccc2c-d751-44fe-b57f-8894c9f5c842
 #periodic_sync_seconds = None
 #cache_driver = sqlalchemy
 
+#####################
+## Pool Configuration
+#####################
+[pool:794ccc2c-d751-44fe-b57f-8894c9f5c842]
+nameservers = f02a0c72-c701-4ec2-85d7-197b30992ce8
+targets = f02a0c72-c701-4ec2-85d7-197b30992ce9
+
+[pool_nameserver:f02a0c72-c701-4ec2-85d7-197b30992ce8]
+host = 127.0.0.1
+port = 53
+
+[pool_target:f02a0c72-c701-4ec2-85d7-197b30992ce9]
+masters = 127.0.0.1:5354
+type = bind9
+options = port: 53, host: 127.0.0.1
+
+###################################
+## Pool Manager Cache Configuration
+###################################
+#-----------------------
+# SQLAlchemy Pool Manager Cache
+#-----------------------
+[pool_manager_cache:sqlalchemy]
+connection = mysql://root:password@127.0.0.1/designate_pool_manager
+#connection_debug = 100
+#connection_trace = False
+#sqlite_synchronous = True
+#idle_timeout = 3600
+#max_retries = 10
+#retry_interval = 10
+
 ########################
 ## Storage Configuration
 ########################
@@ -110,38 +140,3 @@ connection = mysql://root:password@127.0.0.1/designate
 #max_retries = 10
 #retry_interval = 10
 
-###################################
-## Pool Manager Cache Configuration
-###################################
-#-----------------------
-# SQLAlchemy Pool Manager Cache
-#-----------------------
-[pool_manager_cache:sqlalchemy]
-connection = mysql://root:password@127.0.0.1/designate_pool_manager
-#connection_debug = 100
-#connection_trace = False
-#sqlite_synchronous = True
-#idle_timeout = 3600
-#max_retries = 10
-#retry_interval = 10
-
-#############################
-## Pool Backend Configuration
-#############################
-#-----------------------
-# Global Bind9 Pool Backend
-#-----------------------
-[backend:bind9]
-server_ids = 6a5032b6-2d96-43ee-b25b-7d784e2bf3b2
-#masters = 127.0.0.1:5354
-#rndc_host = 127.0.0.1
-#rndc_port = 953
-#rndc_config_file = /etc/rndc.conf
-#rndc_key_file = /etc/rndc.key
-
-#-----------------------
-# Server Specific Bind9 Pool Backend
-#-----------------------
-[backend:bind9:6a5032b6-2d96-43ee-b25b-7d784e2bf3b2]
-#host = 127.0.0.1
-#port = 53

doc/source/install/ubuntu-dev.rst

@@ -48,6 +48,7 @@ Installing Designate
 
 ::
 
+   $ apt-get update
    $ apt-get install python-pip python-virtualenv git
    $ apt-get build-dep python-lxml
 
@@ -76,6 +77,9 @@ Installing Designate
 
 4. Install Designate and its dependencies
 
+.. note::
+   If you run into the error: Installed distribution pbr 1.1.1 conflicts with requirement pbr>=0.6,!=0.7,<1.0, try doing pip install pbr==0.11.0
+
 ::
 
    $ pip install -r requirements.txt -r test-requirements.txt

doc/source/install/ubuntu-juno.rst

@@ -64,16 +64,18 @@ MySQL
 Create the MySQL user
 
 ::
+    $ mysql -u root -p
+    Enter password: <enter your password here>
 
-    $ GRANT ALL ON designate.* TO 'designate'@'localhost' IDENTIFIED BY 'designate'
+    mysql> GRANT ALL ON designate.* TO 'designate'@'localhost' IDENTIFIED BY 'designate';
-    $ GRANT ALL ON powerdns.* TO 'powerdns'@'localhost' IDENTIFIED BY 'powerdns'
+    mysql> GRANT ALL ON powerdns.* TO 'powerdns'@'localhost' IDENTIFIED BY 'powerdns';
 
 Create the database
 
 ::
 
-    $ CREATE DATABASE designate
+    mysql> CREATE DATABASE `designate` CHARACTER SET utf8 COLLATE utf8_general_ci;
-    $ CREATE DATABASE powerdns
+    mysql> CREATE DATABASE `powerdns` CHARACTER SET utf8 COLLATE utf8_general_ci;
 
 .. _install-ubuntu-prereq-pdns:
 
@@ -90,7 +92,7 @@ Settings::
 
 Edit the MySQL backend settings::
 
-    $ sudo editor /etc/powerdns/pdns.d/pdns.local.gmysql
+    $ sudo editor /etc/powerdns/pdns.d/pdns.local.gmysql.conf
 
 Settings::
 
@@ -102,7 +104,7 @@ Settings::
 Delete a couple unnecessary files::
 
     $ rm  /etc/powerdns/bindbackend.conf
-    $ rm /etc/powerdns/pdns.dpdns.simplebind.conf
+    $ rm /etc/powerdns/pdns.d/pdns.simplebind.conf
 
 .. _install-ubuntu-source:
 
@@ -183,7 +185,7 @@ Designate
 
 Copy or mirror the configuration from this sample file here:
 
-.. literalinclude:: /examples/config-mysql-pdns.conf
+.. literalinclude:: /examples/basic-config-sample-juno.conf
    :language: ini
 
 Sync Database schemas

doc/source/install/ubuntu-kilo.rst

@@ -0,0 +1,339 @@
+..
+    Copyright 2013 Rackspace Hosting
+
+    Licensed under the Apache License, Version 2.0 (the "License"); you may
+    not use this file except in compliance with the License. You may obtain
+    a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    License for the specific language governing permissions and limitations
+    under the License.
+
+*************************
+Installing Kilo on Ubuntu
+*************************
+
+.. _Development Environment:
+
+Development Environment
++++++++++++++++++++++++
+
+Installing Designate
+====================
+
+.. index::
+   double: install; designate
+
+1. Install system package dependencies (Ubuntu)
+
+::
+
+   $ apt-get update
+   $ apt-get install python-pip python-virtualenv git
+   $ apt-get build-dep python-lxml
+
+2. Clone the Designate repo from GitHub
+
+::
+
+   $ mkdir openstack
+   $ cd openstack
+   $ git clone https://github.com/openstack/designate.git
+   $ cd designate
+
+3. Checkout a specific version (in this case, the Kilo release)
+
+::
+
+   $ git checkout stable/kilo
+
+4. Setup a virtualenv
+
+.. note::
+   This is an optional step, but will allow Designate's dependencies
+   to be installed in a contained environment that can be easily deleted
+   if you choose to start over or uninstall Designate.
+
+::
+
+   $ virtualenv --no-site-packages .venv
+   $ . .venv/bin/activate
+
+5. Install Designate and its dependencies
+
+.. note::
+   If you run into the error: Installed distribution pbr 1.1.1 conflicts with requirement pbr>=0.6,!=0.7,<1.0, try doing pip install pbr==0.11.0
+
+::
+
+   $ pip install -r requirements.txt -r test-requirements.txt
+   $ python setup.py develop
+
+If you run into the error: "Installed distribution oslo.config 1.9.3 conflicts with requirement oslo.config>=1.11.0", add the following into requirements.txt then repeat step 5:
+
+::
+
+   python-keystoneclient>=1.1.0,<1.4.0
+   pycadf>=0.8.0,<0.9.0
+
+6. Change directories to the etc/designate folder.
+
+.. note::
+    Everything from here on out should take place in or below your designate/etc folder
+
+::
+
+   $ cd etc/designate
+
+
+7. Create Designate's config files by copying the sample config files
+
+::
+
+   $ ls *.sample | while read f; do cp $f $(echo $f | sed "s/.sample$//g"); done
+
+
+8. Make the directory for Designate’s log files
+
+::
+
+   $ mkdir -p ../../log
+
+
+9. Make the directory for Designate’s state files
+
+::
+
+   $ mkdir -p ../../state
+
+
+
+Configuring Designate
+======================
+
+.. index::
+    double: configure; designate
+
+Open the designate.conf file for editing
+
+::
+
+  $ editor designate.conf
+
+
+Copy or mirror the configuration from this sample file here:
+
+.. literalinclude:: ../examples/basic-config-sample-kilo.conf
+    :language: ini
+
+
+Installing RabbitMQ
+===================
+
+.. note::
+
+    Do the following commands as "root" or via sudo <command>
+
+Install the RabbitMQ package
+
+::
+
+    $ apt-get install rabbitmq-server
+
+Create a user:
+
+::
+
+    $ rabbitmqctl add_user designate designate
+
+Give the user access to the / vhost:
+
+::
+
+    $ sudo rabbitmqctl set_permissions -p "/" designate ".*" ".*" ".*"
+
+
+Installing MySQL
+================
+
+.. index::
+    double: install; mysql
+
+Install the MySQL server package
+
+::
+
+    $ apt-get install mysql-server-5.5
+
+
+If you do not have MySQL previously installed, you will be prompted to change the root password.
+By default, the MySQL root password for Designate is "password". You can:
+
+* Change the root password to "password"
+* If you want your own password, edit the designate.conf file and change any instance of
+   "mysql://root:password@127.0.0.1/designate" to "mysql://root:YOUR_PASSWORD@127.0.0.1/designate"
+
+You can change your MySQL password anytime with the following command::
+
+    $ mysqladmin -u root -p password NEW_PASSWORD
+    Enter password <enter your old password>
+
+Create the Designate tables
+
+::
+
+    $ mysql -u root -p
+    Enter password: <enter your password here>
+
+    mysql> CREATE DATABASE `designate` CHARACTER SET utf8 COLLATE utf8_general_ci;
+    mysql> CREATE DATABASE `designate_pool_manager` CHARACTER SET utf8 COLLATE utf8_general_ci;
+    mysql> exit;
+
+
+Install additional packages
+
+::
+
+    $ apt-get install libmysqlclient-dev
+    $ pip install mysql-python
+
+
+Installing BIND9
+================
+
+.. index::
+    double: install; bind9
+
+Install the DNS server, BIND9
+
+::
+
+      $ apt-get install bind9
+
+      # Update the BIND9 Configuration
+      $ editor /etc/bind/named.conf.options
+
+      # Change the corresponding lines in the config file:
+      options {
+        directory "/var/cache/bind";
+        dnssec-validation auto;
+        auth-nxdomain no; # conform to RFC1035
+        listen-on-v6 { any; };
+        allow-new-zones yes;
+        request-ixfr no;
+        recursion no;
+      };
+
+      # Disable AppArmor for BIND9
+      $ touch /etc/apparmor.d/disable/usr.sbin.named
+      $ service apparmor reload
+
+      # Restart BIND9:
+      $ service bind9 restart
+
+
+Initialize & Start the Central Service
+======================================
+
+.. index::
+   double: install; central
+
+
+Sync the Designate database.
+
+::
+
+   $ designate-manage database sync
+
+Start the central service.
+
+::
+
+   $ designate-central
+
+
+You'll now be seeing the log from the central service.
+
+Initialize & Start the API Service
+==================================
+
+.. index::
+   double: install; api
+
+Open up a new ssh window and log in to your server (or however you’re communicating with your server).
+
+::
+
+   $ cd openstack/designate
+
+   # Make sure your virtualenv is sourced
+   $ source .venv/bin/activate
+
+   # Start the API Service
+   $ designate-api
+
+You’ll now be seeing the log from the API service.
+
+
+Initialize & Start the Pool Manager Service
+===========================================
+
+.. index::
+   double: install; pool-manager
+
+Open up a new ssh window and log in to your server (or however you’re communicating with your server).
+
+::
+
+   # Sync the Pool Manager's cache:
+   $ designate-manage pool-manager-cache sync
+
+   # Start the pool manager service:
+   $ designate-pool-manager
+
+
+You'll now be seeing the log from the Pool Manager service.
+
+
+Initialize & Start the MiniDNS Service
+===========================================
+
+.. index::
+   double: install; minidns
+
+Open up a new ssh window and log in to your server (or however you’re communicating with your server).
+
+::
+
+   # Start the minidns service:
+   $ designate-mdns
+
+
+You'll now be seeing the log from the MiniDNS service.
+
+Exercising the API
+==================
+
+.. note:: If you have a firewall enabled, make sure to open port 53, as well as Designate's default port (9001).
+
+Using a web browser, curl statement, or a REST client, calls can be made to the
+Designate API using the following format where "api_version" is either v1 or v2
+and "command" is any of the commands listed under the corresponding version at :ref:`rest`
+
+::
+
+   http://IP.Address:9001/api_version/command
+
+You can find the IP Address of your server by running
+
+::
+
+   curl -s checkip.dyndns.org | sed -e 's/.*Current IP Address: //' -e 's/<.*$//'
+
+A couple of notes on the API:
+
+- Before Domains are created, you must create a server (/v1/servers).