GitList

Browse code

Convert all HTML doc to RST

The motivation for this conversion is to have DevStack's docs be
generated using a more familair workflow for OpenStack projects, using
Sphinx.

Changing from raw HTML to RST will also make it easier to contribute
more documentation, as well as making edits less of a hassle.

The majority of the work was done by using Pandoc to convert from HTML
to RST, with minor edits to the output to remove errors in Sphinx.

Change-Id: I9636017965aeade37b950ddf5bdb0c22ab9004bd

Sean M. Collins authored on 2014/10/22 00:40:08
Showing 42 changed files

doc/source/changes.html index 028e1cf..0000000
doc/source/changes.rst index 0000000..7ce629f
doc/source/conf.py index 0000000..3e9aa45
doc/source/configuration.html index 88d7476..0000000
doc/source/configuration.rst index 0000000..694ad62
doc/source/contributing.html index 9826fc7..0000000
doc/source/contributing.rst index 0000000..e37c06b
doc/source/eucarc.html index 1dd8096..0000000
doc/source/eucarc.rst index 0000000..c1065e6
doc/source/exerciserc.html index 313b0a1..0000000
doc/source/exerciserc.rst index 0000000..22aff9a
doc/source/faq.html index 7cbb9d2..0000000
doc/source/faq.rst index 0000000..9adc58e
doc/source/guides/multinode-lab.html index 6a5f98c..0000000
doc/source/guides/multinode-lab.rst index 0000000..c7901a2
doc/source/guides/pxe-boot.html index d52b25f..0000000
doc/source/guides/pxe-boot.rst index 0000000..584e558
doc/source/guides/ramdisk.html index 23239e2..0000000
doc/source/guides/ramdisk.rst index 0000000..82147a8
doc/source/guides/single-machine.html index 06cc981..0000000
doc/source/guides/single-machine.rst index 0000000..0db0466
doc/source/guides/single-vm.html index d189319..0000000
doc/source/guides/single-vm.rst index 0000000..0e2d157
doc/source/guides/usb-boot.html index 2a05f89..0000000
doc/source/guides/usb-boot.rst index 0000000..888e14f
doc/source/index.html index 5f1efd7..0000000
doc/source/index.rst index 0000000..6e5105d
doc/source/local.conf.html index 2635ac6..0000000
doc/source/local.conf.rst index 0000000..40d0e0f
doc/source/localrc.html index 40a2004..0000000
doc/source/localrc.rst index 0000000..910e274
doc/source/openrc.html index 94b253d..0000000
doc/source/openrc.rst index 0000000..b8759ec
doc/source/overview.html index 9cee052..0000000
doc/source/overview.rst index 0000000..953938b
doc/source/plugins.html index 700a209..0000000
doc/source/plugins.rst index 0000000..db695d3
doc/source/stackrc.html index 2df9d38..0000000
doc/source/stackrc.rst index 0000000..b2766cb
setup.cfg index 0000000..5887134
setup.py index 0000000..70c2b3f
tox.ini index 3677631..b6f2d96 100644

                     deleted file mode 100644
@@ -1,70 +0,0 @@
                     -<!DOCTYPE html>
                     -<html lang="en">
                     -  <head>
                     -    <meta charset="utf-8">
                     -    <title>DevStack - Recent Changes</title>
                     -    <meta name="description" content="">
                     -    <meta name="author" content="">
+                    -
                     -    <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
                     -    <!--[if lt IE 9]>
                     -      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
                     -    <![endif]-->
+                    -
                     -    <!-- Le styles -->
                     -    <link href="assets/css/bootstrap.css" rel="stylesheet">
                     -    <link href="assets/css/local.css" rel="stylesheet">
                     -    <style type="text/css">
                     -      body { padding-top: 60px; }
                     -      dd { padding: 10px; }
                     -    </style>
+                    -
                     -    <!-- Le javascripts -->
                     -    <script src="assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
                     -    <script src="assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
                     -  </head>
+                    -
                     -  <body>
+                    -
                     -    <div class="navbar navbar-fixed-top">
                     -      <div class="navbar-inner">
                     -        <div class="container">
                     -          <a class="brand" href="/">DevStack</a>
                     -          <ul class="nav pull-right">
                     -            <li><a href="overview.html">Overview</a></li>
                     -            <li><a href="changes.html">Changes</a></li>
                     -            <li><a href="faq.html">FAQ</a></li>
                     -            <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
                     -            <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
                     -          </ul>
                     -        </div>
                     -      </div>
                     -    </div>
+                    -
                     -    <div class="container" id="home">
+                    -
                     -      <section id="faq" class="span12">
+                    -
                     -        <div class='row pull-left'>
                     -          <h2>Recent Changes <small>What's been happening?</small></h2>
                     -          <p>These are the commits to DevStack for the last six months.  For the complete list see <a href="https://review.openstack.org/#/q/status:merged+project:openstack-dev/devstack,n,z">the DevStack project in Gerrit</a>.</p>
+                    -
                     -          <ul class='pull-left'>
                     -            <!--
                     -              This list is generated by:
                     -              git log --pretty=format:'            <li>%s - <em>Commit <a href="https://review.openstack.org/#q,%h,n,z">%h</a> %cd</em></li>' --date=short --since 2014-01-01 | grep -v Merge
                     -            -->
                     -            <!-- Begin git log %GIT_LOG% -->
                     -            <!-- End git log -->
                     -          </ul>
                     -        </div>
+                    -
                     -      </section>
+                    -
                     -      <footer>
                     -        <p>&copy; Openstack Foundation 2011-2014 &mdash; An <a href="https://www.openstack.org/">OpenStack</a> <a href="https://wiki.openstack.org/wiki/Programs">program</a></p>
                     -      </footer>
+                    -
                     -    </div> <!-- /container -->
                     -  </body>
                     -</html>

                     new file mode 100644
@@ -0,0 +1,18 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Recent Changes What's been happening?
                     +-------------------------------------
+                    +
                     +These are the commits to DevStack for the last six months. For the
                     +complete list see `the DevStack project in
                     +Gerrit <https://review.openstack.org/#/q/status:merged+project:openstack-dev/devstack,n,z>`__.
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,263 @@
                     +# -*- coding: utf-8 -*-
                     +#
                     +# Tempest documentation build configuration file, created by
                     +# sphinx-quickstart on Tue May 21 17:43:32 2013.
                     +#
                     +# This file is execfile()d with the current directory set to its containing dir.
                     +#
                     +# Note that not all possible configuration values are present in this
                     +# autogenerated file.
                     +#
                     +# All configuration values have a default; values that are commented out
                     +# serve to show the default.
+                    +
                     +import sys
                     +import os
+                    +
                     +# If extensions (or modules to document with autodoc) are in another directory,
                     +# add these directories to sys.path here. If the directory is relative to the
                     +# documentation root, use os.path.abspath to make it absolute, like shown here.
                     +#sys.path.insert(0, os.path.abspath('.'))
+                    +
                     +# -- General configuration -----------------------------------------------------
+                    +
                     +# If your documentation needs a minimal Sphinx version, state it here.
                     +#needs_sphinx = '1.0'
+                    +
                     +# Add any Sphinx extension module names here, as strings. They can be extensions
                     +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
                     +extensions = [ 'oslosphinx' ]
+                    +
                     +todo_include_todos = True
+                    +
                     +# Add any paths that contain templates here, relative to this directory.
                     +templates_path = ['_templates']
+                    +
                     +# The suffix of source filenames.
                     +source_suffix = '.rst'
+                    +
                     +# The encoding of source files.
                     +#source_encoding = 'utf-8-sig'
+                    +
                     +# The master toctree document.
                     +master_doc = 'index'
+                    +
                     +# General information about the project.
                     +project = u'DevStack'
                     +copyright = u'2014, OpenStack Foundation'
+                    +
                     +# The language for content autogenerated by Sphinx. Refer to documentation
                     +# for a list of supported languages.
                     +#language = None
+                    +
                     +# There are two options for replacing |today|: either, you set today to some
                     +# non-false value, then it is used:
                     +#today = ''
                     +# Else, today_fmt is used as the format for a strftime call.
                     +#today_fmt = '%B %d, %Y'
+                    +
                     +# List of patterns, relative to source directory, that match files and
                     +# directories to ignore when looking for source files.
                     +exclude_patterns = ['_build']
+                    +
                     +# The reST default role (used for this markup: `text`) to use for all documents.
                     +#default_role = None
+                    +
                     +# If true, '()' will be appended to :func: etc. cross-reference text.
                     +#add_function_parentheses = True
+                    +
                     +# If true, the current module name will be prepended to all description
                     +# unit titles (such as .. function::).
                     +add_module_names = False
+                    +
                     +# If true, sectionauthor and moduleauthor directives will be shown in the
                     +# output. They are ignored by default.
                     +show_authors = False
+                    +
                     +# The name of the Pygments (syntax highlighting) style to use.
                     +pygments_style = 'sphinx'
+                    +
                     +# A list of ignored prefixes for module index sorting.
                     +modindex_common_prefix = ['DevStack-doc.']
+                    +
                     +# -- Options for man page output ----------------------------------------------
                     +man_pages = []
+                    +
                     +# -- Options for HTML output ---------------------------------------------------
+                    +
                     +# The theme to use for HTML and HTML Help pages.  See the documentation for
                     +# a list of builtin themes.
                     +html_theme = 'nature'
+                    +
                     +# Theme options are theme-specific and customize the look and feel of a theme
                     +# further.  For a list of options available for each theme, see the
                     +# documentation.
                     +#html_theme_options = {}
+                    +
                     +# Add any paths that contain custom themes here, relative to this directory.
                     +#html_theme_path = []
+                    +
                     +# The name for this set of Sphinx documents.  If None, it defaults to
                     +# "<project> v<release> documentation".
                     +#html_title = None
+                    +
                     +# A shorter title for the navigation bar.  Default is the same as html_title.
                     +#html_short_title = None
+                    +
                     +# The name of an image file (relative to this directory) to place at the top
                     +# of the sidebar.
                     +#html_logo = None
+                    +
                     +# The name of an image file (within the static path) to use as favicon of the
                     +# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
                     +# pixels large.
                     +#html_favicon = None
+                    +
                     +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
                     +# using the given strftime format.
                     +git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
                     +html_last_updated_fmt = os.popen(git_cmd).read()
+                    +
                     +# If true, SmartyPants will be used to convert quotes and dashes to
                     +# typographically correct entities.
                     +#html_use_smartypants = True
+                    +
                     +# Custom sidebar templates, maps document names to template names.
                     +#html_sidebars = {}
+                    +
                     +# Additional templates that should be rendered to pages, maps page names to
                     +# template names.
                     +#html_additional_pages = {}
+                    +
                     +# If false, no module index is generated.
                     +html_domain_indices = False
+                    +
                     +# If false, no index is generated.
                     +html_use_index = False
+                    +
                     +# If true, the index is split into individual pages for each letter.
                     +#html_split_index = False
+                    +
                     +# If true, links to the reST sources are added to the pages.
                     +#html_show_sourcelink = True
+                    +
                     +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
                     +#html_show_sphinx = True
+                    +
                     +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
                     +#html_show_copyright = True
+                    +
                     +# If true, an OpenSearch description file will be output, and all pages will
                     +# contain a <link> tag referring to it.  The value of this option must be the
                     +# base URL from which the finished HTML is served.
                     +#html_use_opensearch = ''
+                    +
                     +# This is the file name suffix for HTML files (e.g. ".xhtml").
                     +#html_file_suffix = None
+                    +
                     +# Output file base name for HTML help builder.
                     +htmlhelp_basename = 'DevStack-doc'
+                    +
+                    +
                     +# -- Options for LaTeX output --------------------------------------------------
+                    +
                     +latex_elements = {
                     +# The paper size ('letterpaper' or 'a4paper').
                     +#'papersize': 'letterpaper',
+                    +
                     +# The font size ('10pt', '11pt' or '12pt').
                     +#'pointsize': '10pt',
+                    +
                     +# Additional stuff for the LaTeX preamble.
                     +#'preamble': '',
                     +}
+                    +
                     +# Grouping the document tree into LaTeX files. List of tuples
                     +# (source start file, target name, title, author, documentclass [howto/manual]).
                     +latex_documents = [
                     +  ('index', 'DevStack-doc.tex', u'DevStack Docs',
                     +   u'OpenStack DevStack Team', 'manual'),
                     +]
+                    +
                     +# The name of an image file (relative to this directory) to place at the top of
                     +# the title page.
                     +#latex_logo = None
+                    +
                     +# For "manual" documents, if this is true, then toplevel headings are parts,
                     +# not chapters.
                     +#latex_use_parts = False
+                    +
                     +# If true, show page references after internal links.
                     +#latex_show_pagerefs = False
+                    +
                     +# If true, show URL addresses after external links.
                     +#latex_show_urls = False
