x/vmware-nsx
Code Issues Proposed changes

Create vmware-nsx with history

Browse Source 
A channuka miracle!
This commit is contained in:
Gary Kotton 2014-12-18 07:29:28 -08:00
parent 463e6671c5
commit 68b46468b0
1345 changed files with 5 additions and 228822 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
bin/neutron-rootwrap
View File

@ -1,19 +0,0 @@
#!/usr/bin/env python
# Copyright (c) 2012 OpenStack Foundation.
# All Rights Reserved.
#
# 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.
from oslo.rootwrap import cmd
cmd.main()

141
bin/neutron-rootwrap-xen-dom0
View File

@ -1,141 +0,0 @@
#!/usr/bin/env python
# Copyright (c) 2012 Openstack Foundation
# All Rights Reserved.
#
# 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.
"""Neutron root wrapper for dom0.
Executes networking commands in dom0. The XenAPI plugin is
responsible determining whether a command is safe to execute.
"""
from __future__ import print_function
import ConfigParser
import json
import os
import select
import sys
import traceback
import XenAPI
RC_UNAUTHORIZED = 99
RC_NOCOMMAND = 98
RC_BADCONFIG = 97
RC_XENAPI_ERROR = 96
def parse_args():
# Split arguments, require at least a command
exec_name = sys.argv.pop(0)
# argv[0] required; path to conf file
if len(sys.argv) < 2:
print("%s: No command specified" % exec_name)
sys.exit(RC_NOCOMMAND)
config_file = sys.argv.pop(0)
user_args = sys.argv[:]
return exec_name, config_file, user_args
def _xenapi_section_name(config):
sections = [sect for sect in config.sections() if sect.lower() == "xenapi"]
if len(sections) == 1:
return sections[0]
print("Multiple [xenapi] sections or no [xenapi] section found!")
sys.exit(RC_BADCONFIG)
def load_configuration(exec_name, config_file):
config = ConfigParser.RawConfigParser()
config.read(config_file)
try:
exec_dirs = config.get("DEFAULT", "exec_dirs").split(",")
filters_path = config.get("DEFAULT", "filters_path").split(",")
section = _xenapi_section_name(config)
url = config.get(section, "xenapi_connection_url")
username = config.get(section, "xenapi_connection_username")
password = config.get(section, "xenapi_connection_password")
except ConfigParser.Error:
print("%s: Incorrect configuration file: %s" % (exec_name, config_file))
sys.exit(RC_BADCONFIG)
if not url or not password:
msg = ("%s: Must specify xenapi_connection_url, "
"xenapi_connection_username (optionally), and "
"xenapi_connection_password in %s") % (exec_name, config_file)
print(msg)
sys.exit(RC_BADCONFIG)
return dict(
filters_path=filters_path,
url=url,
username=username,
password=password,
exec_dirs=exec_dirs,
)
def filter_command(exec_name, filters_path, user_args, exec_dirs):
# Add ../ to sys.path to allow running from branch
possible_topdir = os.path.normpath(os.path.join(os.path.abspath(exec_name),
os.pardir, os.pardir))
if os.path.exists(os.path.join(possible_topdir, "neutron", "__init__.py")):
sys.path.insert(0, possible_topdir)
from oslo.rootwrap import wrapper
# Execute command if it matches any of the loaded filters
filters = wrapper.load_filters(filters_path)
filter_match = wrapper.match_filter(
filters, user_args, exec_dirs=exec_dirs)
if not filter_match:
print("Unauthorized command: %s" % ' '.join(user_args))
sys.exit(RC_UNAUTHORIZED)
def run_command(url, username, password, user_args, cmd_input):
try:
session = XenAPI.Session(url)
session.login_with_password(username, password)
host = session.xenapi.session.get_this_host(session.handle)
result = session.xenapi.host.call_plugin(
host, 'netwrap', 'run_command',
{'cmd': json.dumps(user_args), 'cmd_input': json.dumps(cmd_input)})
return json.loads(result)
except Exception as e:
traceback.print_exc()
sys.exit(RC_XENAPI_ERROR)
def main():
exec_name, config_file, user_args = parse_args()
config = load_configuration(exec_name, config_file)
filter_command(exec_name, config['filters_path'], user_args, config['exec_dirs'])
# If data is available on the standard input, we need to pass it to the
# command executed in dom0
cmd_input = None
if select.select([sys.stdin,],[],[],0.0)[0]:
cmd_input = "".join(sys.stdin)
return run_command(config['url'], config['username'], config['password'],
user_args, cmd_input)
if __name__ == '__main__':
print(main())

96
doc/Makefile
View File

@ -1,96 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXSOURCE = source
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
.DEFAULT_GOAL = html
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
if [ -f .autogenerated ] ; then \
cat .autogenerated | xargs rm ; \
rm .autogenerated ; \
fi
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nova.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc"
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

135
doc/pom.xml
View File

