openstack/devstack
Code Issues Proposed changes

Convert all HTML doc to RST

Browse Source 
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
This commit is contained in:
Sean M. Collins 2014-10-21 11:40:08 -04:00
parent 58f1405665
commit 09e550c370
42 changed files with 2836 additions and 2878 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
doc/source/changes.html
View File

@ -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>

18
doc/source/changes.rst Normal file
View File

@ -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>`__

263
doc/source/conf.py Normal file
View File

@ -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

237
doc/source/configuration.html
View File

@ -1,237 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - Overview</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="overview" class="span12">
<div class='row pull-left'>
<h2>Configuration <small>Making it go my way</small></h2>
<p>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 <code>localrc</code> 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 (<code>EXTRAS_OPTS</code> and friends) required specific code for each file and did not scale well.</p>
<p>In Oct 2013 a new configuration method was introduced (in <a href="https://review.openstack.org/#/c/46768/">review 46768</a>) to hopefully simplify this process and meet the following goals:</p>
<ul>
<li>contain all non-default local configuration in a single file</li>
<li>be backward-compatible with <code>localrc</code> to smooth the transition process</li>
<li>allow settings in arbitrary configuration files to be changed</li>
</ul>
<h3>local.conf</h3>
<p>The new configuration file is <code>local.conf</code> and resides in the root DevStack directory like the old <code>localrc</code> 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.</p>
<p>The new header is similar to a normal INI section header but with double brackets (<code>[[ ... ]]</code>) and two internal fields separated by a pipe (<code>|</code>):</p>
<pre>[[ &lt;phase&gt; | &lt;config-file-name&gt; ]]
</pre>
<p>where <code>&lt;phase&gt;</code> is one of a set of phase names defined by <code>stack.sh</code> and <code>&lt;config-file-name&gt;</code> is the configuration filename. The filename is eval'ed in the <code>stack.sh</code> 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 <code>NOVA_CONF</code> example below). If the path of the config file does not exist it is skipped.</p>
<p>The defined phases are:</p>
<ul>
<li><strong>local</strong> - extracts <code>localrc</code> from <code>local.conf</code> before <code>stackrc</code> is sourced</li>
<li><strong>pre-install</strong> - runs after the system packages are installed but before any of the source repositories are installed</li>
<li><strong>install</strong> - runs immediately after the repo installations are complete</li>
<li><strong>post-config</strong> - runs after the layer 2 services are configured and before they are started</li>
<li><strong>extra</strong> - runs after services are started and before any files in <code>extra.d</code> are executed
</ul>
<p>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.</p>
<pre>[[post-config|$NOVA_CONF]]
[DEFAULT]
use_syslog = True
[osapi_v3]
enabled = False
</pre>
<p>A specific meta-section <code>local|localrc</code> is used to
provide a default <code>localrc</code> file (actually
<code>.localrc.auto</code>). This allows all custom settings
for DevStack to be contained in a single file. If <code>localrc</code>
exists it will be used instead to preserve backward-compatibility. More
details on the <a href="localrc.html">contents of localrc</a> are available.</p>
<pre>[[local|localrc]]
FIXED_RANGE=10.254.1.0/24
ADMIN_PASSWORD=speciale
LOGFILE=$DEST/logs/stack.sh.log
</pre>
<p>Note that <code>Q_PLUGIN_CONF_FILE</code> is unique in that it is assumed to <em>NOT</em> start with a <code>/</code> (slash) character. A slash will need to be added:</p>
<pre>[[post-config|/$Q_PLUGIN_CONF_FILE]]
</pre>
<p>Also note that the <code>localrc</code> section is sourced as a shell script fragment amd <string>MUST</strong> conform to the shell requirements, specifically no whitespace around <code>=</code> (equals).</p>
<a id="minimal"></a>
<h3>Minimal Configuration</h3>
<p>While <code>stack.sh</code> is happy to run without a <code>localrc</code> section in <code>local.conf</code>, 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.</p>
<ul>
<li>no logging</li>
<li>pre-set the passwords to prevent interactive prompts</li>
<li>move network ranges away from the local network (<code>FIXED_RANGE</code> and <code>FLOATING_RANGE</code>, commented out below)</li>
<li>set the host IP if detection is unreliable (<code>HOST_IP</code>, commented out below)</li>
</ul>
<pre>[[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</pre>
<p>If the <code>*_PASSWORD</code> variables are not set here you will be prompted to enter values for them by <code>stack.sh</code>.</p>
<p>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.</p>
<p><code>HOST_IP</code> is normally detected on the first run of <code>stack.sh</code> 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 <code>openrc</code> to set <code>OS_AUTH_URL</code>. <code>HOST_IP</code> is not set by default.</p>
<h3>Common Configuration Variables</h3>
<dl>
<dt>Set DevStack install directory</dt>
<dd><em>Default: <code>DEST=/opt/stack</code></em><br />
The DevStack install directory is set by the <code>DEST</code> variable. By setting it early in the <code>localrc</code> 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.
<pre>DEST=/opt/stack</pre></dd>
<dt>stack.sh logging</dt>
<dd><em>Defaults: <code>LOGFILE="" LOGDAYS=7 LOG_COLOR=True</code></em><br />
By default <code>stack.sh</code> output is only written to the console where is runs. It can be sent to a file in addition to the console by setting <code>LOGFILE</code> to the fully-qualified name of the destination log file. A timestamp will be appended to the given filename for each run of <code>stack.sh</code>.
<pre>LOGFILE=$DEST/logs/stack.sh.log</pre>
Old log files are cleaned automatically if <code>LOGDAYS</code> is set to the number of days of old log files to keep.
<pre>LOGDAYS=1</pre>
The some of the project logs (Nova, Cinder, etc) will be colorized by default (if <code>SYSLOG</code> is not set below); this can be turned off by setting <code>LOG_COLOR</code> False.
<pre>LOG_COLOR=False</pre></dd>
<dt>Screen logging</dt>
<dd><em>Default: <code>SCREEN_LOGDIR=""</code></em><br />
By default DevStack runs the OpenStack services using <code>screen</code> which is useful for watching log and debug output. However, in automated testing the interactive <code>screen</code> sessions may not be available after the fact; setting <code>SCREEN_LOGDIR</code> enables logging of the <code>screen</code> sessions in the specified diretory. There will be one file per <code>screen</code> session named for the session name and a timestamp.
<pre>SCREEN_LOGDIR=$DEST/logs/screen</pre>
<em>Note the use of <code>DEST</code> to locate the main install directory; this is why we suggest setting it in <code>local.conf</code>.</em></dd><br />
<dt>One syslog to bind them all</dt>
<dd><em>Default: <code>SYSLOG=False SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516</code></em><br />
Logging all services to a single syslog can be convenient. Enable syslogging by setting <code>SYSLOG</code> to <code>True</code>. If the destination log host is not localhost <code>SYSLOG_HOST</code> and <code>SYSLOG_PORT</code> can be used to direct the message stream to the log host.
<pre>SYSLOG=True
SYSLOG_HOST=$HOST_IP
SYSLOG_PORT=516</pre></dd>
<dt>A clean install every time</dt>
<dd><em>Default: <code>RECLONE=""</code></em><br />
By default <code>stack.sh</code> only clones the project repos if they do not exist in <code>$DEST</code>. <code>stack.sh</code> will freshen each repo on each run if <code>RECLONE</code> is set to <code>yes</code>. This avoids having to manually remove repos in order to get the current branch from <code>$GIT_BASE</code>.
<pre>RECLONE=yes</code></dd>
<dt>Swift</dt>
<dd><em>Default: <code>SWIFT_HASH="" SWIFT_REPLICAS=1 SWIFT_DATA_DIR=$DEST/data/swift</code></em><br />
Swift is now used as the back-end for the S3-like object store. When enabled Nova's objectstore (n-obj in <code>ENABLED_SERVICES</code>) is automatically disabled. Enable Swift by adding it services to <code>ENABLED_SERVICES</code>:
<pre>enable_service s-proxy s-object s-container s-account</pre>
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:
<pre>SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5</pre>
For development purposes the default number of replicas is set to <code>1</code> to reduce the overhead required. To better simulate a production deployment set this to <code>3</code> or more.
<pre>SWIFT_REPLICAS=3</pre>
The data for Swift is stored in the source tree by default
(in <code>$DEST/swift/data</code>) and can be moved by setting
<code>SWIFT_DATA_DIR</code>. The specified directory will be created if it does not exist.
<pre>SWIFT_DATA_DIR=$DEST/data/swift</pre>
<em>Note: Previously just enabling <code>swift</code> 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.</em>
</dd>
<dt>Service Catalog Backend</dt>
<dd><em>Default: <code>KEYSTONE_CATALOG_BACKEND=sql</code></em><br />
DevStack uses Keystone's <code>sql</code> service catalog backend. An alternate <code>template</code> backend is also available. However, it does not support the <code>service-*</code> and <code>endpoint-*</code> commands of the <code>keystone</code> CLI. To
do so requires the <code>sql</code> backend be enabled:
<pre>KEYSTONE_CATALOG_BACKEND=template</pre>
DevStack's default configuration in <code>sql</code> mode is set in
<code>files/keystone_data.sh</code></dd>
<dt>Cinder</dt>
<dd><em>Default: <code>VOLUME_GROUP="stack-volumes" VOLUME_NAME_PREFIX="volume-" VOLUME_BACKING_FILE_SIZE=10250M</code></em><br />
The logical volume group used to hold the Cinder-managed volumes is set by <code>VOLUME_GROUP</code>, the logical volume name prefix is set with <code>VOLUME_NAME_PREFIX</code> and the size of the volume backing file is set with <code>VOLUME_BACKING_FILE_SIZE</code>.
<pre>VOLUME_GROUP="stack-volumes"
VOLUME_NAME_PREFIX="volume-"
VOLUME_BACKING_FILE_SIZE=10250M</pre></dd>
<dt>Multi-host DevStack</dt>
<dd><em>Default: <code>MULTI_HOST=False</code></em><br />
Running DevStack with multiple hosts requires a custom <code>local.conf</code> section for each host. The master is the same as a single host installation with <code>MULTI_HOST=True</code>. The slaves have fewer services enabled and a couple of host variables pointing to the master.
<br /><br />
<strong>Master</strong>
<pre>MULTI_HOST=True</pre>
<strong>Slave</strong>
<pre>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</pre></dd>
<dt>API rate limits</dt>
<dd><em>Default: <code>API_RATE_LIMIT=True</code><br />
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 <code>API_RATE_LIMIT=False</code>.
<pre>API_RATE_LIMIT=False</pre></dd>
</dl>
<h3>Examples</h3>
<ul>
<li>Eliminate a Cinder pass-through (<code>CINDER_PERIODIC_INTERVAL</code>):
<pre>[[post-config|$CINDER_CONF]]
[DEFAULT]
periodic_interval = 60
</pre></li>
<li>Sample <code>local.conf</code> with screen logging enabled:
<pre>[[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</pre></li>
</ul>
</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>

360
doc/source/configuration.rst Normal file
View File

@ -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>`__