+                    +
                     +# Documents to append as an appendix to all manuals.
                     +#latex_appendices = []
+                    +
                     +# If false, no module index is generated.
                     +#latex_domain_indices = True
+                    +
                     +# -- Options for Texinfo output ------------------------------------------------
+                    +
                     +# Grouping the document tree into Texinfo files. List of tuples
                     +# (source start file, target name, title, author,
                     +#  dir menu entry, description, category)
                     +texinfo_documents = [
                     +  ('index', 'DevStack-doc', u'DevStack Docs',
                     +   u'OpenStack DevStack Team', 'DevStack-doc', 'DevStack documentation',
                     +   'Miscellaneous'),
                     +]
+                    +
                     +# Documents to append as an appendix to all manuals.
                     +#texinfo_appendices = []
+                    +
                     +# If false, no module index is generated.
                     +#texinfo_domain_indices = True
+                    +
                     +# How to display URL addresses: 'footnote', 'no', or 'inline'.
                     +#texinfo_show_urls = 'footnote'
+                    +
+                    +
                     +# -- Options for Epub output ---------------------------------------------------
+                    +
                     +# Bibliographic Dublin Core info.
                     +epub_title = u'DevStack Documentation'
                     +epub_author = u'OpenStack DevStack Team'
                     +epub_publisher = u'OpenStack DevStack Team'
                     +epub_copyright = u'2014, OpenStack DevStack Team'
+                    +
                     +# The language of the text. It defaults to the language option
                     +# or en if the language is not set.
                     +#epub_language = ''
+                    +
                     +# The scheme of the identifier. Typical schemes are ISBN or URL.
                     +#epub_scheme = ''
+                    +
                     +# The unique identifier of the text. This can be a ISBN number
                     +# or the project homepage.
                     +#epub_identifier = ''
+                    +
                     +# A unique identification for the text.
                     +#epub_uid = ''
+                    +
                     +# A tuple containing the cover image and cover page html template filenames.
                     +#epub_cover = ()
+                    +
                     +# HTML files that should be inserted before the pages created by sphinx.
                     +# The format is a list of tuples containing the path and title.
                     +#epub_pre_files = []
+                    +
                     +# HTML files shat should be inserted after the pages created by sphinx.
                     +# The format is a list of tuples containing the path and title.
                     +#epub_post_files = []
+                    +
                     +# A list of files that should not be packed into the epub file.
                     +#epub_exclude_files = []
+                    +
                     +# The depth of the table of contents in toc.ncx.
                     +#epub_tocdepth = 3
+                    +
                     +# Allow duplicate toc entries.
                     +#epub_tocdup = True

                     new file mode 100644
@@ -0,0 +1,360 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Configuration Making it go my way
                     +---------------------------------
+                    +
                     +DevStack has always tried to be mostly-functional with a minimal amount
                     +of configuration. The number of options has ballooned as projects add
                     +features, new projects added and more combinations need to be tested.
                     +Historically DevStack obtained all local configuration and
                     +customizations from a ``localrc`` file. The number of configuration
                     +variables that are simply passed-through to the individual project
                     +configuration files is also increasing. The old mechanism for this
                     +(``EXTRAS_OPTS`` and friends) required specific code for each file and
                     +did not scale well.
+                    +
                     +In Oct 2013 a new configuration method was introduced (in `review
                     +46768 <https://review.openstack.org/#/c/46768/>`__) to hopefully
                     +simplify this process and meet the following goals:
+                    +
                     +-  contain all non-default local configuration in a single file
                     +-  be backward-compatible with ``localrc`` to smooth the transition
                     +   process
                     +-  allow settings in arbitrary configuration files to be changed
+                    +
                     +local.conf
                     +~~~~~~~~~~
+                    +
                     +The new configuration file is ``local.conf`` and resides in the root
                     +DevStack directory like the old ``localrc`` file. It is a modified INI
                     +format file that introduces a meta-section header to carry additional
                     +information regarding the configuration files to be changed.
+                    +
                     +The new header is similar to a normal INI section header but with double
                     +brackets (``[[ ... ]]``) and two internal fields separated by a pipe
                     +(``|``):
+                    +
                     +::
+                    +
                     +    [[ <phase> | <config-file-name> ]]
+                    +
                     +where ``<phase>`` is one of a set of phase names defined by ``stack.sh``
                     +and ``<config-file-name>`` is the configuration filename. The filename
                     +is eval'ed in the ``stack.sh`` context so all environment variables are
                     +available and may be used. Using the project config file variables in
                     +the header is strongly suggested (see the ``NOVA_CONF`` example below).
                     +If the path of the config file does not exist it is skipped.
+                    +
                     +The defined phases are:
+                    +
                     +-  **local** - extracts ``localrc`` from ``local.conf`` before
                     +   ``stackrc`` is sourced
                     +-  **pre-install** - runs after the system packages are installed but
                     +   before any of the source repositories are installed
                     +-  **install** - runs immediately after the repo installations are
                     +   complete
                     +-  **post-config** - runs after the layer 2 services are configured and
                     +   before they are started
                     +-  **extra** - runs after services are started and before any files in
                     +   ``extra.d`` are executed
+                    +
                     +The file is processed strictly in sequence; meta-sections may be
                     +specified more than once but if any settings are duplicated the last to
                     +appear in the file will be used.
+                    +
                     +::
+                    +
                     +    [[post-config|$NOVA_CONF]]
                     +    [DEFAULT]
                     +    use_syslog = True
+                    +
                     +    [osapi_v3]
                     +    enabled = False
+                    +
                     +A specific meta-section ``local|localrc`` is used to provide a default
                     +``localrc`` file (actually ``.localrc.auto``). This allows all custom
                     +settings for DevStack to be contained in a single file. If ``localrc``
                     +exists it will be used instead to preserve backward-compatibility. More
                     +details on the `contents of localrc <localrc.html>`__ are available.
+                    +
                     +::
+                    +
                     +    [[local|localrc]]
                     +    FIXED_RANGE=10.254.1.0/24
                     +    ADMIN_PASSWORD=speciale
                     +    LOGFILE=$DEST/logs/stack.sh.log
+                    +
                     +Note that ``Q_PLUGIN_CONF_FILE`` is unique in that it is assumed to
                     +*NOT* start with a ``/`` (slash) character. A slash will need to be
                     +added:
+                    +
                     +::
+                    +
                     +    [[post-config|/$Q_PLUGIN_CONF_FILE]]
+                    +
                     +Also note that the ``localrc`` section is sourced as a shell script
                     +fragment amd MUST conform to the shell requirements, specifically no
                     +whitespace around ``=`` (equals).
+                    +
                     +Minimal Configuration
                     +~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +While ``stack.sh`` is happy to run without a ``localrc`` section in
                     +``local.conf``, devlife is better when there are a few minimal variables
                     +set. This is an example of a minimal configuration that touches the
                     +values that most often need to be set.
+                    +
                     +-  no logging
                     +-  pre-set the passwords to prevent interactive prompts
                     +-  move network ranges away from the local network (``FIXED_RANGE`` and
                     +   ``FLOATING_RANGE``, commented out below)
                     +-  set the host IP if detection is unreliable (``HOST_IP``, commented
                     +   out below)
+                    +
                     +::
+                    +
                     +    [[local|localrc]]
                     +    ADMIN_PASSWORD=secrete
                     +    DATABASE_PASSWORD=$ADMIN_PASSWORD
                     +    RABBIT_PASSWORD=$ADMIN_PASSWORD
                     +    SERVICE_PASSWORD=$ADMIN_PASSWORD
                     +    SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50
                     +    #FIXED_RANGE=172.31.1.0/24
                     +    #FLOATING_RANGE=192.168.20.0/25
                     +    #HOST_IP=10.3.4.5
+                    +
                     +If the ``*_PASSWORD`` variables are not set here you will be prompted to
                     +enter values for them by ``stack.sh``.
+                    +
                     +The network ranges must not overlap with any networks in use on the
                     +host. Overlap is not uncommon as RFC-1918 'private' ranges are commonly
                     +used for both the local networking and Nova's fixed and floating ranges.
+                    +
                     +``HOST_IP`` is normally detected on the first run of ``stack.sh`` but
                     +often is indeterminate on later runs due to the IP being moved from an
                     +Ethernet integace to a bridge on the host. Setting it here also makes it
                     +available for ``openrc`` to set ``OS_AUTH_URL``. ``HOST_IP`` is not set
                     +by default.
+                    +
                     +Common Configuration Variables
                     +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +Set DevStack install directory
                     +    | *Default: ``DEST=/opt/stack``*
                     +    |  The DevStack install directory is set by the ``DEST`` variable.
                     +    |  By setting it early in the ``localrc`` section you can reference it
                     +       in later variables. It can be useful to set it even though it is not
                     +       changed from the default value.
                     +    |
+                    +
                     +    ::
+                    +
                     +        DEST=/opt/stack
+                    +
                     +stack.sh logging
                     +    | *Defaults: ``LOGFILE="" LOGDAYS=7 LOG_COLOR=True``*
                     +    |  By default ``stack.sh`` output is only written to the console
                     +       where is runs. It can be sent to a file in addition to the console
                     +       by setting ``LOGFILE`` to the fully-qualified name of the
                     +       destination log file. A timestamp will be appended to the given
                     +       filename for each run of ``stack.sh``.
                     +    |
+                    +
                     +    ::
+                    +
                     +        LOGFILE=$DEST/logs/stack.sh.log
+                    +
                     +    Old log files are cleaned automatically if ``LOGDAYS`` is set to the
                     +    number of days of old log files to keep.
+                    +
                     +    ::
+                    +
                     +        LOGDAYS=1
+                    +
                     +    The some of the project logs (Nova, Cinder, etc) will be colorized
                     +    by default (if ``SYSLOG`` is not set below); this can be turned off
                     +    by setting ``LOG_COLOR`` False.
+                    +
                     +    ::
+                    +
                     +        LOG_COLOR=False
+                    +
                     +Screen logging
                     +    | *Default: ``SCREEN_LOGDIR=""``*
                     +    |  By default DevStack runs the OpenStack services using ``screen``
                     +       which is useful for watching log and debug output. However, in
                     +       automated testing the interactive ``screen`` sessions may not be
                     +       available after the fact; setting ``SCREEN_LOGDIR`` enables logging
                     +       of the ``screen`` sessions in the specified diretory. There will be
                     +       one file per ``screen`` session named for the session name and a
                     +       timestamp.
                     +    |
+                    +
                     +    ::
+                    +
                     +        SCREEN_LOGDIR=$DEST/logs/screen
+                    +
                     +    *Note the use of ``DEST`` to locate the main install directory; this
                     +    is why we suggest setting it in ``local.conf``.*
+                    +
                     +One syslog to bind them all
                     +    | *Default: ``SYSLOG=False SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516``*
                     +    |  Logging all services to a single syslog can be convenient. Enable
                     +       syslogging by setting ``SYSLOG`` to ``True``. If the destination log
                     +       host is not localhost ``SYSLOG_HOST`` and ``SYSLOG_PORT`` can be
                     +       used to direct the message stream to the log host.
                     +    |
+                    +
                     +    ::
+                    +
                     +        SYSLOG=True
                     +        SYSLOG_HOST=$HOST_IP
                     +        SYSLOG_PORT=516
+                    +
                     +A clean install every time
                     +    | *Default: ``RECLONE=""``*
                     +    |  By default ``stack.sh`` only clones the project repos if they do
                     +       not exist in ``$DEST``. ``stack.sh`` will freshen each repo on each
                     +       run if ``RECLONE`` is set to ``yes``. This avoids having to manually
                     +       remove repos in order to get the current branch from ``$GIT_BASE``.
                     +    |
+                    +
                     +    ::
+                    +
                     +        RECLONE=yes
+                    +
                     +                    Swift
                     +                    Default: SWIFT_HASH="" SWIFT_REPLICAS=1 SWIFT_DATA_DIR=$DEST/data/swift
                     +                    Swift is now used as the back-end for the S3-like object store.  When enabled Nova's objectstore (n-obj in ENABLED_SERVICES) is automatically disabled. Enable Swift by adding it services to ENABLED_SERVICES:
                     +                    enable_service s-proxy s-object s-container s-account
+                    +
                     +    Setting Swift's hash value is required and you will be prompted for
                     +    it if Swift is enabled so just set it to something already:
+                    +
                     +    ::
+                    +
                     +        SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5
+                    +
                     +    For development purposes the default number of replicas is set to
                     +    ``1`` to reduce the overhead required. To better simulate a
                     +    production deployment set this to ``3`` or more.
+                    +
                     +    ::
+                    +
                     +        SWIFT_REPLICAS=3
+                    +
                     +    The data for Swift is stored in the source tree by default (in
                     +    ``$DEST/swift/data``) and can be moved by setting
                     +    ``SWIFT_DATA_DIR``. The specified directory will be created if it
                     +    does not exist.
