From 09e550c370cc79442236f8b05d00a7554bec9505 Mon Sep 17 00:00:00 2001 From: "Sean M. Collins" Date: Tue, 21 Oct 2014 11:40:08 -0400 Subject: [PATCH] Convert all HTML doc to RST The motivation for this conversion is to have DevStack's docs be generated using a more familair workflow for OpenStack projects, using Sphinx. Changing from raw HTML to RST will also make it easier to contribute more documentation, as well as making edits less of a hassle. The majority of the work was done by using Pandoc to convert from HTML to RST, with minor edits to the output to remove errors in Sphinx. Change-Id: I9636017965aeade37b950ddf5bdb0c22ab9004bd --- doc/source/changes.html | 70 ---- doc/source/changes.rst | 18 + doc/source/conf.py | 263 ++++++++++++ doc/source/configuration.html | 237 ----------- doc/source/configuration.rst | 360 +++++++++++++++++ doc/source/contributing.html | 88 ---- doc/source/contributing.rst | 105 +++++ doc/source/eucarc.html | 94 ----- doc/source/eucarc.rst | 57 +++ doc/source/exerciserc.html | 88 ---- doc/source/exerciserc.rst | 54 +++ doc/source/faq.html | 169 -------- doc/source/faq.rst | 184 +++++++++ doc/source/guides/multinode-lab.html | 336 --------------- doc/source/guides/multinode-lab.rst | 382 +++++++++++++++++ doc/source/guides/pxe-boot.html | 147 ------- doc/source/guides/pxe-boot.rst | 143 +++++++ doc/source/guides/ramdisk.html | 119 ------ doc/source/guides/ramdisk.rst | 89 ++++ doc/source/guides/single-machine.html | 131 ------ doc/source/guides/single-machine.rst | 145 +++++++ doc/source/guides/single-vm.html | 137 ------- doc/source/guides/single-vm.rst | 110 +++++ doc/source/guides/usb-boot.html | 99 ----- doc/source/guides/usb-boot.rst | 60 +++ doc/source/index.html | 562 -------------------------- doc/source/index.rst | 383 ++++++++++++++++++ doc/source/local.conf.html | 64 --- doc/source/local.conf.rst | 20 + doc/source/localrc.html | 60 --- doc/source/localrc.rst | 20 + doc/source/openrc.html | 115 ------ doc/source/openrc.rst | 88 ++++ doc/source/overview.html | 118 ------ doc/source/overview.rst | 103 +++++ doc/source/plugins.html | 142 ------- doc/source/plugins.rst | 124 ++++++ doc/source/stackrc.html | 101 ----- doc/source/stackrc.rst | 77 ++++ setup.cfg | 23 ++ setup.py | 22 + tox.ini | 7 +- 42 files changed, 2836 insertions(+), 2878 deletions(-) delete mode 100644 doc/source/changes.html create mode 100644 doc/source/changes.rst create mode 100644 doc/source/conf.py delete mode 100644 doc/source/configuration.html create mode 100644 doc/source/configuration.rst delete mode 100644 doc/source/contributing.html create mode 100644 doc/source/contributing.rst delete mode 100644 doc/source/eucarc.html create mode 100644 doc/source/eucarc.rst delete mode 100644 doc/source/exerciserc.html create mode 100644 doc/source/exerciserc.rst delete mode 100644 doc/source/faq.html create mode 100644 doc/source/faq.rst delete mode 100644 doc/source/guides/multinode-lab.html create mode 100644 doc/source/guides/multinode-lab.rst delete mode 100644 doc/source/guides/pxe-boot.html create mode 100644 doc/source/guides/pxe-boot.rst delete mode 100644 doc/source/guides/ramdisk.html create mode 100644 doc/source/guides/ramdisk.rst delete mode 100644 doc/source/guides/single-machine.html create mode 100644 doc/source/guides/single-machine.rst delete mode 100644 doc/source/guides/single-vm.html create mode 100644 doc/source/guides/single-vm.rst delete mode 100644 doc/source/guides/usb-boot.html create mode 100644 doc/source/guides/usb-boot.rst delete mode 100644 doc/source/index.html create mode 100644 doc/source/index.rst delete mode 100644 doc/source/local.conf.html create mode 100644 doc/source/local.conf.rst delete mode 100644 doc/source/localrc.html create mode 100644 doc/source/localrc.rst delete mode 100644 doc/source/openrc.html create mode 100644 doc/source/openrc.rst delete mode 100644 doc/source/overview.html create mode 100644 doc/source/overview.rst delete mode 100644 doc/source/plugins.html create mode 100644 doc/source/plugins.rst delete mode 100644 doc/source/stackrc.html create mode 100644 doc/source/stackrc.rst create mode 100644 setup.cfg create mode 100755 setup.py diff --git a/doc/source/changes.html b/doc/source/changes.html deleted file mode 100644 index 028e1cf9e5..0000000000 --- a/doc/source/changes.html +++ /dev/null @@ -1,70 +0,0 @@ - - - - - DevStack - Recent Changes - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
- -
-

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.