88
doc/source/contributing.html
View File

@ -1,88 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - Overview</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="overview" class="span12">
<div class='row pull-left'>
<h2>Contributing <small>Help us help you</small></h2>
<p>DevStack uses the standard OpenStack contribution process as outlined in <a href="https://wiki.openstack.org/wiki/How_To_Contribute">the OpenStack wiki 'How To Contribute'</a>. 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.</p>
<h3>Things To Know</h3>
<br /><strong>Where Things Are</strong>
<p>The official DevStack repository is located at <code>git://git.openstack.org/openstack-dev/devstack.git</code>, replicated from the repo maintained by Gerrit. GitHub also has a mirror at <code>git://github.com/openstack-dev/devstack.git</code>.</p>
<p>The <a href="https://blueprints.launchpad.net/devstack">blueprint</a> and <a href="https://bugs.launchpad.net/devstack">bug trackers</a> 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.</p>
<p>The <a href="https://review.openstack.org/#/q/project:openstack-dev/devstack,n,z">Gerrit review queue</a> is, however, used for all commits except for the text of this website. That should also change in the near future.</p>
<br /><strong>HACKING.rst</strong>
<p>Like most OpenStack projects, DevStack includes a <code>HACKING.rst</code> file that describes the layout, style and conventions of the project. Because <code>HACKING.rst</code> is in the main DevStack repo it is considered authoritative. Much of the content on this page is taken from there.</p>
<br /><strong>bashate Formatting</strong>
<p>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 <code>bashate</code>. 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 <code>./run_tests.sh</code>.</p>
<h3>Code</h3>
<br /><strong>Repo Layout</strong>
<p>The DevStack repo generally keeps all of the primary scripts at the root level.</p>
<p><code>docs</code> - Contains the source for this website. It is built using <code>tools/build_docs.sh</code>.</p>
<p><code>exercises</code> - 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.</p>
<p><code>extras.d</code> - Contains the dispatch scripts called by the hooks in <code>stack.sh</code>, <code>unstack.sh</code> and <code>clean.sh</code>. See <a href="plugins.html">the plugins docs</a> for more information.</p>
<p><code>files</code> - 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.</p>
<p><code>lib</code> - 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.</p>
<p><code>samples</code> - Contains a sample of the local files not included in the DevStack repo.</p>
<p><code>tests</code> - the DevStack test suite is rather sparse, mostly consisting of test of specific fragile functions in the <code>functions</code> file.</p>
<p><code>tools</code> - 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.</p>
</section>
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; An <a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a> created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
</footer>
</div> <!-- /container -->
</body>
</html>

105
doc/source/contributing.rst Normal file
View File

@ -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/>`__

94
doc/source/eucarc.html
View File

@ -1,94 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - eucarc</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">
<section class="span12">
<div class="page-header">
<h2>eucarc <small>EC2 settings</small></h2>
<p><code>eucarc</code> creates EC2 credentials for the current user as
defined by <code>OS_TENANT_NAME:OS_USERNAME</code>.
<code>eucarc</code> sources <code>openrc</code> at the beginning
(which in turn sources <code>stackrc</code> and <code>localrc</code>)
in order to set credentials to create EC2 credentials in Keystone.
</div>
<dl>
<dt>EC2_URL</dt>
<dd>Set the EC2 url for euca2ools. The endpoint is extracted from the
service catalog for <code>OS_TENANT_NAME:OS_USERNAME</code>.
<pre>EC2_URL=$(keystone catalog --service ec2 | awk '/ publicURL / { print $4 }')</pre></dd>
<dt>S3_URL</dt>
<dd>Set the S3 endpoint for euca2ools. The endpoint is extracted from the
service catalog for <code>OS_TENANT_NAME:OS_USERNAME</code>.
<pre>export S3_URL=$(keystone catalog --service s3 | awk '/ publicURL / { print $4 }')</pre></dd>
<dt>EC2_ACCESS_KEY, EC2_SECRET_KEY</dt>
<dd>Create EC2 credentials for the current tenant:user in Keystone.
<pre>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 }')</pre></dd>
<dt>Certificates for Bundling</dt>
<dd>Euca2ools requires certificate files to enable bundle uploading.
The exercise script <code>exercises/bundle.sh</code> demonstrated
retrieving certificates using the Nova CLI.
<pre>EC2_PRIVATE_KEY=pk.pem
EC2_CERT=cert.pem
NOVA_CERT=cacert.pem
EUCALYPTUS_CERT=${NOVA_CERT}</pre></dd>
</dl>
</section
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; An
<a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a>
created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
</footer>
</div> <!-- /container -->
</body>
</html>

57
doc/source/eucarc.rst Normal file
View File

@ -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/>`__

88
doc/source/exerciserc.html
View File

@ -1,88 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - exerciserc</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">
<section class="span12">
<div class="page-header">
<h2>exerciserc <small>Exercise settings</small></h2>
<p><code>exerciserc</code> 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 <code>localrc</code>
section.</p>
</div>
<dl>
<dt>ACTIVE_TIMEOUT</dt>
<dd>Max time to wait while vm goes from build to active state
<pre>ACTIVE_TIMEOUT==30</pre></dd>
<dt>ASSOCIATE_TIMEOUT</dt>
<dd>Max time to wait for proper IP association and dis-association.
<pre>ASSOCIATE_TIMEOUT=15</pre></dd>
<dt>BOOT_TIMEOUT</dt>
<dd>Max time till the vm is bootable
<pre>BOOT_TIMEOUT=30</pre></dd>
<dt>RUNNING_TIMEOUT</dt>
<dd>Max time from run instance command until it is running
<pre>RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))</pre></dd>
<dt>TERMINATE_TIMEOUT</dt>
<dd>Max time to wait for a vm to terminate
<pre>TERMINATE_TIMEOUT=30</pre></dd>
</dl>
</section
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; An
<a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a>
created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
</footer>
</div> <!-- /container -->
</body>
</html>

54
doc/source/exerciserc.rst Normal file
View File