+                    +
                     +    ::
+                    +
                     +        SWIFT_DATA_DIR=$DEST/data/swift
+                    +
                     +    *Note: Previously just enabling ``swift`` was sufficient to start
                     +    the Swift services. That does not provide proper service
                     +    granularity, particularly in multi-host configurations, and is
                     +    considered deprecated. Some service combination tests now check for
                     +    specific Swift services and the old blanket acceptance will longer
                     +    work correctly.*
+                    +
                     +Service Catalog Backend
                     +    | *Default: ``KEYSTONE_CATALOG_BACKEND=sql``*
                     +    |  DevStack uses Keystone's ``sql`` service catalog backend. An
                     +       alternate ``template`` backend is also available. However, it does
                     +       not support the ``service-*`` and ``endpoint-*`` commands of the
                     +       ``keystone`` CLI. To do so requires the ``sql`` backend be enabled:
                     +    |
+                    +
                     +    ::
+                    +
                     +        KEYSTONE_CATALOG_BACKEND=template
+                    +
                     +    DevStack's default configuration in ``sql`` mode is set in
                     +    ``files/keystone_data.sh``
+                    +
                     +Cinder
                     +    | Default:
                     +    | VOLUME_GROUP="stack-volumes" VOLUME_NAME_PREFIX="volume-" VOLUME_BACKING_FILE_SIZE=10250M
                     +    |  The logical volume group used to hold the Cinder-managed volumes
                     +       is set by ``VOLUME_GROUP``, the logical volume name prefix is set
                     +       with ``VOLUME_NAME_PREFIX`` and the size of the volume backing file
                     +       is set with ``VOLUME_BACKING_FILE_SIZE``.
                     +    |
+                    +
                     +    ::
+                    +
                     +        VOLUME_GROUP="stack-volumes"
                     +        VOLUME_NAME_PREFIX="volume-"
                     +        VOLUME_BACKING_FILE_SIZE=10250M
+                    +
                     +Multi-host DevStack
                     +    | *Default: ``MULTI_HOST=False``*
                     +    |  Running DevStack with multiple hosts requires a custom
                     +       ``local.conf`` section for each host. The master is the same as a
                     +       single host installation with ``MULTI_HOST=True``. The slaves have
                     +       fewer services enabled and a couple of host variables pointing to
                     +       the master.
                     +    |  **Master**
+                    +
                     +    ::
+                    +
                     +        MULTI_HOST=True
+                    +
                     +    **Slave**
+                    +
                     +    ::
+                    +
                     +        MYSQL_HOST=w.x.y.z
                     +        RABBIT_HOST=w.x.y.z
                     +        GLANCE_HOSTPORT=w.x.y.z:9292
                     +        ENABLED_SERVICES=n-vol,n-cpu,n-net,n-api
+                    +
                     +API rate limits
                     +    | Default: ``API_RATE_LIMIT=True``
                     +    | Integration tests such as Tempest will likely run afoul of the
                     +      default rate limits configured for Nova. Turn off rate limiting
                     +      during testing by setting ``API_RATE_LIMIT=False``.*
                     +    |
+                    +
                     +    ::
+                    +
                     +        API_RATE_LIMIT=False
+                    +
                     +Examples
                     +~~~~~~~~
+                    +
                     +-  Eliminate a Cinder pass-through (``CINDER_PERIODIC_INTERVAL``):
+                    +
                     +   ::
+                    +
                     +       [[post-config|$CINDER_CONF]]
                     +       [DEFAULT]
                     +       periodic_interval = 60
+                    +
                     +-  Sample ``local.conf`` with screen logging enabled:
+                    +
                     +   ::
+                    +
                     +       [[local|localrc]]
                     +       FIXED_RANGE=10.254.1.0/24
                     +       NETWORK_GATEWAY=10.254.1.1
                     +       LOGDAYS=1
                     +       LOGFILE=$DEST/logs/stack.sh.log
                     +       SCREEN_LOGDIR=$DEST/logs/screen
                     +       ADMIN_PASSWORD=quiet
                     +       DATABASE_PASSWORD=$ADMIN_PASSWORD
                     +       RABBIT_PASSWORD=$ADMIN_PASSWORD
                     +       SERVICE_PASSWORD=$ADMIN_PASSWORD
                     +       SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,105 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Contributing Help us help you
                     +-----------------------------
+                    +
                     +DevStack uses the standard OpenStack contribution process as outlined in
                     +`the OpenStack wiki 'How To
                     +Contribute' <https://wiki.openstack.org/wiki/How_To_Contribute>`__. This
                     +means that you will need to meet the requirements of the Contribututors
                     +License Agreement (CLA). If you have already done that for another
                     +OpenStack project you are good to go.
+                    +
                     +Things To Know
                     +~~~~~~~~~~~~~~
+                    +
                     +|
                     +| **Where Things Are**
+                    +
                     +The official DevStack repository is located at
                     +``git://git.openstack.org/openstack-dev/devstack.git``, replicated from
                     +the repo maintained by Gerrit. GitHub also has a mirror at
                     +``git://github.com/openstack-dev/devstack.git``.
+                    +
                     +The `blueprint <https://blueprints.launchpad.net/devstack>`__ and `bug
                     +trackers <https://bugs.launchpad.net/devstack>`__ are on Launchpad. It
                     +should be noted that DevStack generally does not use these as strongly
                     +as other projects, but we're trying to change that.
+                    +
                     +The `Gerrit review
                     +queue <https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z>`__
                     +is, however, used for all commits except for the text of this website.
                     +That should also change in the near future.
+                    +
                     +|
                     +| **HACKING.rst**
+                    +
                     +Like most OpenStack projects, DevStack includes a ``HACKING.rst`` file
                     +that describes the layout, style and conventions of the project. Because
                     +``HACKING.rst`` is in the main DevStack repo it is considered
                     +authoritative. Much of the content on this page is taken from there.
+                    +
                     +|
                     +| **bashate Formatting**
+                    +
                     +Around the time of the OpenStack Havana release we added a tool to do
                     +style checking in DevStack similar to what pep8/flake8 do for Python
                     +projects. It is still \_very\_ simplistic, focusing mostly on stray
                     +whitespace to help prevent -1 on reviews that are otherwise acceptable.
                     +Oddly enough it is called ``bashate``. It will be expanded to enforce
                     +some of the documentation rules in comments that are used in formatting
                     +the script pages for devstack.org and possibly even simple code
                     +formatting. Run it on the entire project with ``./run_tests.sh``.
+                    +
                     +Code
                     +~~~~
+                    +
                     +|
                     +| **Repo Layout**
+                    +
                     +The DevStack repo generally keeps all of the primary scripts at the root
                     +level.
+                    +
                     +``docs`` - Contains the source for this website. It is built using
                     +``tools/build_docs.sh``.
+                    +
                     +``exercises`` - Contains the test scripts used to validate and
                     +demonstrate some OpenStack functions. These scripts know how to exit
                     +early or skip services that are not enabled.
+                    +
                     +``extras.d`` - Contains the dispatch scripts called by the hooks in
                     +``stack.sh``, ``unstack.sh`` and ``clean.sh``. See `the plugins
                     +docs <plugins.html>`__ for more information.
+                    +
                     +``files`` - Contains a variety of otherwise lost files used in
                     +configuring and operating DevStack. This includes templates for
                     +configuration files and the system dependency information. This is also
                     +where image files are downloaded and expanded if necessary.
+                    +
                     +``lib`` - Contains the sub-scripts specific to each project. This is
                     +where the work of managing a project's services is located. Each
                     +top-level project (Keystone, Nova, etc) has a file here. Additionally
                     +there are some for system services and project plugins.
+                    +
                     +``samples`` - Contains a sample of the local files not included in the
                     +DevStack repo.
+                    +
                     +``tests`` - the DevStack test suite is rather sparse, mostly consisting
                     +of test of specific fragile functions in the ``functions`` file.
+                    +
                     +``tools`` - Contains a collection of stand-alone scripts, some of which
                     +have aged a bit (does anyone still do ramdisk installs?). While these
                     +may reference the top-level DevStack configuration they can generally be
                     +run alone. There are also some sub-directories to support specific
                     +environments such as XenServer.
+                    +
                     +© Openstack Foundation 2011-2013 — An `OpenStack
                     +program <https://wiki.openstack.org/wiki/Programs>`__ created by
                     +`Rackspace Cloud
                     +Builders <http://www.rackspace.com/cloud/private_edition/>`__

                     new file mode 100644
@@ -0,0 +1,57 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +eucarc EC2 settings
                     +-------------------
+                    +
                     +``eucarc`` creates EC2 credentials for the current user as defined by
                     +``OS_TENANT_NAME:OS_USERNAME``. ``eucarc`` sources ``openrc`` at the
                     +beginning (which in turn sources ``stackrc`` and ``localrc``) in order
                     +to set credentials to create EC2 credentials in Keystone.
+                    +
                     +EC2\_URL
                     +    Set the EC2 url for euca2ools. The endpoint is extracted from the
                     +    service catalog for ``OS_TENANT_NAME:OS_USERNAME``.
+                    +
                     +    ::
+                    +
                     +        EC2_URL=$(keystone catalog --service ec2 | awk '/ publicURL / { print $4 }')
+                    +
                     +S3\_URL
                     +    Set the S3 endpoint for euca2ools. The endpoint is extracted from
                     +    the service catalog for ``OS_TENANT_NAME:OS_USERNAME``.
+                    +
                     +    ::
+                    +
                     +        export S3_URL=$(keystone catalog --service s3 | awk '/ publicURL / { print $4 }')
+                    +
                     +EC2\_ACCESS\_KEY, EC2\_SECRET\_KEY
                     +    Create EC2 credentials for the current tenant:user in Keystone.
+                    +
                     +    ::
+                    +
                     +        CREDS=$(keystone ec2-credentials-create)
                     +        export EC2_ACCESS_KEY=$(echo "$CREDS" | awk '/ access / { print $4 }')
                     +        export EC2_SECRET_KEY=$(echo "$CREDS" | awk '/ secret / { print $4 }')
+                    +
                     +Certificates for Bundling
                     +    Euca2ools requires certificate files to enable bundle uploading. The
                     +    exercise script ``exercises/bundle.sh`` demonstrated retrieving
                     +    certificates using the Nova CLI.
+                    +
                     +    ::
+                    +
                     +        EC2_PRIVATE_KEY=pk.pem
                     +        EC2_CERT=cert.pem
                     +        NOVA_CERT=cacert.pem
                     +        EUCALYPTUS_CERT=${NOVA_CERT}
+                    +
                     +© Openstack Foundation 2011-2013 — An `OpenStack
                     +program <https://wiki.openstack.org/wiki/Programs>`__ created by
                     +`Rackspace Cloud
                     +Builders <http://www.rackspace.com/cloud/private_edition/>`__

                     new file mode 100644
@@ -0,0 +1,54 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +exerciserc Exercise settings
                     +----------------------------
+                    +
                     +``exerciserc`` is used to configure settings for the exercise scripts.
                     +The values shown below are the default values. Thse can all be
                     +overridden by setting them in the ``localrc`` section.
+                    +
                     +ACTIVE\_TIMEOUT
                     +    Max time to wait while vm goes from build to active state
+                    +
                     +    ::
+                    +
                     +        ACTIVE_TIMEOUT==30
+                    +
                     +ASSOCIATE\_TIMEOUT
                     +    Max time to wait for proper IP association and dis-association.
+                    +
                     +    ::
+                    +
                     +        ASSOCIATE_TIMEOUT=15
+                    +
                     +BOOT\_TIMEOUT
                     +    Max time till the vm is bootable
+                    +
                     +    ::
+                    +
                     +        BOOT_TIMEOUT=30
+                    +
                     +RUNNING\_TIMEOUT
                     +    Max time from run instance command until it is running
+                    +
                     +    ::
+                    +
                     +        RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))
+                    +
                     +TERMINATE\_TIMEOUT
                     +    Max time to wait for a vm to terminate
+                    +
                     +    ::
+                    +
                     +        TERMINATE_TIMEOUT=30
+                    +
                     +© Openstack Foundation 2011-2013 — An `OpenStack
                     +program <https://wiki.openstack.org/wiki/Programs>`__ created by
                     +`Rackspace Cloud
                     +Builders <http://www.rackspace.com/cloud/private_edition/>`__

                     new file mode 100644
@@ -0,0 +1,184 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +FAQ: Using DevStack Making to behave
                     +------------------------------------
+                    +
                     +-  `General Questions <#general>`__
                     +-  `Operation and Configuration <#ops_conf>`__
                     +-  `Miscellaneous <#misc>`__
+                    +
                     +General Questions
                     +~~~~~~~~~~~~~~~~~