- -
    - - - -
-
- -
- - - -
- - diff --git a/doc/source/changes.rst b/doc/source/changes.rst new file mode 100644 index 0000000000..7ce629faa9 --- /dev/null +++ b/doc/source/changes.rst @@ -0,0 +1,18 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__. + +© Openstack Foundation 2011-2014 — An +`OpenStack `__ +`program `__ diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000000..3e9aa45911 --- /dev/null +++ b/doc/source/conf.py @@ -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 +# " v 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 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 diff --git a/doc/source/configuration.html b/doc/source/configuration.html deleted file mode 100644 index 88d7476bec..0000000000 --- a/doc/source/configuration.html +++ /dev/null @@ -1,237 +0,0 @@ - - - - - DevStack - Overview - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
- -
-

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) 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 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
    • -
- -
- - - -
- - diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000000..694ad62844 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,360 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__) 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 +(``|``): + +:: + + [[ | ]] + +where ```` is one of a set of phase names defined by ``stack.sh`` +and ```` 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 `__ 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 `__ +`program `__ diff --git a/doc/source/contributing.html b/doc/source/contributing.html deleted file mode 100644 index 9826fc7f4c..0000000000 --- a/doc/source/contributing.html +++ /dev/null @@ -1,88 +0,0 @@ - - - - - DevStack - Overview - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
- -
-

Contributing Help us help you

-

DevStack uses the standard OpenStack contribution process as outlined in the OpenStack 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 and bug trackers 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 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 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.

- - - -
- - - -
- - diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000000..e37c06b6a9 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,105 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +Contributing Help us help you +----------------------------- + +DevStack uses the standard OpenStack contribution process as outlined in +`the OpenStack 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 `__ and `bug +trackers `__ 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 `__ +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 `__ 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 `__ created by +`Rackspace Cloud +Builders `__ diff --git a/doc/source/eucarc.html b/doc/source/eucarc.html deleted file mode 100644 index 1dd80968d2..0000000000 --- a/doc/source/eucarc.html +++ /dev/null @@ -1,94 +0,0 @@ - - - - - DevStack - eucarc - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

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 - created by Rackspace Cloud Builders

- - -
- - - diff --git a/doc/source/eucarc.rst b/doc/source/eucarc.rst new file mode 100644 index 0000000000..c1065e6f61 --- /dev/null +++ b/doc/source/eucarc.rst @@ -0,0 +1,57 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ created by +`Rackspace Cloud +Builders `__ diff --git a/doc/source/exerciserc.html b/doc/source/exerciserc.html deleted file mode 100644 index 313b0a1daf..0000000000 --- a/doc/source/exerciserc.html +++ /dev/null @@ -1,88 +0,0 @@ - - - - - DevStack - exerciserc - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

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 - created by Rackspace Cloud Builders

- - -
- - - diff --git a/doc/source/exerciserc.rst b/doc/source/exerciserc.rst new file mode 100644 index 0000000000..22aff9a9e2 --- /dev/null +++ b/doc/source/exerciserc.rst @@ -0,0 +1,54 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ created by +`Rackspace Cloud +Builders `__ diff --git a/doc/source/faq.html b/doc/source/faq.html deleted file mode 100644 index 7cbb9d2fc5..0000000000 --- a/doc/source/faq.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - DevStack - Frequently Asked Questions - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
- -
-

FAQ: Using DevStack Making to behave

- - - -

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 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 and bug reports go to LaunchPad. Contributions follow the usual process as described in the OpenStack wiki even though DevStack is not an official OpenStack project. This site is housed in the CloudBuilder's github 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 tools/pip-requiresrequirements.txt to grab project dependencies?
-
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.
-
-
- -
- - - -
- - diff --git a/doc/source/faq.rst b/doc/source/faq.rst new file mode 100644 index 0000000000..9adc58ed1c --- /dev/null +++ b/doc/source/faq.rst @@ -0,0 +1,184 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ 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 `__ + and bug reports go to + `LaunchPad `__. Contributions + follow the usual process as described in the `OpenStack + wiki `__ even though + DevStack is not an official OpenStack project. This site is housed + in the CloudBuilder's + `github `__ 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_AUTH_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 `__ +`program `__ diff --git a/doc/source/guides/multinode-lab.html b/doc/source/guides/multinode-lab.html deleted file mode 100644 index 6a5f98c11d..0000000000 --- a/doc/source/guides/multinode-lab.html +++ /dev/null @@ -1,336 +0,0 @@ - - - - - Multi-Node Lab Server Guide - DevStack - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-

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 for Ubuntu releases since DevStack will download & install all the additional dependencies. The netinstall ISO is available for Fedora and CentOS/RHEL.