@ -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/>`__

169
doc/source/faq.html
View File

@ -1,169 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - Frequently Asked Questions</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>FAQ: Using DevStack <small>Making to behave</small></h2>
<ul>
<li><a href="#general">General Questions</a></li>
<li><a href="#ops_conf">Operation and Configuration</a></li>
<li><a href="#misc">Miscellaneous</a></li>
</ul>
<h3><a name="general">General Questions</a></h3>
<dl class='pull-left'>
<dt>Q: Can I use DevStack for production?</dt>
<dd>A: No. We mean it. Really. DevStack makes some implementation choices that are not appropriate for production deployments. We warned you!</dd>
<dt>Q: Then why selinux in enforcing mode?</dt>
<dd>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. <code>stack.sh</code>'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.</dd>
<dt>Q: But selinux is disabled in RHEL 6!</dt>
<dd>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.</dd>
<dt>Q: Why a shell script, why not chef/puppet/...</dt>
<dd>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.</dd>
<dt>Q: Why not use Crowbar?</dt>
<dd>A: DevStack is optimized for documentation &amp; developers. As some of us use <a href="https://github.com/dellcloudedge/crowbar">Crowbar</a> for production deployments, we hope developers documenting how they setup systems for new features supports projects like Crowbar.</dd>
<dt>Q: I'd like to help!</dt>
<dd>A: That isn't a question, but please do! The source for DevStack is at <a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a> and bug reports go to <a href="http://bugs.launchpad.net/devstack/">LaunchPad</a>. Contributions follow the usual process as described in the <a href="http://wiki.openstack.org/HowToContribute">OpenStack wiki</a> even though DevStack is not an official OpenStack project. This site is housed in the CloudBuilder's <a href="http://github.com/cloudbuilders/devstack">github</a> in the gh-pages branch.</dd>
<dt>Q: Why not use packages?</dt>
<dd>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.</dd>
<dt>Q: Why isn't $MY_FAVORITE_DISTRO supported?</dt>
<dd>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 <code>README.md</code>. DevStack is only supported on releases other than those documented in <code>README.md</code> on a best-effort basis.</dd>
<dt>Q: What about Fedora/RHEL/CentOS?</dt>
<dd>A: Fedora and CentOS/RHEL are supported via rpm dependency files and specific checks in <code>stack.sh</code>. 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.</dd>
<dt>Q: Are there any differences between Ubuntu and Fedora support?</dt>
<dd>A: Neutron is not fully supported prior to Fedora 18 due lack of OpenVSwitch packages.</dd>
<dt>Q: How about RHEL 6?</dt>
<dd>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 <code>stack.sh</code> to handle this. But the testing on py26 is valuable so we do it...</dd>
</dl>
<h3><a name="ops_conf">Operation and Configuration</a></h3>
<dl class='pull-left'>
<dt>Q: Can DevStack handle a multi-node installation?</dt>
<dd>A: Indirectly, yes. You run DevStack on each node with the appropriate configuration in <code>local.conf</code>. 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.</dd>
<dt>Q: How can I document the environment that DevStack is using?</dt>
<dd>A: DevStack includes a script (<code>tools/info.sh</code>) 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.</dd>
<dt>Q: How do I turn off a service that is enabled by default?</dt>
<dd>A: Services can be turned off by adding <code>disable_service xxx</code> to <code>local.conf</code> (using <code>n-vol</code> in this example):
<pre>disable_service n-vol</pre>
</dd>
<dt>Q: Is enabling a service that defaults to off done with the reverse of the above?</dt>
<dd>A: Of course!
<pre>enable_service qpid</pre>
</dd>
<dt>Q: How do I run a specific OpenStack milestone?</dt>
<dd>A: OpenStack milestones have tags set in the git repo. Set the appropriate tag in the <code>*_BRANCH</code> variables in <code>local.conf</code>. Swift is on its own release schedule so pick a tag in the Swift repo that is just before the milestone release. For example:
<pre>[[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</pre>
</dd>
<!--- this is incomplete, remove it until populating the sql catalog is complete
<dt>Q: How do I use the SQL catalog backend in Keystone?</dt>
<dd>A: Comment out the template backend lines in the <code>[catalog]</code> section of <code>keystone/etc/keystone.conf</code> and add the SQL backend config like this:
<pre>[catalog]
#driver = keystone.catalog.backends.templated.TemplatedCatalog
#template_file = ./etc/default_catalog.templates
driver = keystone.catalog.backends.sql.Catalog</pre>
</dd>
-->
<dt>Q: Why not use <strike><code>tools/pip-requires</code></strike><code>requirements.txt</code> to grab project dependencies?</dt>
<dd><strike>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.</strike> 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.</dd>
<dt>Q: What can I do about RabbitMQ not wanting to start on my fresh new VM?</dt>
<dd>A: This is often caused by <code>erlang</code> 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 <code>/etc/hosts</code> is often good enough for a single-node installation. And in an extreme case, use <code>clean.sh</code> to eradicate it and try again.</dd>
<dt>Q: How can I set up Heat in stand-alone configuration?</dt>
<dd>A: Configure <code>local.conf</code> thusly:
<pre>[[local|localrc]]
HEAT_STANDALONE=True
ENABLED_SERVICES=rabbit,mysql,heat,h-api,h-api-cfn,h-api-cw,h-eng
KEYSTONE_SERVICE_HOST=&lt;keystone-host&gt;
KEYSTONE_AUTH_HOST=&lt;keystone-host&gt;</pre>
</dd>
<dt>Q: Why are my configuration changes ignored?</dt>
<dd>A: You may have run into the package prerequisite installation timeout. <code>tools/install_prereqs.sh</code> has a timer that skips the package installation checks if it was run within the last <code>PREREQ_RERUN_HOURS</code> hours (default is 2). To override this, set <code>FORCE_PREREQ=1</code> and the package checks will never be skipped.
</dd>
</dl>
<h3><a name="misc">Miscellaneous</a></h3>
<dl class='pull-left'>
<dt>Q: <code>tools/fixup_stuff.sh</code> is broken and shouldn't 'fix' just one version of packages.</dt>
<dd>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 <code>httplib2</code> and <code>prettytable</code> 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.</dd>
</dl>
</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>

184
doc/source/faq.rst Normal file
View File

@ -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>`__

336
doc/source/guides/multinode-lab.html
View File