+                    +
                     +Q: Can I use DevStack for production?
                     +    A: No. We mean it. Really. DevStack makes some implementation
                     +    choices that are not appropriate for production deployments. We
                     +    warned you!
                     +Q: Then why selinux in enforcing mode?
                     +    A: That is the default on current Fedora and RHEL releases. DevStack
                     +    has (rightly so) a bad reputation for its security practices; it has
                     +    always been meant as a development tool first and system integration
                     +    later. This is changing as the security issues around OpenStack's
                     +    use of root (for example) have been tightened and developers need to
                     +    be better equipped to work in these environments. ``stack.sh``'s use
                     +    of root is primarily to support the activities that would be handled
                     +    by packaging in "real" deployments. To remove additional protections
                     +    that will be desired/required in production would be a step
                     +    backward.
                     +Q: But selinux is disabled in RHEL 6!
                     +    A: Today it is, yes. That is a specific exception that certain
                     +    DevStack contributors fought strongly against. The primary reason it
                     +    was allowed was to support using RHEL6 as the Python 2.6 test
                     +    platform and that took priority time-wise. This will not be the case
                     +    with RHEL 7.
                     +Q: Why a shell script, why not chef/puppet/...
                     +    A: The script is meant to be read by humans (as well as ran by
                     +    computers); it is the primary documentation after all. Using a
                     +    recipe system requires everyone to agree and understand chef or
                     +    puppet.
                     +Q: Why not use Crowbar?
                     +    A: DevStack is optimized for documentation & developers. As some of
                     +    us use `Crowbar <https://github.com/dellcloudedge/crowbar>`__ for
                     +    production deployments, we hope developers documenting how they
                     +    setup systems for new features supports projects like Crowbar.
                     +Q: I'd like to help!
                     +    A: That isn't a question, but please do! The source for DevStack is
                     +    at
                     +    `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +    and bug reports go to
                     +    `LaunchPad <http://bugs.launchpad.net/devstack/>`__. Contributions
                     +    follow the usual process as described in the `OpenStack
                     +    wiki <http://wiki.openstack.org/HowToContribute>`__ even though
                     +    DevStack is not an official OpenStack project. This site is housed
                     +    in the CloudBuilder's
                     +    `github <http://github.com/cloudbuilders/devstack>`__ in the
                     +    gh-pages branch.
                     +Q: Why not use packages?
                     +    A: Unlike packages, DevStack leaves your cloud ready to develop -
                     +    checkouts of the code and services running in screen. However, many
                     +    people are doing the hard work of packaging and recipes for
                     +    production deployments. We hope this script serves as a way to
                     +    communicate configuration changes between developers and packagers.
                     +Q: Why isn't $MY\_FAVORITE\_DISTRO supported?
                     +    A: DevStack is meant for developers and those who want to see how
                     +    OpenStack really works. DevStack is known to run on the
                     +    distro/release combinations listed in ``README.md``. DevStack is
                     +    only supported on releases other than those documented in
                     +    ``README.md`` on a best-effort basis.
                     +Q: What about Fedora/RHEL/CentOS?
                     +    A: Fedora and CentOS/RHEL are supported via rpm dependency files and
                     +    specific checks in ``stack.sh``. Support will follow the pattern set
                     +    with the Ubuntu testing, i.e. only a single release of the distro
                     +    will receive regular testing, others will be handled on a
                     +    best-effort basis.
                     +Q: Are there any differences between Ubuntu and Fedora support?
                     +    A: Neutron is not fully supported prior to Fedora 18 due lack of
                     +    OpenVSwitch packages.
                     +Q: How about RHEL 6?
                     +    A: RHEL 6 has Python 2.6 and many old modules packaged and is a
                     +    challenge to support. There are a number of specific RHEL6
                     +    work-arounds in ``stack.sh`` to handle this. But the testing on py26
                     +    is valuable so we do it...
+                    +
                     +Operation and Configuration
                     +~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +Q: Can DevStack handle a multi-node installation?
                     +    A: Indirectly, yes. You run DevStack on each node with the
                     +    appropriate configuration in ``local.conf``. The primary
                     +    considerations are turning off the services not required on the
                     +    secondary nodes, making sure the passwords match and setting the
                     +    various API URLs to the right place.
                     +Q: How can I document the environment that DevStack is using?
                     +    A: DevStack includes a script (``tools/info.sh``) that gathers the
                     +    versions of the relevant installed apt packages, pip packages and
                     +    git repos. This is a good way to verify what Python modules are
                     +    installed.
                     +Q: How do I turn off a service that is enabled by default?
                     +    A: Services can be turned off by adding ``disable_service xxx`` to
                     +    ``local.conf`` (using ``n-vol`` in this example):
+                    +
                     +    ::
+                    +
                     +        disable_service n-vol
+                    +
                     +Q: Is enabling a service that defaults to off done with the reverse of the above?
                     +    A: Of course!
+                    +
                     +    ::
+                    +
                     +        enable_service qpid
+                    +
                     +Q: How do I run a specific OpenStack milestone?
                     +    A: OpenStack milestones have tags set in the git repo. Set the appropriate tag in the ``*_BRANCH`` variables in ``local.conf``.  Swift is on its own release schedule so pick a tag in the Swift repo that is just before the milestone release. For example:
+                    +
                     +    ::
+                    +
                     +        [[local|localrc]]
                     +        GLANCE_BRANCH=stable/grizzly
                     +        HORIZON_BRANCH=stable/grizzly
                     +        KEYSTONE_BRANCH=stable/grizzly
                     +        NOVA_BRANCH=stable/grizzly
                     +        GLANCE_BRANCH=stable/grizzly
                     +        NEUTRON_BRANCH=stable/grizzly
                     +        SWIFT_BRANCH=1.10.0
+                    +
                     +Q: Why not use [STRIKEOUT:``tools/pip-requires``]\ ``requirements.txt`` to grab project dependencies?
                     +    [STRIKEOUT:The majority of deployments will use packages to install
                     +    OpenStack that will have distro-based packages as dependencies.
                     +    DevStack installs as many of these Python packages as possible to
                     +    mimic the expected production environemnt.] Certain Linux
                     +    distributions have a 'lack of workaround' in their Python
                     +    configurations that installs vendor packaged Python modules and
                     +    pip-installed modules to the SAME DIRECTORY TREE. This is causing
                     +    heartache and moving us in the direction of installing more modules
                     +    from PyPI than vendor packages. However, that is only being done as
                     +    necessary as the packaging needs to catch up to the development
                     +    cycle anyway so this is kept to a minimum.
                     +Q: What can I do about RabbitMQ not wanting to start on my fresh new VM?
                     +    A: This is often caused by ``erlang`` not being happy with the
                     +    hostname resolving to a reachable IP address. Make sure your
                     +    hostname resolves to a working IP address; setting it to 127.0.0.1
                     +    in ``/etc/hosts`` is often good enough for a single-node
                     +    installation. And in an extreme case, use ``clean.sh`` to eradicate
                     +    it and try again.
                     +Q: How can I set up Heat in stand-alone configuration?
                     +    A: Configure ``local.conf`` thusly:
+                    +
                     +    ::
+                    +
                     +        [[local|localrc]]
                     +        HEAT_STANDALONE=True
                     +        ENABLED_SERVICES=rabbit,mysql,heat,h-api,h-api-cfn,h-api-cw,h-eng
                     +        KEYSTONE_SERVICE_HOST=<keystone-host>
                     +        KEYSTONE_AUTH_HOST=<keystone-host>
+                    +
                     +Q: Why are my configuration changes ignored?
                     +    A: You may have run into the package prerequisite installation
                     +    timeout. ``tools/install_prereqs.sh`` has a timer that skips the
                     +    package installation checks if it was run within the last
                     +    ``PREREQ_RERUN_HOURS`` hours (default is 2). To override this, set
                     +    ``FORCE_PREREQ=1`` and the package checks will never be skipped.
+                    +
                     +Miscellaneous
                     +~~~~~~~~~~~~~
+                    +
                     +Q: ``tools/fixup_stuff.sh`` is broken and shouldn't 'fix' just one version of packages.
                     +    A: [Another not-a-question] No it isn't. Stuff in there is to
                     +    correct problems in an environment that need to be fixed elsewhere
                     +    or may/will be fixed in a future release. In the case of
                     +    ``httplib2`` and ``prettytable`` specific problems with specific
                     +    versions are being worked around. If later releases have those
                     +    problems than we'll add them to the script. Knowing about the broken
                     +    future releases is valuable rather than polling to see if it has
                     +    been fixed.
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,382 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <../overview.html>`__
                     +-  `Changes <../changes.html>`__
                     +-  `FAQ <../faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Multi-Node Lab: Serious Stuff
                     +=============================
+                    +
                     +Here is OpenStack in a realistic test configuration with multiple
                     +physical servers.
+                    +
                     +Prerequisites Linux & Network
                     +-----------------------------
+                    +
                     +Minimal Install
                     +~~~~~~~~~~~~~~~
+                    +
                     +You need to have a system with a fresh install of Linux. You can
                     +download the `Minimal
                     +CD <https://help.ubuntu.com/community/Installation/MinimalCD>`__ for
                     +Ubuntu releases since DevStack will download & install all the
                     +additional dependencies. The netinstall ISO is available for
                     +`Fedora <http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso>`__
                     +and
                     +`CentOS/RHEL <http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso>`__.
+                    +
                     +Install a couple of packages to bootstrap configuration:
+                    +
                     +::
+                    +
                     +    apt-get install -y git sudo || yum install -y git sudo
+                    +
                     +Network Configuration
                     +~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +The first iteration of the lab uses OpenStack's FlatDHCP network
                     +controller so only a single network will be required. It should be on
                     +its own subnet without DHCP; the host IPs and floating IP pool(s) will
                     +come out of this block. This example uses the following:
+                    +
                     +-  Gateway: 192.168.42.1
                     +-  Physical nodes: 192.168.42.11-192.168.42.99
                     +-  Floating IPs: 192.168.42.128-192.168.42.254
+                    +
                     +Configure each node with a static IP. For Ubuntu edit
                     +``/etc/network/interfaces``:
+                    +
                     +::
+                    +
                     +    auto eth0
                     +    iface eth0 inet static
                     +        address 192.168.42.11
                     +        netmask 255.255.255.0
                     +        gateway 192.168.42.1
+                    +
                     +For Fedora and CentOS/RHEL edit
                     +``/etc/sysconfig/network-scripts/ifcfg-eth0``:
+                    +
                     +::
+                    +
                     +    BOOTPROTO=static
                     +    IPADDR=192.168.42.11
                     +    NETMASK=255.255.255.0
                     +    GATEWAY=192.168.42.1
+                    +
                     +Installation shake and bake
                     +---------------------------
+                    +
                     +Add the DevStack User
                     +~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +OpenStack runs as a non-root user that has sudo access to root. There is
                     +nothing special about the name, we'll use ``stack`` here. Every node
                     +must use the same name and preferably uid. If you created a user during
                     +the OS install you can use it and give it sudo privileges below.
                     +Otherwise create the stack user:
+                    +
                     +::
+                    +
                     +    groupadd stack
                     +    useradd -g stack -s /bin/bash -d /opt/stack -m stack
+                    +
                     +This user will be making many changes to your system during installation
                     +and operation so it needs to have sudo privileges to root without a
                     +password:
+                    +
                     +::
+                    +
                     +    echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+                    +
                     +From here on use the ``stack`` user. **Logout** and **login** as the
                     +``stack`` user.
+                    +
                     +Set Up Ssh
                     +~~~~~~~~~~
+                    +
                     +Set up the stack user on each node with an ssh key for access:
+                    +
                     +::
+                    +
                     +    mkdir ~/.ssh; chmod 700 ~/.ssh
                     +    echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyYjfgyPazTvGpd8OaAvtU2utL8W6gWC4JdRS1J95GhNNfQd657yO6s1AH5KYQWktcE6FO/xNUC2reEXSGC7ezy+sGO1kj9Limv5vrvNHvF1+wts0Cmyx61D2nQw35/Qz8BvpdJANL7VwP/cFI/p3yhvx2lsnjFE3hN8xRB2LtLUopUSVdBwACOVUmH2G+2BWMJDjVINd2DPqRIA4Zhy09KJ3O1Joabr0XpQL0yt/I9x8BVHdAx6l9U0tMg9dj5+tAjZvMAFfye3PJcYwwsfJoFxC8w/SLtqlFX7Ehw++8RtvomvuipLdmWCy+T9hIkl+gHYE4cS3OIqXH7f49jdJf jesse@spacey.local" > ~/.ssh/authorized_keys
+                    +
                     +Download DevStack
                     +~~~~~~~~~~~~~~~~~
+                    +
                     +Grab the latest version of DevStack:
+                    +
                     +::
+                    +
                     +    git clone https://git.openstack.org/openstack-dev/devstack
                     +    cd devstack