- -

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'
- -
- - - -
- - - diff --git a/doc/source/guides/multinode-lab.rst b/doc/source/guides/multinode-lab.rst new file mode 100644 index 0000000000..c7901a21fb --- /dev/null +++ b/doc/source/guides/multinode-lab.rst @@ -0,0 +1,382 @@ +`DevStack `__ + +- `Overview <../overview.html>`__ +- `Changes <../changes.html>`__ +- `FAQ <../faq.html>`__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ for +Ubuntu releases since DevStack will download & install all the +additional dependencies. The netinstall ISO is available for +`Fedora `__ +and +`CentOS/RHEL `__. + +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= --tenant-id= --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 `__ +`program `__ diff --git a/doc/source/guides/pxe-boot.html b/doc/source/guides/pxe-boot.html deleted file mode 100644 index d52b25f276..0000000000 --- a/doc/source/guides/pxe-boot.html +++ /dev/null @@ -1,147 +0,0 @@ - - - - - PXE Boot Server Guide - DevStack - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
-
-

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.

-
- -
-
-

Installation bit blasting

-
- -

Install the Image

-

This process follows the OpenWRT doc OEM Install 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 to the RAM disk Guide to kick - off your DevStack experience.

- -
- -
-

© Openstack Foundation 2011-2013 — this is not an official OpenStack project...

-
- -
- - - diff --git a/doc/source/guides/pxe-boot.rst b/doc/source/guides/pxe-boot.rst new file mode 100644 index 0000000000..584e5581fd --- /dev/null +++ b/doc/source/guides/pxe-boot.rst @@ -0,0 +1,143 @@ +`DevStack `__ + +- `Overview <../overview.html>`__ +- `Changes <../changes.html>`__ +- `FAQ <../faq.html>`__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__. + +Installation bit blasting +------------------------- + +Install the Image +~~~~~~~~~~~~~~~~~ + +This process follows `the OpenWRT doc OEM +Install `__ 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 + +- 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 `__ to the RAM disk Guide to kick off your +DevStack experience. + +© Openstack Foundation 2011-2013 — this is not an official OpenStack +project... diff --git a/doc/source/guides/ramdisk.html b/doc/source/guides/ramdisk.html deleted file mode 100644 index 23239e2b60..0000000000 --- a/doc/source/guides/ramdisk.html +++ /dev/null @@ -1,119 +0,0 @@ - - - - - RAMdisk Boot Guide - DevStack - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
-
-

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 covers the creation of a bootable USB drive. Your - computer BIOS must support booting from USB.

- -

PXE Boot

-

This guide 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:

- - -

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