@ -1,135 +0,0 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.openstack.docs</groupId>
<artifactId>openstack-guide</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>OpenStack Guides</name>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<profiles>
<profile>
<id>Rackspace Research Repositories</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<build>
<resources>
<resource>
<directory>target/docbkx/pdf</directory>
<excludes>
<exclude>**/*.fo</exclude>
</excludes>
</resource>
</resources>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>1.0.5-SNAPSHOT</version>
<executions>
<execution>
<id>goal1</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<highlightSource>false</highlightSource>
</configuration>
</execution>
<execution>
<id>goal2</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>0</enableDisqus>
<disqusShortname>openstackdocs</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-6</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book title,figure,table,example,equation
chapter toc,title
part toc,title
preface toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
<postProcess>
<!-- Copies the figures to the correct location for webhelp -->
<copy todir="${basedir}/target/docbkx/webhelp/neutron-api-1.0/figures">
<fileset dir="${basedir}/source/docbkx/neutron-api-1.0/figures">
<include name="**/*.png" />
</fileset>
</copy>
<!-- New stuff -->
<copy
todir="${basedir}/target/docbkx/webhelp/trunk/developer/neutron-api-1.0">
<fileset
dir="${basedir}/target/docbkx/webhelp/neutron-api-1.0/neutron-api-guide/">
<include name="**/*" />
</fileset>
</copy>
<!--Moves PDFs to the needed placement -->
<move failonerror="false"
file="${basedir}/target/docbkx/pdf/neutron-api-1.0/neutron-api-guide.pdf"
tofile="${basedir}/target/docbkx/webhelp/trunk/developer/neutron-api-1.0/neutron-api-guide-trunk.pdf"/>
<!--Deletes leftover uneeded directories -->
<delete
dir="${basedir}/target/docbkx/webhelp/neutron-api-1.0"/>
</postProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>source/docbkx</sourceDirectory>
<includes>
neutron-api-1.0/neutron-api-guide.xml
</includes>
<profileSecurity>reviewer</profileSecurity>
<branding>openstack</branding>
</configuration>
</plugin>
</plugins>
</build>
</project>

240
doc/source/conf.py
View File

