Browse Source

import neutron master of cba140dacc

Merge Neutron master branch to tacker master branch with modification
of tox.ini and .gitreview.
This patch imports the following change set of Neutron.

  > commit cba140dacc
  > Merge: 63d8237 6bed4a0
  > Author: Jenkins <jenkins@review.openstack.org>
  > Date:   Sun Jun 22 16:02:56 2014 +0000
  >
  >     Merge "Adding static routes data for members"

Change-Id: I5a0f522bc20530c46e35dc9e03fe72d72ad04577
changes/05/104805/1
Isaku Yamahata 7 years ago
parent
commit
8aff29509f
1426 changed files with 278589 additions and 0 deletions
  1. +7
    -0
      .coveragerc
  2. +28
    -0
      .gitignore
  3. +11
    -0
      .mailmap
  4. +42
    -0
      .pylintrc
  5. +4
    -0
      .testr.conf
  6. +28
    -0
      HACKING.rst
  7. +176
    -0
      LICENSE
  8. +14
    -0
      MANIFEST.in
  9. +25
    -0
      README.rst
  10. +180
    -0
      TESTING.rst
  11. +2
    -0
      babel.cfg
  12. +21
    -0
      bin/neutron-rootwrap
  13. +141
    -0
      bin/neutron-rootwrap-xen-dom0
  14. +96
    -0
      doc/Makefile
  15. +135
    -0
      doc/pom.xml
  16. +250
    -0
      doc/source/conf.py
  17. +7
    -0
      doc/source/devref/advanced_services.rst
  18. +18
    -0
      doc/source/devref/api_extensions.rst
  19. +57
    -0
      doc/source/devref/api_layer.rst
  20. +25
    -0
      doc/source/devref/common.rst
  21. +2
    -0
      doc/source/devref/db_layer.rst
  22. +49
    -0
      doc/source/devref/development.environment.rst
  23. +30
    -0
      doc/source/devref/fwaas.rst
  24. +65
    -0
      doc/source/devref/index.rst
  25. +7
    -0
      doc/source/devref/l2_agents.rst
  26. +199
    -0
      doc/source/devref/layer3.rst
  27. +32
    -0
      doc/source/devref/lbaas.rst
  28. +2
    -0
      doc/source/devref/linuxbridge_agent.rst
  29. +21
    -0
      doc/source/devref/openvswitch_agent.rst
  30. +12
    -0
      doc/source/devref/plugin-api.rst
  31. +2
    -0
      doc/source/devref/rpc_api.rst
  32. +50
    -0
      doc/source/devref/security_group_api.rst
  33. +21
    -0
      doc/source/devref/vpnaas.rst
  34. +14
    -0
      doc/source/docbkx/docbkx-example/README
  35. +38
    -0
      doc/source/docbkx/docbkx-example/pom.xml
  36. +318
    -0
      doc/source/docbkx/docbkx-example/src/docbkx/example.xml
  37. +79
    -0
      doc/source/docbkx/docbkx-example/src/docbkx/figures/example.sdx
  38. +523
    -0
      doc/source/docbkx/docbkx-example/src/docbkx/figures/example.svg
  39. +112
    -0
      doc/source/docbkx/quantum-api-1.0/common.ent
  40. +70
    -0
      doc/source/docbkx/quantum-api-1.0/figures/Arrow_east.svg
  41. +60
    -0
      doc/source/docbkx/quantum-api-1.0/figures/Check_mark_23x20_02.svg
  42. +337
    -0
      doc/source/docbkx/quantum-api-1.0/js/shjs/sh_java.js
  43. +347
    -0
      doc/source/docbkx/quantum-api-1.0/js/shjs/sh_javascript.js
  44. +538
    -0
      doc/source/docbkx/quantum-api-1.0/js/shjs/sh_main.js
  45. +115
    -0
      doc/source/docbkx/quantum-api-1.0/js/shjs/sh_xml.js
  46. +184
    -0
      doc/source/docbkx/quantum-api-1.0/js/trc/schema/controller.js
  47. +137
    -0
      doc/source/docbkx/quantum-api-1.0/js/trc/schema/layoutManager.js
  48. +342
    -0
      doc/source/docbkx/quantum-api-1.0/js/trc/schema/sampleManager.js
  49. +564
    -0
      doc/source/docbkx/quantum-api-1.0/js/trc/util.js
  50. +2011
    -0
      doc/source/docbkx/quantum-api-1.0/quantum-api-guide.xml
  51. +3
    -0
      doc/source/docbkx/quantum-api-1.0/samples/att-get-res-none.json
  52. +1
    -0
      doc/source/docbkx/quantum-api-1.0/samples/att-get-res-none.xml
  53. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/att-get-res.json
  54. +1
    -0
      doc/source/docbkx/quantum-api-1.0/samples/att-get-res.xml
  55. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/att-put-req.json
  56. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/att-put-req.xml
  57. +19
    -0
      doc/source/docbkx/quantum-api-1.0/samples/extensions.json
  58. +21
    -0
      doc/source/docbkx/quantum-api-1.0/samples/extensions.xml
  59. +7
    -0
      doc/source/docbkx/quantum-api-1.0/samples/fault.json
  60. +8
    -0
      doc/source/docbkx/quantum-api-1.0/samples/fault.xml
  61. +22
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-get-detail-res.json
  62. +14
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-get-detail-res.xml
  63. +7
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-get-res.json
  64. +3
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-get-res.xml
  65. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-post-req.json
  66. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-post-req.xml
  67. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-post-res.json
  68. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/network-post-res.xml
  69. +13
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-get-detail-res.json
  70. +8
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-get-detail-res.xml
  71. +11
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-get-res.json
  72. +4
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-get-res.xml
  73. +5
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-post-req.json
  74. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-post-req.xml
  75. +5
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-post-res.json
  76. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/networks-post-res.xml
  77. +7
    -0
      doc/source/docbkx/quantum-api-1.0/samples/notfound.json
  78. +7
    -0
      doc/source/docbkx/quantum-api-1.0/samples/notfound.xml
  79. +7
    -0
      doc/source/docbkx/quantum-api-1.0/samples/notimplemented.json
  80. +5
    -0
      doc/source/docbkx/quantum-api-1.0/samples/notimplemented.xml
  81. +12
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-get-detail-res.json
  82. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-get-detail-res.xml
  83. +8
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-get-res.json
  84. +3
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-get-res.xml
  85. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-post-req.json
  86. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-post-req.xml
  87. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-post-res.json
  88. +2
    -0
      doc/source/docbkx/quantum-api-1.0/samples/port-post-res.xml
  89. +12
    -0
      doc/source/docbkx/quantum-api-1.0/samples/ports-get-detail-res.json
  90. +8
    -0
      doc/source/docbkx/quantum-api-1.0/samples/ports-get-detail-res.xml
  91. +11
    -0
      doc/source/docbkx/quantum-api-1.0/samples/ports-get-res.json
  92. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/ports-get-res.xml
  93. +9
    -0
      doc/source/docbkx/quantum-api-1.0/samples/private.json
  94. +6
    -0
      doc/source/docbkx/quantum-api-1.0/samples/private.xml
  95. +11
    -0
      doc/source/docbkx/quantum-api-1.0/samples/public.json
  96. +8
    -0
      doc/source/docbkx/quantum-api-1.0/samples/public.xml
  97. +22
    -0
      doc/source/docbkx/quantum-api-1.0/samples/versions-atom.xml
  98. +24
    -0
      doc/source/docbkx/quantum-api-1.0/samples/versions.json
  99. +12
    -0
      doc/source/docbkx/quantum-api-1.0/samples/versions.xml
  100. +82
    -0
      doc/source/docbkx/quantum-api-1.0/style/schema.css

