From aa5051a162c496c3beaef0cef24c720f78305eea Mon Sep 17 00:00:00 2001 From: FUJITA Tomonori Date: Fri, 9 Dec 2011 15:56:05 +0900 Subject: initial commit Signed-off-by: FUJITA Tomonori --- doc/source/_static/.placeholder | 0 doc/source/_templates/.placeholder | 0 doc/source/conf.py | 216 +++++ doc/source/getting_started.rst | 43 + doc/source/how_l2_segregation_works.rst | 66 ++ doc/source/images/assoc-ovs-port.png | Bin 0 -> 75044 bytes doc/source/images/assoc-ovs-port.svg | 572 ++++++++++++ doc/source/images/compute-node.png | Bin 0 -> 72923 bytes doc/source/images/compute-node.svg | 722 +++++++++++++++ doc/source/images/filtering-broadcast.png | Bin 0 -> 78515 bytes doc/source/images/filtering-broadcast.svg | 882 ++++++++++++++++++ doc/source/images/filtering-incoming.png | Bin 0 -> 81100 bytes doc/source/images/filtering-incoming.svg | 958 +++++++++++++++++++ doc/source/images/filtering-outgoing.png | Bin 0 -> 83163 bytes doc/source/images/filtering-outgoing.svg | 960 +++++++++++++++++++ doc/source/images/logical-view.png | Bin 0 -> 64712 bytes doc/source/images/logical-view.svg | 623 +++++++++++++ doc/source/images/mac-learning.png | Bin 0 -> 95849 bytes doc/source/images/mac-learning.svg | 764 +++++++++++++++ doc/source/images/minimul-setup.png | Bin 0 -> 123002 bytes doc/source/images/minimul-setup.svg | 903 ++++++++++++++++++ doc/source/images/network-creation.png | Bin 0 -> 44004 bytes doc/source/images/network-creation.svg | 484 ++++++++++ doc/source/images/network-id.svg | 1434 +++++++++++++++++++++++++++++ doc/source/images/physical-view.png | Bin 0 -> 187664 bytes doc/source/images/physical-view.svg | 1434 +++++++++++++++++++++++++++++ doc/source/images/trace-route.png | Bin 0 -> 132098 bytes doc/source/images/trace-route.svg | 1000 ++++++++++++++++++++ doc/source/index.rst | 26 + doc/source/overview.rst | 1 + doc/source/using_with_openstack.rst | 251 +++++ 31 files changed, 11339 insertions(+) create mode 100644 doc/source/_static/.placeholder create mode 100644 doc/source/_templates/.placeholder create mode 100644 doc/source/conf.py create mode 100644 doc/source/getting_started.rst create mode 100644 doc/source/how_l2_segregation_works.rst create mode 100644 doc/source/images/assoc-ovs-port.png create mode 100644 doc/source/images/assoc-ovs-port.svg create mode 100644 doc/source/images/compute-node.png create mode 100644 doc/source/images/compute-node.svg create mode 100644 doc/source/images/filtering-broadcast.png create mode 100644 doc/source/images/filtering-broadcast.svg create mode 100644 doc/source/images/filtering-incoming.png create mode 100644 doc/source/images/filtering-incoming.svg create mode 100644 doc/source/images/filtering-outgoing.png create mode 100644 doc/source/images/filtering-outgoing.svg create mode 100644 doc/source/images/logical-view.png create mode 100644 doc/source/images/logical-view.svg create mode 100644 doc/source/images/mac-learning.png create mode 100644 doc/source/images/mac-learning.svg create mode 100644 doc/source/images/minimul-setup.png create mode 100644 doc/source/images/minimul-setup.svg create mode 100644 doc/source/images/network-creation.png create mode 100644 doc/source/images/network-creation.svg create mode 100644 doc/source/images/network-id.svg create mode 100644 doc/source/images/physical-view.png create mode 100644 doc/source/images/physical-view.svg create mode 100644 doc/source/images/trace-route.png create mode 100644 doc/source/images/trace-route.svg create mode 100644 doc/source/index.rst create mode 100644 doc/source/overview.rst create mode 100644 doc/source/using_with_openstack.rst (limited to 'doc/source') diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/_templates/.placeholder b/doc/source/_templates/.placeholder new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..ed247019 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# ryu documentation build configuration file, created by +# sphinx-quickstart on Mon Dec 5 15:38:48 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'ryu' +copyright = u'2011, ryu development team' + +# 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. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# 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' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = 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, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ryudoc' + + +# -- 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', 'ryu.tex', u'ryu Documentation', + u'ryu 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 + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = 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_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'ryu', u'ryu Documentation', + [u'ryu development team'], 1) +] diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst new file mode 100644 index 00000000..bfc108ec --- /dev/null +++ b/doc/source/getting_started.rst @@ -0,0 +1,43 @@ +.. _getting_started: + +*************** +Getting Started +*************** + +Overview/What's Ryu the Network OS +================================== +Ryu is an open-sourced Network OS which is licensed under GPL v3. +It supports openflow protocol. + +If you are not familiar with Software Defined Network(SDN) and +OpenFlow/openflow controller, +please refer to `openflow org `_ . + +The mailing list is available at +`ryu-devel ML `_ + + +Installing Ryu Network OS +========================= +Extract source code and just type:: + + % python ./setup.py install + +Then, run ryu-manager. +It listens to ip address 0.0.0.0 and port 6633 by default. +Then have your openflow switch (hardware or openvswitch OVS) to connect to +ryu-manager. + +For OVS case, you can done it by + + % ovs-vsctl set-controller tcp:[:] + +At the moment, ryu-manager supports only tcp method. +If you want to use it with openstack nova and quantum OVS plugin, +Please refer to :ref:`using_with_openstack`. + +Configuration +============= +It can be configured by passing configuration file like:: + + ryu-manager [--flagfile ] diff --git a/doc/source/how_l2_segregation_works.rst b/doc/source/how_l2_segregation_works.rst new file mode 100644 index 00000000..4b0d2b9d --- /dev/null +++ b/doc/source/how_l2_segregation_works.rst @@ -0,0 +1,66 @@ +.. _how_it_works: + +**************************** +How Ryu L2 segregation works +**************************** +This section describes how Ryu L2 segregation works. + +tenant/network id creation +========================== +When tenant(= network id) is created, Quantum server tells it to Ryu. +Ryu remembers the network id. + + .. image:: /images/network-creation.png + + +association OVS port to network id +================================== +#. When VM instance is created, the network port is created in OVS and + it is associated to network id that VM belongs to. + +#. quantum OVS agent tells the associated (network id, ovs port) to Ryu. + Ryu remembers (network id, ovs port) relationship. + +#. quantum OVS agent also tells to Ryu which OVS port is not managed by + nova/quantum, but is connected to external ether cable. + We call it external OVS port or that the port is external. + + + .. image:: /images/assoc-ovs-port.png + + +mac learing +=========== +When VM sends packets, Ryu determins network id from OVS port and then +associates src mac address to network id. + + .. image:: /images/mac-learning.png + + +packet filtering(L2 unicast case) +================================= +* When VM sending L2-unicast packet, Ryu checks if the destination mac + address belongs to the same netowrk id of the source mac address which + is same to the network id that the OVS port is associated to. +* If no, the packet is dropped. +* If yes, send the packet is sent to ports which belongs to the same + network id and external port. + + .. image:: /images/filtering-outgoing.png + .. image:: /images/filtering-incoming.png + + +packet filtering(L2 broadcast case) +=================================== +* When VM sending L2-broadcast/multicaset packet, Ryu checks if the source + mac address. +* send the packet to all external ports and all OVS ports that belongs + to the same network id of the source mac address. +* When receiving broacast/multicast packet from the external ports, + Ryu checks if the source mac address belongs to known network id. + + * If yes, send the packet to the external ports except incoming one + and the all OVS ports that belongs to the network id + * if no, drop the packet. + + .. image:: /images/filtering-broadcast.png diff --git a/doc/source/images/assoc-ovs-port.png b/doc/source/images/assoc-ovs-port.png new file mode 100644 index 00000000..16e0386a Binary files /dev/null and b/doc/source/images/assoc-ovs-port.png differ diff --git a/doc/source/images/assoc-ovs-port.svg b/doc/source/images/assoc-ovs-port.svg new file mode 100644 index 00000000..2aa8656e --- /dev/null +++ b/doc/source/images/assoc-ovs-port.svg @@ -0,0 +1,572 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + ryu-openflow-controller + + + nova-compute + + VMtenant-X + + OVS + + physical host + + + + quantum_ovs_agent + + associates OVS port to network id + + + + eth + + + network_id + + external port + + diff --git a/doc/source/images/compute-node.png b/doc/source/images/compute-node.png new file mode 100644 index 00000000..50efa04f Binary files /dev/null and b/doc/source/images/compute-node.png differ diff --git a/doc/source/images/compute-node.svg b/doc/source/images/compute-node.svg new file mode 100644 index 00000000..01b6389f --- /dev/null +++ b/doc/source/images/compute-node.svg @@ -0,0 +1,722 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + compute node: single NIC + + + + + + quantum_ovs_agent + + + + peth + + + bridge + + veth + + veth + + + nova-compute + + + VMtenant-X + + ... + + + OVS + + + + + openflow + + VMtenant-Y + + VMtenant-... + + peth: physical NICveth: virtual NIC + physical host + + diff --git a/doc/source/images/filtering-broadcast.png b/doc/source/images/filtering-broadcast.png new file mode 100644 index 00000000..08dd7b1c Binary files /dev/null and b/doc/source/images/filtering-broadcast.png differ diff --git a/doc/source/images/filtering-broadcast.svg b/doc/source/images/filtering-broadcast.svg new file mode 100644 index 00000000..2b2bb3e4 --- /dev/null +++ b/doc/source/images/filtering-broadcast.svg @@ -0,0 +1,882 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + nova-compute + + VMtenant-X + + OVS + + physical host + broadcast filtering + + + + eth + + + + + tenant-Y + + mac addr + + + ryu-openflow-controller + + + tenant-X + + mac addr + + VMtenant-X + + VMtenant-Y + X:block + + + broadcast/multicast + + src addr + data + + + + + + forward + + diff --git a/doc/source/images/filtering-incoming.png b/doc/source/images/filtering-incoming.png new file mode 100644 index 00000000..5151b540 Binary files /dev/null and b/doc/source/images/filtering-incoming.png differ diff --git a/doc/source/images/filtering-incoming.svg b/doc/source/images/filtering-incoming.svg new file mode 100644 index 00000000..fad8faa7 --- /dev/null +++ b/doc/source/images/filtering-incoming.svg @@ -0,0 +1,958 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + nova-compute + + VMtenant-X + + OVS + + physical host + incoming filtering + + + + eth + + + + + + + dst addr + + src addr + data + + + tenant-Y + + mac addr + + + ryu-openflow-controller + + + tenant-X + + mac addr + + VMtenant-X + + VMtenant-Y + drop + X:block + + + dst addr + + src addr + data + pass + + + + + + forward + + diff --git a/doc/source/images/filtering-outgoing.png b/doc/source/images/filtering-outgoing.png new file mode 100644 index 00000000..c7495929 Binary files /dev/null and b/doc/source/images/filtering-outgoing.png differ diff --git a/doc/source/images/filtering-outgoing.svg b/doc/source/images/filtering-outgoing.svg new file mode 100644 index 00000000..6314fd1d --- /dev/null +++ b/doc/source/images/filtering-outgoing.svg @@ -0,0 +1,960 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + nova-compute + + VMtenant-X + + OVS + + physical host + unicast filtering + + + + eth + + + + + + + dst addr + + src addr + data + + + tenant-Y + + mac addr + + + ryu-openflow-controller + + + tenant-X + + mac addr + + VMtenant-X + + VMtenant-Y + drop + X:block + + + dst addr + + src addr + data + pass + + + + + + forward + forward + + diff --git a/doc/source/images/logical-view.png b/doc/source/images/logical-view.png new file mode 100644 index 00000000..f3a87bbf Binary files /dev/null and b/doc/source/images/logical-view.png differ diff --git a/doc/source/images/logical-view.svg b/doc/source/images/logical-view.svg new file mode 100644 index 00000000..6a6a97a2 --- /dev/null +++ b/doc/source/images/logical-view.svg @@ -0,0 +1,623 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + VM + + VM + + VM + ... + + + Tenant-X + + VM + + VM + + VM + ... + + + Tenant-Y + ... + + + gateway + + + public internet + Logical network view + + L2-levelsegregation + + + + gateway + + dhcp server + + + + + gateway + + dhcp server + NAT + NAT + + diff --git a/doc/source/images/mac-learning.png b/doc/source/images/mac-learning.png new file mode 100644 index 00000000..cdd0f7b3 Binary files /dev/null and b/doc/source/images/mac-learning.png differ diff --git a/doc/source/images/mac-learning.svg b/doc/source/images/mac-learning.svg new file mode 100644 index 00000000..43d806c5 --- /dev/null +++ b/doc/source/images/mac-learning.svg @@ -0,0 +1,764 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + ryu-openflow-controller + + + nova-compute + + VMtenant-X + + OVS + + physical host + associates mac addressto network id of OVS port + + + + eth + + + + send packet + + + + + dst addr + + src addr + data + + packet in event + + tenant-X + + mac addr + + tenant-Y + + mac addr + + associatemac address tonetwork id + + diff --git a/doc/source/images/minimul-setup.png b/doc/source/images/minimul-setup.png new file mode 100644 index 00000000..67f52f78 Binary files /dev/null and b/doc/source/images/minimul-setup.png differ diff --git a/doc/source/images/minimul-setup.svg b/doc/source/images/minimul-setup.svg new file mode 100644 index 00000000..21319546 --- /dev/null +++ b/doc/source/images/minimul-setup.svg @@ -0,0 +1,903 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + nova-compute + + + All-in-One setup + + + + + eth + + + + + OVS + + + + + quantum_ovs_agent + + openflow + + nova-api + + nova-scheduler + + + quantum-server + + + nova-... + + + nova-network + + SNAT + + + + gw-xxx + + gw-yyy + + + + + + gateway + + public internet + physical host + + VMtenant-X + ... + + VMtenant-Y + + VMtenant-... + + + + ryu-openflow-controller + + + SNAT + + diff --git a/doc/source/images/network-creation.png b/doc/source/images/network-creation.png new file mode 100644 index 00000000..d2fe033f Binary files /dev/null and b/doc/source/images/network-creation.png differ diff --git a/doc/source/images/network-creation.svg b/doc/source/images/network-creation.svg new file mode 100644 index 00000000..3d6d1e5f --- /dev/null +++ b/doc/source/images/network-creation.svg @@ -0,0 +1,484 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + quantum-server + + + + ryu-openflow-controller + + + + tenant-X + + + nova-network + User + + tenant creation + + network creation + allocate network id + + tell network id + + diff --git a/doc/source/images/network-id.svg b/doc/source/images/network-id.svg new file mode 100644 index 00000000..ad41e97d --- /dev/null +++ b/doc/source/images/network-id.svg @@ -0,0 +1,1434 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + gateway + public internet + Physical view + + + nova-network + + + OVS + + + + + + SNAT + SNAT + + + + + + eth + + + eth + + gw-xxx + + gw-yyy + + + + eth + + + + quantum_ovs_agent + + nova-api + + nova-scheduler + + + + + eth + + + + + quantum-server + + + + ryu-openflow-controller + + + + + + + eth + + + + quantum_ovs_agent + + + + + + eth + + + ... + + nova-... + + nova-compute + + VMtenant-X + ... + + OVS + + + + openflow + + VMtenant-Y + + VMtenant-... + + + nova-compute + + + VMtenant-X + + ... + + + OVS + + + + + openflow + + VMtenant-Y + + VMtenant-... + + + + + + dnsmasq + + + + + + + physical host + physical host + physical host + + + + dnsmasq + + + + + + + diff --git a/doc/source/images/physical-view.png b/doc/source/images/physical-view.png new file mode 100644 index 00000000..33354379 Binary files /dev/null and b/doc/source/images/physical-view.png differ diff --git a/doc/source/images/physical-view.svg b/doc/source/images/physical-view.svg new file mode 100644 index 00000000..ad41e97d --- /dev/null +++ b/doc/source/images/physical-view.svg @@ -0,0 +1,1434 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + gateway + public internet + Physical view + + + nova-network + + + OVS + + + + + + SNAT + SNAT + + + + + + eth + + + eth + + gw-xxx + + gw-yyy + + + + eth + + + + quantum_ovs_agent + + nova-api + + nova-scheduler + + + + + eth + + + + + quantum-server + + + + ryu-openflow-controller + + + + + + + eth + + + + quantum_ovs_agent + + + + + + eth + + + ... + + nova-... + + nova-compute + + VMtenant-X + ... + + OVS + + + + openflow + + VMtenant-Y + + VMtenant-... + + + nova-compute + + + VMtenant-X + + ... + + + OVS + + + + + openflow + + VMtenant-Y + + VMtenant-... + + + + + + dnsmasq + + + + + + + physical host + physical host + physical host + + + + dnsmasq + + + + + + + diff --git a/doc/source/images/trace-route.png b/doc/source/images/trace-route.png new file mode 100644 index 00000000..694cf1c9 Binary files /dev/null and b/doc/source/images/trace-route.png differ diff --git a/doc/source/images/trace-route.svg b/doc/source/images/trace-route.svg new file mode 100644 index 00000000..a6ab9696 --- /dev/null +++ b/doc/source/images/trace-route.svg @@ -0,0 +1,1000 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + packet traverse between different tenants + + + + + OVS + + + + + + + + + eth + + + + nova-compute + + + + eth + + + + + OVS + + + + + nova-compute + + + + eth + + + + + OVS + + + + gw-xxx + + + gw-yyy + + nova-network + This path is blockedby ryu and OVS + + VMtenant-X + + VMtenant-Y + + VMtenant-X + + VMtenant-Y + + + + + + + + + + + + + + + firewalliptables + physical host + physical host + physical host + + diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..2320e219 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,26 @@ +.. ryu documentation master file, created by + sphinx-quickstart on Mon Dec 5 15:38:48 2011. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +********************************** +Welcome to RYU the Network OS(NOS) +********************************** + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview.rst + getting_started.rst + using_with_openstack.rst + how_l2_segregation_works.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 00000000..a6210d3d --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/doc/source/using_with_openstack.rst b/doc/source/using_with_openstack.rst new file mode 100644 index 00000000..143a3042 --- /dev/null +++ b/doc/source/using_with_openstack.rst @@ -0,0 +1,251 @@ +.. _using_with_openstack: + +*************************************************************** +Using Ryu Network OS with with OpenStack as OpenFlow controller +*************************************************************** +This section describes how to setup openstack (nova, quantum) and +ryu-manager. +It is assumed that kvm with libvirt is used and each host machines that run +nova-compute/nova-network has two physical NICs. +It would be possible to deploy it with single NIC machines as described at +the last section. + +NOTE: How to use nova isn't described in this document. + +Overview +======== + +Ryu is designed/implemented with for production use in mind, so it cooperates +very well with `OpenStack `_ . +With nova and quantum OVS plugin, +Ryu provides L2 segregation of Multi-tenants without any switch feature/settings +like VLAN. So it's very easy to use/experiment/deploy this segregation as +the below figure. + + .. image:: /images/logical-view.png + + + +Physical machine setup +---------------------- +The following figure depicts how physical hosts are connected and each daemons +are deployed. + + .. image:: /images/physical-view.png + +Although the nova-api, nova-scheduler, nova-network and related openstack +daemons are installed in each own physical machines in the above picture, +they can be installed on a physical machine which also runs nova-compute. +Each host machine has two nics and one is connected to management LAN +and other is connected to deployment LAN. + + +How to install/setup +==================== +If you are not familiar with installing/setting up nova/quantum/openvswitch +from the source, please refer to OpenStack document and get back here again. +[ +`OpenStack docs `_ , +`Nova `_ , +`Quantum `_ , +`OpenvSwtich and Quantum Part 1 `_ , +`OpenvSwtich and Quantum Part 2 `_ , +`OVS Quantum Plugin Documentation `_ +] + +* Install ryu and run ryu-manager + * install ryu from the source code on the hosts on which you run + * nova-compute, + * quantum-server and + * ryu-manager. + + This is because quantum-server and ova quantum agent which runs on + nova-compute node needs ryu-client library to communicate ryu-manager. + + Type in ryu source directory:: + + % python ./setup.py install + + * edit /etc/ryu/ryu.conf on the host on which you run ryu-manager + if necessary + + No configuration is needed on hosts that runs quantum and ovs quantum + agent. + + * run ryu network os:: + + % ryu-manager [----flagfile /etc/ryu/ryu.conf] + + +* get nova source and quantum source from github + * They are a bit modified from openstack master tree. They are available + at github for convinience + + * https://github.com/osrg/nova/tree/ryu + * https://github.com/osrg/quantum/tree/ryu + + clone them by typing the followings in an appropriate directory:: + + % git clone --branch ryu git://github.com/osrg/nova.git + % git clone --branch ryu git://github.com/osrg/quantum.git + + If you prefer https, try those:: + + % git clone --branch ryu https://github.com/osrg/nova.git + % git clone --branch ryu https://github.com/osrg/quantum.git + + +* Install nova and quantum as usual. + (And other Openstack related component if necessary. e.g. glance) + + Each daemons can be installed in a single machine or in different machines. + Please refer to Openstack documentation for details. + You may want to set up multiple nova-compute nodes for interesting use case. + +* Setup nova daemons. (Edit nova.conf) + Specifically configure nova-network and nova-compute + + * configure nova-network + * --fixed_ranges= + * --network_size= + * --network_manager=nova.network.quantum.manager.QuantumManage + * --quantum_connection_host= + * --firewall_driver=nova.virt.libvirt.firewall.NopFirewallDriver + + NOP firewall driver is newly introduced for demonstrating Ryu + capability. + If you want, other existing firewall driver can be specified. + But such specification don't have any effect in fact + because ryu directly controls packets to VM instance via OVS bypassing + netfilter/iptables. + + * --linuxnet_interface_driver=nova.network.linux_net.LinuxOVSOFInterfaceDriver + * set up OVS on each nova-compute node + + If Ubuntu is used, you can install it from packages as + openvswitch-datapath-dkms, openvswitch-common, openvswitch-switch + If you already use bridge, you may need to edit /etc/modules to load + openvswitch kernel module, openvswitch_mod and brcompat_mod, before + bridge module and reboot to unload bridge module. + + And then create ovs bridge:: + + # ovs-vsctl add-br + + And if you connect NIC to OVS bridge.:: + + # ovs-vsctl add-port > + + * configure each nova-compute + * --libvirt_type=kvm + * --libvirt_ovs_integration_bridge= + * --libvirt_vif_type=ethernet + * --libvirt_vif_driver=nova.virt.libvirt.vif.LibvirtOpenVswitchDriver + +* install quantum server and have quantum to use OVS pluging + * Edit [PLUGIN] section of /etc/quantum/plugins.ini + * provider = quantum.plugins.openvswitch.ovs_quantum_plugin.OVSQuantumPlugin + + * Edit [OVS] section of + /etc/quantum/plugins/openvswitch/ovs_quantum_plugin.ini + + In addition to normal quantum OVS settings, add the followings. + * integration-bridge = + * plugin_driver = quantum.plugins.openvswitch.ovs_quantum_plugin.OFPRyuDriver + * agent_driver = OVSQuantumOFPRyuAgent + * openflow-controller = : + * openflow-rest-api = : + + * Run quantum server +* install quantum OVS agent on each nova-compute node + * Edit /etc/quantum/plugins/openvswitch/ovs_quantum_plugin.ini + * Run ovs agent:: + + # ovs_quantum_agent.py -v ./etc/quantum/plugins/openvswitch/ovs_quantum_plugin.ini + +* Then as usual openstack nova operation, create user, project, network and + run instances. +* Enjoy! + + +Testing +======= +Yay, now you have ryu network OS set up. +You would want to really they are L2-segregated. + +* create multi projects and run instances. +* ping/traceroute between them. +* tcpdump in the instances + +The routing between gateway(gw-xxx) of each tenants are disabled +by nova.network.linux_net.LinuxOVSOFInterfaceDriver by installing iptables +rule on nova-network host:: + + # iptable -t filter -A nova-network-FORWARD --in-interface gw-+ --out-interface gw-+ + +Thus pinging/tracerouting between VMs in distinct tenants doesn't work. +If you drop the above rule by:: + + # iptable -t filter -D nova-network-FORWARD --in-interface gw-+ --out-interface gw-+ + +You will see ping/tracerout works. Please notice that the packets go through +gw-xxx and gw-yyy, not directly. + + .. image:: /images/trace-route.png + + +Caveats +======= +* Run the following daemons in this order + #. Run Ryu network OS + #. Run quantum with OVS plugin + #. Run quantum OVS agent + #. run your guest instance + + For now, ryu-manager doesn't have persistent store, so if it's rebooted, + all the necessary information must be told again from quantum server/agent. + +* nova-manage network delete doesn't work + + At this moment, quantum doesn't implement network delete fully yet. + If you issue the command, it fails. And you need to fix nova/quantum DB + by hand using SQL. + + +Appendix +======== +In the above, two physical NIC deployment is described. +Some people may want to use those settings with single NIC machine or even +with single machine. +It would be possible as the following pictures, but we haven't tested those +setting. If you success it, please report it. + +single NIC/All-in-One setting +----------------------------- +If your host machines have only single NIC, it would be possible to use +Ryu network OS with Linux bridge. However we haven't tested such setups. + + .. image:: /images/compute-node.png + + +All-in-One Setup +---------------- +You can also setup in single physical host as the following picture. + + .. image:: /images/minimul-setup.png + +You can setup the above environment quickly using DevStack. + + #. Install Ubuntu 11.10 (Oneiric) + + #. Download Ryu enabled DevStack from github + :: + + % git clone --branch ryu git://github.com/osrg/devstack.git + + #. Start the install + :: + + % cd devstack; ./stack.sh + + It will take a few minutes. -- cgit v1.2.3