-
- -
- - - diff --git a/doc/source/guides/ramdisk.rst b/doc/source/guides/ramdisk.rst new file mode 100644 index 0000000000..82147a8c1b --- /dev/null +++ b/doc/source/guides/ramdisk.rst @@ -0,0 +1,89 @@ +`DevStack `__ + +- `Overview <../overview.html>`__ +- `Changes <../changes.html>`__ +- `FAQ <../faq.html>`__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ covers the creation of a bootable USB +drive. Your computer BIOS must support booting from USB. + +PXE Boot +~~~~~~~~ + +`This guide `__ 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 `__ +- `PXE boot `__ + +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:///`` + +© Openstack Foundation 2011-2013 — this is not an official OpenStack +project... diff --git a/doc/source/guides/single-machine.html b/doc/source/guides/single-machine.html deleted file mode 100644 index 06cc981275..0000000000 --- a/doc/source/guides/single-machine.html +++ /dev/null @@ -1,131 +0,0 @@ - - - - - Single Machine Guide - DevStack - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
-
-

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 for Ubuntu releases since DevStack will download & install all the additional dependencies. The netinstall ISO is available for Fedora and CentOS/RHEL. 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.

- -
- - - -
- - - diff --git a/doc/source/guides/single-machine.rst b/doc/source/guides/single-machine.rst new file mode 100644 index 0000000000..0db0466281 --- /dev/null +++ b/doc/source/guides/single-machine.rst @@ -0,0 +1,145 @@ +`DevStack `__ + +- `Overview <../overview.html>`__ +- `Changes <../changes.html>`__ +- `FAQ <../faq.html>`__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ for +Ubuntu releases since DevStack will download & install all the +additional dependencies. The netinstall ISO is available for +`Fedora `__ +and +`CentOS/RHEL `__. +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 `__ created by +`Rackspace Cloud +Builders `__ diff --git a/doc/source/guides/single-vm.html b/doc/source/guides/single-vm.html deleted file mode 100644 index d189319623..0000000000 --- a/doc/source/guides/single-vm.html +++ /dev/null @@ -1,137 +0,0 @@ - - - - - Single Machine Guide - DevStack - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
-
-

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