+ 7
- 0
.coveragerc View File

@ -0,0 +1,7 @@
[run]
branch = True
source = neutron
omit = neutron/tests/*,neutron/plugins/cisco/test/*,neutron/openstack/*
[report]
ignore-errors = True

+ 28
- 0
.gitignore View File

@ -0,0 +1,28 @@
AUTHORS
build/*
build-stamp
ChangeLog
cover/
.coverage
covhtml/
dist/
doc/build
*.DS_Store
*.pyc
neutron.egg-info/
neutron/vcsversion.py
neutron/versioninfo
pbr*.egg/
quantum.egg-info/
quantum/vcsversion.py
quantum/versioninfo
run_tests.err.log
run_tests.log
setuptools*.egg/
subunit.log
.testrepository
.tox/
.venv/
*.mo
*.sw?
*~

+ 11
- 0
.mailmap View File

@ -0,0 +1,11 @@
# Format is:
# <preferred e-mail> <other e-mail 1>
# <preferred e-mail> <other e-mail 2>
lawrancejing <lawrancejing@gmail.com> <liuqing@windawn.com>
Jiajun Liu <jiajun@unitedstack.com> <iamljj@gmail.com>
Zhongyue Luo <zhongyue.nah@intel.com> <lzyeval@gmail.com>
Kun Huang <gareth@unitedstack.com> <academicgareth@gmail.com>
Zhenguo Niu <zhenguo@unitedstack.com> <Niu.ZGlinux@gmail.com>
Isaku Yamahata <isaku.yamahata@intel.com> <isaku.yamahata@gmail.com>
Isaku Yamahata <isaku.yamahata@intel.com> <yamahata@private.email.ne.jp>
Morgan Fainberg <morgan.fainberg@gmail.com> <m@metacloud.com>

+ 42
- 0
.pylintrc View File

@ -0,0 +1,42 @@
# The format of this file isn't really documented; just use --generate-rcfile
[MASTER]
# Add <file or directory> to the black list. It should be a base name, not a
# path. You may set this option multiple times.
ignore=test
[Messages Control]
# NOTE(justinsb): We might want to have a 2nd strict pylintrc in future
# C0111: Don't require docstrings on every method
# W0511: TODOs in code comments are fine.
# W0142: *args and **kwargs are fine.
# W0622: Redefining id is fine.
disable=C0111,W0511,W0142,W0622
[Basic]
# Variable names can be 1 to 31 characters long, with lowercase and underscores
variable-rgx=[a-z_][a-z0-9_]{0,30}$
# Argument names can be 2 to 31 characters long, with lowercase and underscores
argument-rgx=[a-z_][a-z0-9_]{1,30}$
# Method names should be at least 3 characters long
# and be lowecased with underscores
method-rgx=([a-z_][a-z0-9_]{2,50}|setUp|tearDown)$
# Module names matching neutron-* are ok (files in bin/)
module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+)|(neutron-[a-z0-9_-]+))$
# Don't require docstrings on tests.
no-docstring-rgx=((__.*__)|([tT]est.*)|setUp|tearDown)$
[Design]
max-public-methods=100
min-public-methods=0
max-args=6
[Variables]
# List of additional names supposed to be defined in builtins. Remember that
# you should avoid to define new builtins when possible.
# _ is used by our localization
additional-builtins=_

+ 4
- 0
.testr.conf View File

@ -0,0 +1,4 @@
[DEFAULT]
test_command=OS_STDOUT_CAPTURE=1 OS_STDERR_CAPTURE=1 OS_LOG_CAPTURE=1 ${PYTHON:-python} -m subunit.run discover -t ./ ${OS_TEST_PATH:-./neutron/tests/unit} $LISTOPT $IDOPTION
test_id_option=--load-list $IDFILE
test_list_option=--list

+ 28
- 0
HACKING.rst View File

@ -0,0 +1,28 @@
Neutron Style Commandments
=======================
- Step 1: Read the OpenStack Style Commandments
http://docs.openstack.org/developer/hacking/
- Step 2: Read on
Neutron Specific Commandments
--------------------------
- [N320] Validate that LOG messages, except debug ones, have translations
Creating Unit Tests
-------------------
For every new feature, unit tests should be created that both test and
(implicitly) document the usage of said feature. If submitting a patch for a
bug that had no unit test, a new passing unit test should be added. If a
submitted bug fix does have a unit test, be sure to add a new one that fails
without the patch and passes with the patch.
All unittest classes must ultimately inherit from testtools.TestCase. In the
Neutron test suite, this should be done by inheriting from
neutron.tests.base.BaseTestCase.
All setUp and tearDown methods must upcall using the super() method.
tearDown methods should be avoided and addCleanup calls should be preferred.
Never manually create tempfiles. Always use the tempfile fixtures from
the fixture library to ensure that they are cleaned up.

+ 176
- 0
LICENSE View File

@ -0,0 +1,176 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.

+ 14
- 0
MANIFEST.in View File

@ -0,0 +1,14 @@
include AUTHORS
include README.rst
include ChangeLog
include LICENSE
include neutron/db/migration/README
include neutron/db/migration/alembic.ini
include neutron/db/migration/alembic_migrations/script.py.mako
include neutron/db/migration/alembic_migrations/versions/README
recursive-include neutron/locale *
exclude .gitignore
exclude .gitreview
global-exclude *.pyc

+ 25
- 0
README.rst View File

@ -0,0 +1,25 @@
# -- Welcome!
You have come across a cloud computing network fabric controller. It has
identified itself as "Neutron." It aims to tame your (cloud) networking!
# -- External Resources:
The homepage for Neutron is: http://launchpad.net/neutron . Use this
site for asking for help, and filing bugs. Code is available on github at
<http://github.com/openstack/neutron>.
The latest and most in-depth documentation on how to use Neutron is
available at: <http://docs.openstack.org>. This includes:
Neutron Administrator Guide
http://docs.openstack.org/trunk/openstack-network/admin/content/
Neutron API Reference:
http://docs.openstack.org/api/openstack-network/2.0/content/
The start of some developer documentation is available at:
http://wiki.openstack.org/NeutronDevelopment
For help using or hacking on Neutron, you can send mail to
<mailto:openstack-dev@lists.openstack.org>.

+ 180
- 0
TESTING.rst View File

@ -0,0 +1,180 @@
Testing Neutron
=============================================================
Overview
--------
The unit tests are meant to cover as much code as possible and should
be executed without the service running. They are designed to test
the various pieces of the neutron tree to make sure any new changes
don't break existing functionality.
The functional tests are intended to validate actual system
interaction. Mocks should be used sparingly, if at all. Care
should be taken to ensure that existing system resources are not
modified and that resources created in tests are properly cleaned
up.
Development process
-------------------
It is expected that any new changes that are proposed for merge
come with tests for that feature or code area. Ideally any bugs
fixes that are submitted also have tests to prove that they stay
fixed! In addition, before proposing for merge, all of the
current tests should be passing.
Virtual environments
~~~~~~~~~~~~~~~~~~~~
Testing OpenStack projects, including Neutron, is made easier with `DevStack <https://github.com/openstack-dev/devstack>`_.
Create a machine (such as a VM or Vagrant box) running a distribution supported
by DevStack and install DevStack there. For example, there is a Vagrant script
for DevStack at https://github.com/bcwaldon/vagrant_devstack.
.. note::
If you prefer not to use DevStack, you can still check out source code on your local
machine and develop from there.
Running unit tests
------------------
There are three mechanisms for running tests: run_tests.sh, tox,
and nose. Before submitting a patch for review you should always
ensure all test pass; a tox run is triggered by the jenkins gate
executed on gerrit for each patch pushed for review.
With these mechanisms you can either run the tests in the standard
environment or create a virtual environment to run them in.
By default after running all of the tests, any pep8 errors
found in the tree will be reported.
With `run_tests.sh`
~~~~~~~~~~~~~~~~~~~
You can use the `run_tests.sh` script in the root source directory to execute
tests in a virtualenv::
./run_tests -V
With `nose`
~~~~~~~~~~~
You can use `nose`_ to run individual tests, as well as use for debugging
portions of your code::
source .venv/bin/activate
pip install nose
nosetests
There are disadvantages to running Nose - the tests are run sequentially, so
race condition bugs will not be triggered, and the full test suite will
take significantly longer than tox & testr. The upside is that testr has
some rough edges when it comes to diagnosing errors and failures, and there is
no easy way to set a breakpoint in the Neutron code, and enter an
interactive debugging session while using testr.
.. _nose: https://nose.readthedocs.org/en/latest/index.html
With `tox`
~~~~~~~~~~
Neutron, like other OpenStack projects, uses `tox`_ for managing the virtual
environments for running test cases. It uses `Testr`_ for managing the running
of the test cases.
Tox handles the creation of a series of `virtualenvs`_ that target specific
versions of Python (2.6, 2.7, 3.3, etc).
Testr handles the parallel execution of series of test cases as well as
the tracking of long-running tests and other things.
Running unit tests is as easy as executing this in the root directory of the
Neutron source code::
tox
For more information on the standard Tox-based test infrastructure used by
OpenStack and how to do some common test/debugging procedures with Testr,
see this wiki page:
https://wiki.openstack.org/wiki/Testr
.. _Testr: https://wiki.openstack.org/wiki/Testr
.. _tox: http://tox.readthedocs.org/en/latest/
.. _virtualenvs: https://pypi.python.org/pypi/virtualenv
Running individual tests
~~~~~~~~~~~~~~~~~~~~~~~~
For running individual test modules or cases, you just need to pass
the dot-separated path to the module you want as an argument to it.
For executing a specific test case, specify the name of the test case
class separating it from the module path with a colon.
For example, the following would run only the JSONV2TestCase tests from
neutron/tests/unit/test_api_v2.py::
$ ./run_tests.sh neutron.tests.unit.test_api_v2:JSONV2TestCase
or::
$ ./tox neutron.tests.unit.test_api_v2:JSONV2TestCase
Adding more tests
~~~~~~~~~~~~~~~~~
Neutron has a fast growing code base and there is plenty of areas that
need to be covered by unit and functional tests.
To get a grasp of the areas where tests are needed, you can check
current coverage by running::
$ ./run_tests.sh -c
Debugging
---------
By default, calls to pdb.set_trace() will be ignored when tests
are run. For pdb statements to work, invoke run_tests as follows::
$ ./run_tests.sh -d [test module path]
It's possible to debug tests in a tox environment::
$ tox -e venv -- python -m testtools.run [test module path]
Tox-created virtual environments (venv's) can also be activated
after a tox run and reused for debugging::
$ tox -e venv
$ . .tox/venv/bin/activate
$ python -m testtools.run [test module path]
Tox packages and installs the neutron source tree in a given venv
on every invocation, but if modifications need to be made between
invocation (e.g. adding more pdb statements), it is recommended
that the source tree be installed in the venv in editable mode::
# run this only after activating the venv
$ pip install --editable .
Editable mode ensures that changes made to the source tree are
automatically reflected in the venv, and that such changes are not
overwritten during the next tox run.
Post-mortem debugging
~~~~~~~~~~~~~~~~~~~~~
Setting OS_POST_MORTEM_DEBUG=1 in the shell environment will ensure
that pdb.post_mortem() will be invoked on test failure::
$ OS_POST_MORTEM_DEBUG=1 ./run_tests.sh -d [test module path]

+ 2
- 0
babel.cfg View File

@ -0,0 +1,2 @@
[python: **.py]

+ 21
- 0
bin/neutron-rootwrap View File

@ -0,0 +1,21 @@
#!/usr/bin/env python
# vim: tabstop=4 shiftwidth=4 softtabstop=4
# 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
- 0
bin/neutron-rootwrap-xen-dom0 View File

@ -0,0 +1,141 @@
#!/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
- 0
doc/Makefile View File

@ -0,0 +1,96 @@
# 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
- 0
doc/pom.xml View File

@ -0,0 +1,135 @@
<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>

+ 250
- 0
doc/source/conf.py View File

@ -0,0 +1,250 @@
# -*- 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.intersphinx',
'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
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'python': ('http://docs.python.org/', None),
'nova': ('http://nova.openstack.org', None),
'swift': ('http://swift.openstack.org', None),
'glance': ('http://glance.openstack.org', None),
'horizon': ('http://horizon.openstack.org', None),
'keystone': ('http://keystone.openstack.org', None),
}

+ 7
- 0
doc/source/devref/advanced_services.rst View File

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

+ 18
- 0
doc/source/devref/api_extensions.rst View File

@ -0,0 +1,18 @@
==============
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
- 0
doc/source/devref/api_layer.rst View File

@ -0,0 +1,57 @@
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
- 0
doc/source/devref/common.rst View File

@ -0,0 +1,25 @@
..
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

+ 2
- 0
doc/source/devref/db_layer.rst View File

@ -0,0 +1,2 @@
Neutron Database Layer
======================

+ 49
- 0
doc/source/devref/development.environment.rst View File

@ -0,0 +1,49 @@
..
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 wiki page`_ 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 wiki page: https://wiki.openstack.org/wiki/Gerrit_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://github.com/openstack-dev/devstack
.. _setting up Neutron using Devstack: https://wiki.openstack.org/wiki/NeutronDevstack
Getting the code
----------------
Grab the code from GitHub::
git clone git://git.openstack.org/openstack/neutron.git
cd neutron
.. include:: ../../../TESTING.rst

+ 30
- 0
doc/source/devref/fwaas.rst View File

@ -0,0 +1,30 @@
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
- 0
doc/source/devref/index.rst View File

@ -0,0 +1,65 @@
..
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
- 0
doc/source/devref/l2_agents.rst View File

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

+ 199
- 0
doc/source/devref/layer3.rst View File

@ -0,0 +1,199 @@
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
- 0
doc/source/devref/lbaas.rst View File

@ -0,0 +1,32 @@
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
- 0
doc/source/devref/linuxbridge_agent.rst View File

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

+ 21
- 0
doc/source/devref/openvswitch_agent.rst View File

@ -0,0 +1,21 @@
====================
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
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
- 0
doc/source/devref/plugin-api.rst View File

@ -0,0 +1,12 @@
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:

+ 2
- 0
doc/source/devref/rpc_api.rst View File

@ -0,0 +1,2 @@
Neutron RCP API Layer
=====================

+ 50
- 0
doc/source/devref/security_group_api.rst View File

@ -0,0 +1,50 @@
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
- 0
doc/source/devref/vpnaas.rst View File

@ -0,0 +1,21 @@
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
- 0
doc/source/docbkx/docbkx-example/README View File

@ -0,0 +1,14 @@
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
- 0
doc/source/docbkx/docbkx-example/pom.xml View File

@ -0,0 +1,38 @@
<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>