+                    +
                     +Up to this point all of the steps apply to each node in the cluster.
                     +From here on there are some differences between the cluster controller
                     +(aka 'head node') and the compute nodes.
+                    +
                     +Configure Cluster Controller
                     +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +The cluster controller runs all OpenStack services. Configure the
                     +cluster controller's DevStack in ``local.conf``:
+                    +
                     +::
+                    +
                     +    [[local|localrc]]
                     +    HOST_IP=192.168.42.11
                     +    FLAT_INTERFACE=eth0
                     +    FIXED_RANGE=10.4.128.0/20
                     +    FIXED_NETWORK_SIZE=4096
                     +    FLOATING_RANGE=192.168.42.128/25
                     +    MULTI_HOST=1
                     +    LOGFILE=/opt/stack/logs/stack.sh.log
                     +    ADMIN_PASSWORD=labstack
                     +    MYSQL_PASSWORD=supersecret
                     +    RABBIT_PASSWORD=supersecrete
                     +    SERVICE_PASSWORD=supersecrete
                     +    SERVICE_TOKEN=xyzpdqlazydog
+                    +
                     +In the multi-node configuration the first 10 or so IPs in the private
                     +subnet are usually reserved. Add this to ``local.sh`` to have it run
                     +after every ``stack.sh`` run:
+                    +
                     +::
+                    +
                     +    for i in `seq 2 10`; do /opt/stack/nova/bin/nova-manage fixed reserve 10.4.128.$i; done
+                    +
                     +Fire up OpenStack:
+                    +
                     +::
+                    +
                     +    ./stack.sh
+                    +
                     +A stream of activity ensues. When complete you will see a summary of
                     +``stack.sh``'s work, including the relevant URLs, accounts and passwords
                     +to poke at your shiny new OpenStack. The most recent log file is
                     +available in ``stack.sh.log``.
+                    +
                     +Configure Compute Nodes
                     +~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +The compute nodes only run the OpenStack worker services. For additional
                     +machines, create a ``local.conf`` with:
+                    +
                     +::
+                    +
                     +    HOST_IP=192.168.42.12 # change this per compute node
                     +    FLAT_INTERFACE=eth0
                     +    FIXED_RANGE=10.4.128.0/20
                     +    FIXED_NETWORK_SIZE=4096
                     +    FLOATING_RANGE=192.168.42.128/25
                     +    MULTI_HOST=1
                     +    LOGFILE=/opt/stack/logs/stack.sh.log
                     +    ADMIN_PASSWORD=labstack
                     +    MYSQL_PASSWORD=supersecret
                     +    RABBIT_PASSWORD=supersecrete
                     +    SERVICE_PASSWORD=supersecrete
                     +    SERVICE_TOKEN=xyzpdqlazydog
                     +    DATABASE_TYPE=mysql
                     +    SERVICE_HOST=192.168.42.11
                     +    MYSQL_HOST=192.168.42.11
                     +    RABBIT_HOST=192.168.42.11
                     +    GLANCE_HOSTPORT=192.168.42.11:9292
                     +    ENABLED_SERVICES=n-cpu,n-net,n-api,c-sch,c-api,c-vol
                     +    NOVA_VNC_ENABLED=True
                     +    NOVNCPROXY_URL="http://192.168.42.11:6080/vnc_auto.html"
                     +    VNCSERVER_LISTEN=$HOST_IP
                     +    VNCSERVER_PROXYCLIENT_ADDRESS=$VNCSERVER_LISTEN
+                    +
                     +Fire up OpenStack:
+                    +
                     +::
+                    +
                     +    ./stack.sh
+                    +
                     +A stream of activity ensues. When complete you will see a summary of
                     +``stack.sh``'s work, including the relevant URLs, accounts and passwords
                     +to poke at your shiny new OpenStack. The most recent log file is
                     +available in ``stack.sh.log``.
+                    +
                     +Cleaning Up After DevStack
                     +~~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +Shutting down OpenStack is now as simple as running the included
                     +``unstack.sh`` script:
+                    +
                     +::
+                    +
                     +    ./unstack.sh
+                    +
                     +A more aggressive cleanup can be performed using ``clean.sh``. It
                     +removes certain troublesome packages and attempts to leave the system in
                     +a state where changing the database or queue manager can be reliably
                     +performed.
+                    +
                     +::
+                    +
                     +    ./clean.sh
+                    +
                     +Sometimes running instances are not cleaned up. DevStack attempts to do
                     +this when it runs but there are times it needs to still be done by hand:
+                    +
                     +::
+                    +
                     +    sudo rm -rf /etc/libvirt/qemu/inst*
                     +    sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy
+                    +
                     +Options pimp your stack
                     +-----------------------
+                    +
                     +Additional Users
                     +~~~~~~~~~~~~~~~~
+                    +
                     +DevStack creates two OpenStack users (``admin`` and ``demo``) and two
                     +tenants (also ``admin`` and ``demo``). ``admin`` is exactly what it
                     +sounds like, a privileged administrative account that is a member of
                     +both the ``admin`` and ``demo`` tenants. ``demo`` is a normal user
                     +account that is only a member of the ``demo`` tenant. Creating
                     +additional OpenStack users can be done through the dashboard, sometimes
                     +it is easier to do them in bulk from a script, especially since they get
                     +blown away every time ``stack.sh`` runs. The following steps are ripe
                     +for scripting:
+                    +
                     +::
+                    +
                     +    # Get admin creds
                     +    . openrc admin admin
+                    +
                     +    # List existing tenants
                     +    keystone tenant-list
+                    +
                     +    # List existing users
                     +    keystone user-list
+                    +
                     +    # Add a user and tenant
                     +    NAME=bob
                     +    PASSWORD=BigSecrete
                     +    TENANT=$NAME
                     +    keystone tenant-create --name=$NAME
                     +    keystone user-create --name=$NAME --pass=$PASSWORD
                     +    keystone user-role-add --user-id=<bob-user-id> --tenant-id=<bob-tenant-id> --role-id=<member-role-id>
                     +    # member-role-id comes from the existing member role created by stack.sh
                     +    # keystone role-list
+                    +
                     +Swift
                     +~~~~~
+                    +
                     +Swift requires a significant amount of resources and is disabled by
                     +default in DevStack. The support in DevStack is geared toward a minimal
                     +installation but can be used for testing. To implement a true multi-node
                     +test of Swift required more than DevStack provides. Enabling it is as
                     +simple as enabling the ``swift`` service in ``local.conf``:
+                    +
                     +::
+                    +
                     +    enable_service s-proxy s-object s-container s-account
+                    +
                     +Swift will put its data files in ``SWIFT_DATA_DIR`` (default
                     +``/opt/stack/data/swift``). The size of the data 'partition' created
                     +(really a loop-mounted file) is set by ``SWIFT_LOOPBACK_DISK_SIZE``. The
                     +Swift config files are located in ``SWIFT_CONFIG_DIR`` (default
                     +``/etc/swift``). All of these settings can be overridden in (wait for
                     +it...) ``local.conf``.
+                    +
                     +Volumes
                     +~~~~~~~
+                    +
                     +DevStack will automatically use an existing LVM volume group named
                     +``stack-volumes`` to store cloud-created volumes. If ``stack-volumes``
                     +doesn't exist, DevStack will set up a 5Gb loop-mounted file to contain
                     +it. This obviously limits the number and size of volumes that can be
                     +created inside OpenStack. The size can be overridden by setting
                     +``VOLUME_BACKING_FILE_SIZE`` in ``local.conf``.
+                    +
                     +``stack-volumes`` can be pre-created on any physical volume supported by
                     +Linux's LVM. The name of the volume group can be changed by setting
                     +``VOLUME_GROUP`` in ``localrc``. ``stack.sh`` deletes all logical
                     +volumes in ``VOLUME_GROUP`` that begin with ``VOLUME_NAME_PREFIX`` as
                     +part of cleaning up from previous runs. It is recommended to not use the
                     +root volume group as ``VOLUME_GROUP``.
+                    +
                     +The details of creating the volume group depends on the server hardware
                     +involved but looks something like this:
+                    +
                     +::
+                    +
                     +    pvcreate /dev/sdc
                     +    vgcreate stack-volumes /dev/sdc
+                    +
                     +Syslog
                     +~~~~~~
+                    +
                     +DevStack is capable of using ``rsyslog`` to aggregate logging across the
                     +cluster. It is off by default; to turn it on set ``SYSLOG=True`` in
                     +``local.conf``. ``SYSLOG_HOST`` defaults to ``HOST_IP``; on the compute
                     +nodes it must be set to the IP of the cluster controller to send syslog
                     +output there. In the example above, add this to the compute node
                     +``local.conf``:
+                    +
                     +::
+                    +
                     +    SYSLOG_HOST=192.168.42.11
+                    +
                     +Using Alternate Repositories/Branches
                     +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +The git repositories for all of the OpenStack services are defined in
                     +``stackrc``. Since this file is a part of the DevStack package changes
                     +to it will probably be overwritten as updates are applied. Every setting
                     +in ``stackrc`` can be redefined in ``local.conf``.
+                    +
                     +To change the repository or branch that a particular OpenStack service
                     +is created from, simply change the value of ``*_REPO`` or ``*_BRANCH``
                     +corresponding to that service.
+                    +
                     +After making changes to the repository or branch, if ``RECLONE`` is not
                     +set in ``localrc`` it may be necessary to remove the corresponding
                     +directory from ``/opt/stack`` to force git to re-clone the repository.
+                    +
                     +For example, to pull Nova from a proposed release candidate in the
                     +primary Nova repository:
+                    +
                     +::
+                    +
                     +    NOVA_BRANCH=rc-proposed
+                    +
                     +To pull Glance from an experimental fork:
+                    +
                     +::
+                    +
                     +    GLANCE_BRANCH=try-something-big
                     +    GLANCE_REPO=https://github.com/mcuser/glance.git
+                    +
                     +Notes stuff you might need to know
                     +----------------------------------
+                    +
                     +Reset the Bridge
                     +~~~~~~~~~~~~~~~~
+                    +
                     +How to reset the bridge configuration:
+                    +
                     +::
+                    +
                     +    sudo brctl delif br100 eth0.926
                     +    sudo ip link set dev br100 down
                     +    sudo brctl delbr br100
+                    +
                     +Set MySQL Password
                     +~~~~~~~~~~~~~~~~~~
+                    +
                     +If you forgot to set the root password you can do this:
+                    +
                     +::
+                    +
                     +    mysqladmin -u root -pnova password 'supersecret'
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,143 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <../overview.html>`__
                     +-  `Changes <../changes.html>`__
                     +-  `FAQ <../faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +PXE Boot Server Guide: Magic Dust for Network Boot
                     +==================================================
+                    +
                     +Boot DevStack from a PXE server to a RAM disk.
+                    +
                     +Prerequisites Hardware & OpenWRT
                     +--------------------------------
+                    +
                     +Hardware
                     +~~~~~~~~
+                    +
                     +The whole point of this exercise is to have a highly portable boot
                     +server, so using a small router with a USB port is the desired platform.
                     +This guide uses a Buffalo WZR-HP-G300NH as an example, but it is easily
                     +generalized for other supported platforms. See openwrt.org for more.
+                    +
                     +OpenWRT
                     +~~~~~~~
+                    +
                     +Any recent 'Backfire' build of OpenWRT will work for the boot server
                     +project. We build from trunk and have made the images available at
                     +`http://openwrt.xr7.org/openwrt <http://openwrt.xr7.org/openwrt>`__.
+                    +
                     +Installation bit blasting
                     +-------------------------
+                    +
                     +Install the Image
                     +~~~~~~~~~~~~~~~~~
+                    +
                     +This process follows `the OpenWRT doc OEM
                     +Install <http://wiki.openwrt.org/toh/buffalo/wzr-hp-g300h>`__ to tftp
                     +the new image onto the router. You need a computer to set up the router,
                     +we assume it is a recent Linux or OS/X installation.
+                    +
                     +-  Get openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+                    +
                     +   ::
+                    +
                     +       wget http://openwrt.xr7.org/openwrt/ar71xx/openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+                    +
                     +-  Connect computer to LAN port 4 (closest to WAN port)
                     +-  Set computer interface to IP address in the 192.168.11.2
                     +-  Add static arp entry for router
+                    +
                     +   ::
+                    +
                     +       arp -s 192.168.11.1 <mac-address>
+                    +
                     +-  Start TFTP transfer attempt
+                    +
                     +   ::
+                    +
                     +       tftp 192.168.11.1
                     +       binary
                     +       rexmt 1
                     +       timeout 60
                     +       put openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+                    +
                     +-  Power on router. Router will reboot and initialize on 192.168.1.1.
                     +-  Delete static arp entry for router
+                    +
                     +   ::
+                    +
                     +       arp -d 192.168.11.1