@ -1,336 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Multi-Node Lab Server Guide - DevStack</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">
<section id="overview">
<h1>Multi-Node Lab: Serious Stuff</h1>
<p>Here is OpenStack in a realistic test configuration with multiple physical servers.</p>
</section>
<section id="prerequisites">
<div class="page-header">
<h2>Prerequisites <small>Linux & Network</small></h2>
</div>
<h3>Minimal Install</h3>
<p>You need to have a system with a fresh install of Linux. You can download the <a href="https://help.ubuntu.com/community/Installation/MinimalCD">Minimal CD</a> for Ubuntu releases since DevStack will download &amp; install all the additional dependencies. The netinstall ISO is available for <a href="http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso">Fedora</a> and <a href="http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso">CentOS/RHEL</a>.</p>
<p>Install a couple of packages to bootstrap configuration:</p>
<pre>apt-get install -y git sudo || yum install -y git sudo</pre>
<h3>Network Configuration</h3>
<p>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:</p>
<ul>
<li>Gateway: 192.168.42.1</li>
<li>Physical nodes: 192.168.42.11-192.168.42.99</li>
<li>Floating IPs: 192.168.42.128-192.168.42.254</li>
</ul>
<p>Configure each node with a static IP.
For Ubuntu edit <code>/etc/network/interfaces</code>:</p>
<pre>auto eth0
iface eth0 inet static
address 192.168.42.11
netmask 255.255.255.0
gateway 192.168.42.1
</pre>
<p>For Fedora and CentOS/RHEL edit
<code>/etc/sysconfig/network-scripts/ifcfg-eth0</code>:</p>
<pre>BOOTPROTO=static
IPADDR=192.168.42.11
NETMASK=255.255.255.0
GATEWAY=192.168.42.1
</pre>
<!-- save these for the VLAN version
auto eth0.926
iface eth0.926 inet static
address 10.4.144.3
netmask 255.255.240.0
#gateway 10.4.144.1
up ifconfig eth0.926
auto eth0.605
iface eth0.605 inet static
address 172.16.103.3
netmask 255.255.255.0
#gateway 172.16.103.1
up ifconfig eth0.605 up
-->
</section>
<section id="installation">
<div class="page-header">
<h2>Installation <small>shake and bake</small></h2>
</div>
<h3>Add the DevStack User</h3>
<p>OpenStack runs as a non-root user that has sudo access to root. There is nothing special
about the name, we'll use <code>stack</code> 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:</p>
<pre>groupadd stack
useradd -g stack -s /bin/bash -d /opt/stack -m stack</pre>
<p>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:</p>
<pre>echo "stack ALL=(ALL) NOPASSWD: ALL" &gt;&gt; /etc/sudoers</pre>
<p>From here on use the <code>stack</code> user. <b>Logout</b> and <b>login</b> as the
<code>stack</code> user.</p>
<h3>Set Up Ssh</h3>
<p>Set up the stack user on each node with an ssh key for access:</p>
<pre>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</pre>
<h3>Download DevStack</h3>
<p>Grab the latest version of DevStack:</p>
<pre>git clone https://git.openstack.org/openstack-dev/devstack
cd devstack</pre>
<p>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.</p>
<h3>Configure Cluster Controller</h3>
<p>The cluster controller runs all OpenStack services. Configure the cluster controller's DevStack in <code>local.conf</code>:</p>
<pre>[[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</pre>
<!-- save for vlan
FLAT_INTERFACE=eth0.926
-->
<p>In the multi-node configuration the first 10 or so IPs in the private subnet are usually reserved. Add this to <code>local.sh</code> to have it run after every <code>stack.sh</code> run:</p>
<pre>for i in `seq 2 10`; do /opt/stack/nova/bin/nova-manage fixed reserve 10.4.128.$i; done</pre>
<p>Fire up OpenStack:</p>
<pre>./stack.sh</pre>
<p>A stream of activity ensues. When complete you will see a summary of
<code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
shiny new OpenStack. The most recent log file is available in <code>stack.sh.log</code>.</p>
<h3>Configure Compute Nodes</h3>
<p>The compute nodes only run the OpenStack worker services. For additional machines, create a <code>local.conf</code> with:</p>
<pre>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
</pre>
<!-- save for vlan
FLAT_INTERFACE=eth0.926
-->
<p>Fire up OpenStack:</p>
<pre>./stack.sh</pre>
<p>A stream of activity ensues. When complete you will see a summary of
<code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
shiny new OpenStack. The most recent log file is available in <code>stack.sh.log</code>.</p>
<h3>Cleaning Up After DevStack</h3>
<p>Shutting down OpenStack is now as simple as running the included <code>unstack.sh</code> script:</p>
<pre>./unstack.sh</pre>
<p>A more aggressive cleanup can be performed using <code>clean.sh</code>. 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.
<pre>./clean.sh</pre>
<p>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:</p>
<pre>sudo rm -rf /etc/libvirt/qemu/inst*
sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy</pre>
</section>
<section id="options">
<div class="page-header">
<h2>Options <small>pimp your stack</small></h2>
</div>
<h3>Additional Users</h3>
<p>DevStack creates two OpenStack users (<code>admin</code> and <code>demo</code>) and two tenants (also <code>admin</code> and <code>demo</code>). <code>admin</code> is exactly what it sounds like, a privileged administrative account that is a member of both the <code>admin</code> and <code>demo</code> tenants. <code>demo</code> is a normal user account that is only a member of the <code>demo</code> 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
<code>stack.sh</code> runs. The following steps are ripe for scripting:</p>
<pre># 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=&lt;bob-user-id&gt; --tenant-id=&lt;bob-tenant-id&gt; --role-id=&lt;member-role-id&gt;
# member-role-id comes from the existing member role created by stack.sh
# keystone role-list</pre>
<h3>Swift</h3>
<p>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 <code>swift</code> service in <code>local.conf</code>:
<pre>enable_service s-proxy s-object s-container s-account</pre>
<p>Swift will put its data files in <code>SWIFT_DATA_DIR</code> (default <code>/opt/stack/data/swift</code>).
The size of the data 'partition' created (really a loop-mounted file) is set by
<code>SWIFT_LOOPBACK_DISK_SIZE</code>. The Swift config files are located in
<code>SWIFT_CONFIG_DIR</code> (default <code>/etc/swift</code>). All of these settings can be overridden in
(wait for it...) <code>local.conf</code>.</p>
<h3>Volumes</h3>
<p>DevStack will automatically use an existing LVM volume group named <code>stack-volumes</code>
to store cloud-created volumes. If <code>stack-volumes</code> 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 <code>VOLUME_BACKING_FILE_SIZE</code> in <code>local.conf</code>.</p>
<p><code>stack-volumes</code> can be pre-created on any physical volume supported by
Linux's LVM. The name of the volume group can be changed by setting <code>VOLUME_GROUP</code>
in <code>localrc</code>. <code>stack.sh</code> deletes
all logical volumes in <code>VOLUME_GROUP</code> that begin with
<code>VOLUME_NAME_PREFIX</code> as part of cleaning up from previous runs.
It is recommended to not use the root volume group as <code>VOLUME_GROUP</code>.</p>
<p>The details of creating the volume group depends on the server hardware involved
but looks something like this:</p>
<pre>pvcreate /dev/sdc
vgcreate stack-volumes /dev/sdc</pre>
<h3>Syslog</h3>
<p>DevStack is capable of using <code>rsyslog</code> to aggregate logging across the cluster.
It is off by default; to turn it on set <code>SYSLOG=True</code> in <code>local.conf</code>.
<code>SYSLOG_HOST</code> defaults to <code>HOST_IP</code>; 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 <code>local.conf</code>:</p>
<pre>SYSLOG_HOST=192.168.42.11</pre>
<h3>Using Alternate Repositories/Branches</h3>
<p>The git repositories for all of the OpenStack services are defined in <code>stackrc</code>.
Since this file is a part of the DevStack package changes to it will probably be overwritten
as updates are applied. Every setting in <code>stackrc</code> can be redefined in
<code>local.conf</code>.</p>
<p>To change the repository or branch that a particular OpenStack service is created from,
simply change the value of <code>*_REPO</code> or <code>*_BRANCH</code> corresponding to
that service.</p>
<p>After making changes to the repository or branch, if <code>RECLONE</code> is not set
in <code>localrc</code> it may be necessary to remove the corresponding directory from
<code>/opt/stack</code> to force git to re-clone the repository.</p>
<p>For example, to pull Nova from a proposed release candidate in the primary Nova
repository:</p>
<pre>NOVA_BRANCH=rc-proposed</pre>
<p>To pull Glance from an experimental fork:</p>
<pre>GLANCE_BRANCH=try-something-big
GLANCE_REPO=https://github.com/mcuser/glance.git</pre>
</section>
<section id="Notes">
<div class="page-header">
<h2>Notes <small>stuff you might need to know</small></h2>
</div>
<h3>Reset the Bridge</h3>
<p>How to reset the bridge configuration:</p>
<pre>sudo brctl delif br100 eth0.926
sudo ip link set dev br100 down
sudo brctl delbr br100</pre>
<!--
sudo rm /etc/libvirt/qemu/*.xml
-->
<h3>Set MySQL Password</h3>
<p>If you forgot to set the root password you can do this:</p>
<pre>mysqladmin -u root -pnova password 'supersecret'</pre>
</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>

382
doc/source/guides/multinode-lab.rst Normal file
View File

@ -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>`__

147
doc/source/guides/pxe-boot.html
View File

@ -1,147 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>PXE Boot Server Guide - DevStack</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">
<section id="overview">
<h1>PXE Boot Server Guide: Magic Dust for Network Boot</h1>
<p>Boot DevStack from a PXE server to a RAM disk.</p>
</section>
<section id="requirements">
<div class="page-header">
<h2>Prerequisites <small>Hardware & OpenWRT</small></h2>
</div>
<h3>Hardware</h3>
<p>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.</p>
<h3>OpenWRT</h3>
<p>Any recent 'Backfire' build of OpenWRT will work for the boot server project. We build from trunk and have made the images available at <a href="http://openwrt.xr7.org/openwrt">http://openwrt.xr7.org/openwrt</a>.</p>
</section>
<section id="installation">
<div class="page-header">
<h2>Installation <small>bit blasting</small></h2>
</div>
<h3>Install the Image</h3>
<p>This process follows <a href="http://wiki.openwrt.org/toh/buffalo/wzr-hp-g300h">the OpenWRT doc OEM Install</a> 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.</p>
<ul>
<li>Get openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
<pre>wget http://openwrt.xr7.org/openwrt/ar71xx/openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin</pre>
</li>
<li>Connect computer to LAN port 4 (closest to WAN port)</li>
<li>Set computer interface to IP address in the 192.168.11.2</li>
<li>Add static arp entry for router
<pre>arp -s 192.168.11.1 &lt;mac-address&gt;</pre>
</li>
<li>Start TFTP transfer attempt
<pre>tftp 192.168.11.1
binary
rexmt 1
timeout 60
put openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin</pre>
</li>
<li>Power on router. Router will reboot and initialize on 192.168.1.1.</li>
<li>Delete static arp entry for router
<pre>arp -d 192.168.11.1</pre>
</li>
<li>Set computer to DHCP, connect and telnet to router and set root password.</li>
</ul>
<h3>Configure the Router</h3>
<ul>
<li>Update <code>/etc/opkg.conf</code> to point to our repo:
<pre>src/gz packages http://192.168.5.13/openwrt/build/ar71xx/packages</pre>
</li>
<li>Configure anon mounts:
<pre>uci delete fstab.@mount[0]
uci commit fstab
/etc/init.d/fstab restart</pre>
</li>
<li>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:
<pre>uci set dhcp.lan.start=65
uci set dhcp.lan.limit=60
uci commit dhcp</pre>
</li>
<li>Enable TFTP:
<pre>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</pre>
</li>
</ul>
<h3>Set Up tftpboot</h3>
<ul>
<li>Create the <code>/tmp/tftpboot</code> structure and populate it:
<pre>cd ~/devstack
tools/build_pxe_boot.sh /tmp</pre>
This calls <code>tools/build_ramdisk.sh</code> to create a 2GB ramdisk
containing a complete development Oneiric OS plus the
OpenStack code checkouts.
</li>
<li>Copy <code>tftpboot</code> to a USB drive:
<pre>mount /dev/sdb1 /mnt/tmp
rsync -a /tmp/tftpboot/ /mnt/tmp/tftpboot/
umount /mnt/tmp</pre>
</li>
<li>Plug USB drive into router. It will be automounted and is ready to serve content.</li>
</ul>
<p>Now <a href="ramdisk.html">return</a> to the RAM disk Guide to kick
off your DevStack experience.</p>
</section>
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; this is not an official OpenStack project...</p>
</footer>
</div> <!-- /container -->
</body>
</html>

143
doc/source/guides/pxe-boot.rst Normal file
View File

@ -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...

119
doc/source/guides/ramdisk.html
View File

@ -1,119 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>RAMdisk Boot Guide - DevStack</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">
<section id="overview">
<h1>Stack-in-a-Box: Try before you mkfs</h1>
<p>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.</p>
</section>
<section id="requirements">
<div class="page-header">
<h2>Prerequisites <small>Hardware</small></h2>
</div>
<h3>USB Boot</h3>
<p><a href="usb-boot.html">This guide</a> covers the creation of a bootable USB drive. Your
computer BIOS must support booting from USB.</p>
<h3>PXE Boot</h3>
<p><a href="pxe-boot.html">This guide</a> 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.
</section>
<section id="installation">
<div class="page-header">
<h2>Installation <small>bit blasting</small></h2>
</div>
<h3>Install DevStack</h3>
<p>Grab the latest version of DevStack via https:</p>
<pre>sudo apt-get install git -y
git clone https://git.openstack.org/openstack-dev/devstack
cd devstack</pre>
<h3>Prepare the Boot RAMdisk</h3>
<p>Pick your boot method and follow the guide to prepare to build
the RAM disk and set up the boot process:</p>
<ul>
<li><a href="usb-boot.html">USB boot</a></li>
<li><a href="pxe-boot.html">PXE boot</a></li>
</ul>
<h3>Fire It Up</h3>
<ul>
<li>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.</li>
<li>Select 'DevStack' from the Boot Menu.</li>
<li>Log in with the 'stack' user and 'pass' password.</li>
<li>Create <code>devstack/localrc</code> 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:
<pre>ADMIN_PASSWORD=openstack</pre>
</li>
<li>Fire up OpenStack!
<pre>./run.sh</pre>
</li>
<li>See the processes running in screen:
<pre>screen -x</pre>
</li>
<li>Connect to the dashboard at <code>http://&lt;ip-address&gt;/</code></li>
</ul>
</section>
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; this is not an official OpenStack project...</p>
</footer>
</div> <!-- /container -->
</body>
</html>

89
doc/source/guides/ramdisk.rst Normal file
View File

@ -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...

131
doc/source/guides/single-machine.html
View File

@ -1,131 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Single Machine Guide - DevStack</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">
<section id="overview">
<h1>All-In-One: Dedicated Hardware</h1>
<p>Things are about to get real! Using OpenStack in containers or VMs is nice for kicking the tires, but doesn't compare to the feeling you get with hardware.</p>
</section>
<section id="prerequisites">
<div class="page-header">
<h2>Prerequisites <small>Linux & Network</small></h2>
</div>
<h3>Minimal Install</h3>
<p>You need to have a system with a fresh install of Linux. You can download the <a href="https://help.ubuntu.com/community/Installation/MinimalCD">Minimal CD</a> for Ubuntu releases since DevStack will download &amp; install all the additional dependencies. The netinstall ISO is available for <a href="http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso">Fedora</a> and <a href="http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso">CentOS/RHEL</a>. You may be tempted to use a desktop distro on a laptop, it will probably work but you may need to tell Network Manager to keep its fingers off the interface(s) that OpenStack uses for bridging.</p>
<h3>Network Configuration</h3>
<p>Determine the network configuration on the interface used to integrate your
OpenStack cloud with your existing network. For example, if the IPs given out on your network
by DHCP are 192.168.1.X - where X is between 100 and 200 you will be able to use IPs
201-254 for <b>floating ips</b>.</p>
<p>To make things easier later change your host to use a static IP instead of DHCP (i.e. 192.168.1.201).</p>
</section>
<section id="installation">
<div class="page-header">
<h2>Installation <small>shake and bake</small></h2>
</div>
<h3>Add your user</h3>
<p>We need to add a user to install DevStack. (if you created a user during install you can skip this step and just give the user sudo privileges below)</p>
<pre>adduser stack</pre>
<p>Since this user will be making many changes to your system, it will need to have sudo privileges:</p>
<pre>apt-get install sudo -y || yum install -y sudo
echo "stack ALL=(ALL) NOPASSWD: ALL" &gt;&gt; /etc/sudoers</pre>
<p>From here on you should use the user you created. <b>Logout</b> and <b>login</b> as that user.</p>
<h3>Download DevStack</h3>
<p>We'll grab the latest version of DevStack via https:</p>
<pre>sudo apt-get install git -y || yum install -y git
git clone https://git.openstack.org/openstack-dev/devstack
cd devstack</pre>
<h3>Run DevStack</h3>
<p>Now to configure <code>stack.sh</code>. DevStack includes a sample in <code>devstack/samples/local.conf</code>. Create <code>local.conf</code> as shown below to do the following:</p>
<ul>
<li>Set <code>FLOATING_RANGE</code> to a range not used on the local network, i.e. 192.168.1.224/27. This configures IP addresses ending in 225-254 to be used as floating IPs.</li>
<li>Set <code>FIXED_RANGE</code> and <code>FIXED_NETWORK_SIZE</code> to configure the internal address space used by the instances.</li>
<li>Set <code>FLAT_INTERFACE</code> to the Ethernet interface that connects the host to your local network. This is the interface that should be configured with the static IP address mentioned above.</li>
<li>Set the administrative password. This password is used for the <b>admin</b> and <b>demo</b> accounts set up as OpenStack users.</li>
<li>Set the MySQL administrative password. The default here is a random hex string which is inconvenient if you need to look at the database directly for anything.</li>
<li>Set the RabbitMQ password.</li>
<li>Set the service password. This is used by the OpenStack services (Nova, Glance, etc) to authenticate with Keystone.</li>
</ul>
<p><code>local.conf</code> should look something like this:</p>
<pre>[[local|localrc]]
FLOATING_RANGE=192.168.1.224/27
FIXED_RANGE=10.11.12.0/24
FIXED_NETWORK_SIZE=256
FLAT_INTERFACE=eth0
ADMIN_PASSWORD=supersecret
MYSQL_PASSWORD=iheartdatabases
RABBIT_PASSWORD=flopsymopsy
SERVICE_PASSWORD=iheartksl</pre>
<p>Run DevStack:</p>
<pre>./stack.sh</pre>
<p>A seemingly endless stream of activity ensues. When complete you will see a summary of
<code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
shiny new OpenStack.</p>
<h3>Using OpenStack</h3>
<p>At this point you should be able to access the dashboard from other computers on the
local network. In this example that would be http://192.168.1.201/ for the dashboard (aka Horizon).
Launch VMs and if you give them floating IPs and security group access those VMs will be accessible from other machines on your network.</p>
<p>Some examples of using the OpenStack command-line clients <code>nova</code> and <code>glance</code>
are in the shakedown scripts in <code>devstack/exercises</code>. <code>exercise.sh</code>
will run all of those scripts and report on the results.</p>
</section>
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; An <a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a> created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
</footer>
</div> <!-- /container -->
</body>
</html>

145
doc/source/guides/single-machine.rst Normal file
View File

@ -0,0 +1,145 @@
`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>`__
All-In-One: Dedicated Hardware
==============================
Things are about to get real! Using OpenStack in containers or VMs is
nice for kicking the tires, but doesn't compare to the feeling you get
with hardware.
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>`__.
You may be tempted to use a desktop distro on a laptop, it will probably
work but you may need to tell Network Manager to keep its fingers off
the interface(s) that OpenStack uses for bridging.
Network Configuration
~~~~~~~~~~~~~~~~~~~~~
Determine the network configuration on the interface used to integrate
your OpenStack cloud with your existing network. For example, if the IPs
given out on your network by DHCP are 192.168.1.X - where X is between
100 and 200 you will be able to use IPs 201-254 for **floating ips**.
To make things easier later change your host to use a static IP instead
of DHCP (i.e. 192.168.1.201).
Installation shake and bake
---------------------------
Add your user
~~~~~~~~~~~~~
We need to add a user to install DevStack. (if you created a user during
install you can skip this step and just give the user sudo privileges
below)
::
adduser stack
Since this user will be making many changes to your system, it will need
to have sudo privileges:
::
apt-get install sudo -y || yum install -y sudo
echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
From here on you should use the user you created. **Logout** and
**login** as that user.
Download DevStack
~~~~~~~~~~~~~~~~~
We'll grab the latest version of DevStack via https:
::
sudo apt-get install git -y || yum install -y git
git clone https://git.openstack.org/openstack-dev/devstack
cd devstack
Run DevStack
~~~~~~~~~~~~
Now to configure ``stack.sh``. DevStack includes a sample in
``devstack/samples/local.conf``. Create ``local.conf`` as shown below to
do the following:
- Set ``FLOATING_RANGE`` to a range not used on the local network, i.e.
192.168.1.224/27. This configures IP addresses ending in 225-254 to
be used as floating IPs.
- Set ``FIXED_RANGE`` and ``FIXED_NETWORK_SIZE`` to configure the
internal address space used by the instances.
- Set ``FLAT_INTERFACE`` to the Ethernet interface that connects the
host to your local network. This is the interface that should be
configured with the static IP address mentioned above.
- Set the administrative password. This password is used for the
**admin** and **demo** accounts set up as OpenStack users.
- Set the MySQL administrative password. The default here is a random
hex string which is inconvenient if you need to look at the database
directly for anything.
- Set the RabbitMQ password.
- Set the service password. This is used by the OpenStack services
(Nova, Glance, etc) to authenticate with Keystone.
``local.conf`` should look something like this:
::
[[local|localrc]]
FLOATING_RANGE=192.168.1.224/27
FIXED_RANGE=10.11.12.0/24
FIXED_NETWORK_SIZE=256
FLAT_INTERFACE=eth0
ADMIN_PASSWORD=supersecret
MYSQL_PASSWORD=iheartdatabases
RABBIT_PASSWORD=flopsymopsy
SERVICE_PASSWORD=iheartksl
Run DevStack:
::
./stack.sh
A seemingly endless 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.
Using OpenStack
~~~~~~~~~~~~~~~
At this point you should be able to access the dashboard from other
computers on the local network. In this example that would be
http://192.168.1.201/ for the dashboard (aka Horizon). Launch VMs and if
you give them floating IPs and security group access those VMs will be
accessible from other machines on your network.
Some examples of using the OpenStack command-line clients ``nova`` and
``glance`` are in the shakedown scripts in ``devstack/exercises``.
``exercise.sh`` will run all of those scripts and report on the results.
© 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/>`__

137
doc/source/guides/single-vm.html
View File

@ -1,137 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Single Machine Guide - DevStack</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">
<section id="overview">
<h1>Running a Cloud in a VM</h1>
<p>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.</p>
</section>
<section id="prerequisites">
<div class="page-header">
<h2>Prerequisites <small>Cloud & Image</small></h2>
</div>
<h3>Virtual Machine</h3>
<p>DevStack should run in any virtual machine running a supported Linux release. It will perform best with 2Gb or more of RAM.</p>
<h3>OpenStack Deployment &amp; cloud-init</h3>
<p>If the cloud service has an image with <code>cloud-init</code> pre-installed, use it. You can
get one from <a href="http://uec-images.ubuntu.com">Ubuntu's Daily Build</a>
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 <code>cloud-init</code>
is outside the scope of this document, refer to <a href"http://cloudinit.readthedocs.org/en/latest/index.html">the
<code>cloud-init</code> docs</a> for more information.</p>
<p>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.</p>
</section>
<section id="requirements">
<div class="page-header">
<h2>Installation <small>shake and bake</small></h2>
</div>
<h3>Launching With Cloud-Init</h3>
<p>This cloud config grabs the latest version of DevStack via git, creates a minimal
<code>local.conf</code> file and kicks off <code>stack.sh</code>. It should
be passed as the user-data file when booting the VM.</p>
<pre>#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</pre>
<p>As DevStack will refuse to run as root, this configures <code>cloud-init</code>
to create a non-root user and run the <code>start.sh</code> script as that user.</p>
<h3>Launching By Hand</h3>
<p>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.</p>
<h3>Using OpenStack</h3>
<p>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.</p>
<p>One interesting use case is for developers working on a VM on their laptop. Once
<code>stack.sh</code> has completed once, all of the pre-requisite packages are installed
in the VM and the source trees checked out. Setting <code>OFFLINE=True</code> in
<code>local.conf</code> enables <code>stack.sh</code> to run multiple times without an Internet
connection. DevStack, making hacking at the lake possible since 2012!</p>
</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>

110
doc/source/guides/single-vm.rst Normal file
View File

@ -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>`__

99
doc/source/guides/usb-boot.html
View File

@ -1,99 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>USB Boot Server Guide - DevStack</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">
<section id="overview">
<h1>USB Boot: Undoable Stack Boot</h1>
<p>Boot DevStack from a USB disk into a RAM disk.</p>
</section>
<section id="requirements">
<div class="page-header">
<h2>Prerequisites</h2>
</div>
<h3>Hardware</h3>
<p>This guide covers the creation of a bootable USB drive. Your
computer BIOS must support booting from USB and You will want at least 3GB of
RAM. You also will need a USB drive of at least 2GB.</p>
<h3>Software</h3>
<p>Ubuntu 11.10 (Oneiric Ocelot) is required on host to create images.</p>
</section>
<section id="installation">
<div class="page-header">
<h2>Installation <small>bit blasting</small></h2>
</div>
<h3>Set Up USB Drive</h3>
<ul>
<li>Insert the USB drive into the computer. Make a note of the device name, such as
<code>sdb</code>. Do not mount the device.</li>
<li>Install the boot system:
<pre>tools/build_usb_boot.sh /dev/sdb1</pre>
<p>This calls tools/build_ramdisk.sh to create a 2GB ramdisk
containing a complete development Oneiric OS plus the
OpenStack code checkouts. It then writes a syslinux boot sector
to the specified device and creates <code>/syslinux</code>.</p>
</li>
<li>If desired, you may now mount the device:
<pre>mount /dev/sdb1 /mnt/tmp
# foo
umount /mnt/tmp</pre>
</li>
</ul>
<p>Now <a href="ramdisk.html">return</a> to the RAM disk Guide to kick
off your DevStack experience.</p>
</section>
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; this is not an official OpenStack project...</p>
</footer>
</div> <!-- /container -->
</body>
</html>

60
doc/source/guides/usb-boot.rst Normal file
View File

@ -0,0 +1,60 @@
`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>`__
USB Boot: Undoable Stack Boot
=============================
Boot DevStack from a USB disk into a RAM disk.
Prerequisites
-------------
Hardware
~~~~~~~~
This guide covers the creation of a bootable USB drive. Your computer
BIOS must support booting from USB and You will want at least 3GB of
RAM. You also will need a USB drive of at least 2GB.
Software
~~~~~~~~
Ubuntu 11.10 (Oneiric Ocelot) is required on host to create images.
Installation bit blasting
-------------------------
Set Up USB Drive
~~~~~~~~~~~~~~~~
- Insert the USB drive into the computer. Make a note of the device
name, such as ``sdb``. Do not mount the device.
- Install the boot system:
::
tools/build_usb_boot.sh /dev/sdb1
This calls tools/build\_ramdisk.sh to create a 2GB ramdisk containing
a complete development Oneiric OS plus the OpenStack code checkouts.
It then writes a syslinux boot sector to the specified device and
creates ``/syslinux``.
- If desired, you may now mount the device:
::
mount /dev/sdb1 /mnt/tmp
# foo
umount /mnt/tmp
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...

562
doc/source/index.html
View File

@ -1,562 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - Deploying OpenStack for Developers</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">
<div class="hero-unit">
<div class="pull-left">
<h1 id="main_header">DevStack - an OpenStack Community Production</h1>
<div class="sub_header">
<p></p>
<p>A documented shell script to build complete OpenStack development environments. <br /><br />
An OpenStack program maintained by the developer community.</p>
</div>
</div>
<div class="pull-left">
<ol id="getting_started">
<li id="ubuntu">Setup a fresh supported Linux installation.</li>
<li id="git">
Clone devstack from git.openstack.org.
<pre>git clone https://git.openstack.org/openstack-dev/devstack</pre>
</li>
<li id="install">
Deploy your OpenStack Cloud
<pre>cd devstack &amp;&amp; ./stack.sh</pre>
</li>
</ol>
</div>
<div class="clear">&nbsp;</div>
</div>
<section id="quickstart" class="span12">
<div class="page-header">
<h2>Quick Start <small>This ain't your first rodeo</small></h2>
</div>
<ol>
<li value="0">
<h3>Select a Linux Distribution</h3>
<p>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.</p>
</li>
<li>
<h3>Install Selected OS</h3>
<p>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.</p>
</li>
<li>
<h3>Download DevStack</h3>
<pre>git clone https://git.openstack.org/openstack-dev/devstack</pre>
<p>The <code>devstack</code> repo contains a script that installs OpenStack and templates for configuration files</p>
</li>
<li>
<h3>Configure</h3>
<p>We recommend at least a <a href="configuration.html">minimal configuration</a> be set up.</p>
</li>
<li>
<h3>Start the install</h3>
<pre>cd devstack; ./stack.sh</pre>
<p>It takes a few minutes, we recommend <a href="stack.sh.html">reading the script</a> while it is building.</p>
</li>
</ol>
</section>
<section id="guides" class='span12'>
<div class="page-header">
<h2>Guides <small>Walk through various setups used by stackers</small></h2>
</div>
<div class='row span8'>
<h2>OpenStack on VMs</h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Title</th>
<th>Description</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>Virtual Machine</td>
<td>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.</td>
<td><a class="btn btn-small btn-primary table-action" href="guides/single-vm.html">Read &raquo;</a></td>
</tr>
<!--
<tr>
<td>LXC Containers</td>
<td>Already running Ubuntu on your machine? Using containers lets you build even faster.</td>
<td>Coming soon!</td>
</tr>
-->
</tbody>
<tfoot>
<td colspan="3">1 Guide</td>
</tfoot>
</table>
</div>
<div class="wat span3 pull-right">
<h4>What is this?</h4>
<p>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.</p>
</div>
<div class='row span8'>
<h2>OpenStack on Hardware</h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Title</th>
<th>Description</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>All-In-One</td>
<td>Run OpenStack on dedicated hardware to get real performance in your VMs. This can include a server-class machine or a laptop at home.</td>
<td><a class="btn btn-small btn-primary table-action" href="guides/single-machine.html">Read &raquo;</a></td>
</tr>
<tr>
<td>Multi-Node + VLANs</td>
<td>Setup a multi-node cluster with dedicated VLANs for VMs &amp; Management.</td>
<td><a class="btn btn-small btn-primary table-action" href="guides/multinode-lab.html">Read &raquo;</a></td>
</tr>
<!--
<tr>
<td>Stack-in-a-Box</td>
<td>Run OpenStack from a RAM disk to give it a spin without touching your existing OS installation. Includes PXE and USB boot methods.</td>
<td><a class="btn btn-small btn-primary table-action" href="guides/ramdisk.html">Read &raquo;</a></td>
</tr>
-->
</tbody>
<tfoot>
<td colspan="3">2 Guides</td>
</tfoot>
</table>
</div>
<div class="wat span3 pull-right">
<h4>What is this?</h4>
<p>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.</p>
</div>
</section>
<section id="docs" class="span12">
<div class="page-header">
<h2>Documentation <small>Help yourself to stack</small></h2>
</div>
<div class='row span5 pull-left'>
<h2>Overview</h2>
<p><a href="overview.html">An overview of DevStack goals and priorities</a></p>
<h2>Configuration</h2>
<p><a href="configuration.html">Configuring and customizing the stack</a></p>
<h2>Plugins</h2>
<p><a href="plugins.html">Extending DevStack with new features</a></p>
</div>
<div class='span5 pull-right'>
<h2>Recent Changes</h2>
<p><a href="changes.html">An incomplete summary of recent changes</a></p>
<h2>FAQ</h2>
<p><a href="faq.html">The DevStack FAQ</a></p>
<h2>Contributing</h2>
<p><a href="contributing.html">Pitching in to make DevStack a better place</a></p>
</div>
</section>
<section id="docs" class="span12">
<div class="page-header">
<h2>Code <small>A look at the bits that make it all go</small></h2>
</div>
<div class='row span5 pull-left'>
<h2>Scripts <small>Generated documentation of DevStack scripts.</small></h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Filename</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>stack.sh</td>
<td><a href="stack.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>functions</td>
<td><a href="functions.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>functions-common</td>
<td><a href="functions-common.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/apache</td>
<td><a href="lib/apache.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/baremetal</td>
<td><a href="lib/baremetal.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/ceilometer</td>
<td><a href="lib/ceilometer.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/cinder</td>
<td><a href="lib/cinder.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/config</td>
<td><a href="lib/config.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/database</td>
<td><a href="lib/database.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/glance</td>
<td><a href="lib/glance.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/heat</td>
<td><a href="lib/heat.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/horizon</td>
<td><a href="lib/horizon.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/infra</td>
<td><a href="lib/infra.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/ironic</td>
<td><a href="lib/ironic.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/keystone</td>
<td><a href="lib/keystone.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/ldap</td>
<td><a href="lib/ldap.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/zaqar</td>
<td><a href="lib/zaqar.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/neutron</td>
<td><a href="lib/neutron.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/nova</td>
<td><a href="lib/nova.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/oslo</td>
<td><a href="lib/oslo.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/rpc_backend</td>
<td><a href="lib/rpc_backend.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/sahara</td>
<td><a href="lib/sahara.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/savanna</td>
<td><a href="lib/savanna.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/stackforge</td>
<td><a href="lib/stackforge.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/swift</td>
<td><a href="lib/swift.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/tempest</td>
<td><a href="lib/tempest.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/tls</td>
<td><a href="lib/tls.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>lib/trove</td>
<td><a href="lib/trove.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>unstack.sh</td>
<td><a href="unstack.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>clean.sh</td>
<td><a href="clean.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>run_tests.sh</td>
<td><a href="run_tests.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/50-ironic.sh</td>
<td><a href="extras.d/50-ironic.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/70-zaqar.sh</td>
<td><a href="extras.d/70-zaqar.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/70-sahara.sh</td>
<td><a href="extras.d/70-sahara.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/70-savanna.sh</td>
<td><a href="extras.d/70-savanna.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/70-trove.sh</td>
<td><a href="extras.d/70-trove.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/80-opendaylight.sh</td>
<td><a href="extras.d/80-opendaylight.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>extras.d/80-tempest.sh</td>
<td><a href="extras.d/80-tempest.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
</tbody>
</table>
</div>
<div class='span5 pull-right'>
<h2>Configuration <small>Setting the table</small></h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Filename</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>local.conf</td>
<td><a href="local.conf.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>stackrc</td>
<td><a href="stackrc.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>openrc</td>
<td><a href="openrc.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exerciserc</td>
<td><a href="exerciserc.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>eucarc</td>
<td><a href="eucarc.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
</tbody>
</table>
<h2>Tools <small>Support scripts</small></h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Filename</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>tools/info.sh</td>
<td><a href="tools/info.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>tools/build_docs.sh</td>
<td><a href="tools/build_docs.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>tools/create_userrc.sh</td>
<td><a href="tools/create_userrc.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>tools/fixup_stuff.sh</td>
<td><a href="tools/fixup_stuff.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>tools/install_prereqs.sh</td>
<td><a href="tools/install_prereqs.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>tools/install_pip.sh</td>
<td><a href="tools/install_pip.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>tools/upload_image.sh</td>
<td><a href="tools/upload_image.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
</tbody>
</table>
<h2>Samples <small>Generated documentation of DevStack sample files.</small></h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Filename</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>local.sh</td>
<td><a href="samples/local.sh.html" class="btn btn-small btn-success table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>localrc</td>
<td><a href="samples/localrc.html" class="btn btn-small btn-success table-action">Read &raquo;</a></td>
</tr>
</tbody>
</table>
<div class='row span5 pull-right'>
<h2>Exercises <small>Generated documentation of DevStack scripts.</small></h2>
<table class='table table-striped table-bordered'>
<thead>
<tr>
<th>Filename</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>exercise.sh</td>
<td><a href="exercise.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/aggregates.sh</td>
<td><a href="exercises/aggregates.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/boot_from_volume.sh</td>
<td><a href="exercises/boot_from_volume.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/bundle.sh</td>
<td><a href="exercises/bundle.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/client-args.sh</td>
<td><a href="exercises/client-args.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/client-env.sh</td>
<td><a href="exercises/client-env.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/euca.sh</td>
<td><a href="exercises/euca.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/floating_ips.sh</td>
<td><a href="exercises/floating_ips.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/horizon.sh</td>
<td><a href="exercises/horizon.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/neutron-adv-test.sh</td>
<td><a href="exercises/neutron-adv-test.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<td>exercises/sahara.sh</td>
<td><a href="exercises/sahara.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<td>exercises/savanna.sh</td>
<td><a href="exercises/savanna.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/sec_groups.sh</td>
<td><a href="exercises/sec_groups.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/swift.sh</td>
<td><a href="exercises/swift.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<td>exercises/trove.sh</td>
<td><a href="exercises/trove.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/volumes.sh</td>
<td><a href="exercises/volumes.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
<tr>
<td>exercises/zaqar.sh</td>
<td><a href="exercises/zaqar.sh.html" class="btn btn-small btn-primary table-action">Read &raquo;</a></td>
</tr>
</tbody>
</table>
</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>

383
doc/source/index.rst Normal file
View File

@ -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>`__

64
doc/source/local.conf.html
View File

@ -1,64 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - local.conf</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">
<section class="span12">
<div class="page-header">
<h2>local.conf <small>User settings</small></h2>
<p><code>local.conf</code> is a user-maintained setings file that is
sourced in <code>stackrc</code>. It contains a section that replaces
the historical <code>localrc</code> file. See
<a href="configuration.html">the description of local.conf</a> for
more details about the mechanics of the file.</p>
</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>

20
doc/source/local.conf.rst Normal file
View File

@ -0,0 +1,20 @@
`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>`__
local.conf User settings
------------------------
``local.conf`` is a user-maintained setings file that is sourced in
``stackrc``. It contains a section that replaces the historical
``localrc`` file. See `the description of
local.conf <configuration.html>`__ for more details about the mechanics
of the file.
© Openstack Foundation 2011-2014 — An
`OpenStack <https://www.openstack.org/>`__
`program <https://wiki.openstack.org/wiki/Programs>`__

60
doc/source/localrc.html
View File

@ -1,60 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - localrc</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">
<section class="span12">
<div class="page-header">
<h2>localrc <small>User settings</small></h2>
<p><code>localrc</code> is the old file used to configure DevStack. It is deprecated and has been replaced by <a href="local.conf.html"><code>local.conf</code></a>. DevStack will continue to use <code>localrc</code> if it is present and ignore the <code>localrc</code> section in <code>local.conf.</code>. Remove <code>localrc</code> to switch to using the new file.</p>
</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>

20
doc/source/localrc.rst Normal file
View File

@ -0,0 +1,20 @@
`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>`__
localrc User settings
---------------------
``localrc`` is the old file used to configure DevStack. It is deprecated
and has been replaced by ```local.conf`` <local.conf.html>`__. DevStack
will continue to use ``localrc`` if it is present and ignore the
``localrc`` section in ``local.conf.``. Remove ``localrc`` to switch to
using the new file.
© Openstack Foundation 2011-2014 — An
`OpenStack <https://www.openstack.org/>`__
`program <https://wiki.openstack.org/wiki/Programs>`__

115
doc/source/openrc.html
View File

@ -1,115 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - openrc</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">
<section class="span12">
<div class="page-header">
<h2>openrc <small>User authentication settings</small></h2>
<p><code>openrc</code> configures login credentials suitable for use
with the OpenStack command-line tools. <code>openrc</code> sources
<code>stackrc</code> at the beginning (which in turn sources
the <code>localrc</code> setion of <code>local.conf</code>) in
order to pick up <code>HOST_IP</code>
and/or <code>SERVICE_HOST</code> to use in the endpoints.
The values shown below are the default values.</p>
</div>
<dl>
<dt>OS_TENANT_NAME</dt>
<dd>The introduction of Keystone to the OpenStack ecosystem has standardized the
term <em>tenant</em> as the entity that owns resources. In some places references
still exist to the original Nova term <em>project</em> for this use. Also,
<em>tenant_name</em> is preferred to <em>tenant_id</em>.
<pre>OS_TENANT_NAME=demo</pre></dd>
<dt>OS_USERNAME</dt>
<dd>In addition to the owning entity (tenant), Nova stores the entity performing
the action as the <em>user</em>.
<pre>OS_USERNAME=demo</pre></dd>
<dt>OS_PASSWORD</dt>
<dd>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.
<pre>OS_PASSWORD=secrete</pre></dd>
<dt>HOST_IP, SERVICE_HOST</dt>
<dd>Set API endpoint host using <code>HOST_IP</code>. <code>SERVICE_HOST</code>
may also be used to specify the endpoint, which is convenient for
some <code>localrc</code> configurations. Typically, <code>HOST_IP</code>
is set in the <code>localrc</code> section.
<pre>HOST_IP=127.0.0.1
SERVICE_HOST=$HOST_IP</pre></dd>
<dt>OS_AUTH_URL</dt>
<dd>Authenticating against an OpenStack cloud using Keystone returns a <em>Token</em>
and <em>Service Catalog</em>. The catalog contains the endpoints for all services
the user/tenant has access to - including Nova, Glance, Keystone and Swift.
<pre>OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0</pre></dd>
<dt>GLANCE_HOST</dt>
<dd>Some exercises call Glance directly. On a single-node installation, Glance
should be listening on <code>HOST_IP</code>. If its running elsewhere
it can be set here.
<pre>GLANCE_HOST=$HOST_IP</pre></dd>
<dt>KEYSTONECLIENT_DEBUG, NOVACLIENT_DEBUG</dt>
<dd>Set command-line client log level to <code>DEBUG</code>. These are
commented out by default.
<pre># export KEYSTONECLIENT_DEBUG=1
# export NOVACLIENT_DEBUG=1</pre></dd>
</dl>
</section
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; An
<a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a>
created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
</footer>
</div> <!-- /container -->
</body>
</html>

88
doc/source/openrc.rst Normal file
View File

@ -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/>`__

118
doc/source/overview.html
View File

@ -1,118 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - Overview</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="overview" class="span12">
<div class='row pull-left'>
<h2>Overview <small>DevStack from a cloud-height view</small></h2>
<p>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..</p>
<p>Below is a list of what is specifically is supported (read that as "tested") going forward.</p>
<h2>Supported Components</h2>
<h3>Base OS</h3>
<p><em>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).</em></p>
<ul>
<li>Ubuntu: current LTS release plus current development release</li>
<li>Fedora: current release plus previous release</li>
<li>RHEL: current major release</li>
<li>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.</li>
<li>Patches for Ubuntu and/or Fedora will not be held up due to side-effects on other OS platforms.</li>
</ul>
<h3>Databases</h3>
<p><em>As packaged by the host OS</em></p>
<ul>
<li>MySQL</li>
<li>PostgreSQL</li>
</ul>
<h3>Queues</h3>
<p><em>As packaged by the host OS</em></p>
<ul>
<li>Rabbit</li>
<li>Qpid</li>
<!--
<li>ZeroMQ</li>
-->
</ul>
<h3>Web Server</h3>
<p><em>As packaged by the host OS</em></p>
<ul>
<li>Apache</li>
</ul>
<h3>OpenStack Network</h3>
<p><em>Default to Nova Network, optionally use Neutron</em></p>
<ul>
<li>Nova Network: FlatDHCP</li>
<li>Neutron: A basic configuration approximating the original FlatDHCP mode using linuxbridge or OpenVSwitch.</li>
</ul>
<h3>Services</h3>
<p>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)</p>
<p>Additional services not included directly in DevStack can be tied in to <code>stack.sh</code> using the <a href="plugins.html">plugin mechanism</a> to call scripts that perform the configuration and startup of the service.</p>
<h3>Node Configurations</h3>
<ul>
<li>single node</li>
<li>multi-node is not tested regularly by the core team, and even then only minimal configurations are reviewed</li>
</ul>
<h3>Exercises</h3>
<p>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.</p>
</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>

103
doc/source/overview.rst Normal file
View File

@ -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>`__

142
doc/source/plugins.html
View File

@ -1,142 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - Plugins</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>Plugins <small>Add stuff</small></h2>
<p>DevStack has a couple of plugin mechanisms to allow easily adding support for additional projects and features.</p>
<h3>Extras.d Hooks</h3>
<p>These relatively new hooks are an extension of the existing calls from <code>stack.sh</code> at the end of its run, plus <code>unstack.sh</code> and <code>clean.sh</code>. A number of the higher-layer projects are implemented in DevStack using this mechanism.</p>
<p>The script in <code>extras.d</code> is expected to be mostly a dispatcher to functions in a <code>lib/*</code> 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 <code>.sh</code>. DevSack reserves for itself the sequence numbers 00 through 09 and 90 through 99.</p>
<p>Below is a template that shows handlers for the possible command-line arguments:</p>
<pre>
# 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
</pre>
<p>The arguments are:
<ul>
<li><strong>source</strong> - Called by each script that utilizes <code>extras.d</code> hooks; this replaces directly sourcing the <code>lib/*</code> script.</li>
<li><strong>stack</strong> - Called by <code>stack.sh</code> three times for different phases of its run:
<ul>
<li><strong>pre-install</strong> - Called after system (OS) setup is complete and before project source is installed.</li>
<li><strong>install</strong> - Called after the layer 1 and 2 projects source and their dependencies have been installed.</li>
<li><strong>post-config</strong> - Called after the layer 1 and 2 services have been configured. All configuration files for enabled services should exist at this point.</li>
<li><strong>extra</strong> - Called near the end after layer 1 and 2 services have been started. This is the existing hook and has not otherwise changed.</li>
</ul></li>
<li><strong>unstack</strong> - Called by <code>unstack.sh</code> before other services are shut down.</li>
<li><strong>clean</strong> - Called by <code>clean.sh</code> before other services are cleaned, but after <code>unstack.sh</code> has been called.
</ul></p>
<h3>Hypervisor</h3>
<p>Hypervisor plugins are fairly new and condense most hypervisor configuration into one place.</p>
<p>The initial plugin implemented was for Docker support and is a useful template for the required support. Plugins are placed in <code>lib/nova_plugins</code> and named <code>hypervisor-&lt;name&gt;</code> where <code>&lt;name&gt;</code> is the value of <code>VIRT_DRIVER</code>. Plugins must define the following functions:</p>
<ul>
<li><code>install_nova_hypervisor</code> - install any external requirements</li>
<li><code>configure_nova_hypervisor</code> - make configuration changes, including those to other services</li>
<li><code>start_nova_hypervisor</code> - start any external services</li>
<li><code>stop_nova_hypervisor</code> - stop any external services</li>
<li><code>cleanup_nova_hypervisor</code> - remove transient data and cache</li>
</ul>
</div>
</section>
<footer>
<p>&copy; Openstack Foundation 2011-2013 &mdash; An <a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a> created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
</footer>
</div> <!-- /container -->
</body>
</html>

124
doc/source/plugins.rst Normal file
View File

@ -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/>`__

101
doc/source/stackrc.html
View File

@ -1,101 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DevStack - stackrc</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">
<section class="span12">
<div class="page-header">
<h2>stackrc <small>DevStack settings</small></h2>
<p><code>stackrc</code> 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.
<code>stackrc</code> sources the <code>localrc</code> section of
<code>local.conf</code> to perform the default overrides.</p>
</div>
<dl>
<dt>DATABASE_TYPE</dt>
<dd>Select the database backend to use. The default is <code>mysql</code>,
<code>postgresql</code> is also available.</dd>
<dt>ENABLED_SERVICES</dt>
<dd>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.
<pre>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</pre>
Other services that are not enabled by default can be enabled in
<code>localrc</code>. For example, to add Swift, use the following service names:
<pre>enable_service s-proxy s-object s-container s-account</pre>
A service can similarly be disabled:
<pre>disable_service horizon</pre></dd>
<dt>Service Repos</dt>
<dd>The Git repositories used to check out the source for each service
are controlled by a pair of variables set for each service.
<code>*_REPO</code> points to the repository and <code>*_BRANCH</code>
selects which branch to check out. These may be overridden in
<code>local.conf</code> to pull source from a different repo for testing,
such as a Gerrit branch proposal. <code>GIT_BASE</code> points to the primary repository server.
<pre>NOVA_REPO=$GIT_BASE/openstack/nova.git
NOVA_BRANCH=master</pre>
To pull a branch directly from Gerrit, get the repo and branch from the
Gerrit review page:
<pre>git fetch https://review.openstack.org/p/openstack/nova refs/changes/50/5050/1 && git checkout FETCH_HEAD</pre>
The repo is the stanza following <code>fetch</code> and the branch
is the stanza following that:
<pre>NOVA_REPO=https://review.openstack.org/p/openstack/nova
NOVA_BRANCH=refs/changes/50/5050/1</pre></dd>
</dl>
</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>

77
doc/source/stackrc.rst Normal file
View File

@ -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>`__

23
setup.cfg Normal file
View File

@ -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

22
setup.py Executable file
View File

@ -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)

7
tox.ini
View File

@ -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