-
- - - -
- - - diff --git a/doc/source/guides/single-vm.rst b/doc/source/guides/single-vm.rst new file mode 100644 index 0000000000..0e2d1573aa --- /dev/null +++ b/doc/source/guides/single-vm.rst @@ -0,0 +1,110 @@ +`DevStack `__ + +- `Overview <../overview.html>`__ +- `Changes <../changes.html>`__ +- `FAQ <../faq.html>`__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ 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 `__ +`program `__ diff --git a/doc/source/guides/usb-boot.html b/doc/source/guides/usb-boot.html deleted file mode 100644 index 2a05f89d89..0000000000 --- a/doc/source/guides/usb-boot.html +++ /dev/null @@ -1,99 +0,0 @@ - - - - - USB Boot Server Guide - DevStack - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
-
-

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 to the RAM disk Guide to kick - off your DevStack experience.

- -
- -
-

© Openstack Foundation 2011-2013 — this is not an official OpenStack project...

-
- -
- - - diff --git a/doc/source/guides/usb-boot.rst b/doc/source/guides/usb-boot.rst new file mode 100644 index 0000000000..888e14feb3 --- /dev/null +++ b/doc/source/guides/usb-boot.rst @@ -0,0 +1,60 @@ +`DevStack `__ + +- `Overview <../overview.html>`__ +- `Changes <../changes.html>`__ +- `FAQ <../faq.html>`__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ to the RAM disk Guide to kick off your +DevStack experience. + +© Openstack Foundation 2011-2013 — this is not an official OpenStack +project... diff --git a/doc/source/index.html b/doc/source/index.html deleted file mode 100644 index 5f1efd77fb..0000000000 --- a/doc/source/index.html +++ /dev/null @@ -1,562 +0,0 @@ - - - - - DevStack - Deploying OpenStack for Developers - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

DevStack - an OpenStack Community Production

-
-

-

A documented shell script to build complete OpenStack development environments.

- An OpenStack program maintained by the developer community.

-
-
-
-
    -
  1. Setup a fresh supported Linux installation.
    2. -
  2. - Clone devstack from git.openstack.org. - 
    git clone https://git.openstack.org/openstack-dev/devstack
    -
    3. -
  3. - Deploy your OpenStack Cloud - 
    cd devstack && ./stack.sh
    -
    4. -
-
-
 
-
- - -
-
-

Quick Start This ain't your first rodeo

-
-
    -
  1. -

    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.

    -
    2. -
  2. -

    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.

    -
    3. -
  3. -

    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

    -
    4. -
  4. -

    Configure

    -

    We recommend at least a minimal configuration be set up.

    -
    5. -
  5. -

    Start the install

    - 
    cd devstack; ./stack.sh
    -

    It takes a few minutes, we recommend reading the script while it is building.

    -
    6. -
-
- -
-
-

Guides Walk through various setups used by stackers

-
- -
-

OpenStack on VMs

- - - - - - - - - - - - - - - - - - - - -
TitleDescriptionLink
Virtual MachineRun 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 »
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

- - - - - - - - - - - - - - - - - - - - - - - - - - -
TitleDescriptionLink
All-In-OneRun OpenStack on dedicated hardware to get real performance in your VMs. This can include a server-class machine or a laptop at home.Read »
Multi-Node + VLANsSetup a multi-node cluster with dedicated VLANs for VMs & Management.Read »
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

-

Configuration

-

Configuring and customizing the stack

-

Plugins

-

Extending DevStack with new features

-
- -
-

Recent Changes

-

An incomplete summary of recent changes

-

FAQ

-

The DevStack FAQ

-

Contributing

-

Pitching in to make DevStack a better place

-
- -
- -
-
-

Code A look at the bits that make it all go

-
- -
-

Scripts Generated documentation of DevStack scripts.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameLink
stack.shRead »
functionsRead »
functions-commonRead »
lib/apacheRead »
lib/baremetalRead »
lib/ceilometerRead »
lib/cinderRead »
lib/configRead »
lib/databaseRead »
lib/glanceRead »
lib/heatRead »
lib/horizonRead »
lib/infraRead »
lib/ironicRead »
lib/keystoneRead »
lib/ldapRead »
lib/zaqarRead »
lib/neutronRead »
lib/novaRead »
lib/osloRead »
lib/rpc_backendRead »
lib/saharaRead »
lib/savannaRead »
lib/stackforgeRead »
lib/swiftRead »
lib/tempestRead »
lib/tlsRead »
lib/troveRead »
unstack.shRead »
clean.shRead »
run_tests.shRead »
extras.d/50-ironic.shRead »
extras.d/70-zaqar.shRead »
extras.d/70-sahara.shRead »
extras.d/70-savanna.shRead »
extras.d/70-trove.shRead »
extras.d/80-opendaylight.shRead »
extras.d/80-tempest.shRead »
-
- -
-

Configuration Setting the table

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameLink
local.confRead »
stackrcRead »
openrcRead »
exercisercRead »
eucarcRead »
- -

Tools Support scripts

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameLink
tools/info.shRead »
tools/build_docs.shRead »
tools/create_userrc.shRead »
tools/fixup_stuff.shRead »
tools/install_prereqs.shRead »
tools/install_pip.shRead »
tools/upload_image.shRead »
- -

Samples Generated documentation of DevStack sample files.

- - - - - - - - - - - - - - - - - -
FilenameLink
local.shRead »
localrcRead »
- -
-

Exercises Generated documentation of DevStack scripts.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameLink
exercise.shRead »
exercises/aggregates.shRead »
exercises/boot_from_volume.shRead »
exercises/bundle.shRead »
exercises/client-args.shRead »
exercises/client-env.shRead »
exercises/euca.shRead »
exercises/floating_ips.shRead »
exercises/horizon.shRead »
exercises/neutron-adv-test.shRead »
exercises/sahara.shRead »
exercises/savanna.shRead »
exercises/sec_groups.shRead »
exercises/swift.shRead »
exercises/trove.shRead »
exercises/volumes.shRead »
exercises/zaqar.shRead »
- -
- -
- - - -
- - diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000000..6e5105dcff --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,383 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +.. 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 `__ be set up. + +#. Start the install + + :: + + cd devstack; ./stack.sh + + It takes a few minutes, we recommend `reading the + script `__ 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 » `__ + +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 » `__ + +Multi-Node + VLANs + +Setup a multi-node cluster with dedicated VLANs for VMs & Management. + +`Read » `__ + +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 `__ + +Configuration +------------- + +`Configuring and customizing the stack `__ + +Plugins +------- + +`Extending DevStack with new features `__ + +Recent Changes +-------------- + +`An incomplete summary of recent changes `__ + +FAQ +--- + +`The DevStack FAQ `__ + +Contributing +------------ + +`Pitching in to make DevStack a better place `__ + +Code A look at the bits that make it all go +------------------------------------------- + +Scripts Generated documentation of DevStack scripts. +---------------------------------------------------- + ++-------------------------------+----------------------------------------------+ +| Filename | Link | ++===============================+==============================================+ +| stack.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| functions | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| functions-common | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/apache | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/baremetal | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/ceilometer | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/cinder | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/config | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/database | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/glance | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/heat | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/horizon | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/infra | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/ironic | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/keystone | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/ldap | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/zaqar | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/neutron | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/nova | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/oslo | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/rpc\_backend | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/sahara | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/savanna | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/stackforge | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/swift | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/tempest | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/tls | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| lib/trove | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| unstack.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| clean.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| run\_tests.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/50-ironic.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/70-zaqar.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/70-sahara.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/70-savanna.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/70-trove.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/80-opendaylight.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ +| extras.d/80-tempest.sh | `Read » `__ | ++-------------------------------+----------------------------------------------+ + +Configuration Setting the table +------------------------------- + ++--------------+--------------------------------+ +| Filename | Link | ++==============+================================+ +| local.conf | `Read » `__ | ++--------------+--------------------------------+ +| stackrc | `Read » `__ | ++--------------+--------------------------------+ +| openrc | `Read » `__ | ++--------------+--------------------------------+ +| exerciserc | `Read » `__ | ++--------------+--------------------------------+ +| eucarc | `Read » `__ | ++--------------+--------------------------------+ + +Tools Support scripts +--------------------- + ++-----------------------------+----------------------------------------------+ +| Filename | Link | ++=============================+==============================================+ +| tools/info.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ +| tools/build\_docs.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ +| tools/create\_userrc.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ +| tools/fixup\_stuff.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ +| tools/install\_prereqs.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ +| tools/install\_pip.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ +| tools/upload\_image.sh | `Read » `__ | ++-----------------------------+----------------------------------------------+ + +Samples Generated documentation of DevStack sample files. +--------------------------------------------------------- + ++------------+--------------------------------------+ +| Filename | Link | ++============+======================================+ +| local.sh | `Read » `__ | ++------------+--------------------------------------+ +| localrc | `Read » `__ | ++------------+--------------------------------------+ + +Exercises Generated documentation of DevStack scripts. +------------------------------------------------------ + +Filename + +Link + +exercise.sh + +`Read » `__ + +exercises/aggregates.sh + +`Read » `__ + +exercises/boot\_from\_volume.sh + +`Read » `__ + +exercises/bundle.sh + +`Read » `__ + +exercises/client-args.sh + +`Read » `__ + +exercises/client-env.sh + +`Read » `__ + +exercises/euca.sh + +`Read » `__ + +exercises/floating\_ips.sh + +`Read » `__ + +exercises/horizon.sh + +`Read » `__ + +exercises/neutron-adv-test.sh + +`Read » `__ + +exercises/sahara.sh + +`Read » `__ + +exercises/savanna.sh + +`Read » `__ + +exercises/sec\_groups.sh + +`Read » `__ + +exercises/swift.sh + +`Read » `__ + +exercises/trove.sh + +`Read » `__ + +exercises/volumes.sh + +`Read » `__ + +exercises/zaqar.sh + +`Read » `__ + +© Openstack Foundation 2011-2014 — An +`OpenStack `__ +`program `__ diff --git a/doc/source/local.conf.html b/doc/source/local.conf.html deleted file mode 100644 index 2635ac6694..0000000000 --- a/doc/source/local.conf.html +++ /dev/null @@ -1,64 +0,0 @@ - - - - - DevStack - local.conf - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

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 for - more details about the mechanics of the file.

