diff --git a/doc/source/examples/config-mysql-pdns.conf b/doc/source/examples/basic-config-sample-juno.conf similarity index 100% rename from doc/source/examples/config-mysql-pdns.conf rename to doc/source/examples/basic-config-sample-juno.conf diff --git a/doc/source/examples/basic-config-sample-kilo.conf b/doc/source/examples/basic-config-sample-kilo.conf new file mode 100644 index 00000000..0c6f5dbc --- /dev/null +++ b/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 + diff --git a/doc/source/examples/basic-config-sample.conf b/doc/source/examples/basic-config-sample.conf index bc65a187..0c6f5dbc 100644 --- a/doc/source/examples/basic-config-sample.conf +++ b/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 diff --git a/doc/source/install/ubuntu-dev.rst b/doc/source/install/ubuntu-dev.rst index 0af97d8c..9525a8fc 100644 --- a/doc/source/install/ubuntu-dev.rst +++ b/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 diff --git a/doc/source/install/ubuntu-juno.rst b/doc/source/install/ubuntu-juno.rst index 8ce4f557..c1195ac1 100644 --- a/doc/source/install/ubuntu-juno.rst +++ b/doc/source/install/ubuntu-juno.rst @@ -64,16 +64,18 @@ MySQL Create the MySQL user :: + $ mysql -u root -p + Enter password: - $ GRANT ALL ON designate.* TO 'designate'@'localhost' IDENTIFIED BY 'designate' - $ GRANT ALL ON powerdns.* TO 'powerdns'@'localhost' IDENTIFIED BY 'powerdns' + mysql> GRANT ALL ON designate.* TO 'designate'@'localhost' IDENTIFIED BY 'designate'; + mysql> GRANT ALL ON powerdns.* TO 'powerdns'@'localhost' IDENTIFIED BY 'powerdns'; Create the database :: - $ CREATE DATABASE designate - $ CREATE DATABASE powerdns + mysql> CREATE DATABASE `designate` CHARACTER SET utf8 COLLATE utf8_general_ci; + 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 diff --git a/doc/source/install/ubuntu-kilo.rst b/doc/source/install/ubuntu-kilo.rst new file mode 100644 index 00000000..574c7261 --- /dev/null +++ b/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 + +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 + +Create the Designate tables + +:: + + $ mysql -u root -p + Enter password: + + 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).