+                    +
                     +-  Set computer to DHCP, connect and telnet to router and set root
                     +   password.
+                    +
                     +Configure the Router
                     +~~~~~~~~~~~~~~~~~~~~
+                    +
                     +-  Update ``/etc/opkg.conf`` to point to our repo:
+                    +
                     +   ::
+                    +
                     +       src/gz packages http://192.168.5.13/openwrt/build/ar71xx/packages
+                    +
                     +-  Configure anon mounts:
+                    +
                     +   ::
+                    +
                     +       uci delete fstab.@mount[0]
                     +       uci commit fstab
                     +       /etc/init.d/fstab restart
+                    +
                     +-  Reset the DHCP address range. DevStack will claim the upper /25 of
                     +   the router's LAN address space for floating IPs so the default DHCP
                     +   address range needs to be moved:
+                    +
                     +   ::
+                    +
                     +       uci set dhcp.lan.start=65
                     +       uci set dhcp.lan.limit=60
                     +       uci commit dhcp
+                    +
                     +-  Enable TFTP:
+                    +
                     +   ::
+                    +
                     +       uci set dhcp.@dnsmasq[0].enable_tftp=1
                     +       uci set dhcp.@dnsmasq[0].tftp_root=/mnt/sda1/tftpboot
                     +       uci set dhcp.@dnsmasq[0].dhcp_boot=pxelinux.0
                     +       uci commit dhcp
                     +       /etc/init.d/dnsmasq restart
+                    +
                     +Set Up tftpboot
                     +~~~~~~~~~~~~~~~
+                    +
                     +-  Create the ``/tmp/tftpboot`` structure and populate it:
+                    +
                     +   ::
+                    +
                     +       cd ~/devstack
                     +       tools/build_pxe_boot.sh /tmp
+                    +
                     +   This calls ``tools/build_ramdisk.sh`` to create a 2GB ramdisk
                     +   containing a complete development Oneiric OS plus the OpenStack code
                     +   checkouts.
+                    +
                     +-  Copy ``tftpboot`` to a USB drive:
+                    +
                     +   ::
+                    +
                     +       mount /dev/sdb1 /mnt/tmp
                     +       rsync -a /tmp/tftpboot/ /mnt/tmp/tftpboot/
                     +       umount /mnt/tmp
+                    +
                     +-  Plug USB drive into router. It will be automounted and is ready to
                     +   serve content.
+                    +
                     +Now `return <ramdisk.html>`__ to the RAM disk Guide to kick off your
                     +DevStack experience.
+                    +
                     +© Openstack Foundation 2011-2013 — this is not an official OpenStack
                     +project...

                     new file mode 100644
@@ -0,0 +1,89 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <../overview.html>`__
                     +-  `Changes <../changes.html>`__
                     +-  `FAQ <../faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Stack-in-a-Box: Try before you mkfs
                     +===================================
+                    +
                     +Run DevStack from a RAM disk to give it a whirl before making the
                     +commitment to install it. We'll cover booting from a USB drive or over
                     +the network via PXE. We'll even thow in configuring a home router to
                     +handle the PXE boot. You will need a minimum of 3GB for both of these
                     +configurations as the RAM disk itself is 2GB.
+                    +
                     +Prerequisites Hardware
                     +----------------------
+                    +
                     +USB Boot
                     +~~~~~~~~
+                    +
                     +`This guide <usb-boot.html>`__ covers the creation of a bootable USB
                     +drive. Your computer BIOS must support booting from USB.
+                    +
                     +PXE Boot
                     +~~~~~~~~
+                    +
                     +`This guide <pxe-boot.html>`__ covers the installation of OpenWRT on a
                     +home router and configuring it as a PXE server, plus the creation of the
                     +boot images and PXE support files.
+                    +
                     +Installation bit blasting
                     +-------------------------
+                    +
                     +Install DevStack
                     +~~~~~~~~~~~~~~~~
+                    +
                     +Grab the latest version of DevStack via https:
+                    +
                     +::
+                    +
                     +    sudo apt-get install git -y
                     +    git clone https://git.openstack.org/openstack-dev/devstack
                     +    cd devstack
+                    +
                     +Prepare the Boot RAMdisk
                     +~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +Pick your boot method and follow the guide to prepare to build the RAM
                     +disk and set up the boot process:
+                    +
                     +-  `USB boot <usb-boot.html>`__
                     +-  `PXE boot <pxe-boot.html>`__
+                    +
                     +Fire It Up
                     +~~~~~~~~~~
+                    +
                     +-  Boot the computer into the RAM disk. The details will vary from
                     +   machine to machine but most BIOSes have a method to select the boot
                     +   device, often by pressing F12 during POST.
                     +-  Select 'DevStack' from the Boot Menu.
                     +-  Log in with the 'stack' user and 'pass' password.
                     +-  Create ``devstack/localrc`` if you wish to change any of the
                     +   configuration variables. You will probably want to at least set the
                     +   admin login password to something memorable rather than the default
                     +   20 random characters:
+                    +
                     +   ::
+                    +
                     +       ADMIN_PASSWORD=openstack
+                    +
                     +-  Fire up OpenStack!
+                    +
                     +   ::
+                    +
                     +       ./run.sh
+                    +
                     +-  See the processes running in screen:
+                    +
                     +   ::
+                    +
                     +       screen -x
+                    +
                     +-  Connect to the dashboard at ``http://<ip-address>/``
+                    +
                     +© Openstack Foundation 2011-2013 — this is not an official OpenStack
                     +project...

                     new file mode 100644
@@ -0,0 +1,110 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <../overview.html>`__
                     +-  `Changes <../changes.html>`__
                     +-  `FAQ <../faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Running a Cloud in a VM
                     +=======================
+                    +
                     +Use the cloud to build the cloud! Use your cloud to launch new versions
                     +of OpenStack in about 5 minutes. When you break it, start over! The VMs
                     +launched in the cloud will be slow as they are running in QEMU
                     +(emulation), but their primary use is testing OpenStack development and
                     +operation. Speed not required.
+                    +
                     +Prerequisites Cloud & Image
                     +---------------------------
+                    +
                     +Virtual Machine
                     +~~~~~~~~~~~~~~~
+                    +
                     +DevStack should run in any virtual machine running a supported Linux
                     +release. It will perform best with 2Gb or more of RAM.
+                    +
                     +OpenStack Deployment & cloud-init
                     +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +If the cloud service has an image with ``cloud-init`` pre-installed, use
                     +it. You can get one from `Ubuntu's Daily
                     +Build <http://uec-images.ubuntu.com>`__ site if necessary. This will
                     +enable you to launch VMs with userdata that installs everything at boot
                     +time. The userdata script below will install and run DevStack with a
                     +minimal configuration. The use of ``cloud-init`` is outside the scope of
                     +this document, refer to the ``cloud-init`` docs for more information.
+                    +
                     +If you are directly using a hypervisor like Xen, kvm or VirtualBox you
                     +can manually kick off the script below as a non-root user in a
                     +bare-bones server installation.
+                    +
                     +Installation shake and bake
                     +---------------------------
+                    +
                     +Launching With Cloud-Init
                     +~~~~~~~~~~~~~~~~~~~~~~~~~
+                    +
                     +This cloud config grabs the latest version of DevStack via git, creates
                     +a minimal ``local.conf`` file and kicks off ``stack.sh``. It should be
                     +passed as the user-data file when booting the VM.
+                    +
                     +::
+                    +
                     +    #cloud-config
+                    +
                     +    users:
                     +      - default
                     +      - name: stack
                     +        lock_passwd: False
                     +        sudo: ["ALL=(ALL) NOPASSWD:ALL\nDefaults:stack !requiretty"]
                     +        shell: /bin/bash
+                    +
                     +    write_files:
                     +      - content: |
                     +            #!/bin/sh
                     +            DEBIAN_FRONTEND=noninteractive sudo apt-get -qqy update || sudo yum update -qy
                     +            DEBIAN_FRONTEND=noninteractive sudo apt-get install -qqy git || sudo yum install -qy git
                     +            sudo chown stack:stack /home/stack
                     +            cd /home/stack
                     +            git clone https://git.openstack.org/openstack-dev/devstack
                     +            cd devstack
                     +            echo '[[local|localrc]]' > local.conf
                     +            echo ADMIN_PASSWORD=password >> local.conf
                     +            echo MYSQL_PASSWORD=password >> local.conf
                     +            echo RABBIT_PASSWORD=password >> local.conf
                     +            echo SERVICE_PASSWORD=password >> local.conf
                     +            echo SERVICE_TOKEN=tokentoken >> local.conf
                     +            ./stack.sh
                     +        path: /home/stack/start.sh
                     +        permissions: 0755
+                    +
                     +    runcmd:
                     +      - su -l stack ./start.sh
+                    +
                     +As DevStack will refuse to run as root, this configures ``cloud-init``
                     +to create a non-root user and run the ``start.sh`` script as that user.
+                    +
                     +Launching By Hand
                     +~~~~~~~~~~~~~~~~~
+                    +
                     +Using a hypervisor directly, launch the VM and either manually perform
                     +the steps in the embedded shell script above or copy it into the VM.
+                    +
                     +Using OpenStack
                     +~~~~~~~~~~~~~~~
+                    +
                     +At this point you should be able to access the dashboard. Launch VMs and
                     +if you give them floating IPs access those VMs from other machines on
                     +your network.
+                    +
                     +One interesting use case is for developers working on a VM on their
                     +laptop. Once ``stack.sh`` has completed once, all of the pre-requisite
                     +packages are installed in the VM and the source trees checked out.
                     +Setting ``OFFLINE=True`` in ``local.conf`` enables ``stack.sh`` to run
                     +multiple times without an Internet connection. DevStack, making hacking
                     +at the lake possible since 2012!
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,383 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.rst>`__
                     +-  `Changes <changes.rst>`__
                     +-  `FAQ <faq.rst>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +.. toctree::
                     +   :glob:
                     +   :maxdepth: 2