-
-
-

© Openstack Foundation 2011-2014 — An OpenStack program

- - -
- - - diff --git a/doc/source/local.conf.rst b/doc/source/local.conf.rst new file mode 100644 index 0000000000..40d0e0f57a --- /dev/null +++ b/doc/source/local.conf.rst @@ -0,0 +1,20 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ for more details about the mechanics +of the file. + +© Openstack Foundation 2011-2014 — An +`OpenStack `__ +`program `__ diff --git a/doc/source/localrc.html b/doc/source/localrc.html deleted file mode 100644 index 40a20043a2..0000000000 --- a/doc/source/localrc.html +++ /dev/null @@ -1,60 +0,0 @@ - - - - - DevStack - localrc - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

localrc User settings

-

localrc is the old file used to configure DevStack. It is deprecated and has been replaced by local.conf. 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 program

- - -
- - - diff --git a/doc/source/localrc.rst b/doc/source/localrc.rst new file mode 100644 index 0000000000..910e274209 --- /dev/null +++ b/doc/source/localrc.rst @@ -0,0 +1,20 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +localrc User settings +--------------------- + +``localrc`` is the old file used to configure DevStack. It is deprecated +and has been replaced by ```local.conf`` `__. 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 `__ +`program `__ diff --git a/doc/source/openrc.html b/doc/source/openrc.html deleted file mode 100644 index 94b253dfe1..0000000000 --- a/doc/source/openrc.html +++ /dev/null @@ -1,115 +0,0 @@ - - - - - DevStack - openrc - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

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 - created by Rackspace Cloud Builders

- - -
- - - diff --git a/doc/source/openrc.rst b/doc/source/openrc.rst new file mode 100644 index 0000000000..b8759ecb49 --- /dev/null +++ b/doc/source/openrc.rst @@ -0,0 +1,88 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ created by +`Rackspace Cloud +Builders `__ diff --git a/doc/source/overview.html b/doc/source/overview.html deleted file mode 100644 index 9cee052129..0000000000 --- a/doc/source/overview.html +++ /dev/null @@ -1,118 +0,0 @@ - - - - - DevStack - Overview - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
- -
-

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

- -
- -
- - - -
- - diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 0000000000..953938baaf --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,103 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ 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 `__ +`program `__ diff --git a/doc/source/plugins.html b/doc/source/plugins.html deleted file mode 100644 index 700a209ac9..0000000000 --- a/doc/source/plugins.html +++ /dev/null @@ -1,142 +0,0 @@ - - - - - DevStack - Plugins - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
- -
-

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
    • -
