diff --git a/doc/examples/basic-config-sample.conf b/doc/examples/basic-config-sample.conf new file mode 100644 index 000000000..a74dee139 --- /dev/null +++ b/doc/examples/basic-config-sample.conf @@ -0,0 +1,156 @@ +[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 = /root/designate + +# Log directory #Make sure and create this directory, or set it to some other directory that exists +logdir = /var/log/designate + +# Driver used for issuing notifications +notification_driver = designate.openstack.common.notifier.rabbit_notifier + +# 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 + +# There has to be a better way to set these defaults +allowed_rpc_exception_modules = designate.exceptions, designate.openstack.common.exception +default_log_levels = amqplib=WARN, sqlalchemy=WARN, boto=WARN, suds=INFO, keystone=INFO, eventlet.wsgi.server=WARN, stevedore=WARN, keystoneclient.middleware.auth_token=INFO + +######################## +## Service Configuration +######################## +#----------------------- +# Central Service +#----------------------- +[service:central] +# Driver used for backend communication (e.g. fake, rpc, bind9, powerdns) +backend_driver = powerdns + +# List of blacklist domain name regexes +#domain_name_blacklist = \.arpa\.$, \.novalocal\.$, \.localhost\.$, \.localdomain\.$, \.local\.$ + +# Accepted TLD list - http://data.iana.org/TLD/tlds-alpha-by-domain.txt +accepted_tld_list = COM, NET + +# 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 the bind the API server to +api_port = 9001 + +# Authentication strategy to use - can be either "noauth" or "keystone" +auth_strategy = noauth + +# Enabled API Version 1 extensions +enabled_extensions_v1 = diagnostics, sync, import, export, reports + +#----------------------- +# Agent Service +#----------------------- +[service:agent] +# Driver used for backend communication (e.g. bind9, powerdns) +#backend_driver = bind9 + +#----------------------- +# Sink Service +#----------------------- +[service:sink] +# List of notification handlers to enable, configuration of these needs to +# correspond to a [handler:my_driver] section below or else in the config +#enabled_notification_handlers = nova_fixed + +######################## +## Storage Configuration +######################## +#----------------------- +# SQLAlchemy Storage +#----------------------- +[storage:sqlalchemy] +# Database connection string - to configure options for a given implementation +# like sqlalchemy or other see below +database_connection = sqlite:///$state_path/designate.sqlite +connection_debug = 100 +connection_trace = True +sqlite_synchronous = True +idle_timeout = 3600 +max_retries = 10 +retry_interval = 10 + +######################## +## Handler Configuration +######################## +#----------------------- +# Nova Fixed Handler +#----------------------- +[handler:nova_fixed] +#domain_id = +#notification_topics = monitor +#control_exchange = 'nova' +#format = '%(octet0)s-%(octet1)s-%(octet2)s-%(octet3)s.%(domain)s' + +#------------------------ +# Quantum Floating Handler +#------------------------ +[handler:quantum_floating] +#domain_id = +#notification_topics = monitor +#control_exchange = 'quantum' +#format = '%(octet0)s-%(octet1)s-%(octet2)s-%(octet3)s.%(domain)s' + + +######################## +## Backend Configuration +######################## +#----------------------- +# Bind9 Backend +#----------------------- +[backend:bind9] +#rndc_host = 127.0.0.1 +#rndc_port = 953 +#rndc_config_file = /etc/rndc.conf +#rndc_key_file = /etc/rndc.key + +#----------------------- +# Bind9+MySQL Backend +#----------------------- +[backend:mysqlbind9] +#database_connection = mysql://user:password@host/schema +#rndc_host = 127.0.0.1 +#rndc_port = 953 +#rndc_config_file = /etc/rndc.conf +#rndc_key_file = /etc/rndc.key +#write_database = True +#dns_server_type = master + +#----------------------- +# PowerDNS Backend +#----------------------- +[backend:powerdns] +#database_connection = mysql://root:password@localhost/pdns +database_connection = sqlite:///$state_path/pdns.sqlite +connection_debug = 100 +connection_trace = True +sqlite_synchronous = True +idle_timeout = 3600 +max_retries = 10 +retry_interval = 10 diff --git a/doc/source/gettingstarted.rst b/doc/source/gettingstarted.rst new file mode 100644 index 000000000..5a15b2e40 --- /dev/null +++ b/doc/source/gettingstarted.rst @@ -0,0 +1,196 @@ +.. + 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. + +.. _gettingstarted: + +======================== +Getting Started +======================== + +Designate provides DNS As A Service (DNSaaS) for OpenStack: + +- REST API for domain/record management +- Multi-tenant +- Integrated with Keystone for authentication +- Framework in place to integrate with Nova and Quantum notifications (for auto-generated records) + +- Support for PowerDNS and Bind9 out of the box + +Designate is comprised of three components. For more info see :doc:`architecture`. + +This guide will show how to install a simple development environment for Designate, with a PowerDNS backend. +You will be able to see Designate in action, although not to its full potential. + +For this guide you will need access to an Ubuntu Server (12.04). + +Development Environment ++++++++++++++++++++++++ + +Installing Designate +==================== + +.. index:: + double: install; designate + +1. Install system package dependencies (Ubuntu) + +:: + + $ apt-get install python-pip python-virtualenv + $ apt-get install rabbitmq-server + $ apt-get build-dep python-lxml + +2. Clone the Designate repo off of Stackforge + +:: + + $ git clone https://github.com/stackforge/designate.git + $ cd designate + + +3. Setup virtualenv + +.. note:: + This is to not interfere with system packages etc. + +:: + + $ virtualenv --no-site-packages .venv + $ . .venv/bin/activate + +4. Install Designate and its dependencies + +:: + + $ pip install -r requirements.txt -r test-requirements.txt + $ python setup.py develop + + +.. note:: + Everything from here on out should take place in or below your designate/etc folder + +5. Copy sample config files to edit + +:: + + $ cd etc/designate + $ ls *.sample | while read f; do cp $f $(echo $f | sed "s/.sample$//g"); done + +6. Install the DNS server, PowerDNS + +:: + + $ DEBIAN_FRONTEND=noninteractive apt-get install pdns-server pdns-backend-sqlite3 + #Update path to SQLite database to /root/designate/powerdns.sqlite or wherever your top level designate directory resides + $ editor /etc/powerdns/pdns.d/pdns.local.gsqlite3 + #Change the corresponding line in the config file to mirror: + gsqlite3-database=/root/designate/powerdns.sqlite + #Restart PowerDNS: + $ service pdns restart + + +7. If you intend to run Designate as a non-root user, then sudo permissions need to be granted + +:: + + $ echo "designate ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/90-designate + $ sudo chmod 0440 /etc/sudoers.d/90-designate + + +Configure Designate +=================== + +.. index:: + double: configure; designate +:: + + $ editor designate.conf + +Copy or mirror the configuration from this sample file here: + +.. literalinclude:: ../examples/basic-config-sample.conf + +Initialize & Start the Central Service +====================================== + +.. index:: + double: install; central + +:: + + #Initialize and sync the Designate database: + $ designate-manage database-init + $ designate-manage database-sync + #Initialize and sync the PowerDNS database: + $ designate-manage powerdns database-init + $ designate-manage powerdns database-sync + #Start the central service: + $ designate-central + +.. note:: + If you get an error of the form: ERROR [designate.openstack.common.rpc.common] AMQP server on localhost:5672 is unreachable: Socket closed + + Run the following command: + +:: + + $ rabbitmqctl change_password guest guest + #Then try starting the service again + $ 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 root/designate + #Make sure your virtualenv is sourced + $ . .venv/bin/activate + $ cd etc/designate + #Start the API Service + $ designate-api + #You may have to run root/designate/bin/designate-api + +You’ll now be seeing the log from the API service. + +Exercising the API +================== +Using a web browser, curl statement, or a Rest client calls can be made to the Designate API using the following format where “command” is any of the commands listed in the Designate Documentation_. + +.. _Documentation: http://designate.readthedocs.org/en/latest/rest.html + +http://IP.Address:9001/v1/command + +You can find the IP Address of your server by running + +:: + + wget http://ipecho.net/plain -O - -q ; echo + +If you’d like to see an instance in action, go here: +http://166.78.183.212:9001/ + +A couple of notes on the API: + +- Before Domains are created, you must create a server. +- On GET requests for domains, servers, records, etc be sure not to append a ‘/’ to the end of the request. For example …:9001/v1/servers/ + diff --git a/doc/source/index.rst b/doc/source/index.rst index 63677c20f..9ccfcc49e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 2 architecture + gettingstarted install configuration rest