+                    +
                     +   *
                     +   guides/*
+                    +
+                    +
+                    +
                     +DevStack - an OpenStack Community Production
                     +============================================
+                    +
                     +| A documented shell script to build complete OpenStack development environments.
                     +|  An OpenStack program maintained by the developer community.
+                    +
                     +#. Setup a fresh supported Linux installation.
                     +#. Clone devstack from git.openstack.org.
+                    +
                     +   ::
+                    +
                     +       git clone https://git.openstack.org/openstack-dev/devstack
+                    +
                     +#. Deploy your OpenStack Cloud
+                    +
                     +   ::
+                    +
                     +       cd devstack && ./stack.sh
+                    +
+                    +
+                    +
                     +Quick Start This ain't your first rodeo
                     +---------------------------------------
+                    +
                     +#. Select a Linux Distribution
+                    +
                     +   Only Ubuntu 14.04 (Trusty), Fedora 20 and CentOS/RHEL 6.5 are
                     +   documented here. OpenStack also runs and is packaged on other flavors
                     +   of Linux such as OpenSUSE and Debian.
+                    +
                     +#. Install Selected OS
+                    +
                     +   In order to correctly install all the dependencies, we assume a
                     +   specific minimal version of the supported distributions to make it as
                     +   easy as possible. We recommend using a minimal install of Ubuntu or
                     +   Fedora server in a VM if this is your first time.
+                    +
                     +#. Download DevStack
+                    +
                     +   ::
+                    +
                     +       git clone https://git.openstack.org/openstack-dev/devstack
+                    +
                     +   The ``devstack`` repo contains a script that installs OpenStack and
                     +   templates for configuration files
+                    +
                     +#. Configure
+                    +
                     +   We recommend at least a `minimal
                     +   configuration <configuration.html>`__ be set up.
+                    +
                     +#. Start the install
+                    +
                     +   ::
+                    +
                     +       cd devstack; ./stack.sh
+                    +
                     +   It takes a few minutes, we recommend `reading the
                     +   script <stack.sh.html>`__ while it is building.
+                    +
                     +Guides Walk through various setups used by stackers
                     +---------------------------------------------------
+                    +
                     +OpenStack on VMs
                     +----------------
+                    +
                     +Title
+                    +
                     +Description
+                    +
                     +Link
+                    +
                     +Virtual Machine
+                    +
                     +Run OpenStack in a VM. The VMs launched in your cloud will be slow as
                     +they are running in QEMU (emulation), but it is useful if you don't have
                     +spare hardware laying around.
+                    +
                     +`Read » <guides/single-vm.html>`__
+                    +
                     +1 Guide
+                    +
                     +What is this?
                     +^^^^^^^^^^^^^
+                    +
                     +These guides tell you how to virtualize your OpenStack cloud in virtual
                     +machines. This means that you can get started without having to purchase
                     +any hardware.
+                    +
                     +OpenStack on Hardware
                     +---------------------
+                    +
                     +Title
+                    +
                     +Description
+                    +
                     +Link
+                    +
                     +All-In-One
+                    +
                     +Run OpenStack on dedicated hardware to get real performance in your VMs.
                     +This can include a server-class machine or a laptop at home.
+                    +
                     +`Read » <guides/single-machine.html>`__
+                    +
                     +Multi-Node + VLANs
+                    +
                     +Setup a multi-node cluster with dedicated VLANs for VMs & Management.
+                    +
                     +`Read » <guides/multinode-lab.html>`__
+                    +
                     +2 Guides
+                    +
                     +What is this?
                     +^^^^^^^^^^^^^
+                    +
                     +These guides tell you how to deploy a development environment on real
                     +hardware. Guides range from running OpenStack on a single laptop to
                     +running a multi-node deployment on datacenter hardware.
+                    +
                     +Documentation Help yourself to stack
                     +------------------------------------
+                    +
                     +Overview
                     +--------
+                    +
                     +`An overview of DevStack goals and priorities <overview.html>`__
+                    +
                     +Configuration
                     +-------------
+                    +
                     +`Configuring and customizing the stack <configuration.html>`__
+                    +
                     +Plugins
                     +-------
+                    +
                     +`Extending DevStack with new features <plugins.html>`__
+                    +
                     +Recent Changes
                     +--------------
+                    +
                     +`An incomplete summary of recent changes <changes.html>`__
+                    +
                     +FAQ
                     +---
+                    +
                     +`The DevStack FAQ <faq.html>`__
+                    +
                     +Contributing
                     +------------
+                    +
                     +`Pitching in to make DevStack a better place <contributing.html>`__
+                    +
                     +Code A look at the bits that make it all go
                     +-------------------------------------------
+                    +
                     +Scripts Generated documentation of DevStack scripts.
                     +----------------------------------------------------
+                    +
                     ++-------------------------------+----------------------------------------------+
                     +| Filename                      | Link                                         |
                     ++===============================+==============================================+
                     +| stack.sh                      | `Read » <stack.sh.html>`__                   |
                     ++-------------------------------+----------------------------------------------+
                     +| functions                     | `Read » <functions.html>`__                  |
                     ++-------------------------------+----------------------------------------------+
                     +| functions-common              | `Read » <functions-common.html>`__           |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/apache                    | `Read » <lib/apache.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/baremetal                 | `Read » <lib/baremetal.html>`__              |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/ceilometer                | `Read » <lib/ceilometer.html>`__             |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/cinder                    | `Read » <lib/cinder.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/config                    | `Read » <lib/config.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/database                  | `Read » <lib/database.html>`__               |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/glance                    | `Read » <lib/glance.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/heat                      | `Read » <lib/heat.html>`__                   |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/horizon                   | `Read » <lib/horizon.html>`__                |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/infra                     | `Read » <lib/infra.html>`__                  |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/ironic                    | `Read » <lib/ironic.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/keystone                  | `Read » <lib/keystone.html>`__               |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/ldap                      | `Read » <lib/ldap.html>`__                   |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/zaqar                     | `Read » <lib/zaqar.html>`__                  |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/neutron                   | `Read » <lib/neutron.html>`__                |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/nova                      | `Read » <lib/nova.html>`__                   |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/oslo                      | `Read » <lib/oslo.html>`__                   |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/rpc\_backend              | `Read » <lib/rpc_backend.html>`__            |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/sahara                    | `Read » <lib/sahara.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/savanna                   | `Read » <lib/savanna.html>`__                |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/stackforge                | `Read » <lib/stackforge.html>`__             |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/swift                     | `Read » <lib/swift.html>`__                  |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/tempest                   | `Read » <lib/tempest.html>`__                |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/tls                       | `Read » <lib/tls.html>`__                    |
                     ++-------------------------------+----------------------------------------------+
                     +| lib/trove                     | `Read » <lib/trove.html>`__                  |
                     ++-------------------------------+----------------------------------------------+
                     +| unstack.sh                    | `Read » <unstack.sh.html>`__                 |
                     ++-------------------------------+----------------------------------------------+
                     +| clean.sh                      | `Read » <clean.sh.html>`__                   |
                     ++-------------------------------+----------------------------------------------+
                     +| run\_tests.sh                 | `Read » <run_tests.sh.html>`__               |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/50-ironic.sh         | `Read » <extras.d/50-ironic.html>`__         |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/70-zaqar.sh          | `Read » <extras.d/70-zaqar.html>`__          |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/70-sahara.sh         | `Read » <extras.d/70-sahara.html>`__         |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/70-savanna.sh        | `Read » <extras.d/70-savanna.html>`__        |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/70-trove.sh          | `Read » <extras.d/70-trove.html>`__          |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/80-opendaylight.sh   | `Read » <extras.d/80-opendaylight.html>`__   |
                     ++-------------------------------+----------------------------------------------+
                     +| extras.d/80-tempest.sh        | `Read » <extras.d/80-tempest.html>`__        |
                     ++-------------------------------+----------------------------------------------+
+                    +
                     +Configuration Setting the table
                     +-------------------------------
+                    +
                     ++--------------+--------------------------------+
                     +| Filename     | Link                           |
                     ++==============+================================+
                     +| local.conf   | `Read » <local.conf.html>`__   |
                     ++--------------+--------------------------------+
                     +| stackrc      | `Read » <stackrc.html>`__      |
                     ++--------------+--------------------------------+
                     +| openrc       | `Read » <openrc.html>`__       |
                     ++--------------+--------------------------------+
                     +| exerciserc   | `Read » <exerciserc.html>`__   |
                     ++--------------+--------------------------------+
                     +| eucarc       | `Read » <eucarc.html>`__       |
                     ++--------------+--------------------------------+
+                    +
                     +Tools Support scripts
                     +---------------------
+                    +
                     ++-----------------------------+----------------------------------------------+
                     +| Filename                    | Link                                         |
                     ++=============================+==============================================+
                     +| tools/info.sh               | `Read » <tools/info.sh.html>`__              |
                     ++-----------------------------+----------------------------------------------+
                     +| tools/build\_docs.sh        | `Read » <tools/build_docs.sh.html>`__        |
                     ++-----------------------------+----------------------------------------------+
                     +| tools/create\_userrc.sh     | `Read » <tools/create_userrc.sh.html>`__     |
                     ++-----------------------------+----------------------------------------------+
                     +| tools/fixup\_stuff.sh       | `Read » <tools/fixup_stuff.sh.html>`__       |
                     ++-----------------------------+----------------------------------------------+
                     +| tools/install\_prereqs.sh   | `Read » <tools/install_prereqs.sh.html>`__   |
                     ++-----------------------------+----------------------------------------------+
                     +| tools/install\_pip.sh       | `Read » <tools/install_pip.sh.html>`__       |
                     ++-----------------------------+----------------------------------------------+
                     +| tools/upload\_image.sh      | `Read » <tools/upload_image.sh.html>`__      |
                     ++-----------------------------+----------------------------------------------+
+                    +
                     +Samples Generated documentation of DevStack sample files.
                     +---------------------------------------------------------
+                    +
                     ++------------+--------------------------------------+
                     +| Filename   | Link                                 |
                     ++============+======================================+
                     +| local.sh   | `Read » <samples/local.sh.html>`__   |
                     ++------------+--------------------------------------+
                     +| localrc    | `Read » <samples/localrc.html>`__    |
                     ++------------+--------------------------------------+
+                    +
                     +Exercises Generated documentation of DevStack scripts.
                     +------------------------------------------------------
+                    +
                     +Filename
+                    +
                     +Link
+                    +
                     +exercise.sh
+                    +
                     +`Read » <exercise.sh.html>`__
+                    +
                     +exercises/aggregates.sh
+                    +
                     +`Read » <exercises/aggregates.sh.html>`__
+                    +
                     +exercises/boot\_from\_volume.sh
+                    +
                     +`Read » <exercises/boot_from_volume.sh.html>`__
+                    +
                     +exercises/bundle.sh
+                    +
                     +`Read » <exercises/bundle.sh.html>`__
+                    +
                     +exercises/client-args.sh
+                    +
                     +`Read » <exercises/client-args.sh.html>`__
+                    +
                     +exercises/client-env.sh
+                    +
                     +`Read » <exercises/client-env.sh.html>`__
+                    +
                     +exercises/euca.sh
+                    +
                     +`Read » <exercises/euca.sh.html>`__
+                    +
                     +exercises/floating\_ips.sh
+                    +
                     +`Read » <exercises/floating_ips.sh.html>`__
+                    +
                     +exercises/horizon.sh
+                    +
                     +`Read » <exercises/horizon.sh.html>`__
+                    +
                     +exercises/neutron-adv-test.sh
+                    +
                     +`Read » <exercises/neutron-adv-test.sh.html>`__
+                    +
                     +exercises/sahara.sh
+                    +
                     +`Read » <exercises/sahara.sh.html>`__
+                    +
                     +exercises/savanna.sh
+                    +
                     +`Read » <exercises/savanna.sh.html>`__
+                    +
                     +exercises/sec\_groups.sh
+                    +
                     +`Read » <exercises/sec_groups.sh.html>`__
+                    +
                     +exercises/swift.sh
+                    +
                     +`Read » <exercises/swift.sh.html>`__
+                    +
                     +exercises/trove.sh
+                    +
                     +`Read » <exercises/trove.sh.html>`__
+                    +
                     +exercises/volumes.sh
+                    +
                     +`Read » <exercises/volumes.sh.html>`__
+                    +
                     +exercises/zaqar.sh
+                    +
                     +`Read » <exercises/zaqar.sh.html>`__
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,88 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +openrc User authentication settings
                     +-----------------------------------
+                    +
                     +``openrc`` configures login credentials suitable for use with the
                     +OpenStack command-line tools. ``openrc`` sources ``stackrc`` at the
                     +beginning (which in turn sources the ``localrc`` setion of
                     +``local.conf``) in order to pick up ``HOST_IP`` and/or ``SERVICE_HOST``
                     +to use in the endpoints. The values shown below are the default values.
+                    +
                     +OS\_TENANT\_NAME
                     +    The introduction of Keystone to the OpenStack ecosystem has
                     +    standardized the term *tenant* as the entity that owns resources. In
                     +    some places references still exist to the original Nova term
                     +    *project* for this use. Also, *tenant\_name* is preferred to
                     +    *tenant\_id*.
+                    +
                     +    ::
+                    +
                     +        OS_TENANT_NAME=demo
+                    +
                     +OS\_USERNAME
                     +    In addition to the owning entity (tenant), Nova stores the entity
                     +    performing the action as the *user*.
+                    +
                     +    ::
+                    +
                     +        OS_USERNAME=demo
+                    +
                     +OS\_PASSWORD
                     +    With Keystone you pass the keystone password instead of an api key.
                     +    Recent versions of novaclient use OS\_PASSWORD instead of
                     +    NOVA\_API\_KEYs or NOVA\_PASSWORD.
+                    +
                     +    ::
+                    +
                     +        OS_PASSWORD=secrete
+                    +
                     +HOST\_IP, SERVICE\_HOST
                     +    Set API endpoint host using ``HOST_IP``. ``SERVICE_HOST`` may also
                     +    be used to specify the endpoint, which is convenient for some
                     +    ``localrc`` configurations. Typically, ``HOST_IP`` is set in the
                     +    ``localrc`` section.
+                    +
                     +    ::
+                    +
                     +        HOST_IP=127.0.0.1
                     +        SERVICE_HOST=$HOST_IP
+                    +
                     +OS\_AUTH\_URL
                     +    Authenticating against an OpenStack cloud using Keystone returns a
                     +    *Token* and *Service Catalog*. The catalog contains the endpoints
                     +    for all services the user/tenant has access to - including Nova,
                     +    Glance, Keystone and Swift.
+                    +
                     +    ::
+                    +
                     +        OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0
+                    +
                     +GLANCE\_HOST
                     +    Some exercises call Glance directly. On a single-node installation,
                     +    Glance should be listening on ``HOST_IP``. If its running elsewhere
                     +    it can be set here.
+                    +
                     +    ::
+                    +
                     +        GLANCE_HOST=$HOST_IP
+                    +
                     +KEYSTONECLIENT\_DEBUG, NOVACLIENT\_DEBUG
                     +    Set command-line client log level to ``DEBUG``. These are commented
                     +    out by default.
+                    +
                     +    ::
+                    +
                     +        # export KEYSTONECLIENT_DEBUG=1
                     +        # export NOVACLIENT_DEBUG=1
+                    +
                     +© Openstack Foundation 2011-2013 — An `OpenStack
                     +program <https://wiki.openstack.org/wiki/Programs>`__ created by
                     +`Rackspace Cloud
                     +Builders <http://www.rackspace.com/cloud/private_edition/>`__

                     new file mode 100644
@@ -0,0 +1,103 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Overview DevStack from a cloud-height view
                     +------------------------------------------
+                    +
                     +DevStack has evolved to support a large number of configuration options
                     +and alternative platforms and support services. That evolution has grown
                     +well beyond what was originally intended and the majority of
                     +configuration combinations are rarely, if ever, tested. DevStack is not
                     +a general OpenStack installer and was never meant to be everything to
                     +everyone..
+                    +
                     +Below is a list of what is specifically is supported (read that as
                     +"tested") going forward.
+                    +
                     +Supported Components
                     +--------------------
+                    +
                     +Base OS
                     +~~~~~~~
+                    +
                     +*The OpenStack Technical Committee (TC) has defined the current CI
                     +strategy to include the latest Ubuntu release and the latest RHEL
                     +release (for Python 2.6 testing).*
+                    +
                     +-  Ubuntu: current LTS release plus current development release
                     +-  Fedora: current release plus previous release
                     +-  RHEL: current major release
                     +-  Other OS platforms may continue to be included but the maintenance of
                     +   those platforms shall not be assumed simply due to their presence.
                     +   Having a listed point-of-contact for each additional OS will greatly
                     +   increase its chance of being well-maintained.
                     +-  Patches for Ubuntu and/or Fedora will not be held up due to
                     +   side-effects on other OS platforms.
+                    +
                     +Databases
                     +~~~~~~~~~
+                    +
                     +*As packaged by the host OS*
+                    +
                     +-  MySQL
                     +-  PostgreSQL
+                    +
                     +Queues
                     +~~~~~~
+                    +
                     +*As packaged by the host OS*
+                    +
                     +-  Rabbit
                     +-  Qpid
+                    +
                     +Web Server
                     +~~~~~~~~~~
+                    +
                     +*As packaged by the host OS*
+                    +
                     +-  Apache
+                    +
                     +OpenStack Network
                     +~~~~~~~~~~~~~~~~~
+                    +
                     +*Default to Nova Network, optionally use Neutron*
+                    +
                     +-  Nova Network: FlatDHCP
                     +-  Neutron: A basic configuration approximating the original FlatDHCP
                     +   mode using linuxbridge or OpenVSwitch.
+                    +
                     +Services
                     +~~~~~~~~
+                    +
                     +The default services configured by DevStack are Identity (Keystone),
                     +Object Storage (Swift), Image Storage (Glance), Block Storage (Cinder),
                     +Compute (Nova), Network (Nova), Dashboard (Horizon), Orchestration
                     +(Heat)
+                    +
                     +Additional services not included directly in DevStack can be tied in to
                     +``stack.sh`` using the `plugin mechanism <plugins.html>`__ to call
                     +scripts that perform the configuration and startup of the service.
+                    +
                     +Node Configurations
                     +~~~~~~~~~~~~~~~~~~~
+                    +
                     +-  single node
                     +-  multi-node is not tested regularly by the core team, and even then
                     +   only minimal configurations are reviewed
+                    +
                     +Exercises
                     +~~~~~~~~~
+                    +
                     +The DevStack exercise scripts are no longer used as integration and gate
                     +testing as that job has transitioned to Tempest. They are still
                     +maintained as a demonstrations of using OpenStack from the command line
                     +and for quick operational testing.
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,124 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +Plugins Add stuff
                     +-----------------
+                    +
                     +DevStack has a couple of plugin mechanisms to allow easily adding
                     +support for additional projects and features.
+                    +
                     +Extras.d Hooks
                     +~~~~~~~~~~~~~~
+                    +
                     +These relatively new hooks are an extension of the existing calls from
                     +``stack.sh`` at the end of its run, plus ``unstack.sh`` and
                     +``clean.sh``. A number of the higher-layer projects are implemented in
                     +DevStack using this mechanism.
+                    +
                     +The script in ``extras.d`` is expected to be mostly a dispatcher to
                     +functions in a ``lib/*`` script. The scripts are named with a
                     +zero-padded two digits sequence number prefix to control the order that
                     +the scripts are called, and with a suffix of ``.sh``. DevSack reserves
                     +for itself the sequence numbers 00 through 09 and 90 through 99.
+                    +
                     +Below is a template that shows handlers for the possible command-line
                     +arguments:
+                    +
                     +::
+                    +
                     +    # template.sh - DevStack extras.d dispatch script template
+                    +
                     +    # check for service enabled
                     +    if is_service_enabled template; then
+                    +
                     +        if [[ "$1" == "source" ]]; then
                     +            # Initial source of lib script
                     +            source $TOP_DIR/lib/template
                     +        fi
+                    +
                     +        if [[ "$1" == "stack" && "$2" == "pre-install" ]]; then
                     +            # Set up system services
                     +            echo_summary "Configuring system services Template"
                     +            install_package cowsay
+                    +
                     +        elif [[ "$1" == "stack" && "$2" == "install" ]]; then
                     +            # Perform installation of service source
                     +            echo_summary "Installing Template"
                     +            install_template
+                    +
                     +        elif [[ "$1" == "stack" && "$2" == "post-config" ]]; then
                     +            # Configure after the other layer 1 and 2 services have been configured
                     +            echo_summary "Configuring Template"
                     +            configure_template
+                    +
                     +        elif [[ "$1" == "stack" && "$2" == "extra" ]]; then
                     +            # Initialize and start the template service
                     +            echo_summary "Initializing Template"
                     +            ##init_template
                     +        fi
+                    +
                     +        if [[ "$1" == "unstack" ]]; then
                     +            # Shut down template services
                     +            # no-op
                     +            :
                     +        fi
+                    +
                     +        if [[ "$1" == "clean" ]]; then
                     +            # Remove state and transient data
                     +            # Remember clean.sh first calls unstack.sh
                     +            # no-op
                     +            :
                     +        fi
                     +    fi
+                    +
                     +The arguments are:
+                    +
                     +-  **source** - Called by each script that utilizes ``extras.d`` hooks;
                     +   this replaces directly sourcing the ``lib/*`` script.
                     +-  **stack** - Called by ``stack.sh`` three times for different phases
                     +   of its run:
+                    +
                     +   -  **pre-install** - Called after system (OS) setup is complete and
                     +      before project source is installed.
                     +   -  **install** - Called after the layer 1 and 2 projects source and
                     +      their dependencies have been installed.
                     +   -  **post-config** - Called after the layer 1 and 2 services have
                     +      been configured. All configuration files for enabled services
                     +      should exist at this point.
                     +   -  **extra** - Called near the end after layer 1 and 2 services have
                     +      been started. This is the existing hook and has not otherwise
                     +      changed.
+                    +
                     +-  **unstack** - Called by ``unstack.sh`` before other services are shut
                     +   down.
                     +-  **clean** - Called by ``clean.sh`` before other services are cleaned,
                     +   but after ``unstack.sh`` has been called.
+                    +
                     +Hypervisor
                     +~~~~~~~~~~
+                    +
                     +Hypervisor plugins are fairly new and condense most hypervisor
                     +configuration into one place.
+                    +
                     +The initial plugin implemented was for Docker support and is a useful
                     +template for the required support. Plugins are placed in
                     +``lib/nova_plugins`` and named ``hypervisor-<name>`` where ``<name>`` is
                     +the value of ``VIRT_DRIVER``. Plugins must define the following
                     +functions:
+                    +
                     +-  ``install_nova_hypervisor`` - install any external requirements
                     +-  ``configure_nova_hypervisor`` - make configuration changes, including
                     +   those to other services
                     +-  ``start_nova_hypervisor`` - start any external services
                     +-  ``stop_nova_hypervisor`` - stop any external services
                     +-  ``cleanup_nova_hypervisor`` - remove transient data and cache
+                    +
                     +© Openstack Foundation 2011-2013 — An `OpenStack
                     +program <https://wiki.openstack.org/wiki/Programs>`__ created by
                     +`Rackspace Cloud
                     +Builders <http://www.rackspace.com/cloud/private_edition/>`__

                     new file mode 100644
@@ -0,0 +1,77 @@
                     +`DevStack </>`__
+                    +
                     +-  `Overview <overview.html>`__
                     +-  `Changes <changes.html>`__
                     +-  `FAQ <faq.html>`__
                     +-  `git.openstack.org <https://git.openstack.org/cgit/openstack-dev/devstack>`__
                     +-  `Gerrit <https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z>`__
+                    +
                     +stackrc DevStack settings
                     +-------------------------
+                    +
                     +``stackrc`` is the primary configuration file for DevStack. It contains
                     +all of the settings that control the services started and the
                     +repositories used to download the source for those services. ``stackrc``
                     +sources the ``localrc`` section of ``local.conf`` to perform the default
                     +overrides.
+                    +
                     +DATABASE\_TYPE
                     +    Select the database backend to use. The default is ``mysql``,
                     +    ``postgresql`` is also available.
                     +ENABLED\_SERVICES
                     +    Specify which services to launch. These generally correspond to
                     +    screen tabs. The default includes: Glance (API and Registry),
                     +    Keystone, Nova (API, Certificate, Object Store, Compute, Network,
                     +    Scheduler, VNC proxies, Certificate Authentication), Cinder
                     +    (Scheduler, API, Volume), Horizon, MySQL, RabbitMQ, Tempest.
+                    +
                     +    ::
+                    +
                     +        ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-obj,n-cpu,n-net,n-cond,cinder,c-sch,c-api,c-vol,n-sch,n-novnc,n-xvnc,n-cauth,horizon,rabbit,tempest,$DATABASE_TYPE
+                    +
                     +    Other services that are not enabled by default can be enabled in
                     +    ``localrc``. For example, to add Swift, use the following service
                     +    names:
+                    +
                     +    ::
+                    +
                     +        enable_service s-proxy s-object s-container s-account
+                    +
                     +    A service can similarly be disabled:
+                    +
                     +    ::
+                    +
                     +        disable_service horizon
+                    +
                     +Service Repos
                     +    The Git repositories used to check out the source for each service
                     +    are controlled by a pair of variables set for each service.
                     +    ``*_REPO`` points to the repository and ``*_BRANCH`` selects which
                     +    branch to check out. These may be overridden in ``local.conf`` to
                     +    pull source from a different repo for testing, such as a Gerrit
                     +    branch proposal. ``GIT_BASE`` points to the primary repository
                     +    server.
+                    +
                     +    ::
+                    +
                     +        NOVA_REPO=$GIT_BASE/openstack/nova.git
                     +        NOVA_BRANCH=master
+                    +
                     +    To pull a branch directly from Gerrit, get the repo and branch from
                     +    the Gerrit review page:
+                    +
                     +    ::
+                    +
                     +        git fetch https://review.openstack.org/p/openstack/nova refs/changes/50/5050/1 && git checkout FETCH_HEAD
+                    +
                     +    The repo is the stanza following ``fetch`` and the branch is the
                     +    stanza following that:
+                    +
                     +    ::
+                    +
                     +        NOVA_REPO=https://review.openstack.org/p/openstack/nova
                     +        NOVA_BRANCH=refs/changes/50/5050/1
+                    +
                     +© Openstack Foundation 2011-2014 — An
                     +`OpenStack <https://www.openstack.org/>`__
                     +`program <https://wiki.openstack.org/wiki/Programs>`__

                     new file mode 100644
@@ -0,0 +1,23 @@
                     +[metadata]
                     +name = DevStack
                     +summary = OpenStack DevStack
                     +description-file =
                     +    README.md
                     +author = OpenStack
                     +author-email = openstack-dev@lists.openstack.org
                     +home-page = http://devstack.org
                     +classifier =
                     +    Intended Audience :: Developers
                     +    License :: OSI Approved :: Apache Software License
                     +    Operating System :: POSIX :: Linux
+                    +
                     +[build_sphinx]
                     +all_files = 1
                     +build-dir = doc/build
                     +source-dir = doc/source
+                    +
                     +[pbr]
                     +warnerrors = True
+                    +
                     +[wheel]
                     +universal = 1

                     new file mode 100755
@@ -0,0 +1,22 @@
                     +#!/usr/bin/env python
                     +# Copyright (c) 2013 Hewlett-Packard Development Company, L.P.
                     +#
                     +# 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.
+                    +
                     +# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT
                     +import setuptools
+                    +
                     +setuptools.setup(
                     +    setup_requires=['pbr'],
                     +    pbr=True)

@@ -16,8 +16,13 @@ commands = bash -c "find {toxinidir} -not -wholename \*.tox/\* -and \( -name \*.
                      deps =
                         Pygments
                         docutils
                     +   sphinx>=1.1.2,<1.2
                     +   pbr>=0.6,!=0.7,<1.0
                     +   oslosphinx
                      whitelist_externals = bash
                      setenv =
                        TOP_DIR={toxinidir}
                        INSTALL_SHOCCO=true
                     -commands = bash tools/build_docs.sh
                     +commands =
                     +	bash tools/build_docs.sh
                     +	python setup.py build_sphinx