@ -1,240 +0,0 @@
# -*- coding: utf-8 -*-
# Copyright (c) 2010 OpenStack Foundation.
#
# 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.
#
# Keystone documentation build configuration file, created by
# sphinx-quickstart on Tue May 18 13:50:15 2010.
#
# This file is execfile()'d with the current directory set to it's 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 os
import sys
# 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.
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
NEUTRON_DIR = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
sys.path.insert(0, NEUTRON_DIR)
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.coverage',
'sphinx.ext.ifconfig',
'sphinx.ext.pngmath',
'sphinx.ext.graphviz',
'sphinx.ext.todo',
'oslosphinx']
todo_include_todos = True
# Add any paths that contain templates here, relative to this directory.
templates_path = []
if os.getenv('HUDSON_PUBLISH_DOCS'):
templates_path = ['_ga', '_templates']
else:
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Neutron'
copyright = u'2011-present, OpenStack Foundation.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# Version info
from neutron.version import version_info as neutron_version
release = neutron_version.release_string()
# The short X.Y version.
version = neutron_version.version_string()
# 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 documents that shouldn't be included in the build.
# unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = []
# The reST default role (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 = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = True
# 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 = ['neutron.']
# -- Options for man page output --------------------------------------------
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
man_pages = [
('man/neutron-server', 'neutron-server', u'Neutron Server',
[u'OpenStack'], 1)
]
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# 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 = ['_theme']
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
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_use_modindex = True
# If false, no index is generated.
#html_use_index = True
# 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, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'neutrondoc'
# -- Options for LaTeX output ------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author,
# documentclass [howto/manual]).
latex_documents = [
('index', 'Neutron.tex', u'Neutron Documentation',
u'Neutron development 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
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_use_modindex = True

7
doc/source/devref/advanced_services.rst
View File

@ -1,7 +0,0 @@
Advanced Services
=================
.. toctree::
fwaas
lbaas
vpnaas

18
doc/source/devref/api_extensions.rst
View File

@ -1,18 +0,0 @@
==============
API Extensions
==============
API extensions is the standard way of introducing new functionality
to the Neutron project, it allows plugins to
determine if they wish to support the functionality or not.
Examples
========
The easiest way to demonstrate how an API extension is written, is
by studying an existing API extension and explaining the different layers.
.. toctree::
:maxdepth: 1
security_group_api

57
doc/source/devref/api_layer.rst
View File

@ -1,57 +0,0 @@
Neutron WSGI/HTTP API layer
===========================
This section will cover the internals of Neutron's HTTP API, and the classes
in Neutron that can be used to create Extensions to the Neutron API.
Python web applications interface with webservers through the Python Web
Server Gateway Interface (WSGI) - defined in `PEP 333 <http://legacy.python.org/dev/peps/pep-0333/>`_
Startup
-------
Neutron's WSGI server is started from the `server module <http://git.openstack.org/cgit/openstack/neutron/tree/neutron/server/__init__.py>`_
and the entry point `serve_wsgi` is called to build an instance of the
`NeutronApiService`_, which is then returned to the server module,
which spawns a `Eventlet`_ `GreenPool`_ that will run the WSGI
application and respond to requests from clients.
.. _NeutronApiService: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/service.py
.. _Eventlet: http://eventlet.net/
.. _GreenPool: http://eventlet.net/doc/modules/greenpool.html
WSGI Application
----------------
During the building of the NeutronApiService, the `_run_wsgi` function
creates a WSGI application using the `load_paste_app` function inside
`config.py`_ - which parses `api-paste.ini`_ - in order to create a WSGI app
using `Paste`_'s `deploy`_.
The api-paste.ini file defines the WSGI applications and routes - using the
`Paste INI file format`_.
The INI file directs paste to instantiate the `APIRouter`_ class of
Neutron, which contains several methods that map Neutron resources (such as
Ports, Networks, Subnets) to URLs, and the controller for each resource.
.. _config.py: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/common/config.py
.. _api-paste.ini: http://git.openstack.org/cgit/openstack/neutron/tree/etc/api-paste.ini
.. _APIRouter: http://git.openstack.org/cgit/openstack/neutron/tree/neutron/api/v2/router.py
.. _Paste: http://pythonpaste.org/
.. _Deploy: http://pythonpaste.org/deploy/
.. _Paste INI file format: http://pythonpaste.org/deploy/#applications
Further reading
---------------
`Yong Sheng Gong: Deep Dive into Neutron <http://www.slideshare.net/gongys2004/inside-neutron-2>`_

25
doc/source/devref/common.rst
View File

@ -1,25 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
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.
Open Stack Common
=================
A number of modules used are from the openstack-common project.
The imported files are in 'neutron/openstack-common.conf'.
More information can be found at `OpenStack Common`_.
.. _`OpenStack Common`: https://launchpad.net/openstack-common

11
doc/source/devref/db_layer.rst
View File

@ -1,11 +0,0 @@
Neutron Database Layer
======================
Testing database and models sync
--------------------------------
.. automodule:: neutron.tests.unit.db.test_migration
.. autoclass:: _TestModelsMigrations
:members:

49
doc/source/devref/development.environment.rst
View File

@ -1,49 +0,0 @@
..
Copyright 2010-2013 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
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.
Setting Up a Development Environment
====================================
This page describes how to setup a working Python development
environment that can be used in developing Neutron on Ubuntu, Fedora or
Mac OS X. These instructions assume you're already familiar with
Git and Gerrit, which is a code repository mirror and code review toolset
, however if you aren't please see `this Git tutorial`_ for an introduction
to using Git and `this guide`_ for a tutorial on using Gerrit and Git for
code contribution to Openstack projects.
.. _this Git tutorial: http://git-scm.com/book/en/Getting-Started
.. _this guide: http://docs.openstack.org/infra/manual/developers.html#development-workflow
Following these instructions will allow you to run the Neutron unit
tests. If you want to be able to run Neutron in a full OpenStack environment,
you can use the excellent `DevStack`_ project to do so. There is a wiki page
that describes `setting up Neutron using DevStack`_.
.. _DevStack: https://git.openstack.org/cgit/openstack-dev/devstack
.. _setting up Neutron using Devstack: https://wiki.openstack.org/wiki/NeutronDevstack
Getting the code
----------------
Grab the code::
git clone git://git.openstack.org/openstack/neutron.git
cd neutron
.. include:: ../../../TESTING.rst

30
doc/source/devref/fwaas.rst
View File

@ -1,30 +0,0 @@
Firewall as a Service
=====================
`Design Document`_
.. _Design Document: https://docs.google.com/document/d/1PJaKvsX2MzMRlLGfR0fBkrMraHYF0flvl0sqyZ704tA/edit#heading=h.aed6tiupj0qk
Plugin
------
.. automodule:: neutron.services.firewall.fwaas_plugin
.. autoclass:: FirewallPlugin
:members:
Database layer
--------------
.. automodule:: neutron.db.firewall.firewall_db
.. autoclass:: Firewall_db_mixin
:members:
Driver layer
------------
.. automodule:: neutron.services.firewall.drivers.fwaas_base
.. autoclass:: FwaasDriverBase
:members:

65
doc/source/devref/index.rst
View File

@ -1,65 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
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.
Developer Guide
===============
In the Developer Guide, you will find information on Neutron's lower level
programming APIs. There are sections that cover the core pieces of Neutron,
including its database, message queue, and scheduler components. There are
also subsections that describe specific plugins inside Neutron.
Programming HowTos and Tutorials
--------------------------------
.. toctree::
:maxdepth: 3
development.environment
Neutron Internals
-----------------
.. toctree::
:maxdepth: 3
api_layer
api_extensions
plugin-api
db_layer
rpc_api
layer3
l2_agents
advanced_services
Module Reference
----------------
.. toctree::
:maxdepth: 3
.. todo::
Add in all the big modules as automodule indexes.
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

7
doc/source/devref/l2_agents.rst
View File

@ -1,7 +0,0 @@
L2 Agent Networking
-------------------
.. toctree::
:maxdepth: 3
openvswitch_agent
linuxbridge_agent

199
doc/source/devref/layer3.rst
View File

@ -1,199 +0,0 @@
Layer 3 Networking in Neutron - via Layer 3 agent & OpenVSwitch
===============================================================
This page discusses the usage of Neutron with Layer 3 functionality enabled.
Neutron logical network setup
-----------------------------
::
vagrant@precise64:~/devstack$ neutron net-list
+--------------------------------------+---------+--------------------------------------------------+
| id | name | subnets |
+--------------------------------------+---------+--------------------------------------------------+
| 84b6b0cc-503d-448a-962f-43def05e85be | public | 3a56da7c-2f6e-41af-890a-b324d7bc374d |
| a4b4518c-800d-4357-9193-57dbb42ac5ee | private | 1a2d26fb-b733-4ab3-992e-88554a87afa6 10.0.0.0/24 |
+--------------------------------------+---------+--------------------------------------------------+
vagrant@precise64:~/devstack$ neutron subnet-list
+--------------------------------------+------+-------------+--------------------------------------------+
| id | name | cidr | allocation_pools |
+--------------------------------------+------+-------------+--------------------------------------------+
| 1a2d26fb-b733-4ab3-992e-88554a87afa6 | | 10.0.0.0/24 | {"start": "10.0.0.2", "end": "10.0.0.254"} |
+--------------------------------------+------+-------------+--------------------------------------------+
vagrant@precise64:~/devstack$ neutron port-list
+--------------------------------------+------+-------------------+---------------------------------------------------------------------------------+
| id | name | mac_address | fixed_ips |
+--------------------------------------+------+-------------------+---------------------------------------------------------------------------------+
| 0ba8700e-da06-4318-8fe9-00676dd994b8 | | fa:16:3e:78:43:5b | {"subnet_id": "1a2d26fb-b733-4ab3-992e-88554a87afa6", "ip_address": "10.0.0.1"} |
| b2044570-ad52-4f31-a2c3-5d767dc9a8a7 | | fa:16:3e:5b:cf:4c | {"subnet_id": "1a2d26fb-b733-4ab3-992e-88554a87afa6", "ip_address": "10.0.0.3"} |
| bb60d1bb-0cab-41cb-9678-30d2b2fdb169 | | fa:16:3e:af:a9:bd | {"subnet_id": "1a2d26fb-b733-4ab3-992e-88554a87afa6", "ip_address": "10.0.0.2"} |
+--------------------------------------+------+-------------------+---------------------------------------------------------------------------------+
vagrant@precise64:~/devstack$ neutron subnet-show 1a2d26fb-b733-4ab3-992e-88554a87afa6
+------------------+--------------------------------------------+
| Field | Value |
+------------------+--------------------------------------------+
| allocation_pools | {"start": "10.0.0.2", "end": "10.0.0.254"} |
| cidr | 10.0.0.0/24 |
| dns_nameservers | |
| enable_dhcp | True |
| gateway_ip | 10.0.0.1 |
| host_routes | |
| id | 1a2d26fb-b733-4ab3-992e-88554a87afa6 |
| ip_version | 4 |
| name | |
| network_id | a4b4518c-800d-4357-9193-57dbb42ac5ee |
| tenant_id | 3368290ab10f417390acbb754160dbb2 |
+------------------+--------------------------------------------+
Neutron logical router setup
----------------------------
* http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html#under_the_hood_openvswitch_scenario1_network
::
vagrant@precise64:~/devstack$ neutron router-list
+--------------------------------------+---------+--------------------------------------------------------+
| id | name | external_gateway_info |
+--------------------------------------+---------+--------------------------------------------------------+
| 569469c7-a2a5-4d32-9cdd-f0b18a13f45e | router1 | {"network_id": "84b6b0cc-503d-448a-962f-43def05e85be"} |
+--------------------------------------+---------+--------------------------------------------------------+
vagrant@precise64:~/devstack$ neutron router-show router1
+-----------------------+--------------------------------------------------------+
| Field | Value |
+-----------------------+--------------------------------------------------------+
| admin_state_up | True |
| external_gateway_info | {"network_id": "84b6b0cc-503d-448a-962f-43def05e85be"} |
| id | 569469c7-a2a5-4d32-9cdd-f0b18a13f45e |
| name | router1 |
| routes | |
| status | ACTIVE |
| tenant_id | 3368290ab10f417390acbb754160dbb2 |
+-----------------------+--------------------------------------------------------+
vagrant@precise64:~/devstack$ neutron router-port-list router1
+--------------------------------------+------+-------------------+---------------------------------------------------------------------------------+
| id | name | mac_address | fixed_ips |
+--------------------------------------+------+-------------------+---------------------------------------------------------------------------------+
| 0ba8700e-da06-4318-8fe9-00676dd994b8 | | fa:16:3e:78:43:5b | {"subnet_id": "1a2d26fb-b733-4ab3-992e-88554a87afa6", "ip_address": "10.0.0.1"} |
+--------------------------------------+------+-------------------+---------------------------------------------------------------------------------+
Neutron Routers are realized in OpenVSwitch
-------------------------------------------
.. image:: http://docs.openstack.org/admin-guide-cloud/content/figures/10/a/common/figures/under-the-hood-scenario-1-ovs-network.png
"router1" in the Neutron logical network is realized through a port ("qr-0ba8700e-da") in OpenVSwitch - attached to "br-int"::
vagrant@precise64:~/devstack$ sudo ovs-vsctl show
b9b27fc3-5057-47e7-ba64-0b6afe70a398
Bridge br-int
Port "qr-0ba8700e-da"
tag: 1
Interface "qr-0ba8700e-da"
type: internal
Port br-int
Interface br-int
type: internal
Port int-br-ex
Interface int-br-ex
Port "tapbb60d1bb-0c"
tag: 1
Interface "tapbb60d1bb-0c"
type: internal
Port "qvob2044570-ad"
tag: 1
Interface "qvob2044570-ad"
Port "int-br-eth1"
Interface "int-br-eth1"
Bridge "br-eth1"
Port "phy-br-eth1"
Interface "phy-br-eth1"
Port "br-eth1"
Interface "br-eth1"
type: internal
Bridge br-ex
Port phy-br-ex
Interface phy-br-ex
Port "qg-0143bce1-08"
Interface "qg-0143bce1-08"
type: internal
Port br-ex
Interface br-ex
type: internal
ovs_version: "1.4.0+build0"
vagrant@precise64:~/devstack$ brctl show
bridge name bridge id STP enabled interfaces
br-eth1 0000.e2e7fc5ccb4d no
br-ex 0000.82ee46beaf4d no phy-br-ex
qg-39efb3f9-f0
qg-77e0666b-cd
br-int 0000.5e46cb509849 no int-br-ex
qr-54c9cd83-43
qvo199abeb2-63
qvo1abbbb60-b8
tap74b45335-cc
qbr199abeb2-63 8000.ba06e5f8675c no qvb199abeb2-63
tap199abeb2-63
qbr1abbbb60-b8 8000.46a87ed4fb66 no qvb1abbbb60-b8
tap1abbbb60-b8
virbr0 8000.000000000000 yes
Finding the router in ip/ipconfig
---------------------------------
* http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html
The neutron-l3-agent uses the Linux IP stack and iptables to perform L3 forwarding and NAT.
In order to support multiple routers with potentially overlapping IP addresses, neutron-l3-agent
defaults to using Linux network namespaces to provide isolated forwarding contexts. As a result,
the IP addresses of routers will not be visible simply by running "ip addr list" or "ifconfig" on
the node. Similarly, you will not be able to directly ping fixed IPs.
To do either of these things, you must run the command within a particular router's network
namespace. The namespace will have the name "qrouter-<UUID of the router>.
.. image:: http://docs.openstack.org/admin-guide-cloud/content/figures/10/a/common/figures/under-the-hood-scenario-1-ovs-netns.png
For example::
vagrant@precise64:~$ neutron router-list
+--------------------------------------+---------+--------------------------------------------------------+
| id | name | external_gateway_info |
+--------------------------------------+---------+--------------------------------------------------------+
| ad948c6e-afb6-422a-9a7b-0fc44cbb3910 | router1 | {"network_id": "e6634fef-03fa-482a-9fa7-e0304ce5c995"} |
+--------------------------------------+---------+--------------------------------------------------------+
vagrant@precise64:~/devstack$ sudo ip netns exec qrouter-ad948c6e-afb6-422a-9a7b-0fc44cbb3910 ip addr list
18: lo: <LOOPBACK,UP,LOWER_UP> mtu 16436 qdisc noqueue state UNKNOWN
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
19: qr-54c9cd83-43: <BROADCAST,MULTICAST,PROMISC,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN
link/ether fa:16:3e:dd:c1:8f brd ff:ff:ff:ff:ff:ff
inet 10.0.0.1/24 brd 10.0.0.255 scope global qr-54c9cd83-43
inet6 fe80::f816:3eff:fedd:c18f/64 scope link
valid_lft forever preferred_lft forever
20: qg-77e0666b-cd: <BROADCAST,MULTICAST,PROMISC,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN
link/ether fa:16:3e:1f:d3:ec brd ff:ff:ff:ff:ff:ff
inet 192.168.27.130/28 brd 192.168.27.143 scope global qg-77e0666b-cd
inet6 fe80::f816:3eff:fe1f:d3ec/64 scope link
valid_lft forever preferred_lft forever
Provider Networking
-------------------
Neutron can also be configured to create `provider networks <http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html#provider_terminology>`_
Further Reading
---------------
* `Packet Pushers - Neutron Network Implementation on Linux <http://packetpushers.net/openstack-neutron-network-implementation-in-linux/>`_
* `OpenStack Cloud Administrator Guide <http://docs.openstack.org/admin-guide-cloud/content/ch_networking.html>`_
* `Neutron - Layer 3 API extension usage guide <http://docs.openstack.org/api/openstack-network/2.0/content/router_ext.html>`_
* `Darragh O'Reilly - The Quantum L3 router and floating IPs <http://techbackground.blogspot.com/2013/05/the-quantum-l3-router-and-floating-ips.html>`_

32
doc/source/devref/lbaas.rst
View File

@ -1,32 +0,0 @@
Loadbalancer as a Service
=========================
https://wiki.openstack.org/wiki/Neutron/LBaaS/Architecture
https://wiki.openstack.org/wiki/Neutron/LBaaS/API_1.0
Plugin
------
.. automodule:: neutron.services.loadbalancer.plugin
.. autoclass:: LoadBalancerPlugin
:members:
Database layer
--------------
.. automodule:: neutron.db.loadbalancer.loadbalancer_db
.. autoclass:: LoadBalancerPluginDb
:members:
Driver layer
------------
.. automodule:: neutron.services.loadbalancer.drivers.abstract_driver
.. autoclass:: LoadBalancerAbstractDriver
:members:

2
doc/source/devref/linuxbridge_agent.rst
View File

@ -1,2 +0,0 @@
L2 Networking with Linux Bridge
-------------------------------

29
doc/source/devref/openvswitch_agent.rst
View File

@ -1,29 +0,0 @@
====================
OpenVSwitch L2 Agent
====================
This Agent uses the `OpenVSwitch`_ virtual switch to create L2
connectivity for instances, along with bridges created in conjunction
with OpenStack Nova for filtering.
ovs-neutron-agent can be configured to use two different networking technologies to create tenant isolation, either GRE tunnels or VLAN tags.
VLAN Tags
---------
.. image:: http://docs.openstack.org/admin-guide-cloud/content/figures/10/a/common/figures/under-the-hood-scenario-1-ovs-compute.png
.. _OpenVSwitch: http://openvswitch.org
GRE Tunnels
-----------
GRE Tunneling is documented in depth in the `Networking in too much
detail <http://openstack.redhat.com/Networking_in_too_much_detail>`_
by RedHat.
Further Reading
---------------
* `Darragh O'Reilly - The Open vSwitch plugin with VLANs <http://techbackground.blogspot.com/2013/07/the-open-vswitch-plugin-with-vlans.html>`_

12
doc/source/devref/plugin-api.rst
View File

@ -1,12 +0,0 @@
Neutron Plugin Architecture
===========================
`Salvatore Orlando: How to write a Neutron Plugin (if you really need to) <http://www.slideshare.net/salv_orlando/how-to-write-a-neutron-plugin-if-you-really-need-to>`_
Plugin API
----------
.. automodule:: neutron.neutron_plugin_base_v2
.. autoclass:: NeutronPluginBaseV2
:members:

174
doc/source/devref/rpc_api.rst
View File

@ -1,174 +0,0 @@
=====================
Neutron RPC API Layer
=====================
Neutron uses the oslo.messaging library to provide an internal communication
channel between Neutron services. This communication is typically done via
AMQP, but those details are mostly hidden by the use of oslo.messaging and it
could be some other protocol in the future.
RPC APIs are defined in Neutron in two parts: client side and server side.
Client Side
===========
Here is an example of an rpc client definition:
::
from oslo import messaging
from neutron.common import rpc as n_rpc
class ClientAPI(object):
"""Client side RPC interface definition.
API version history:
1.0 - Initial version
1.1 - Added my_remote_method_2
"""
def __init__(self, topic):
target = messaging.Target(topic=topic, version='1.0')
self.client = n_rpc.get_client(target)
def my_remote_method(self, context, arg1, arg2):
cctxt = self.client.prepare()
return cctxt.call(context, 'my_remote_method', arg1=arg1, arg2=arg2)
def my_remote_method_2(self, context, arg1):
cctxt = self.client.prepare(version='1.1')
return cctxt.call(context, 'my_remote_method_2', arg1=arg1)
This class defines the client side interface for an rpc API. The interface has
2 methods. The first method existed in version 1.0 of the interface. The
second method was added in version 1.1. When the newer method is called, it
specifies that the remote side must implement at least version 1.1 to handle
this request.
Server Side
===========
The server side of an rpc interface looks like this:
::
from oslo import messaging
class ServerAPI(object):
target = messaging.Target(version='1.1')
def my_remote_method(self, context, arg1, arg2):
return 'foo'
def my_remote_method_2(self, context, arg1):
return 'bar'
This class implements the server side of the interface. The messaging.Target()
defined says that this class currently implements version 1.1 of the interface.
Versioning
==========
Note that changes to rpc interfaces must always be done in a backwards
compatible way. The server side should always be able to handle older clients
(within the same major version series, such as 1.X).
It is possible to bump the major version number and drop some code only needed
for backwards compatibility. For more information about how to do that, see
https://wiki.openstack.org/wiki/RpcMajorVersionUpdates.
Example Change
--------------
As an example minor API change, let's assume we want to add a new parameter to
my_remote_method_2. First, we add the argument on the server side. To be
backwards compatible, the new argument must have a default value set so that the
interface will still work even if the argument is not supplied. Also, the
interface's minor version number must be incremented. So, the new server side
code would look like this:
::
from oslo import messaging
class ServerAPI(object):
target = messaging.Target(version='1.2')
def my_remote_method(self, context, arg1, arg2):
return 'foo'
def my_remote_method_2(self, context, arg1, arg2=None):
if not arg2:
# Deal with the fact that arg2 was not specified if needed.
return 'bar'
We can now update the client side to pass the new argument. The client must
also specify that version '1.2' is required for this method call to be
successful. The updated client side would look like this:
::
from oslo import messaging
from neutron.common import rpc as n_rpc
class ClientAPI(object):
"""Client side RPC interface definition.
API version history:
1.0 - Initial version
1.1 - Added my_remote_method_2
1.2 - Added arg2 to my_remote_method_2
"""
def __init__(self, topic):
target = messaging.Target(topic=topic, version='1.0')
self.client = n_rpc.get_client(target)
def my_remote_method(self, context, arg1, arg2):
cctxt = self.client.prepare()
return cctxt.call(context, 'my_remote_method', arg1=arg1, arg2=arg2)
def my_remote_method_2(self, context, arg1, arg2):
cctxt = self.client.prepare(version='1.2')
return cctxt.call(context, 'my_remote_method_2',
arg1=arg1, arg2=arg2)
Neutron RPC APIs
================
As discussed before, RPC APIs are defined in two parts: a client side and a
server side. Several of these pairs exist in the Neutron code base. The code
base is being updated with documentation on every rpc interface implementation
that indicates where the corresponding server or client code is located.
Example: DHCP
-------------
The DHCP agent includes a client API, neutron.agent.dhcp_agent.DhcpPluginAPI.
The DHCP agent uses this class to call remote methods back in the Neutron
server. The server side is defined in
neutron.api.rpc.handlers.dhcp_rpc.DhcpRpcCallback. It is up to the Neutron
plugin in use to decide whether the DhcpRpcCallback interface should be
exposed.
Similarly, there is an RPC interface defined that allows the Neutron plugin to
remotely invoke methods in the DHCP agent. The client side is defined in
neutron.api.rpc.agentnotifiers.dhcp_rpc_agent_api.DhcpAgentNotifyApi. The
server side of this interface that runs in the DHCP agent is
neutron.agent.dhcp_agent.DhcpAgent.
More Info
=========
For more information, see the oslo.messaging documentation:
http://docs.openstack.org/developer/oslo.messaging/.

50
doc/source/devref/security_group_api.rst
View File

@ -1,50 +0,0 @@
Guided Tour: The Neutron Security Group API
===========================================
https://wiki.openstack.org/wiki/Neutron/SecurityGroups
API Extension
-------------
The API extension is the 'front' end portion of the code, which handles defining a `REST-ful API`_, which is used by tenants.
.. _`REST-ful API`: https://github.com/openstack/neutron/blob/master/neutron/extensions/securitygroup.py
Database API
------------
The Security Group API extension adds a number of `methods to the database layer`_ of Neutron
.. _`methods to the database layer`: https://github.com/openstack/neutron/blob/master/neutron/db/securitygroups_db.py
Agent RPC
---------
This portion of the code handles processing requests from tenants, after they have been stored in the database. It involves messaging all the L2 agents
running on the compute nodes, and modifying the IPTables rules on each hypervisor.
* `Plugin RPC classes <https://github.com/openstack/neutron/blob/master/neutron/db/securitygroups_rpc_base.py>`_
* `SecurityGroupServerRpcCallbackMixin <https://github.com/openstack/neutron/blob/master/neutron/db/securitygroups_rpc_base.py#L126>`_ - defines the RPC API that the plugin uses to communicate with the agents running on the compute nodes
* SecurityGroupServerRpcMixin - Defines the API methods used to fetch data from the database, in order to return responses to agents via the RPC API
* `Agent RPC classes <https://github.com/openstack/neutron/blob/master/neutron/agent/securitygroups_rpc.py>`_
* The SecurityGroupServerRpcApiMixin defines the API methods that can be called by agents, back to the plugin that runs on the Neutron controller
* The SecurityGroupAgentRpcCallbackMixin defines methods that a plugin uses to call back to an agent after performing an action called by an agent.
IPTables Driver
---------------
* ``prepare_port_filter`` takes a ``port`` argument, which is a ``dictionary`` object that contains information about the port - including the ``security_group_rules``
* ``prepare_port_filter`` `appends the port to an internal dictionary <https://github.com/openstack/neutron/blob/master/neutron/agent/linux/iptables_firewall.py#L60>`_, ``filtered_ports`` which is used to track the internal state.
* Each security group has a `chain <http://www.thegeekstuff.com/2011/01/iptables-fundamentals/>`_ in Iptables.
* The ``IptablesFirewallDriver`` has a method to `convert security group rules into iptables statements <https://github.com/openstack/neutron/blob/master/neutron/agent/linux/iptables_firewall.py#L248>`_

21
doc/source/devref/vpnaas.rst
View File

@ -1,21 +0,0 @@
VPN as a Service
=====================
`API Specification`_
.. _API Specification: http://docs.openstack.org/api/openstack-network/2.0/content/vpnaas_ext.html
Plugin
------
.. automodule:: neutron.services.vpn.plugin
.. autoclass:: VPNPlugin
:members:
Database layer
--------------
.. automodule:: neutron.db.vpn.vpn_db
.. autoclass:: VPNPluginDb
:members:

14
doc/source/docbkx/docbkx-example/README
View File

@ -1,14 +0,0 @@
README
This docbkx-example folder is provided for those who want to use the maven mojo supplied with the project to build their own documents to PDF and HTML (webhelp) format. It's intended to be a template and model.
You can edit the src/docbkx/example.xml file using vi, emacs, or another DocBook editor. At Rackspace we use Oxygen. Both Oxygen and XML Mind offer free licenses to those working on open source project documentation.
To build the output, install Apache Maven (https://maven.apache.org/) and then run:
mvn clean generate-sources
in the directory containing the pom.xml file.
Feel free to ask questions of the openstack-docs team at https://launchpad.net/~openstack-doc.

38
doc/source/docbkx/docbkx-example/pom.xml
View File

@ -1,38 +0,0 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>my-groupid</groupId>
<artifactId>my-guide</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>OpenStack stand alone documentation examples</name>
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>generate-pdf</goal>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<xincludeSupported>true</xincludeSupported>
<chunkSectionDepth>100</chunkSectionDepth>
<postProcess>
<copy todir="target/docbkx/webhelp/example/content/figures">
<fileset dir="src/docbkx/figures">
<include name="**/*.png" />
</fileset>
</copy>
</postProcess>
</configuration>
</plugin>
</plugins>
</build>
</project>

318
doc/source/docbkx/docbkx-example/src/docbkx/example.xml
View File

@ -1,318 +0,0 @@
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" status="DRAFT">
<title>Maven Example Documentation</title>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>Badges! We don't need any stinking badges!</orgname>
</affiliation>
</author>
<copyright>
<year>2011</year>
<holder>Timothy D. Witham</holder>
</copyright>
<releaseinfo>Example v0.1</releaseinfo>
<productname>Product Name Doesn't Exist - it's an example!™</productname>
<pubdate>2011-01-01</pubdate>
<legalnotice role="rs-api">
<annotation>
<remark>Copyright details are filled in by the template. Change the value of the role
attribute on the legalnotice element to change the license. </remark>
</annotation>
</legalnotice>
<abstract>
<para> This document is intended for individuals who whish to produce documentation using Maven and having
the same "feel" as the documentation that is produced by the mainline OpenStack projects.
</para>
</abstract>
<cover>
<para>this is a placeholder for the front cover</para>
</cover>
<cover>
<para>this is a placeholder for the back cover</para>
</cover>
</info>
<chapter>
<title>Overview</title>
<para>Welcome to the getting started with Maven documentation. Congratulations you have
successfully downloaded and built the example.
</para>
<para>For more details on the Product Name service, please refer to <link
xlink:href="http://www.rackspacecloud.com/cloud_hosting_products/files"
>http://www.rackspacecloud.com/cloud_hosting_products/product name</link>
</para>
<para>We welcome feedback, comments, and bug reports at <link
xlink:href="mailto:support@rackspacecloud.com">support@rackspacecloud.com</link>. </para>
<section>
<title>Intended Audience</title>
<para>This guide is intended to individuals who want to develop standalone documentation
to use within an OpenStack deployment. Using this tool chain will give you the look and
feel of the mainline OpenStack documentation.
</para>
</section>
<section>
<title>Document Change History</title>
<para>This version of the Maven Getting Started Guide replaces and obsoletes all previous versions. The
most recent changes are described in the table below:</para>
<informaltable rules="all">
<thead>
<tr>
<td align="center" colspan="1">Revision Date</td>
<td align="center" colspan="4">Summary of Changes</td>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" align="center">July. 14, 2011</td>
<td colspan="4">
<itemizedlist spacing="compact">
<listitem>
<para>Initial document creation.</para>
</listitem>
</itemizedlist>
</td>
</tr>
</tbody>
</informaltable>
</section>
<section>
<title>Additional Resources</title>
<itemizedlist spacing="compact">
<listitem>
<para>
<link xlink:href="http://www.openstack.org">
Openstack - Cloud Software
</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.docbook.org">
Docbook Main Web Site
</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://docbook.org/tdg/en/html/quickref.html">
Docbook Quick Reference
</link>
</para>
</listitem>
</itemizedlist>
</section>
</chapter>
<chapter>
<title>Concepts</title>
<para>
<