-
- -
- - - -
- - diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst new file mode 100644 index 0000000000..db695d3e84 --- /dev/null +++ b/doc/source/plugins.rst @@ -0,0 +1,124 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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-`` where ```` 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 `__ created by +`Rackspace Cloud +Builders `__ diff --git a/doc/source/stackrc.html b/doc/source/stackrc.html deleted file mode 100644 index 2df9d385f7..0000000000 --- a/doc/source/stackrc.html +++ /dev/null @@ -1,101 +0,0 @@ - - - - - DevStack - stackrc - - - - - - - - - - - - - - - - - - -
-
-
- DevStack - -
-
-
- -
- -
-
-

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 program

- - -
- - - diff --git a/doc/source/stackrc.rst b/doc/source/stackrc.rst new file mode 100644 index 0000000000..b2766cb971 --- /dev/null +++ b/doc/source/stackrc.rst @@ -0,0 +1,77 @@ +`DevStack `__ + +- `Overview `__ +- `Changes `__ +- `FAQ `__ +- `git.openstack.org `__ +- `Gerrit `__ + +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 `__ +`program `__ diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000000..58871344aa --- /dev/null +++ b/setup.cfg @@ -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 diff --git a/setup.py b/setup.py new file mode 100755 index 0000000000..70c2b3f32b --- /dev/null +++ b/setup.py @@ -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) diff --git a/tox.ini b/tox.ini index 3677631c5e..b6f2d9655e 100644 --- a/tox.ini +++ b/tox.ini @@ -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