[ovs-dev] [RFC 3/5] doc: Add a 'testing-guide' section
This provides a location to include all testing-related aspects of documentation. Signed-off-by: Stephen Finucane --- Documentation/index.rst| 2 + Documentation/install-guide/dpdk.rst | 197 +--- Documentation/install-guide/general.rst| 348 + Documentation/test-guide/code-analysis.rst | 45 Documentation/test-guide/datapath.rst | 138 Documentation/test-guide/dpdk.rst | 226 +++ Documentation/test-guide/index.rst | 45 Documentation/test-guide/oftest.rst| 87 Documentation/test-guide/ryu.rst | 62 + Documentation/test-guide/travis.rst| 64 ++ Documentation/test-guide/unit.rst | 106 + 11 files changed, 780 insertions(+), 540 deletions(-) create mode 100644 Documentation/test-guide/code-analysis.rst create mode 100644 Documentation/test-guide/datapath.rst create mode 100644 Documentation/test-guide/dpdk.rst create mode 100644 Documentation/test-guide/index.rst create mode 100644 Documentation/test-guide/oftest.rst create mode 100644 Documentation/test-guide/ryu.rst create mode 100644 Documentation/test-guide/travis.rst create mode 100644 Documentation/test-guide/unit.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index e6b9c44..7eb262a 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -27,6 +27,8 @@ Welcome to Open vSwitch's documentation .. include:: install-guide/index.rst +.. include:: test-guide/index.rst + Bugs diff --git a/Documentation/install-guide/dpdk.rst b/Documentation/install-guide/dpdk.rst index 50e2872..b51716f 100644 --- a/Documentation/install-guide/dpdk.rst +++ b/Documentation/install-guide/dpdk.rst @@ -57,9 +57,6 @@ Detailed system requirements can be found at `DPDK requirements`_, while more detailed install information can be found in the `advanced installation guide <../../INSTALL.DPDK-advanced.md>`__. -.. _DPDK supported NIC: http://dpdk.org/doc/nics -.. _DPDK requirements: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html - Installing -- @@ -86,8 +83,6 @@ DPDK $ export DPDK_TARGET=x86_64-ivshmem-linuxapp-gcc -.. _DPDK sources: http://dpdk.org/browse/dpdk/refs/ - Install OVS ~~~ @@ -98,8 +93,6 @@ has to be configured with DPDK support (``--with-dpdk``). This section focuses on generic recipe that suits most cases. For distribution specific instructions, refer to one of the more relevant guides. -.. _OVS sources: http://openvswitch.org/releases/ - 1. Ensure the standard OVS requirements, described in :ref:`general-build-reqs` and :ref:`general-install-reqs`, are installed. @@ -390,192 +383,6 @@ Setup huge pages and DPDK devices using UIO:: lspci | grep Ethernet -Testing - -Below are few testcases and the list of steps to be followed. Before beginning, -ensure a userspace bridge has been created and two DPDK ports added:: - -$ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev -$ ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk -$ ovs-vsctl add-port br0 dpdk1 -- set Interface dpdk1 type=dpdk - -PHY-PHY -~~~ - -Add test flows to forward packets betwen DPDK port 0 and port 1:: - -# Clear current flows -$ ovs-ofctl del-flows br0 - -# Add flows between port 1 (dpdk0) to port 2 (dpdk1) -$ ovs-ofctl add-flow br0 in_port=1,action=output:2 -$ ovs-ofctl add-flow br0 in_port=2,action=output:1 - -Transmit traffic into either port. You should see it returned via the other. - -PHY-VM-PHY (vhost loopback) -~~~ - -Add two ``dpdkvhostuser`` ports to bridge ``br0``:: - -$ ovs-vsctl add-port br0 dpdkvhostuser0 \ --- set Interface dpdkvhostuser0 type=dpdkvhostuser -$ ovs-vsctl add-port br0 dpdkvhostuser1 \ --- set Interface dpdkvhostuser1 type=dpdkvhostuser - -Add test flows to forward packets betwen DPDK devices and VM ports:: - -# Clear current flows -$ ovs-ofctl del-flows br0 - -# Add flows -$ ovs-ofctl add-flow br0 in_port=1,action=output:3 -$ ovs-ofctl add-flow br0 in_port=3,action=output:1 -$ ovs-ofctl add-flow br0 in_port=4,action=output:2 -$ ovs-ofctl add-flow br0 in_port=2,action=output:4 - -# Dump flows -$ ovs-ofctl dump-flows br0 - -Create a VM using the following configuration: - -+--++-+ -| configuration| values | comments| -+--++-+ -| qemu version | 2.2.0 | n/a | -| qemu thread affinity | core 5 | taskset 0x20| -| memory | 4GB| n/a | -| cores| 2 | n/a | -| Qcow2 image | CentOS7| n/a | -| mrg_rxbuf| off| n/a | -+--++-+ -
[ovs-dev] [RFC 4/5] doc: Add a 'contributor-guide' section
Signed-off-by: Stephen Finucane --- .../committer-grant-revocation.rst | 398 + .../committer-responsibilities.rst | 96 + Documentation/contributor-guide/index.rst | 34 ++ Documentation/index.rst| 2 + 4 files changed, 530 insertions(+) create mode 100644 Documentation/contributor-guide/committer-grant-revocation.rst create mode 100644 Documentation/contributor-guide/committer-responsibilities.rst create mode 100644 Documentation/contributor-guide/index.rst diff --git a/Documentation/contributor-guide/committer-grant-revocation.rst b/Documentation/contributor-guide/committer-grant-revocation.rst new file mode 100644 index 000..5d6435b --- /dev/null +++ b/Documentation/contributor-guide/committer-grant-revocation.rst @@ -0,0 +1,398 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + += +OVS Committer Grant/Revocation Policy += + +An OVS committer is a participant in the project with the ability to commit +code directly to the master repository. Commit access grants a broad ability to +affect the progress of the project as presented by its most important artifact, +the code and related resources that produce working binaries of Open vSwitch. +As such it represents a significant level of trust in an individual's +commitment to working with other committers and the community at large for the +benefit of the project. It can not be granted lightly and, in the worst case, +must be revocable if the trust placed in an individual was inappropriate. + +This document suggests guidelines for granting and revoking commit access. It +is intended to provide a framework for evaluation of such decisions without +specifying deterministic rules that wouldn't be sensitive to the nuance of +specific situations. In the end the decision to grant or revoke committer +privileges is a judgment call made by the existing set of committers. + +Granting Commit Access +-- + +Granting commit access should be considered when a candidate has demonstrated +the following in their interaction with the project: + +- Contribution of significant new features through the patch submission + process where: + + - Submissions are free of obvious critical defects + - Submissions do not typically require many iterations of improvement + to be accepted + +- Consistent participation in code review of other's patches, including + existing committers, with comments consistent with the overall project + standards + +- Assistance to those in the community who are less knowledgeable through + active participation in project forums such as the ovs-discuss mailing list. + +- Plans for sustained contribution to the project compatible with the project's + direction as viewed by current committers. + +- Commitment to meet the expectations described in the "Expectations of + Developer's with Open vSwitch Access" + +The process to grant commit access to a candidate is simple: + +- An existing committer nominates the candidate by sending an email to all + existing committers with information substantiating the contributions of the + candidate in the areas described above. + +- All existing committers discuss the pros and cons of granting commit + access to the candidate in the email thread. + +- When the discussion has converged or a reasonable time has elapsed without + discussion developing (e.g. a few business days) the nominator calls for a + final decision on the candidate with a followup email to the thread. + +- Each committer may vote yes, no, or abstain by replying to the email thread. + A failure to reply is an implicit abstention. + +- After votes from all existing committers have been collected or a reasonable + time has elapsed for them to be provided (e.g. a couple of business days) the + votes are evaluated. To be granted commit access the candidate must receive + yes votes from a majority of the existing
[ovs-dev] [RFC 5/5] doc: Convert README to rST
This is a top-level document, so plain old rST is preferred. Signed-off-by: Stephen Finucane --- This is the first time we completely replace a Markdown file with its reStructuredText equivalent. How will this affect the 'dist-docs' target? --- Documentation/install-guide/general.rst | 2 +- INSTALL.md | 4 +- Makefile.am | 2 +- README.md | 131 README.rst | 115 rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- utilities/ovs-ctl.8 | 2 +- 8 files changed, 122 insertions(+), 138 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/Documentation/install-guide/general.rst b/Documentation/install-guide/general.rst index e003563..cd3c4d5 100644 --- a/Documentation/install-guide/general.rst +++ b/Documentation/install-guide/general.rst @@ -86,7 +86,7 @@ details). To compile the kernel module on Linux, you must also install the following: -- A supported Linux kernel version. Refer to the `README <../../README.md>`__ +- A supported Linux kernel version. Refer to the `README <../../README.rst>`__ for a list of supported versions. For optional support of ingress policing, you must enable kernel diff --git a/INSTALL.md b/INSTALL.md index 36ecfb8..59cf762 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -60,7 +60,7 @@ at some cost in features and performance (see [INSTALL.userspace.md] for details). To compile the kernel module on Linux, you must also install the following: - - A supported Linux kernel version. Please refer to [README.md] for a + - A supported Linux kernel version. Please refer to [README] for a list of supported versions. For optional support of ingress policing, you must enable kernel @@ -811,7 +811,7 @@ Bug Reporting Please report problems to b...@openvswitch.org. -[README.md]:README.md +[README]:README.rst [INSTALL.Debian.md]:INSTALL.Debian.md [INSTALL.Fedora.md]:INSTALL.Fedora.md [INSTALL.RHEL.md]:INSTALL.RHEL.md diff --git a/Makefile.am b/Makefile.am index 724a893..e05b1b1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -89,7 +89,7 @@ docs = \ MAINTAINERS.md \ OPENFLOW-1.1+.md \ PORTING.md \ - README.md \ + README.rst \ README-lisp.md \ README-native-tunneling.md \ REPORTING-BUGS.md \ diff --git a/README.md b/README.md deleted file mode 100644 index 53b0faf..000 --- a/README.md +++ /dev/null @@ -1,131 +0,0 @@ -Open vSwitch - - -Build Status: -- - -[](https://travis-ci.org/openvswitch/ovs) - -What is Open vSwitch? -- - -Open vSwitch is a multilayer software switch licensed under the open -source Apache 2 license. Our goal is to implement a production -quality switch platform that supports standard management interfaces -and opens the forwarding functions to programmatic extension and -control. - -Open vSwitch is well suited to function as a virtual switch in VM -environments. In addition to exposing standard control and visibility -interfaces to the virtual networking layer, it was designed to support -distribution across multiple physical servers. Open vSwitch supports -multiple Linux-based virtualization technologies including -Xen/XenServer, KVM, and VirtualBox. - -The bulk of the code is written in platform-independent C and is -easily ported to other environments. The current release of Open -vSwitch supports the following features: - -* Standard 802.1Q VLAN model with trunk and access ports -* NIC bonding with or without LACP on upstream switch -* NetFlow, sFlow(R), and mirroring for increased visibility -* QoS (Quality of Service) configuration, plus policing -* Geneve, GRE, VXLAN, STT, and LISP tunneling -* 802.1ag connectivity fault management -* OpenFlow 1.0 plus numerous extensions -* Transactional configuration database with C and Python bindings -* High-performance forwarding using a Linux kernel module - -The included Linux kernel module supports Linux 3.10 and up. - -Open vSwitch can also operate, at a cost in performance, entirely in -userspace, without assistance from a kernel module. This userspace -implementation should be easier to port than the kernel-based switch. -It is considered experimental. - -What's here? - - -The main components of this distribution are: - -* ovs-vswitchd, a daemon that implements the switch, along with - a companion Linux kernel module for flow-based switching. -* ovsdb-server, a lightweight database server that ovs-vswitchd - queries to obtain its configuration. -* ovs-dpctl, a tool for configuring the switch kernel module. -* Scripts and specs for building RPMs for Citrix XenServer and Red - Hat Enterprise Linux
[ovs-dev] [RFC 2/5] doc: Add a 'install-guide' section
Add reStructuredText versions of three installation guides: the general installation guide, the basic DPDK guide and the Docker guide. To achive this, the docs were first passed through Pandoc. For example: $ pandoc --from=markdown --to=rst INSTALL.XenServer.md \ --output doc/source/install/xenserver.rst Once done, the documents were manually inspected to fix up the (many) broken links to other INSTALL docs, correct the mistakes from the conversion (damn GitHub-style Markdown) and generally prettify the docs. Finally, the docs were listed on the index page, i.e. the root of the documentation. Signed-off-by: Stephen Finucane --- Documentation/index.rst | 8 +- Documentation/install-guide/dpdk.rst| 594 ++ Documentation/install-guide/general.rst | 870 Documentation/install-guide/index.rst | 34 ++ 4 files changed, 1503 insertions(+), 3 deletions(-) create mode 100644 Documentation/install-guide/dpdk.rst create mode 100644 Documentation/install-guide/general.rst create mode 100644 Documentation/install-guide/index.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index 61a3b4c..e6b9c44 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -25,10 +25,12 @@ Welcome to Open vSwitch's documentation === -Contents: +.. include:: install-guide/index.rst -.. toctree:: - :maxdepth: 2 +Bugs + + +Report problems to b...@openvswitch.org. Indices and tables -- diff --git a/Documentation/install-guide/dpdk.rst b/Documentation/install-guide/dpdk.rst new file mode 100644 index 000..50e2872 --- /dev/null +++ b/Documentation/install-guide/dpdk.rst @@ -0,0 +1,594 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +== +Open vSwitch with DPDK +== + +This document describes how to build and install Open vSwitch using a DPDK +datapath. Open vSwitch can use the DPDK library to operate entirely in +userspace. + +.. warning:: + The DPDK support of Open vSwitch is considered 'experimental'. + +Build requirements +-- + +In addition to the requirements described in :ref:`general-build-reqs`, +building Open vSwitch with DPDK will require the following: + +- DPDK 16.07 + +- A `DPDK supported NIC`_ + + Only required when physical ports are in use + +- A suitable kernel + + On Linux Distros running kernel version >= 3.0, only `IOMMU` needs to enabled + via the grub cmdline, assuming you are using :ref:`vfio `. For + older kernels, ensure the kernel is built with ``UIO``, ``HUGETLBFS``, + ``PROC_PAGE_MONITOR``, ``HPET``, ``HPET_MMAP`` support. If these are not + present, it will be necessary to upgrade your kernel or build a custom kernel + with these flags enabled. + +Detailed system requirements can be found at `DPDK requirements`_, while more +detailed install information can be found in the `advanced installation guide +<../../INSTALL.DPDK-advanced.md>`__. + +.. _DPDK supported NIC: http://dpdk.org/doc/nics +.. _DPDK requirements: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html + +Installing +-- + +DPDK + + +1. Download the `DPDK sources`_, extract the file and set ``DPDK_DIR``:: + + $ cd /usr/src/ + $ wget http://dpdk.org/browse/dpdk/snapshot/dpdk-16.07.zip + $ unzip dpdk-16.07.zip + $ export DPDK_DIR=/usr/src/dpdk-16.07 + $ cd $DPDK_DIR + +2. Configure and install DPDK + + Build and install the DPDK library:: + + $ export DPDK_TARGET=x86_64-native-linuxapp-gcc + $ export DPDK_BUILD=$DPDK_DIR/$DPDK_TARGET + $ make install T=$DPDK_TARGET DESTDIR=install + + If IVSHMEM support is required, use a different target:: + + $ export DPDK_TARGET=x86_64-ivshmem-linuxapp-gcc + +.. _DPDK sources: http://dpdk.org/browse/dpdk/refs/ + +Install OVS +~~~ + +OVS can be installed using different methods. For OVS to use DPDK datapath, it +has to be configured with DPDK support (``--with-dpdk``). +
[ovs-dev] [RFC 1/5] Add initial sphinx configuration
This is essentially the output of 'sphinx-quickstart' but with parts of
the Makefile merged into the existing Makefile.am and a license added
to the index.rst file.
Signed-off-by: Stephen Finucane
---
I need to know who to assign copyright to. I've used "Open vSwitch
Developers" as a placeholder until I get better information.
---
Documentation/_build/.keep | 0
Documentation/_static/.keep| 0
Documentation/_templates/.keep | 0
Documentation/conf.py | 338 +
Documentation/index.rst| 38 +
Makefile.am| 6 +
6 files changed, 382 insertions(+)
create mode 100644 Documentation/_build/.keep
create mode 100644 Documentation/_static/.keep
create mode 100644 Documentation/_templates/.keep
create mode 100644 Documentation/conf.py
create mode 100644 Documentation/index.rst
diff --git a/Documentation/_build/.keep b/Documentation/_build/.keep
new file mode 100644
index 000..e69de29
diff --git a/Documentation/_static/.keep b/Documentation/_static/.keep
new file mode 100644
index 000..e69de29
diff --git a/Documentation/_templates/.keep b/Documentation/_templates/.keep
new file mode 100644
index 000..e69de29
diff --git a/Documentation/conf.py b/Documentation/conf.py
new file mode 100644
index 000..55e0be7
--- /dev/null
+++ b/Documentation/conf.py
@@ -0,0 +1,338 @@
+# -*- coding: utf-8 -*-
+#
+# Open vSwitch documentation build configuration file, created by
+# sphinx-quickstart on Fri Sep 30 09:57:36 2016.
+#
+# 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.
+
+# 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.
+#
+# import os
+# import sys
+# 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(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+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'Open vSwitch'
+copyright = u'2016, Open vSwitch Developers'
+author = u'Open vSwitch Developers'
+
+# 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 = u'2.6'
+# The full version, including alpha/beta/rc tags.
+release = u'2.6.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+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.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# 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 p
[ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator
Since the move to GitHub, OVS has increasingly used Markdown for all of its documentation. This seems like a natural fit, given Markdown's low overhead and support in the GitHub web UI. However, Markdown is a documentation format, not a documentation system, and it starts to fall over as you add more and more documents and see the need for thing like cross-referencing, or insertion of partial documents into other docs. I'd like to propose integrating the Sphinx documentation tool into the OVS documentation. This would mean converting most or all of the documentation to reStructuredText, but it would bring significant advantages including: * native cross-referencing * multiple output formats (including pretty HTML) * automatic indexing/searching of docs * hierarchial structuring of the docs * DRY documents, through inclusion of partial docs in multiple files * ... I chose rST+Sphinx due to the overwhelming popularity of the tool within other open source communities like the Linux kernel and OpenStack, which have all migrated documentation from other tools (DocBook, mostly) in recent times. Documents located in the top-level directory should also be converted to rST to be consistent, but these should not include any Sphinx extensions to ensure that these continue to be readable on GitHub. I've included some patches that show the kind of changes that would be necessary. I've actually converted far more of the docs (~40%?) at this point, but I'd like to gauge interest before continuing with the remainder. I'd also appreciate help from folks who would take a stab at coverting docs so I don't have to do it all by myself. Feel free to direct any questions at me. Stephen Finucane (5): Add initial sphinx configuration doc: Add a 'install-guide' section doc: Add a 'testing-guide' section doc: Add a 'contributor-guide' section doc: Convert README to rST Documentation/_build/.keep | 0 Documentation/_static/.keep| 0 Documentation/_templates/.keep | 0 Documentation/conf.py | 338 + .../committer-grant-revocation.rst | 398 .../committer-responsibilities.rst | 96 Documentation/contributor-guide/index.rst | 34 ++ Documentation/index.rst| 44 ++ Documentation/install-guide/dpdk.rst | 405 Documentation/install-guide/general.rst| 524 + Documentation/install-guide/index.rst | 34 ++ Documentation/test-guide/code-analysis.rst | 45 ++ Documentation/test-guide/datapath.rst | 138 ++ Documentation/test-guide/dpdk.rst | 226 + Documentation/test-guide/index.rst | 45 ++ Documentation/test-guide/oftest.rst| 87 Documentation/test-guide/ryu.rst | 62 +++ Documentation/test-guide/travis.rst| 64 +++ Documentation/test-guide/unit.rst | 106 + INSTALL.md | 4 +- Makefile.am| 8 +- README.md | 131 -- README.rst | 115 + rhel/openvswitch-fedora.spec.in| 2 +- rhel/openvswitch.spec.in | 2 +- utilities/ovs-ctl.8| 2 +- 26 files changed, 2773 insertions(+), 137 deletions(-) create mode 100644 Documentation/_build/.keep create mode 100644 Documentation/_static/.keep create mode 100644 Documentation/_templates/.keep create mode 100644 Documentation/conf.py create mode 100644 Documentation/contributor-guide/committer-grant-revocation.rst create mode 100644 Documentation/contributor-guide/committer-responsibilities.rst create mode 100644 Documentation/contributor-guide/index.rst create mode 100644 Documentation/index.rst create mode 100644 Documentation/install-guide/dpdk.rst create mode 100644 Documentation/install-guide/general.rst create mode 100644 Documentation/install-guide/index.rst create mode 100644 Documentation/test-guide/code-analysis.rst create mode 100644 Documentation/test-guide/datapath.rst create mode 100644 Documentation/test-guide/dpdk.rst create mode 100644 Documentation/test-guide/index.rst create mode 100644 Documentation/test-guide/oftest.rst create mode 100644 Documentation/test-guide/ryu.rst create mode 100644 Documentation/test-guide/travis.rst create mode 100644 Documentation/test-guide/unit.rst delete mode 100644 README.md create mode 100644 README.rst -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator
On 2016-10-04 22:01, Ben Pfaff wrote: On Sat, Oct 01, 2016 at 08:01:29PM +0100, Stephen Finucane wrote: Since the move to GitHub, OVS has increasingly used Markdown for all of its documentation. This seems like a natural fit, given Markdown's low overhead and support in the GitHub web UI. However, Markdown is a documentation format, not a documentation system, and it starts to fall over as you add more and more documents and see the need for thing like cross-referencing, or insertion of partial documents into other docs. I'd like to propose integrating the Sphinx documentation tool into the OVS documentation. This would mean converting most or all of the documentation to reStructuredText, but it would bring significant advantages including: * native cross-referencing * multiple output formats (including pretty HTML) * automatic indexing/searching of docs * hierarchial structuring of the docs * DRY documents, through inclusion of partial docs in multiple files * ... I chose rST+Sphinx due to the overwhelming popularity of the tool within other open source communities like the Linux kernel and OpenStack, which have all migrated documentation from other tools (DocBook, mostly) in recent times. Documents located in the top-level directory should also be converted to rST to be consistent, but these should not include any Sphinx extensions to ensure that these continue to be readable on GitHub. I've included some patches that show the kind of changes that would be necessary. I've actually converted far more of the docs (~40%?) at this point, but I'd like to gauge interest before continuing with the remainder. I'd also appreciate help from folks who would take a stab at coverting docs so I don't have to do it all by myself. Feel free to direct any questions at me. This seems quite nice. I played with it for a few minutes and looked at the generated HTML output, which is nicer than the current "make dist-docs" output. I assume that, if this were to be fully converted, then the generated webpage would replace "make dist-docs" and point to all the documentation that that currently outputs? Yes, that would be the intention. We could keep the 'dist-docs' target to build offline copies of the documentation but it would eventually use sphinx instead of the 'dist-docs' script. I would also like to provide a custom stylesheet/Sphinx theme so we could display docs on the current documentation page [1] with a consistent style. For an example of what's possible here, look at the OpenStack docs [2], the Nova developer docs [3] and the Python docs [4]. Despite varying appearances, all are generated using Sphinx. In particular, it would be good to make sure that the manpages make it into the output. manpages would be included. We may wish to rewrite these in reST like OpenStack do [5], but this is totally optional and should be done at another time. I had to fold in the appended patch to get "make" to pass, to support out-of-tree builds, and to make the license disappear from the "unit tests" page. Yeah, the Makefile was a (poor) first pass, so thanks for the patch. The proper version will be actually tested. Assuming we're good with the idea, here's my current POA. 1) Convert all docs in-place to reStructuredText Update the 'dist-docs' script to use 'rst2html' [6] for '*.rst' files. The documentation output will remain essentially the same for now. This will be a slog, but it's rather trivial to review (cursory visual inspection) and is necessary for (2) 2) Integrate Sphinx Move all documents except traditional top-level docs (README, CodingStyle etc.) to 'Documentation' and build with sphinx instead of 'rst2html'. The openvswitch.org docs page [1] will start using the sphinx output. Files would retain their existing names and structure meaning the docs index page will simply be a dumb list of these files (like today, really). 3) Rework docs into a series of guides I see the following guides as being helpful - Installation guide - Usage guide - Contributor guide I had a 'testing-guide', but this makes more sense split between the middle two. Any other guides? This would be three separate series so I don't have to do everything at once. I'd also welcome assistance from anyone who wants to take the chance to rework some aspect of the docs. Cheers, Stephen [1] http://openvswitch.org/support/dist-docs/ [2] http://docs.openstack.org/admin-guide/compute-cpu-topologies.html [3] http://docs.openstack.org/developer/nova/testing/libvirt-numa.html [4] https://docs.python.org/3/library/mailbox.html [5] https://github.com/openstack/python-openstackclient/blob/3.2.0/doc/source/man/openstack.rst [6] http://docutils.sourceforge.net/docs/user/tools.html#rst2html-py ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [RFC 1/5] Add initial sphinx configuration
On 2016-10-05 00:32, Ben Pfaff wrote: On Wed, Oct 05, 2016 at 09:25:11AM +0900, Joe Stringer wrote: On 2 October 2016 at 04:01, Stephen Finucane wrote: > This is essentially the output of 'sphinx-quickstart' but with parts of > the Makefile merged into the existing Makefile.am and a license added > to the index.rst file. > > Signed-off-by: Stephen Finucane > --- > I need to know who to assign copyright to. I've used "Open vSwitch > Developers" as a placeholder until I get better information. ... > +# General information about the project. > +project = u'Open vSwitch' > +copyright = u'2016, Open vSwitch Developers' > +author = u'Open vSwitch Developers' I think Ben's response is addressing your contributions to the project; but I suppose that you're asking how this should be written in the general information section above. Ben? Oh, I misunderstood then ;-) The documentation is the work of many people with many employers. I don't know of a better way to express that, in a maintainable way, than the above. (I hope that doesn't make any lawyers cringe.) Sounds good to me. OpenStack docs use 'OpenStack Foundation', but 'Linux Foundation' seemed like the wrong choice here. Speaking of licenses, I've included the Apache 2.0 license header at the top of all reworked docs. Is this necessary? Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator
On 2016-10-05 17:29, Ben Pfaff wrote: On Wed, Oct 05, 2016 at 10:05:50AM +, Stephen Finucane wrote: [snip] 3) Rework docs into a series of guides I see the following guides as being helpful - Installation guide - Usage guide - Contributor guide I had a 'testing-guide', but this makes more sense split between the middle two. Any other guides? We probably want to have separate guides for OVS and for OVN, at least for installation and usage. Agreed. I'll scope this out a little further once the basic conversion is complete. This would be three separate series so I don't have to do everything at once. I'd also welcome assistance from anyone who wants to take the chance to rework some aspect of the docs. I can help with some MD->RST. You mentioned that you've already done it for about half the docs and hadn't posted all of those. I've actually got a good deal more done over the weekend (it didn't stop raining) so there's only the below left: - INSTALL.Fedora.md - INSTALL.Libvirt.md - INSTALL.RHEL.md - INSTALL.SELinux.md - INSTALL.SSL.md - tutorial/Tutorial.md - tutorial/OVN-Tutorial.md - ovn/CONTAINERS.OpenStack.md - ovn/OVN-GW-HA.md - Documentation/OVSDB-replication.md - Documentation/release-process.md (I'm also half way through the FAQ, which is crazy long and should probable be broken up at some point) I won't get a chance to work on these until next weekend at the earliest, so if you (or anyone) wants to take a look at any of that would be helpful. As far as converting goes, I've found a lot of the Markdown is broken meaning pandoc doesn't handle it well. Doing it manually takes as much time as fixing the badly parsed text and gives you the chance to refactor some stuff. Thanks a lot for taking this on! It's something I've thought of before (I was thinking of a DocBook or Texinfo route, although I wasn't really satisfied with either of those; Sphinx seems fine), but I've never actually taken it on. No problem. reST is definitely the best choice based on my investigations and ties in well with related projects. Hopefully this helps lower the entry curve for OVS yet more. Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 1/2] docs: Add documentation style guide
We have one for coding and could do with one for docs. Signed-off-by: Stephen Finucane --- DocumentationStyle.rst | 274 + 1 file changed, 274 insertions(+) create mode 100644 DocumentationStyle.rst diff --git a/DocumentationStyle.rst b/DocumentationStyle.rst new file mode 100644 index 000..d37f3c0 --- /dev/null +++ b/DocumentationStyle.rst @@ -0,0 +1,274 @@ +.. + Copyright (c) 2016 Stephen Finucane + + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + + +Open vSwitch Documentation Style + + +This file describes the documentation style used in all documentation found in +Open vSwitch. All documents should follow this guide. + +reStructuredText vs. Sphinx +--- + +reStructuredText (reST) is the syntax, while Sphinx is a documentation +generator. Sphinx introduces a number of extensions to reST, like the +``:ref:`` role, which can and should be used in documentation, but these will +not work correctly on GitHub. As such, these extensions should not be used in +any documentation in the root level, such as the ``README``. + +Basics +-- + +Many of the basic documentation guidelines match those of the `coding style +guide `__. + +- Use reStructuredText (reST) for all documentation. + + Sphinx extensions can be used, but only for documentation in the + ``Documentation`` folder. + + .. note:: +Some legacy documents may exist in other formats. When time allows, these +should be converted to reST. + +- Limit lines at 79 characters. + + .. note:: +An exception to this rule is text within code-block elements that cannot be +wrapped and links within references. + +- Use spaces for indenation. + +- Match indentation levels. + + A change in indentation level usually signifies a change in content nesting, + by either closing the existing level or introducing a new level. + +- Avoid trailing spaces on lines. + +- Use the following headers levels. + + | === Heading 0 (reserved for the title in a document) + | --- Heading 1 + | ~~~ Heading 2 + | +++ Heading 3 + | ''''''' Heading 4 + +- Include a license (see this file) in all docs. + +- Most importantly, always build and display documentation before submitting + changes! Docs aren't unit testable, so visible inspection is necessary. + +File Names +-- + +- Use hyphens as space delimiters. For example: ``my-readme-document.rst`` + +- Use lowercase filenames. + + .. note:: +An exception to this rule is any documents found in the root-level of the +project. + +Titles +-- + +- Use the following headers levels. + + | === Heading 0 (reserved for the title in a document) + | --- Heading 1 + | ~~~ Heading 2 + | +++ Heading 3 + | ''''''' Heading 4 + + .. note:: + +Avoid using lower heading levels by rewriting and reorganizing the +information. + +- Under- and overlines should be of the same length as that of the heading + text. + +- Use "title case" for headers. + +Code + + +- Use ``::``, the ``code`` role or the ``code-block:: `` role to prefix + code. + +- Prefix commands with ``$``. + +- Where possible, include fully-working snippets of code. If there + pre-requisites, explain what they are and how to achieve them. + +Admonitions +--- + +- Use admonitions to call attention to important information.:: + + .. note:: + +This is a sample callout for some useful tip or trick. + + Example admonitions include: ``warning``, ``important``, ``note``, ``tip`` or + ``seealso``. + +Tables +-- + +- Use either graphic tables, list tables or CSV tables. + +Graphic tables +~~ + +:: + +.. table:: OVS-Linux kernel compatibility + + == + Open vSwitch Linux kernel + == + 1.4.x2.6.18 to 3.2 + 1.5.x
[ovs-dev] [PATCH 2/2] docs: Add writing guide
Help documentation authors avoid common pitfalls. Signed-off-by: Stephen Finucane --- I imagine this could be contentious, which is why I included it separately :) --- DocumentationStyle.rst | 92 +++--- 1 file changed, 80 insertions(+), 12 deletions(-) diff --git a/DocumentationStyle.rst b/DocumentationStyle.rst index d37f3c0..10271eb 100644 --- a/DocumentationStyle.rst +++ b/DocumentationStyle.rst @@ -39,8 +39,11 @@ generator. Sphinx introduces a number of extensions to reST, like the not work correctly on GitHub. As such, these extensions should not be used in any documentation in the root level, such as the ``README``. +reST Conventions + + Basics --- +~~ Many of the basic documentation guidelines match those of the `coding style guide `__. @@ -83,7 +86,7 @@ guide `__. changes! Docs aren't unit testable, so visible inspection is necessary. File Names --- +~~ - Use hyphens as space delimiters. For example: ``my-readme-document.rst`` @@ -94,7 +97,7 @@ File Names project. Titles --- +~~ - Use the following headers levels. @@ -115,7 +118,7 @@ Titles - Use "title case" for headers. Code - + - Use ``::``, the ``code`` role or the ``code-block:: `` role to prefix code. @@ -126,7 +129,7 @@ Code pre-requisites, explain what they are and how to achieve them. Admonitions +~~~ - Use admonitions to call attention to important information.:: @@ -137,13 +140,15 @@ Admonitions Example admonitions include: ``warning``, ``important``, ``note``, ``tip`` or ``seealso``. +- Use notes sparingly. Avoid having more than one per subsection. + Tables --- +~~ - Use either graphic tables, list tables or CSV tables. Graphic tables -~~ +++ :: @@ -175,7 +180,7 @@ Graphic tables The ``table`` role (`` .. table:: ``) can be safely omitted. List tables -~~~ :: @@ -193,7 +198,7 @@ List tables - 2.6.18 to 3.2 CSV tables -~~ +++ :: @@ -206,7 +211,7 @@ CSV tables 1.6.x, 2.6.18 to 3.2 Cross-referencing -- +~ - To link to an external file or document, include as a link.:: @@ -251,7 +256,7 @@ Cross-referencing This is a Sphinx extension. Do not use this in any top-level documents. Figures and Other Media +~~~ - All images should be in ASCII format and included in code-blocks to preserve formatting. @@ -259,13 +264,76 @@ Figures and Other Media - Include other reStructuredText verbatim in a current document Comments - + - Comments are indicated by means of the ``..`` marker.:: .. TODO(stephenfin) This section needs some work. This TODO will not appear in the final generated document, however. +Writing Style +- + +Follow these guidelines to ensure readability and consistency of the Open +vSwitch documentation. These guidelines are based on the `IBM Style Guide +<http://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`__. + +- Use standard US English + + Use a spelling and grammar checking tool as necessary. + +- Expand initialisms and acronyms on first usage. + + Commonly used terms like CPU or RAM are allowed. + + .. list-table:: Example + :header-rows: 1 + + * - Do not use + - Do use + * - OVS is a virtual switch. OVS has... + - Open vSwitch (OVS) is a virtual switch. OVS has... + * - The VTEP emulator is... + - The Virtual Tunnel Endpoint (VTEP) emulator is... + +- Write in the active voice + + The subject should do the verb's action, rather than be acted upon. + + .. list-table:: Example + :header-rows: 1 + + * - Do not use + - Do use + * - A bridge is created by you + - Create a bridge + +- Write in the present tense + + .. list-table:: Example + :header-rows: 1 + + * - Do not use + - Do use + * - Once the bridge is created, you can create a port + - Once the bridge is created, create a port + +- Write in second person + + .. list-table:: Example + :header-rows: 1 + + * - Do not use + - Do use + * - To create a bridge, the user runs: + - To create a bridge, run: + +- Keep sentences short and consise + +- Eliminate needless politeness + + Avoid "please" and "thank you" + Useful Links -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 0/9 md->rst] Convert most INSTALL guides
I'm going to dripfeed the conversion patches to avoid overloading peoples (there are ~25 of them so far). This is the first batch. Stephen Finucane (9): dist-docs: Add support for rST doc: Convert INSTALL to rST doc: Convert INSTALL.DPDK to rST doc: Convert INSTALL.Debian to rST doc: Convert INSTALL.Docker to rST doc: Convert INSTALL.Windows to rST doc: Convert INSTALL.userspace to rST doc: Convert INSTALL.XenServer to rST doc: Convert INSTALL.KVM to rST CONTRIBUTING.md | 6 +- FAQ.md | 16 +- INSTALL.DPDK-ADVANCED.md| 12 +- INSTALL.DPDK.md | 625 - INSTALL.DPDK.rst| 599 +++ INSTALL.Debian.md | 101 - INSTALL.Debian.rst | 117 ++ INSTALL.Docker.md | 298 -- INSTALL.Docker.rst | 320 +++ INSTALL.Fedora.md | 6 +- INSTALL.KVM.md | 87 INSTALL.KVM.rst | 99 + INSTALL.Libvirt.md | 4 +- INSTALL.NetBSD.md | 8 +- INSTALL.RHEL.md | 6 +- INSTALL.SELinux.md | 2 +- INSTALL.SSL.md | 4 +- INSTALL.Windows.md | 527 INSTALL.Windows.rst | 621 INSTALL.XenServer.md| 6 +- INSTALL.XenServer.rst | 224 +++ INSTALL.md | 823 -- INSTALL.rst | 866 INSTALL.userspace.md| 86 INSTALL.userspace.rst | 101 + Makefile.am | 20 +- PORTING.md | 4 +- README.md | 28 +- build-aux/dist-docs | 22 +- debian/openvswitch-common.docs | 2 +- rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- tutorial/OVN-Tutorial.md| 2 +- tutorial/Tutorial.md| 4 +- vswitchd/ovs-vswitchd.8.in | 2 +- vtep/README.ovs-vtep.md | 2 +- 36 files changed, 3035 insertions(+), 2619 deletions(-) delete mode 100644 INSTALL.DPDK.md create mode 100644 INSTALL.DPDK.rst delete mode 100644 INSTALL.Debian.md create mode 100644 INSTALL.Debian.rst delete mode 100644 INSTALL.Docker.md create mode 100644 INSTALL.Docker.rst delete mode 100644 INSTALL.KVM.md create mode 100644 INSTALL.KVM.rst delete mode 100644 INSTALL.Windows.md create mode 100644 INSTALL.Windows.rst create mode 100644 INSTALL.XenServer.rst delete mode 100644 INSTALL.md create mode 100644 INSTALL.rst delete mode 100644 INSTALL.userspace.md create mode 100644 INSTALL.userspace.rst -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 4/9] doc: Convert INSTALL.Debian to rST
Signed-off-by: Stephen Finucane --- INSTALL.Debian.md | 101 - INSTALL.Debian.rst | 117 INSTALL.rst | 2 +- Makefile.am | 2 +- README.md | 4 +- vtep/README.ovs-vtep.md | 2 +- 6 files changed, 122 insertions(+), 106 deletions(-) delete mode 100644 INSTALL.Debian.md create mode 100644 INSTALL.Debian.rst diff --git a/INSTALL.Debian.md b/INSTALL.Debian.md deleted file mode 100644 index e8a6392..000 --- a/INSTALL.Debian.md +++ /dev/null @@ -1,101 +0,0 @@ -How to Build Debian Packages for Open vSwitch -= - -This document describes how to build Debian packages for Open vSwitch. -To install Open vSwitch on Debian without building Debian packages, -see [INSTALL.rst] instead. - -These instructions should also work on Ubuntu and other Debian -derivative distributions. - - -Before You Begin - - -Before you begin, consider whether you really need to build packages -yourself. Debian "wheezy" and "sid", as well as recent versions of -Ubuntu, contain pre-built Debian packages for Open vSwitch. It is -easier to install these than to build your own. To use packages from -your distribution, skip ahead to "Installing .deb Packages", below. - - -Building Open vSwitch Debian packages -- - -You may build from an Open vSwitch distribution tarball or from an -Open vSwitch Git tree with these instructions. - -You do not need to be the superuser to build the Debian packages. - -1. Install the "build-essential" and "fakeroot" packages, e.g. with - `apt-get install build-essential fakeroot`. - -2. Obtain and unpack an Open vSwitch source distribution and `cd` into - its top level directory. - -3. Install the build dependencies listed under "Build-Depends:" near - the top of debian/control. You can install these any way you like, - e.g. with `apt-get install`. - - Check your work by running `dpkg-checkbuilddeps` in the top level of - your ovs directory. If you've installed all the dependencies - properly, dpkg-checkbuilddeps will exit without printing anything. - If you forgot to install some dependencies, it will tell you which ones. - -4. Run: - - `fakeroot debian/rules binary` - - This will do a serial build that runs the unit tests. This will take - approximately 8 to 10 minutes. If you prefer, you can run a faster - parallel build, e.g.: - - `DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary` - - If you are in a big hurry, you can even skip the unit tests: - - `DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary` - - (There are a few pitfalls in the Debian packaging building system - so that, occasionally, you may find that in a tree that you have - using for a while, the build command above exits immediately - without actually building anything. To fix the problem, run - - `fakeroot debian/rules clean` - - or start over from a fresh copy of the source tree.) - -5. The generated .deb files will be in the parent directory of the - Open vSwitch source distribution. - - -Installing .deb Packages - - -These instructions apply to installing from Debian packages that you -built yourself, as described in the previous section, or from packages -provided by Debian or a Debian derivative distribution such as Ubuntu. -In the former case, use a command such as `dpkg -i` to install the -.deb files that you build, and in the latter case use a program such -as `apt-get` or `aptitude` to download and install the provided -packages. - -You must be superuser to install Debian packages. - -1. Start by installing an Open vSwitch kernel module. See - debian/openvswitch-switch.README.Debian for the available options. - -2. Install the "openvswitch-switch" and "openvswitch-common" packages. - These packages include the core userspace components of the switch. - -Open vSwitch .deb packages not mentioned above are rarely useful. -Please refer to their individual package descriptions to find out -whether any of them are useful to you. - - -Bug Reporting -- - -Please report problems to b...@openvswitch.org. - -[INSTALL.rst]:INSTALL.rst diff --git a/INSTALL.Debian.rst b/INSTALL.Debian.rst new file mode 100644 index 000..a073158 --- /dev/null +++ b/INSTALL.Debian.rst @@ -0,0 +1,117 @@ +.. + 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 distr
[ovs-dev] [PATCH 8/9] doc: Convert INSTALL.XenServer to rST
Signed-off-by: Stephen Finucane
---
INSTALL.XenServer.rst | 224 ++
INSTALL.rst | 2 +-
Makefile.am | 2 +-
README.md | 4 +-
4 files changed, 228 insertions(+), 4 deletions(-)
create mode 100644 INSTALL.XenServer.rst
diff --git a/INSTALL.XenServer.rst b/INSTALL.XenServer.rst
new file mode 100644
index 000..746b118
--- /dev/null
+++ b/INSTALL.XenServer.rst
@@ -0,0 +1,224 @@
+..
+ 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.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ === Heading 0 (reserved for the title in a document)
+ --- Heading 1
+ ~~~ Heading 2
+ +++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+===
+How to Install Open vSwitch on Citrix XenServer
+===
+
+This document describes how to build and install Open vSwitch on a Citrix
+XenServer host. If you want to install Open vSwitch on a generic Linux or BSD
+host, see the `installation guide `__ instead.
+
+Open vSwitch should work with XenServer 5.6.100 and later. However, Open
+vSwitch requires Python 2.7 or later, so using Open vSwitch with XenServer 6.5
+or earlier requires installing Python 2.7.
+
+Building
+
+
+You may build from an Open vSwitch distribution tarball or from an Open vSwitch
+Git tree. The recommended build environment to build RPMs for Citrix XenServer
+is the DDK VM available from Citrix.
+
+1. If you are building from an Open vSwitch Git tree, then you will need to
+ first create a distribution tarball by running:::
+
+ $ ./boot.sh
+ $ ./configure
+ $ make dist
+
+ You cannot run this in the DDK VM, because it lacks tools that are necessary
+ to bootstrap the Open vSwitch distribution. Instead, you must run this on a
+ machine that has the tools listed in the installation guide `__
+ as prerequisites for building from a Git tree.
+
+2. Copy the distribution tarball into ``/usr/src/redhat/SOURCES`` inside
+ the DDK VM.
+
+3. In the DDK VM, unpack the distribution tarball into a temporary directory
+ and "cd" into the root of the distribution tarball.
+
+4. To build Open vSwitch userspace, run:::
+
+ $ rpmbuild -bb xenserver/openvswitch-xen.spec
+
+ This produces three RPMs in ``/usr/src/redhat/RPMS/i386``:
+
+ - ``openvswitch``
+ - ``openvswitch-modules-xen``
+ - ``openvswitch-debuginfo``
+
+ The above command automatically runs the Open vSwitch unit tests. To
+ disable the unit tests, run:::
+
+ $ rpmbuild -bb --without check xenserver/openvswitch-xen.spec
+
+Build Parameters
+
+
+``openvswitch-xen.spec`` needs to know a number of pieces of information about
+the XenServer kernel. Usually, it can figure these out for itself, but if it
+does not do it correctly then you can specify them yourself as parameters to
+the build. Thus, the final ``rpmbuild`` step above can be elaborated as:::
+
+$ VERSION=
+$ KERNEL_NAME=
+$ KERNEL_VERSION=
+$ KERNEL_FLAVOR=
+$ rpmbuild \
+ -D "openvswitch_version $VERSION" \
+ -D "kernel_name $KERNEL_NAME" \
+ -D "kernel_version $KERNEL_VERSION" \
+ -D "kernel_flavor $KERNEL_FLAVOR" \
+ -bb xenserver/openvswitch-xen.spec
+
+where:
+
+
+ is the version number that appears in the name of the Open vSwitch tarball,
+ e.g. 0.90.0.
+
+
+ is the name of the XenServer kernel package, e.g. ``kernel-xen`` or
+ ``kernel-NAME-xen``, without the ``kernel-`` prefix.
+
+
+ is the output of:::
+
+ $ rpm -q --queryformat "%{Version}-%{Release}" ,
+
+ e.g. ``2.6.32.12-0.7.1.xs5.6.100.323.170596``, where
+ is the name of the ``-devel`` package
+ corresponding to .
+
+
+ is either ``xen`` or ``kdump``, where ``xen`` flavor is the main running
+ kernel flavor and the ``kdump`` flavor is the crashdump kernel flavor.
+ Commonly, one would specify ``xen`` here.
+
+For XenServer 6.5 or above, the kernel version naming no longer contains
+KERNEL_FLAVOR. In fact, only providing the ``uname -r`` output is enough. So,
+the final ``rpmbuild`` step changes to:::
+
+$ KERNEL_UNAME=<`una
[ovs-dev] [PATCH 1/9] dist-docs: Add support for rST
This will eventually go away once Sphinx starts doing all this work for
us. For now, however, let's make sure we don't break the OVS website.
This introduces a new dependency for the dist-docs script - 'rst2html'.
This tool is packaged on Ubuntu, Fedora (via 'python-docutils'), etc.
and can be installed from pip using the 'docsutils' package.
Signed-off-by: Stephen Finucane
---
Makefile.am | 4 ++--
build-aux/dist-docs | 22 +++---
2 files changed, 21 insertions(+), 5 deletions(-)
diff --git a/Makefile.am b/Makefile.am
index 49010b3..4b01766 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -63,8 +63,8 @@ CLEAN_LOCAL =
DISTCLEANFILES =
PYCOV_CLEAN_FILES = build-aux/check-structs,cover
-# A list of Markdown-formatted documentation that will automatically be
-# included in the "make dist-docs" output.
+# A list of Markdown- or reStructuredText-formatted documentation that will
+# automatically be included in the "make dist-docs" output.
docs = \
CONTRIBUTING.md \
CodingStyle.md \
diff --git a/build-aux/dist-docs b/build-aux/dist-docs
index a81e4b2..677ceeb 100755
--- a/build-aux/dist-docs
+++ b/build-aux/dist-docs
@@ -35,6 +35,7 @@ search_path () {
}
search_path man
search_path markdown
+search_path rst2html
search_path ps2pdf
# Create dist-docs directory.
@@ -61,9 +62,9 @@ cat >&3 <
EOF
-# Add top-level documentation to index.html, giving it .txt extensions so
-# that the webserver doesn't serve it as Markdown and make your web browser
-# try to invoke some kind of external helper you don't have installed.
+# Add top-level documentation to index.html, giving it .txt extensions so that
+# the webserver doesn't serve it as Markdown/rST and make your web browser try
+# to invoke some kind of external helper you don't have installed.
#
# Also translate documentation to HTML.
for file
@@ -92,6 +93,21 @@ EOF
EOF
;;
+*.rst)
+cp "$srcdir/$file" "$distdir/$file.txt"
+ln -s $(basename "$file.txt") "$distdir/$file"
+rst2html "$distdir/$file.txt" --stylesheet-path="style.css" \
+--link-stylesheet --title="$file (Open vSwitch $VERSION)" \
+> "$distdir/$file.html"
+cat <
+ $file
+ $title
+ HTML, plain text
+
+EOF
+;;
+
*)
cp "$srcdir/$file" "$distdir/$file"
cat <http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 9/9] doc: Convert INSTALL.KVM to rST
Signed-off-by: Stephen Finucane
---
INSTALL.KVM.md | 87 --
INSTALL.KVM.rst | 99 +
Makefile.am | 2 +-
README.md | 4 +--
4 files changed, 102 insertions(+), 90 deletions(-)
delete mode 100644 INSTALL.KVM.md
create mode 100644 INSTALL.KVM.rst
diff --git a/INSTALL.KVM.md b/INSTALL.KVM.md
deleted file mode 100644
index 99f481d..000
--- a/INSTALL.KVM.md
+++ /dev/null
@@ -1,87 +0,0 @@
-How to Use Open vSwitch with KVM
-=
-
-This document describes how to use Open vSwitch with the Kernel-based
-Virtual Machine (KVM). This document assumes that you have read and
-followed [INSTALL.rst] to get Open vSwitch setup on your Linux system.
-
-Setup
--
-
-First, follow the setup instructions in [INSTALL.rst] to get a working
-Open vSwitch installation.
-
-KVM uses tunctl to handle various bridging modes, which you can
-install with the Debian/Ubuntu package uml-utilities.
-
- % apt-get install uml-utilities
-
-Next, you will need to modify or create custom versions of the qemu-ifup
-and qemu-ifdown scripts. In this guide, we'll create custom versions
-that make use of example Open vSwitch bridges that we'll describe in this
-guide.
-
-Create the following two files and store them in known locations.
-
-For example /etc/ovs-ifup and /etc/ovs-ifdown
-
-/etc/ovs-ifup
-
-```
-#!/bin/sh
-
-switch='br0'
-/sbin/ifconfig $1 0.0.0.0 up
-ovs-vsctl add-port ${switch} $1
-```
-
-/etc/ovs-ifdown
-
-```
-#!/bin/sh
-
-switch='br0'
-/sbin/ifconfig $1 0.0.0.0 down
-ovs-vsctl del-port ${switch} $1
-```
-
-At the end of [INSTALL.rst], it describes basic usage of creating
-bridges and ports. If you haven't already, create a bridge named
-br0 with the following command:
-
- % ovs-vsctl add-br br0
-
-Then, add a port to the bridge for the NIC that you want your guests
-to communicate over (e.g. eth0):
-
- % ovs-vsctl add-port br0 eth0
-
-Please refer to ovs-vsctl(8) for more details.
-
-Next, we'll start a guest that will use our ifup and ifdown scripts.
-
- % kvm -m 512 -net nic,macaddr=00:11:22:EE:EE:EE -net \
-tap,script=/etc/ovs-ifup,downscript=/etc/ovs-ifdown -drive \
-file=/path/to/disk-image,boot=on
-
-This will start the guest and associate a tap device with it. The
-ovs-ifup script will add a port on the br0 bridge so that the
-guest will be able to communicate over that bridge.
-
-To get some more information and for debugging you can use Open
-vSwitch utilities such as ovs-dpctl and ovs-ofctl, For example:
-
- % ovs-dpctl show
- % ovs-ofctl show br0
-
-You should see tap devices for each KVM guest added as ports to
-the bridge (e.g. tap0)
-
-Please refer to ovs-dpctl(8) and ovs-ofctl(8) for more details.
-
-Bug Reporting
--
-
-Please report problems to b...@openvswitch.org.
-
-[INSTALL.rst]:INSTALL.rst
diff --git a/INSTALL.KVM.rst b/INSTALL.KVM.rst
new file mode 100644
index 000..c963193
--- /dev/null
+++ b/INSTALL.KVM.rst
@@ -0,0 +1,99 @@
+..
+ 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.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ === Heading 0 (reserved for the title in a document)
+ --- Heading 1
+ ~~~ Heading 2
+ +++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+
+How to Use Open vSwitch with KVM
+
+
+This document describes how to use Open vSwitch with the Kernel-based Virtual
+Machine (KVM).
+
+.. note::
+
+ This document assumes that you have read and followed the `installation guide
+ `__ to get Open vSwitch setup on your Linux system.
+
+Setup
+-
+
+KVM uses tunctl to handle various bridging modes, which you can install with
+the Debian/Ubuntu package ``uml-utilities``:::
+
+$ apt-get install uml-utilities
+
+Next, you will need to modify or create custom versions of the ``qemu-ifup``
+and ``qemu-ifdown`` scripts. In this guide, we'll create custom versions that
+make use of example Open vSwitch bridges that we'll describe in this guide.
+
+Create the following two files and store them in known locations. For
example:::
+
+echo << EOF > /etc/ovs-ifup
[ovs-dev] [PATCH 2/9] doc: Convert INSTALL to rST
Signed-off-by: Stephen Finucane --- CONTRIBUTING.md | 6 +- FAQ.md | 10 +- INSTALL.DPDK-ADVANCED.md | 2 +- INSTALL.DPDK.md | 6 +- INSTALL.Debian.md| 4 +- INSTALL.Docker.md| 6 +- INSTALL.Fedora.md| 6 +- INSTALL.KVM.md | 8 +- INSTALL.Libvirt.md | 4 +- INSTALL.NetBSD.md| 4 +- INSTALL.RHEL.md | 6 +- INSTALL.SELinux.md | 2 +- INSTALL.SSL.md | 4 +- INSTALL.XenServer.md | 6 +- INSTALL.md | 823 INSTALL.rst | 867 +++ INSTALL.userspace.md | 4 +- Makefile.am | 2 +- README.md| 6 +- tutorial/Tutorial.md | 4 +- 20 files changed, 912 insertions(+), 868 deletions(-) delete mode 100644 INSTALL.md create mode 100644 INSTALL.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6dc3a92..9d9f035 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,7 @@ In particular: Testing is also important: - A patch that modifies existing code should be tested with `make -check` before submission. Please see INSTALL.md, under +check` before submission. Please see INSTALL.rst, under "Self-Tests", for more information. - A patch that adds or deletes files should also be tested with @@ -50,7 +50,7 @@ Testing is also important: If you are using GitHub, then you may utilize the travis-ci.org CI build system by linking your GitHub repository to it. This will run some of the above tests automatically when you push changes to your repository. -See the "Continuous Integration with Travis-CI" in the [INSTALL.md] file +See the "Continuous Integration with Travis-CI" in the [INSTALL.rst] file for details on how to set it up. Email Subject @@ -410,5 +410,5 @@ index fdd952e..f6cb88e 100644 1.7.7.3 ``` -[INSTALL.md]:INSTALL.md +[INSTALL.rst]:INSTALL.rst [CodingStyle.md]:CodingStyle.md diff --git a/FAQ.md b/FAQ.md index b769f89..de595c5 100644 --- a/FAQ.md +++ b/FAQ.md @@ -851,7 +851,7 @@ A: On Linux kernels before 3.11, the OVS GRE module and Linux GRE module dmesg for errors regarding GRE registration). To fix this, unload all GRE modules that appear in lsmod as well as the OVS kernel module. You can then reload the OVS module following the directions in - [INSTALL.md], which will ensure that dependencies are satisfied. + [INSTALL.rst], which will ensure that dependencies are satisfied. ### Q: Open vSwitch does not seem to obey my packet filter rules. @@ -2098,7 +2098,7 @@ A: Add your new message to "enum ofpraw" and "enum ofptype" in lib/ofp-msgs.h, following the existing pattern. Then recompile and fix all of the new warnings, implementing new functionality for the new message as needed. (If you configure with --enable-Werror, as - described in [INSTALL.md], then it is impossible to miss any warnings.) + described in [INSTALL.rst], then it is impossible to miss any warnings.) If you need to add an OpenFlow vendor extension message for a vendor that doesn't yet have any extension messages, then you will @@ -2114,7 +2114,7 @@ A: Add new members for your field to "struct flow" in lib/flow.h, and lib/nx-match.c to output your new field in OXM matches. Then recompile and fix all of the new warnings, implementing new functionality for the new field or header as needed. (If you - configure with --enable-Werror, as described in [INSTALL.md], then + configure with --enable-Werror, as described in [INSTALL.rst], then it is impossible to miss any warnings.) If you want kernel datapath support for your new field, you also @@ -2135,7 +2135,7 @@ A: Add your new action to "enum ofp_raw_action_type" in lib/ofp-actions.c, following the existing pattern. Then recompile and fix all of the new warnings, implementing new functionality for the new action as needed. (If you configure with --enable-Werror, - as described in [INSTALL.md], then it is impossible to miss any + as described in [INSTALL.rst], then it is impossible to miss any warnings.) If you need to add an OpenFlow vendor extension action for a vendor @@ -2151,7 +2151,7 @@ http://openvswitch.org/ [PORTING.md]:PORTING.md [WHY-OVS.md]:WHY-OVS.md -[INSTALL.md]:INSTALL.md +[INSTALL.rst]:INSTALL.rst [OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md [INSTALL.DPDK.md]:INSTALL.DPDK.md [Tutorial.md]:tutorial/Tutorial.md diff --git a/INSTALL.DPDK-ADVANCED.md b/INSTALL.DPDK-ADVANCED.md index 555f026..cf5023c 100644 --- a/INSTALL.DPDK-ADVANCED.md +++ b/INSTALL.DPDK-ADVANCED.md @@ -880,7 +880,7 @@ Please report problems to b...@openvswitch.org. [INSTALL.userspace.md]:INSTALL.userspace.md -[INSTALL.md]:INSTALL.md +[INSTALL.rst]:INSTALL.rst [DPDK Linux GSG]: http://www.dpdk.o
[ovs-dev] [PATCH 7/9] doc: Convert INSTALL.userspace to rST
Signed-off-by: Stephen Finucane --- INSTALL.DPDK-ADVANCED.md | 2 +- INSTALL.NetBSD.md| 4 +- INSTALL.rst | 3 +- INSTALL.userspace.md | 86 INSTALL.userspace.rst| 101 +++ Makefile.am | 2 +- PORTING.md | 4 +- README.md| 4 +- 8 files changed, 110 insertions(+), 96 deletions(-) delete mode 100644 INSTALL.userspace.md create mode 100644 INSTALL.userspace.rst diff --git a/INSTALL.DPDK-ADVANCED.md b/INSTALL.DPDK-ADVANCED.md index 0ed4762..8e4edfc 100644 --- a/INSTALL.DPDK-ADVANCED.md +++ b/INSTALL.DPDK-ADVANCED.md @@ -879,7 +879,7 @@ Bug Reporting: Please report problems to b...@openvswitch.org. -[INSTALL.userspace.md]:INSTALL.userspace.md +[INSTALL.userspace.rst]:INSTALL.userspace.rst [INSTALL.rst]:INSTALL.rst [DPDK Linux GSG]: http://www.dpdk.org/doc/guides/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-igb-uioor-vfio-modules [DPDK Docs]: http://dpdk.org/doc diff --git a/INSTALL.NetBSD.md b/INSTALL.NetBSD.md index a214b51..3002bad 100644 --- a/INSTALL.NetBSD.md +++ b/INSTALL.NetBSD.md @@ -31,8 +31,8 @@ As all executables installed with pkgsrc are placed in `/usr/pkg/bin/` directory, it might be a good idea to add it to your PATH. Open vSwitch on NetBSD is currently "userspace switch" implementation -in the sense described in [INSTALL.userspace.md] and [PORTING.md]. +in the sense described in [INSTALL.userspace.rst] and [PORTING.md]. [INSTALL.rst]:INSTALL.rst -[INSTALL.userspace.md]:INSTALL.userspace.md +[INSTALL.userspace.rst]:INSTALL.userspace.rst [PORTING.md]:PORTING.md diff --git a/INSTALL.rst b/INSTALL.rst index 963be09..b6c2ee1 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -80,8 +80,7 @@ vSwitch distribution or to use the kernel module built into the Linux kernel are not available in the Open vSwitch kernel datapath that ships as part of the upstream Linux kernel?" for more information on this trade-off. You may also use the userspace-only implementation, at some cost in features and performance -(see the `userspace installation guide `__ for -details). +(see the `userspace installation guide `__ for details). To compile the kernel module on Linux, you must also install the following: diff --git a/INSTALL.userspace.md b/INSTALL.userspace.md deleted file mode 100644 index cca6dc6..000 --- a/INSTALL.userspace.md +++ /dev/null @@ -1,86 +0,0 @@ -Using Open vSwitch without kernel support -= - -Open vSwitch can operate, at a cost in performance, entirely in -userspace, without assistance from a kernel module. This file -explains how to install Open vSwitch in such a mode. - -The userspace-only mode of Open vSwitch is considered experimental. -It has not been thoroughly tested. - -This version of Open vSwitch should be built manually with `configure` -and `make`. Debian packaging for Open vSwitch is also included, but -it has not been recently tested, and so Debian packages are not a -recommended way to use this version of Open vSwitch. - -Building and Installing - -The requirements and procedure for building, installing, and -configuring Open vSwitch are the same as those given in [INSTALL.rst]. -You may omit configuring, building, and installing the kernel module, -and the related requirements. - -On Linux, the userspace switch additionally requires the kernel -TUN/TAP driver to be available, either built into the kernel or loaded -as a module. If you are not sure, check for a directory named -/sys/class/misc/tun. If it does not exist, then attempt to load the -module with `modprobe tun`. - -The tun device must also exist as `/dev/net/tun`. If it does not exist, -then create /dev/net (if necessary) with `mkdir /dev/net`, then create -`/dev/net/tun` with `mknod /dev/net/tun c 10 200`. - -On FreeBSD and NetBSD, the userspace switch additionally requires the -kernel tap(4) driver to be available, either built into the kernel or -loaded as a module. - -Using the Userspace Datapath with ovs-vswitchd --- - -To use ovs-vswitchd in userspace mode, create a bridge with datapath_type -"netdev" in the configuration database. For example: - -ovs-vsctl add-br br0 -ovs-vsctl set bridge br0 datapath_type=netdev -ovs-vsctl add-port br0 eth0 -ovs-vsctl add-port br0 eth1 -ovs-vsctl add-port br0 eth2 - -ovs-vswitchd will create a TAP device as the bridge's local interface, -named the same as the bridge, as well as for each configured internal -interface. - -Currently, on FreeBSD, the functionality required for in-band control -support is not implemented. To avoid related errors, you can disable -the in-band support with the following command. - -ovs-vsctl set bridge br0 other_config:disable-in-band=true - -Firewall Rules -
[ovs-dev] [PATCH 6/9] doc: Convert INSTALL.Windows to rST
This has been extensively reworked such that the format of the document matches that of INSTALL.rst. The sum of the content remains the same, however. Signed-off-by: Stephen Finucane --- INSTALL.Windows.md | 527 INSTALL.Windows.rst | 621 INSTALL.rst | 2 +- Makefile.am | 2 +- 4 files changed, 623 insertions(+), 529 deletions(-) delete mode 100644 INSTALL.Windows.md create mode 100644 INSTALL.Windows.rst diff --git a/INSTALL.Windows.md b/INSTALL.Windows.md deleted file mode 100644 index 59f3936..000 --- a/INSTALL.Windows.md +++ /dev/null @@ -1,527 +0,0 @@ -How to Build the Kernel module & userspace daemons for Windows -== - -Autoconf, Automake and Visual C++: -- -Open vSwitch on Linux uses autoconf and automake for generating Makefiles. -It will be useful to maintain the same build system while compiling on Windows -too. One approach is to compile Open vSwitch in a MinGW environment that -contains autoconf and automake utilities and then use Visual C++ as a compiler -and linker. - -The following explains the steps in some detail. - -* Install Mingw on a Windows machine by following the instructions at: -http://www.mingw.org/wiki/Getting_Started - -This should install mingw at C:\Mingw and msys at C:\Mingw\msys. -Add "C:\MinGW\bin" and "C:\Mingw\msys\1.0\bin" to PATH environment variable -of Windows. - -You can either use the MinGW installer or the command line utility 'mingw-get' -to install both the base packages and additional packages like automake and -autoconf(version 2.68). - -Also make sure that /mingw mount point exists. If its not, please add/create -the following entry in /etc/fstab - 'C:/MinGW /mingw'. - -* Install the latest Python 2.x from python.org and verify that its path is -part of Windows' PATH environment variable. - -* You will need at least Visual Studio 2013 (update 4) to compile userspace -binaries. In addition to that, if you want to compile the kernel module you -will also need to install Windows Driver Kit (WDK) 8.1 Update. - -It is important to get the Visual Studio related environment variables and to -have the $PATH inside the bash to point to the proper compiler and linker. One -easy way to achieve this for VS2013 is to get into the "VS2013 x86 Native -Tools Command Prompt" (in a default installation of Visual Studio 2013 this can -be found under the following location: -C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\Shortcuts) -and through it enter into the bash shell available from msys by typing -'bash --login'. - -There is support for generating 64 bit binaries too. To compile under x64, -open the "VS2013 x64 Native Tools Command Prompt" (if your current running OS -is 64 bit) or "VS2013 x64 Cross Tools Command Prompt" (if your current running -OS is not 64 bit) instead of opening its x86 variant. This will point the -compiler and the linker to their 64 bit equivalent. - -If after the above step, a 'which link' inside MSYS's bash says, -"/bin/link.exe", rename /bin/link.exe to something else so that the -Visual studio's linker is used. You should also see a 'which sort' report -"/bin/sort.exe". - -* For pthread support, install the library, dll and includes of pthreads-win32 -project from -ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release to a -directory (e.g.: C:/pthread). You should add the pthread-win32's dll -path (e.g.: C:\pthread\dll\x86) to the Windows' PATH environment variable. - -* Get the Open vSwitch sources from either cloning the repo using git -or from a distribution tar ball. - -* If you pulled the sources directly from an Open vSwitch Git tree, - run boot.sh in the top source directory: - -% ./boot.sh - -* In the top source directory, configure the package by running the - configure script. You should provide some configure options to choose - the right compiler, linker, libraries, Open vSwitch component installation - directories, etc. For example, - -% ./configure CC=./build-aux/cccl LD="`which link`" \ - LIBS="-lws2_32 -liphlpapi" --prefix="C:/openvswitch/usr" \ - --localstatedir="C:/openvswitch/var" --sysconfdir="C:/openvswitch/etc" \ - --with-pthread="C:/pthread" - -By default, the above enables compiler optimization for fast code. -For default compiler optimization, pass the "--with-debug" configure -option. - -* Run make for the ported executables in the top source directory, e.g.: - -% make - - For faster compilation, you can pass the '-j' argument to make. For - example, to run 4 jobs simultaneously, run '
[ovs-dev] [PATCH 5/9] doc: Convert INSTALL.Docker to rST
Signed-off-by: Stephen Finucane --- INSTALL.Docker.md| 298 --- INSTALL.Docker.rst | 320 +++ Makefile.am | 2 +- README.md| 4 +- tutorial/OVN-Tutorial.md | 2 +- 5 files changed, 324 insertions(+), 302 deletions(-) delete mode 100644 INSTALL.Docker.md create mode 100644 INSTALL.Docker.rst diff --git a/INSTALL.Docker.md b/INSTALL.Docker.md deleted file mode 100644 index bb5e711..000 --- a/INSTALL.Docker.md +++ /dev/null @@ -1,298 +0,0 @@ -How to Use Open Virtual Networking With Docker -== - -This document describes how to use Open Virtual Networking with Docker -1.9.0 or later. This document assumes that you have installed Open -vSwitch by following [INSTALL.rst] or by using the distribution packages -such as .deb or.rpm. Consult www.docker.com for instructions on how to -install Docker. Docker 1.9.0 comes with support for multi-host networking. - -Setup -= - -For multi-host networking with OVN and Docker, Docker has to be started -with a destributed key-value store. For e.g., if you decide to use consul -as your distributed key-value store, and your host IP address is $HOST_IP, -start your Docker daemon with: - -``` -docker daemon --cluster-store=consul://127.0.0.1:8500 \ ---cluster-advertise=$HOST_IP:0 -``` - -OVN provides network virtualization to containers. OVN's integration with -Docker currently works in two modes - the "underlay" mode or the "overlay" -mode. - -In the "underlay" mode, OVN requires a OpenStack setup to provide container -networking. In this mode, one can create logical networks and can have -containers running inside VMs, standalone VMs (without having any containers -running inside them) and physical machines connected to the same logical -network. This is a multi-tenant, multi-host solution. - -In the "overlay" mode, OVN can create a logical network amongst containers -running on multiple hosts. This is a single-tenant (extendable to -multi-tenants depending on the security characteristics of the workloads), -multi-host solution. In this mode, you do not need a pre-created OpenStack -setup. - -For both the modes to work, a user has to install and start Open vSwitch in -each VM/host that he plans to run his containers. - - -The "overlay" mode -== - -OVN in "overlay" mode needs a minimum Open vSwitch version of 2.5. - -* Start the central components. - -OVN architecture has a central component which stores your networking intent -in a database. On one of your machines, with an IP Address of $CENTRAL_IP, -where you have installed and started Open vSwitch, you will need to start some -central components. - -Start ovn-northd daemon. This daemon translates networking intent from Docker -stored in the OVN_Northbound database to logical flows in OVN_Southbound -database. - -``` -/usr/share/openvswitch/scripts/ovn-ctl start_northd -``` - -* One time setup. - -On each host, where you plan to spawn your containers, you will need to -run the following command once. (You need to run it again if your OVS database -gets cleared. It is harmless to run it again in any case.) - -$LOCAL_IP in the below command is the IP address via which other hosts -can reach this host. This acts as your local tunnel endpoint. - -$ENCAP_TYPE is the type of tunnel that you would like to use for overlay -networking. The options are "geneve" or "stt". (Please note that your -kernel should have support for your chosen $ENCAP_TYPE. Both geneve -and stt are part of the Open vSwitch kernel module that is compiled from this -repo. If you use the Open vSwitch kernel module from upstream Linux, -you will need a minumum kernel version of 3.18 for geneve. There is no stt -support in upstream Linux. You can verify whether you have the support in your -kernel by doing a "lsmod | grep $ENCAP_TYPE".) - -``` -ovs-vsctl set Open_vSwitch . external_ids:ovn-remote="tcp:$CENTRAL_IP:6642" \ - external_ids:ovn-nb="tcp:$CENTRAL_IP:6641" external_ids:ovn-encap-ip=$LOCAL_IP external_ids:ovn-encap-type="$ENCAP_TYPE" -``` - -Each Open vSwitch instance in an OVN deployment needs a unique, persistent -identifier, called the "system-id". If you install OVS from distribution -packaging for Open vSwitch (e.g. .deb or .rpm packages), or if you use the -ovs-ctl utility included with Open vSwitch, it automatically configures a -system-id. If you start Open vSwitch manually, you should set one up yourself, -e.g.: - -``` -id_file=/etc/openvswitch/system-id.conf -test -e $id_file || uuidgen > $id_file -ovs-vsctl set Open_vSwitch . external_ids:system-id=$(cat $id_file) -``` - -And finally, start the ovn-controller. (You need to run the below command -on every boot) - -``` -/usr/shar
[ovs-dev] [PATCH 3/9] doc: Convert INSTALL.DPDK to rST
Signed-off-by: Stephen Finucane --- FAQ.md | 6 +- INSTALL.DPDK-ADVANCED.md| 8 +- INSTALL.DPDK.md | 625 INSTALL.DPDK.rst| 599 ++ INSTALL.rst | 2 +- Makefile.am | 2 +- README.md | 4 +- debian/openvswitch-common.docs | 2 +- rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- vswitchd/ovs-vswitchd.8.in | 2 +- 11 files changed, 614 insertions(+), 640 deletions(-) delete mode 100644 INSTALL.DPDK.md create mode 100644 INSTALL.DPDK.rst diff --git a/FAQ.md b/FAQ.md index de595c5..cfa5e70 100644 --- a/FAQ.md +++ b/FAQ.md @@ -465,7 +465,7 @@ A: Firstly, you must have a DPDK-enabled version of Open vSwitch. Finally, it is required that DPDK port names begin with 'dpdk'. - See [INSTALL.DPDK.md] for more information on enabling and using DPDK with + See [INSTALL.DPDK.rst] for more information on enabling and using DPDK with Open vSwitch. ### Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all traffic to that VLAN? @@ -778,7 +778,7 @@ A: More than likely, you've looped your network. Probably, eth0 and for all the details. Configuration for DPDK-enabled interfaces is slightly less - straightforward: see [INSTALL.DPDK.md]. + straightforward: see [INSTALL.DPDK.rst]. - Perhaps you don't actually need eth0 and eth1 to be on the same bridge. For example, if you simply want to be able to @@ -2153,6 +2153,6 @@ http://openvswitch.org/ [WHY-OVS.md]:WHY-OVS.md [INSTALL.rst]:INSTALL.rst [OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md -[INSTALL.DPDK.md]:INSTALL.DPDK.md +[INSTALL.DPDK.rst]:INSTALL.DPDK.rst [Tutorial.md]:tutorial/Tutorial.md [release-process.md]:Documentation/release-process.md diff --git a/INSTALL.DPDK-ADVANCED.md b/INSTALL.DPDK-ADVANCED.md index cf5023c..0ed4762 100644 --- a/INSTALL.DPDK-ADVANCED.md +++ b/INSTALL.DPDK-ADVANCED.md @@ -884,7 +884,7 @@ Please report problems to b...@openvswitch.org. [DPDK Linux GSG]: http://www.dpdk.org/doc/guides/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-igb-uioor-vfio-modules [DPDK Docs]: http://dpdk.org/doc [libvirt]: http://libvirt.org/formatdomain.html -[Guest VM using libvirt]: INSTALL.DPDK.md#ovstc -[Vhost walkthrough]: INSTALL.DPDK.md#vhost -[INSTALL DPDK]: INSTALL.DPDK.md#build -[INSTALL OVS]: INSTALL.DPDK.md#build +[Guest VM using libvirt]: INSTALL.DPDK.rst#ovstc +[Vhost walkthrough]: INSTALL.DPDK.rst#vhost +[INSTALL DPDK]: INSTALL.DPDK.rst#build +[INSTALL OVS]: INSTALL.DPDK.rst#build diff --git a/INSTALL.DPDK.md b/INSTALL.DPDK.md deleted file mode 100644 index 7eac86c..000 --- a/INSTALL.DPDK.md +++ /dev/null @@ -1,625 +0,0 @@ -OVS DPDK INSTALL GUIDE - - -## Contents - -1. [Overview](#overview) -2. [Building and Installation](#build) -3. [Setup OVS DPDK datapath](#ovssetup) -4. [DPDK in the VM](#builddpdk) -5. [OVS Testcases](#ovstc) -6. [Limitations ](#ovslimits) - -## 1. Overview - -Open vSwitch can use DPDK lib to operate entirely in userspace. -This file provides information on installation and use of Open vSwitch -using DPDK datapath. This version of Open vSwitch should be built manually -with `configure` and `make`. - -The DPDK support of Open vSwitch is considered 'experimental'. - -### Prerequisites - -* Required: DPDK 16.07 -* Hardware: [DPDK Supported NICs] when physical ports in use - -## 2. Building and Installation - -### 2.1 Configure & build the Linux kernel - -On Linux Distros running kernel version >= 3.0, kernel rebuild is not required -and only grub cmdline needs to be updated for enabling IOMMU [VFIO support - 3.2]. -For older kernels, check if kernel is built with UIO, HUGETLBFS, PROC_PAGE_MONITOR, -HPET, HPET_MMAP support. - -Detailed system requirements can be found at [DPDK requirements] and also refer to -advanced install guide [INSTALL.DPDK-ADVANCED.md] - -### 2.2 Install DPDK - 1. [Download DPDK] and extract the file, for example in to /usr/src - and set DPDK_DIR - - ``` - cd /usr/src/ - wget http://dpdk.org/browse/dpdk/snapshot/dpdk-16.07.zip - unzip dpdk-16.07.zip - - export DPDK_DIR=/usr/src/dpdk-16.07 - cd $DPDK_DIR - ``` - - 2. Configure and Install DPDK - - Build and install the DPDK library. - - ``` - export DPDK_TARGET=x86_64-native-linuxapp-gcc - export DPDK_BUILD=$DPDK_DIR/$DPDK_TARGET - make install T=$DPDK_TARGET DESTDIR=install - ``` - - Note: For IVSHMEM, Set `export DPDK_TARGET=x86_64-ivshmem-linuxapp-gcc` - -### 2.3 Install OVS - OVS can be installed using different methods. For OVS to use DPDK datapath, - it has to be configured with DPDK support and is done by './configure --with-dpdk'. - This sectio
Re: [ovs-dev] [PATCH 0/9 md->rst] Convert most INSTALL guides
On 2016-10-12 20:20, Russell Bryant wrote: On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane wrote: I'm going to dripfeed the conversion patches to avoid overloading peoples (there are ~25 of them so far). This is the first batch. Stephen Finucane (9): dist-docs: Add support for rST doc: Convert INSTALL to rST doc: Convert INSTALL.DPDK to rST doc: Convert INSTALL.Debian to rST doc: Convert INSTALL.Docker to rST doc: Convert INSTALL.Windows to rST doc: Convert INSTALL.userspace to rST doc: Convert INSTALL.XenServer to rST doc: Convert INSTALL.KVM to rST Do you have the end result published anywhere? It would be nice to see the before and after before diving into the detailed reviews. I visually inspected them myself but I haven't published them anywhere. You can run 'make dist-docs' and visually compare the resulting HTML files to what's on openvswitch.org (remembering that the reStructuredText versions should actually be more complete due to latent bugs in the Markdown versions). I could find somewhere to publish them if it would help but I don't know if it's really necessary :) To be honest though, I don't know how detailed we need to be right now. IMO if the functional aspects of these patches work (i.e. the 'dist-docs' target generates sane HTML for all rST files) and we haven't lost any of the raw information then any stylistic issues I may have introduced can be fixed in follow up patches. Most of these docs are going to get shuffled around or rewritten when we start moving to sphinx anyway, so we'll have the chance to really review the content itself then. Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH 0/9 md->rst] Convert most INSTALL guides
On 2016-10-13 13:10, Russell Bryant wrote: On Thu, Oct 13, 2016 at 6:00 AM, Stephen Finucane wrote: On 2016-10-12 20:20, Russell Bryant wrote: On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane wrote: I'm going to dripfeed the conversion patches to avoid overloading peoples (there are ~25 of them so far). This is the first batch. Stephen Finucane (9): dist-docs: Add support for rST doc: Convert INSTALL to rST doc: Convert INSTALL.DPDK to rST doc: Convert INSTALL.Debian to rST doc: Convert INSTALL.Docker to rST doc: Convert INSTALL.Windows to rST doc: Convert INSTALL.userspace to rST doc: Convert INSTALL.XenServer to rST doc: Convert INSTALL.KVM to rST Do you have the end result published anywhere? It would be nice to see the before and after before diving into the detailed reviews. I visually inspected them myself but I haven't published them anywhere. You can run 'make dist-docs' and visually compare the resulting HTML files to what's on openvswitch.org [1] (remembering that the reStructuredText versions should actually be more complete due to latent bugs in the Markdown versions). I could find somewhere to publish them if it would help but I don't know if it's really necessary :) To be honest though, I don't know how detailed we need to be right now. IMO if the functional aspects of these patches work (i.e. the 'dist-docs' target generates sane HTML for all rST files) and we haven't lost any of the raw information then any stylistic issues I may have introduced can be fixed in follow up patches. Most of these docs are going to get shuffled around or rewritten when we start moving to sphinx anyway, so we'll have the chance to really review the content itself then. OK, sounds good. I also see the previous conversation about this work now. Sorry about that. I'm on board with all of this. Ben, I'm happy to review all of the patches for this conversion if you'd like. ..and sorry for not setting the scene: I forget how active this mailing list is :) Let me know if you've any questions. Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH 2/9] doc: Convert INSTALL to rST
On 15 Oct 22:01, Russell Bryant wrote: > On Sat, Oct 15, 2016 at 9:57 PM, Russell Bryant wrote: > > > > > On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane > > wrote: > > > >> Signed-off-by: Stephen Finucane > >> --- > >> CONTRIBUTING.md | 6 +- > >> FAQ.md | 10 +- > >> INSTALL.DPDK-ADVANCED.md | 2 +- > >> INSTALL.DPDK.md | 6 +- > >> INSTALL.Debian.md| 4 +- > >> INSTALL.Docker.md| 6 +- > >> INSTALL.Fedora.md| 6 +- > >> INSTALL.KVM.md | 8 +- > >> INSTALL.Libvirt.md | 4 +- > >> INSTALL.NetBSD.md| 4 +- > >> INSTALL.RHEL.md | 6 +- > >> INSTALL.SELinux.md | 2 +- > >> INSTALL.SSL.md | 4 +- > >> INSTALL.XenServer.md | 6 +- > >> INSTALL.md | 823 -- > >> -- > >> INSTALL.rst | 867 ++ > >> + > >> INSTALL.userspace.md | 4 +- > >> Makefile.am | 2 +- > >> README.md| 6 +- > >> tutorial/Tutorial.md | 4 +- > >> 20 files changed, 912 insertions(+), 868 deletions(-) > >> delete mode 100644 INSTALL.md > >> create mode 100644 INSTALL.rst > >> > > > > I made a couple of minor changes to this patch. I renamed the new > > "Profiling" section header to "Valgrind", since I don't think the use of > > valgrind here is for profiling, it's primarily for catching certain types > > of errors. > > > > I also re-added the bug reporting section at the end of the document. All fine by me. > > diff --git a/INSTALL.rst b/INSTALL.rst > > index a159b00..2b7f9b1 100644 > > --- a/INSTALL.rst > > +++ b/INSTALL.rst > > @@ -599,8 +599,8 @@ All the same options are avaiable via TESTSUITEFLAGS. > > For example:: > > > > $ make check-lcov TESTSUITEFLAGS=-j8 -k ovn > > > > -Profiling > > -+ > > +Valgrind > > + > > > > If you have ``valgrind`` installed, you can run the testsuite under > > valgrind by using the ``check-valgrind`` target:: > > @@ -865,3 +865,8 @@ Open vSwitch includes a Makefile target to trigger > > static code analysis:: > > You should invoke scan-view to view analysis results. The last line of > > output > > from ``clang-analyze`` will list the command (containing results > > directory) > > that you should invoke to view the results on a browser. > > + > > +Bug Reporting > > +- > > + > > +Please report problems to b...@openvswitch.org. > > > > > > Very minor nit ... I think I would find it easier to review these if > content changes were separate from the md to rst conversion. I also > understand that it's much easier to do the cleanups as you go during the > conversion. I certainly don't want you to re-do these patches, but it's > something to keep in mind for future patches if separating formatting from > content is easy enough to do. Agreed. Most of those content changes are there from my initial attempts to migrate straight to Sphinx (before deciding a staged approach was wiser). I'll try to keep the noise down for the remaining transitions [*]. Stephen [*] The one exception will be the Windows guide, which I rewrote based on the INSTALL.(md|rst) file and would be loathe to revert changes on :) ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH 1/9] dist-docs: Add support for rST
On 15 Oct 21:20, Russell Bryant wrote:
> On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane wrote:
>
> > This will eventually go away once Sphinx starts doing all this work for
> > us. For now, however, let's make sure we don't break the OVS website.
> >
> > This introduces a new dependency for the dist-docs script - 'rst2html'.
> > This tool is packaged on Ubuntu, Fedora (via 'python-docutils'), etc.
> > and can be installed from pip using the 'docsutils' package.
> >
> > Signed-off-by: Stephen Finucane
> >
>
> I'm working through this patch series now. I had one small addition to
> this one to run by you.
>
>
> > ---
> > Makefile.am | 4 ++--
> > build-aux/dist-docs | 22 +++---
> > 2 files changed, 21 insertions(+), 5 deletions(-)
> >
> > diff --git a/Makefile.am b/Makefile.am
> > index 49010b3..4b01766 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -63,8 +63,8 @@ CLEAN_LOCAL =
> > DISTCLEANFILES =
> > PYCOV_CLEAN_FILES = build-aux/check-structs,cover
> >
> > -# A list of Markdown-formatted documentation that will automatically be
> > -# included in the "make dist-docs" output.
> > +# A list of Markdown- or reStructuredText-formatted documentation that
> > will
> > +# automatically be included in the "make dist-docs" output.
> > docs = \
> > CONTRIBUTING.md \
> > CodingStyle.md \
> > diff --git a/build-aux/dist-docs b/build-aux/dist-docs
> > index a81e4b2..677ceeb 100755
> > --- a/build-aux/dist-docs
> > +++ b/build-aux/dist-docs
> > @@ -35,6 +35,7 @@ search_path () {
> > }
> > search_path man
> > search_path markdown
> > +search_path rst2html
> > search_path ps2pdf
> >
> > # Create dist-docs directory.
> > @@ -61,9 +62,9 @@ cat >&3 < >
> > EOF
> >
> > -# Add top-level documentation to index.html, giving it .txt extensions so
> > -# that the webserver doesn't serve it as Markdown and make your web
> > browser
> > -# try to invoke some kind of external helper you don't have installed.
> > +# Add top-level documentation to index.html, giving it .txt extensions so
> > that
> > +# the webserver doesn't serve it as Markdown/rST and make your web
> > browser try
> > +# to invoke some kind of external helper you don't have installed.
> > #
> > # Also translate documentation to HTML.
> > for file
> > @@ -92,6 +93,21 @@ EOF
> > EOF
> > ;;
> >
> > +*.rst)
> >
>
> I added this line here:
>
> +title=`grep -A 1 -e "^=" $srcdir/$file | sed -n 2p`
>
> To get a proper title for each rst doc in index.html. Previously it was
> just using the first line, which was ".." for the rst files. Let me know
> if you have an idea for something better.
Sure thing. This is an intermediate step on the way to Sphinx, so
whatever works is fine by. Just don't expect me to debug anything
involving sed or awk, heh.
Stephen
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 00/15] Covert most of the remaining top-level documents
This is the second conversion series. This one is slightly larger, but it covers all top-level documents that I've converted thus far. I'll move onto those later this week. There's also an unrelated patch which I noticed as I was typing this cover letter. Feel free to ignore :) Stephen Finucane (15): doc: Convert CodingStyle to rST doc: Convert IntegrationGuide to rST doc: Convert MAINTAINERS to rST doc: Convert PORTING to rST doc: Convert README to rST doc: Convert REPORTING-BUGS to rST doc: Convert WHY-OVS to rST doc: Convert SECURITY to rST doc: Convert README-lisp to rST doc: Convert README-native-tunneling to rST doc: Convert CONTRIBUTING to rST doc: Convert OPENFLOW-1.1+ to rST doc: Convert DESIGN to rST doc: Convert FAQ to rST trivial: Resolve whitespace issues with acinclude CONTRIBUTING.md | 414 - CONTRIBUTING.rst| 444 ++ CodingStyle.md | 578 --- CodingStyle.rst | 642 DESIGN.md | 1093 -- DESIGN.rst | 1151 ++ Documentation/committer-responsibilities.md |4 +- FAQ.md | 2158 --- FAQ.rst | 2091 ++ INSTALL.Fedora.md |4 +- INSTALL.NetBSD.md |4 +- INSTALL.rst |6 +- IntegrationGuide.md | 169 --- IntegrationGuide.rst| 195 +++ MAINTAINERS.md | 29 - MAINTAINERS.rst | 75 + Makefile.am | 30 +- OPENFLOW-1.1+.md| 317 OPENFLOW.rst| 415 ++ PORTING.md | 326 PORTING.rst | 330 README-lisp.md | 81 - README-lisp.rst | 113 ++ README-native-tunneling.md | 85 -- README-native-tunneling.rst | 176 +++ README.md | 131 -- README.rst | 116 ++ REPORTING-BUGS.md | 58 - REPORTING-BUGS.rst | 73 + SECURITY.md => SECURITY.rst | 200 ++- WHY-OVS.md | 106 -- WHY-OVS.rst | 128 ++ acinclude.m4| 14 +- debian/openvswitch-common.docs |4 +- include/openvswitch/ofp-util.h |2 +- lib/ofp-util.c |2 +- ofproto/ofproto-tnl-unixctl.man |2 +- ovn/CONTAINERS.OpenStack.md |4 +- ovn/controller/pinctrl.c|2 +- ovn/ovn-architecture.7.xml |8 +- ovn/ovn-sb.xml |2 +- rhel/openvswitch-fedora.spec.in |4 +- rhel/openvswitch.spec.in|4 +- tests/run-oftest|2 +- tests/run-ryu |2 +- tutorial/ovs-sandbox|2 +- utilities/ovs-ctl.8 |2 +- utilities/ovs-dev.py|2 +- utilities/ovs-sim.1.xml |2 +- utilities/ovs-sim.in|4 +- 50 files changed, 6099 insertions(+), 5707 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst delete mode 100644 CodingStyle.md create mode 100644 CodingStyle.rst delete mode 100644 DESIGN.md create mode 100644 DESIGN.rst delete mode 100644 FAQ.md create mode 100644 FAQ.rst delete mode 100644 IntegrationGuide.md create mode 100644 IntegrationGuide.rst delete mode 100644 MAINTAINERS.md create mode 100644 MAINTAINERS.rst delete mode 100644 OPENFLOW-1.1+.md create mode 100644 OPENFLOW.rst delete mode 100644 PORTING.md create mode 100644 PORTING.rst delete mode 100644 README-lisp.md create mode 100644 README-lisp.rst delete mode 100644 README-native-tunneling.md create mode 100644 README-native-tunneling.rst delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 REPORTING-BUGS.md create mode 100644 REPORTING-BUGS.rst rename SECURITY.md => SECURITY.rst (55%) delete mode 100644 WHY-OVS.md create mode 100644 WHY-OVS.rst -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 01/15] doc: Convert CodingStyle to rST
Signed-off-by: Stephen Finucane
---
CONTRIBUTING.md | 4 +-
CodingStyle.md | 578 -
CodingStyle.rst | 642 +++
Makefile.am | 4 +-
OPENFLOW-1.1+.md | 6 +-
5 files changed, 649 insertions(+), 585 deletions(-)
delete mode 100644 CodingStyle.md
create mode 100644 CodingStyle.rst
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9d9f035..f848536 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -366,7 +366,7 @@ If you cannot convince your email client not to mangle
patches, then
sending the patch as an attachment is a second choice.
Please follow the style used in the code that you are modifying. The
-[CodingStyle.md] file describes the coding style used in most of Open
+[CodingStyle] file describes the coding style used in most of Open
vSwitch. Use Linux kernel coding style for Linux kernel code.
If your code is non-datapath code, you may use the
@@ -411,4 +411,4 @@ index fdd952e..f6cb88e 100644
```
[INSTALL.rst]:INSTALL.rst
-[CodingStyle.md]:CodingStyle.md
+[CodingStyle]: CodingStyle.rst
diff --git a/CodingStyle.md b/CodingStyle.md
deleted file mode 100644
index 0a441e0..000
--- a/CodingStyle.md
+++ /dev/null
@@ -1,578 +0,0 @@
-Open vSwitch Coding Style
-=
-
-This file describes the coding style used in most C files in the Open
-vSwitch distribution. However, Linux kernel code datapath directory
-follows the Linux kernel's established coding conventions. For the
-Windows kernel datapath code, use the coding style described in
-datapath-windows/CodingStyle.
-
-The following GNU indent options approximate this style:
-
--npro -bad -bap -bbb -br -blf -brs -cdw -ce -fca -cli0 -npcs -i4 -l79 \
--lc79 -nbfda -nut -saf -sai -saw -sbi4 -sc -sob -st -ncdb -pi4 -cs -bs \
--di1 -lp -il0 -hnl
-
-
-## BASICS
-
- Limit lines to 79 characters.
-
- Use form feeds (control+L) to divide long source files into logical
-pieces. A form feed should appear as the only character on a line.
-
- Do not use tabs for indentation.
-
- Avoid trailing spaces on lines.
-
-
-## NAMING
-
- - Use names that explain the purpose of a function or object.
-
- - Use underscores to separate words in an identifier: multi_word_name.
-
- - Use lowercase for most names. Use uppercase for macros, macro
-parameters, and members of enumerations.
-
- - Give arrays names that are plural.
-
- - Pick a unique name prefix (ending with an underscore) for each
-module, and apply that prefix to all of that module's externally
-visible names. Names of macro parameters, struct and union members,
-and parameters in function prototypes are not considered externally
-visible for this purpose.
-
- - Do not use names that begin with _. If you need a name for
-"internal use only", use __ as a suffix instead of a prefix.
-
- - Avoid negative names: "found" is a better name than "not_found".
-
- - In names, a "size" is a count of bytes, a "length" is a count of
-characters. A buffer has size, but a string has length. The length
-of a string does not include the null terminator, but the size of the
-buffer that contains the string does.
-
-
-## COMMENTS
-
- Comments should be written as full sentences that start with a
-capital letter and end with a period. Put two spaces between
-sentences.
-
- Write block comments as shown below. You may put the /* and */ on
-the same line as comment text if you prefer.
-
-/*
- * We redirect stderr to /dev/null because we often want to remove all
- * traffic control configuration on a port so its in a known state. If
- * this done when there is no such configuration, tc complains, so we just
- * always ignore it.
- */
-
- Each function and each variable declared outside a function, and
-each struct, union, and typedef declaration should be preceded by a
-comment. See FUNCTION DEFINITIONS below for function comment
-guidelines.
-
- Each struct and union member should each have an inline comment that
-explains its meaning. structs and unions with many members should be
-additionally divided into logical groups of members by block comments,
-e.g.:
-
-/* An event that will wake the following call to poll_block(). */
-struct poll_waiter {
-/* Set when the waiter is created. */
-struct ovs_list node; /* Element in global waiters list. */
-int fd; /* File descriptor. */
-short int events; /* Events to wait for (POLLIN, POLLOUT). */
-poll_fd_func *function; /* Callback function, if any, or null. */
-void *aux; /* Argument to callback function. */
-struct backtrace *backtrace; /* Event that created waiter, or null. */
-
-/* Set only when poll_block() is called. */
-struct pol
[ovs-dev] [PATCH 02/15] doc: Convert IntegrationGuide to rST
Signed-off-by: Stephen Finucane
---
IntegrationGuide.md | 169 --
IntegrationGuide.rst| 195
Makefile.am | 2 +-
ovn/CONTAINERS.OpenStack.md | 4 +-
ovn/ovn-architecture.7.xml | 6 +-
ovn/ovn-sb.xml | 2 +-
6 files changed, 202 insertions(+), 176 deletions(-)
delete mode 100644 IntegrationGuide.md
create mode 100644 IntegrationGuide.rst
diff --git a/IntegrationGuide.md b/IntegrationGuide.md
deleted file mode 100644
index 5d3e574..000
--- a/IntegrationGuide.md
+++ /dev/null
@@ -1,169 +0,0 @@
-Integration Guide for Centralized Control
-=
-
-This document describes how to integrate Open vSwitch onto a new
-platform to expose the state of the switch and attached devices for
-centralized control. (If you are looking to port the switching
-components of Open vSwitch to a new platform, please see the PORTING
-document.) The focus of this guide is on hypervisors, but many of the
-interfaces are useful for hardware switches, as well. The XenServer
-integration is the most mature implementation, so most of the examples
-are drawn from it.
-
-The externally visible interface to this integration is
-platform-agnostic. We encourage anyone who integrates Open vSwitch to
-use the same interface, because keeping a uniform interface means that
-controllers require less customization for individual platforms (and
-perhaps no customization at all).
-
-Integration centers around the Open vSwitch database and mostly involves
-the 'external_ids' columns in several of the tables. These columns are
-not interpreted by Open vSwitch itself. Instead, they provide
-information to a controller that permits it to associate a database
-record with a more meaningful entity. In contrast, the 'other_config'
-column is used to configure behavior of the switch. The main job of the
-integrator, then, is to ensure that these values are correctly populated
-and maintained.
-
-An integrator sets the columns in the database by talking to the
-ovsdb-server daemon. A few of the columns can be set during startup by
-calling the ovs-ctl tool from inside the startup scripts. The
-'xenserver/etc_init.d_openvswitch' script provides examples of its use,
-and the ovs-ctl(8) manpage contains complete documentation. At runtime,
-ovs-vsctl can be be used to set columns in the database. The script
-'xenserver/etc_xensource_scripts_vif' contains examples of its use, and
-ovs-vsctl(8) manpage contains complete documentation.
-
-Python and C bindings to the database are provided if deeper integration
-with a program are needed. The XenServer ovs-xapi-sync daemon
-('xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync') provides an
-example of using the Python bindings. More information on the python
-bindings is available at 'python/ovs/db/idl.py'. Information on the C
-bindings is available at 'lib/ovsdb-idl.h'.
-
-The following diagram shows how integration scripts fit into the Open vSwitch
-architecture:
-
-++
-| Controller Cluster +
-++
-|
-|
- +--+
- || |
- | +--+---+ |
- | | | |
- | +---+ +--+ |
- | | ovsdb-server|---| ovs-vswitchd | |
- | +---+ +--+ |
- | | | |
- | +-+ | |
- | | Integration scripts | | |
- | | (ex: ovs-xapi-sync) | | |
- | +-+ | |
- || Userspace |
- |--|
- || Kernel |
- || |
- | +-+ |
- | | OVS Kernel Module | |
- | +-+ |
- +--+
-
-
-A description of the most relevant fields for integration follows. By
-setting these values, controllers are able to understand the network and
-manage it more dynamically an
[ovs-dev] [PATCH 04/15] doc: Convert PORTING to rST
Signed-off-by: Stephen Finucane --- FAQ.md| 4 +- INSTALL.NetBSD.md | 4 +- Makefile.am | 2 +- PORTING.md| 326 - PORTING.rst | 330 ++ 5 files changed, 335 insertions(+), 331 deletions(-) delete mode 100644 PORTING.md create mode 100644 PORTING.rst diff --git a/FAQ.md b/FAQ.md index cfa5e70..9ab5210 100644 --- a/FAQ.md +++ b/FAQ.md @@ -75,7 +75,7 @@ A: No, Open vSwitch has been ported to a number of different operating ### Q: What's involved with porting Open vSwitch to a new platform or switching ASIC? -A: The [PORTING.md] document describes how one would go about +A: The [PORTING.rst] document describes how one would go about porting Open vSwitch to a new operating system or hardware platform. ### Q: Why would I use Open vSwitch instead of the Linux bridge? @@ -2149,7 +2149,7 @@ Contact b...@openvswitch.org http://openvswitch.org/ -[PORTING.md]:PORTING.md +[PORTING.rst]:PORTING.rst [WHY-OVS.md]:WHY-OVS.md [INSTALL.rst]:INSTALL.rst [OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md diff --git a/INSTALL.NetBSD.md b/INSTALL.NetBSD.md index 3002bad..b89201a 100644 --- a/INSTALL.NetBSD.md +++ b/INSTALL.NetBSD.md @@ -31,8 +31,8 @@ As all executables installed with pkgsrc are placed in `/usr/pkg/bin/` directory, it might be a good idea to add it to your PATH. Open vSwitch on NetBSD is currently "userspace switch" implementation -in the sense described in [INSTALL.userspace.rst] and [PORTING.md]. +in the sense described in [INSTALL.userspace.rst] and [PORTING.rst]. [INSTALL.rst]:INSTALL.rst [INSTALL.userspace.rst]:INSTALL.userspace.rst -[PORTING.md]:PORTING.md +[PORTING.rst]:PORTING.rst diff --git a/Makefile.am b/Makefile.am index 5e55650..73e94ba 100644 --- a/Makefile.am +++ b/Makefile.am @@ -88,7 +88,7 @@ docs = \ IntegrationGuide.rst \ MAINTAINERS.rst \ OPENFLOW-1.1+.md \ - PORTING.md \ + PORTING.rst \ README.md \ README-lisp.md \ README-native-tunneling.md \ diff --git a/PORTING.md b/PORTING.md deleted file mode 100644 index b7a5073..000 --- a/PORTING.md +++ /dev/null @@ -1,326 +0,0 @@ -How to Port Open vSwitch to New Software or Hardware - - -Open vSwitch (OVS) is intended to be easily ported to new software and -hardware platforms. This document describes the types of changes that -are most likely to be necessary in porting OVS to Unix-like platforms. -(Porting OVS to other kinds of platforms is likely to be more -difficult.) - - -Vocabulary --- - -For historical reasons, different words are used for essentially the -same concept in different areas of the Open vSwitch source tree. Here -is a concordance, indexed by the area of the source tree: - -datapath/ vport --- -vswitchd/ iface port -ofproto/portbundle -ofproto/bond.c slave bond -lib/lacp.c slave lacp -lib/netdev.cnetdev --- -databaseInterface Port - - -Open vSwitch Architectural Overview - -The following diagram shows the very high-level architecture of Open -vSwitch from a porter's perspective. - - +---+ - |ovs-vswitchd |<-->ovsdb-server - +---+ - | ofproto |<-->OpenFlow controllers - ++-++ - | netdev | | ofproto| - ++ |provider| - | netdev | ++ - |provider| - ++ - -Some of the components are generic. Modulo bugs or inadequacies, -these components should not need to be modified as part of a port: - - - "ovs-vswitchd" is the main Open vSwitch userspace program, in -vswitchd/. It reads the desired Open vSwitch configuration from -the ovsdb-server program over an IPC channel and passes this -configuration down to the "ofproto" library. It also passes -certain status and statistical information from ofproto back -into the database. - - - "ofproto" is the Open vSwitch library, in ofproto/, that -implements an OpenFlow switch. It talks to OpenFlow controllers -over the network and to switch hardware or software through an -"ofproto provider", explained further below. - - - "netdev" is the Open vSwitch library, in lib/netdev.c, that -abstracts interacting with network devices, that is, Ethernet -interfaces. The netdev library is a thin layer over "netdev -provider" code, explained further below. - -The other components may need attention during a port. You will -almost ce
[ovs-dev] [PATCH 03/15] doc: Convert MAINTAINERS to rST
Signed-off-by: Stephen Finucane --- MAINTAINERS.md | 29 -- MAINTAINERS.rst | 75 + Makefile.am | 2 +- 3 files changed, 76 insertions(+), 30 deletions(-) delete mode 100644 MAINTAINERS.md create mode 100644 MAINTAINERS.rst diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 9af6c89..000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,29 +0,0 @@ -Committers --- - -OVS committers are the people who have been granted access to push changes to -to the OVS git repository. The responsibilities of an OVS committer are -documented in -[committer-responsibilities.md](./Documentation/committer-responsibilities.md). - -The process for adding or removing committers is in -[committer-grant-revocation.md](./Documentation/committer-grant-revocation.md). - -This is the current list of OVS committers: - -Alex Wang ee07b...@gmail.com -Andy Zhou az...@ovn.org -Ansis Attekaaatt...@nicira.com -Ben Pfaff b...@ovn.org -Daniele Di Proietto daniele.di.proie...@gmail.com -Ethan J. Jacksone...@eecs.berkeley.edu -Gurucharan Shetty g...@ovn.org -Jarno Rajahalme ja...@ovn.org -Jesse Gross je...@kernel.org -Joe Stringerj...@ovn.org -Justin Pettit jpet...@ovn.org -Pravin B Shelar pshe...@nicira.com -Russell Bryant russ...@ovn.org -Simon Hormanho...@ovn.org -Thomas Graf tg...@noironetworks.com -YAMAMOTO Takashiyamam...@midokura.com diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst new file mode 100644 index 000..34f4e7b --- /dev/null +++ b/MAINTAINERS.rst @@ -0,0 +1,75 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +== +Committers +== + +Open vSwitch committers are the people who have been granted access to push +changes to to the Open vSwitch git repository. + +The responsibilities of an Open vSwitch committer are documented +`here `__. + +The process for adding or removing committers is documented +`here `__. + +This is the current list of Open vSwitch committers: + +.. list-table:: OVS Maintainers + :header-rows: 1 + + * - Name + - Email + * - Alex Wang + - ee07b...@gmail.com + * - Andy Zhou + - az...@ovn.org + * - Ansis Atteka + - aatt...@nicira.com + * - Ben Pfaff + - b...@ovn.org + * - Daniele Di Proietto + - daniele.di.proie...@gmail.com + * - Ethan J. Jackson + - e...@eecs.berkeley.edu + * - Gurucharan Shetty + - g...@ovn.org + * - Jarno Rajahalme + - ja...@ovn.org + * - Jesse Gross + - je...@kernel.org + * - Joe Stringer + - j...@ovn.org + * - Justin Pettit + - jpet...@ovn.org + * - Pravin B Shelar + - pshe...@nicira.com + * - Russell Bryant + - russ...@ovn.org + * - Simon Horman + - ho...@ovn.org + * - Thomas Graf + - tg...@noironetworks.com + * - YAMAMOTO Takashi + - yamam...@midokura.com diff --git a/Makefile.am b/Makefile.am index 5f0cdd8..5e55650 100644 --- a/Makefile.am +++ b/Makefile.am @@ -86,7 +86,7 @@ docs = \ INSTALL.userspace.rst \ INSTALL.Windows.rst \ IntegrationGuide.rst \ - MAINTAINERS.md \ + MAINTAINERS.rst \ OPENFLOW-1.1+.md \ PORTING.md \ README.md \ -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 05/15] doc: Convert README to rST
Signed-off-by: Stephen Finucane --- INSTALL.rst | 2 +- Makefile.am | 2 +- README.md | 131 README.rst | 116 +++ rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- utilities/ovs-ctl.8 | 2 +- 7 files changed, 121 insertions(+), 136 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/INSTALL.rst b/INSTALL.rst index 07d69f1..055f201 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -85,7 +85,7 @@ use the userspace-only implementation, at some cost in features and performance To compile the kernel module on Linux, you must also install the following: -- A supported Linux kernel version. Refer to the `README `__ +- A supported Linux kernel version. Refer to the `README `__ for a list of supported versions. For optional support of ingress policing, you must enable kernel diff --git a/Makefile.am b/Makefile.am index 73e94ba..6117ca8 100644 --- a/Makefile.am +++ b/Makefile.am @@ -89,7 +89,7 @@ docs = \ MAINTAINERS.rst \ OPENFLOW-1.1+.md \ PORTING.rst \ - README.md \ + README.rst \ README-lisp.md \ README-native-tunneling.md \ REPORTING-BUGS.md \ diff --git a/README.md b/README.md deleted file mode 100644 index f824581..000 --- a/README.md +++ /dev/null @@ -1,131 +0,0 @@ -Open vSwitch - - -Build Status: -- - -[](https://travis-ci.org/openvswitch/ovs) - -What is Open vSwitch? -- - -Open vSwitch is a multilayer software switch licensed under the open -source Apache 2 license. Our goal is to implement a production -quality switch platform that supports standard management interfaces -and opens the forwarding functions to programmatic extension and -control. - -Open vSwitch is well suited to function as a virtual switch in VM -environments. In addition to exposing standard control and visibility -interfaces to the virtual networking layer, it was designed to support -distribution across multiple physical servers. Open vSwitch supports -multiple Linux-based virtualization technologies including -Xen/XenServer, KVM, and VirtualBox. - -The bulk of the code is written in platform-independent C and is -easily ported to other environments. The current release of Open -vSwitch supports the following features: - -* Standard 802.1Q VLAN model with trunk and access ports -* NIC bonding with or without LACP on upstream switch -* NetFlow, sFlow(R), and mirroring for increased visibility -* QoS (Quality of Service) configuration, plus policing -* Geneve, GRE, VXLAN, STT, and LISP tunneling -* 802.1ag connectivity fault management -* OpenFlow 1.0 plus numerous extensions -* Transactional configuration database with C and Python bindings -* High-performance forwarding using a Linux kernel module - -The included Linux kernel module supports Linux 3.10 and up. - -Open vSwitch can also operate, at a cost in performance, entirely in -userspace, without assistance from a kernel module. This userspace -implementation should be easier to port than the kernel-based switch. -It is considered experimental. - -What's here? - - -The main components of this distribution are: - -* ovs-vswitchd, a daemon that implements the switch, along with - a companion Linux kernel module for flow-based switching. -* ovsdb-server, a lightweight database server that ovs-vswitchd - queries to obtain its configuration. -* ovs-dpctl, a tool for configuring the switch kernel module. -* Scripts and specs for building RPMs for Citrix XenServer and Red - Hat Enterprise Linux. The XenServer RPMs allow Open vSwitch to - be installed on a Citrix XenServer host as a drop-in replacement - for its switch, with additional functionality. -* ovs-vsctl, a utility for querying and updating the configuration - of ovs-vswitchd. -* ovs-appctl, a utility that sends commands to running Open - vSwitch daemons. - -Open vSwitch also provides some tools: - -* ovs-ofctl, a utility for querying and controlling OpenFlow - switches and controllers. -* ovs-pki, a utility for creating and managing the public-key - infrastructure for OpenFlow switches. -* ovs-testcontroller, a simple OpenFlow controller that may be useful - for testing (though not for production). -* A patch to tcpdump that enables it to parse OpenFlow messages. - -What other documentation is available? --- - -To install Open vSwitch on a regular Linux or FreeBSD host, please -read [INSTALL.rst]. For specifics around installation on a specific -platform, please see one of these files: - -- [INSTALL.Debian.rst] -- [INSTALL.Fedora.md] -- [INSTALL.RHEL.md] -- [INSTALL.XenServer.rst] - -To use Open vSwitch... - -- ...with Docker on Linux,
[ovs-dev] [PATCH 06/15] doc: Convert REPORTING-BUGS to rST
Signed-off-by: Stephen Finucane --- Makefile.am| 2 +- REPORTING-BUGS.md | 58 --- REPORTING-BUGS.rst | 73 ++ SECURITY.md| 2 +- 4 files changed, 75 insertions(+), 60 deletions(-) delete mode 100644 REPORTING-BUGS.md create mode 100644 REPORTING-BUGS.rst diff --git a/Makefile.am b/Makefile.am index 6117ca8..dc92b71 100644 --- a/Makefile.am +++ b/Makefile.am @@ -92,7 +92,7 @@ docs = \ README.rst \ README-lisp.md \ README-native-tunneling.md \ - REPORTING-BUGS.md \ + REPORTING-BUGS.rst \ SECURITY.md \ WHY-OVS.md EXTRA_DIST = \ diff --git a/REPORTING-BUGS.md b/REPORTING-BUGS.md deleted file mode 100644 index c046af9..000 --- a/REPORTING-BUGS.md +++ /dev/null @@ -1,58 +0,0 @@ -Reporting Bugs in Open vSwitch -== - -We are eager to hear from users about problems that they have -encountered with Open vSwitch. This file documents how best to report -bugs so as to ensure that they can be fixed as quickly as possible. - -Please report bugs by sending email to b...@openvswitch.org. - -For reporting security vulnerabilities, please read SECURITY.md. - -The most important parts of your bug report are the following: - - * What you did that make the problem appear. - - * What you expected to happen. - - * What actually happened. - -Please also include the following information: - - * The Open vSwitch version number (as output by `ovs-vswitchd ---version`). - - * The Git commit number (as output by `git rev-parse HEAD`), -if you built from a Git snapshot. - - * Any local patches or changes you have applied (if any). - -The following are also handy sometimes: - - * The kernel version on which Open vSwitch is running (from -`/proc/version`) and the distribution and version number of -your OS (e.g. "Centos 5.0"). - - * The contents of the vswitchd configuration database (usually -`/etc/openvswitch/conf.db`). - - * The output of `ovs-dpctl show`. - - * If you have Open vSwitch configured to connect to an -OpenFlow controller, the output of `ovs-ofctl show ` -for each `` configured in the vswitchd configuration -database. - - * A fix or workaround, if you have one. - - * Any other information that you think might be relevant. - -b...@openvswitch.org is a public mailing list, to which anyone can -subscribe, so please do not include confidential information in your -bug report. - -Contact - -b...@openvswitch.org -http://openvswitch.org/ diff --git a/REPORTING-BUGS.rst b/REPORTING-BUGS.rst new file mode 100644 index 000..73e0df3 --- /dev/null +++ b/REPORTING-BUGS.rst @@ -0,0 +1,73 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +== +Reporting Bugs in Open vSwitch +== + +We are eager to hear from users about problems that they have encountered with +Open vSwitch. This file documents how best to report bugs so as to ensure that +they can be fixed as quickly as possible. + +Please report bugs by sending email to b...@openvswitch.org. + +For reporting security vulnerabilities, please read SECURITY.md. + +The most important parts of your bug report are the following: + +- What you did that make the problem appear. + +- What you expected to happen. + +- What actually happened. + +Please also include the following information: + +- The Open vSwitch version number (as output by ``ovs-vswitchd --version``). + +- The Git commit number (as output by ``git rev-parse HEAD``), if you built + from a Git snapshot. + +- Any local patches or changes you have applied (if any). + +The following are also handy sometimes: + +- The kernel version on which Open vSwitch is running (from ``/proc/version``) + and the distribution and version number of your OS (e.g. "Centos 5.0"). + +- The contents of the vswitchd configuration database (usually + ``/etc/openvswitch/conf.db``). + +- The output of ``ovs-dpctl show``. + +- If yo
[ovs-dev] [PATCH 07/15] doc: Convert WHY-OVS to rST
Signed-off-by: Stephen Finucane --- FAQ.md | 4 +- Makefile.am | 2 +- WHY-OVS.md | 106 - WHY-OVS.rst | 128 rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- tests/run-oftest| 2 +- tests/run-ryu | 2 +- tutorial/ovs-sandbox| 2 +- utilities/ovs-dev.py| 2 +- utilities/ovs-sim.in| 4 +- 11 files changed, 139 insertions(+), 117 deletions(-) delete mode 100644 WHY-OVS.md create mode 100644 WHY-OVS.rst diff --git a/FAQ.md b/FAQ.md index 9ab5210..420e40e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -83,7 +83,7 @@ A: The [PORTING.rst] document describes how one would go about A: Open vSwitch is specially designed to make it easier to manage VM network configuration and monitor state spread across many physical hosts in dynamic virtualized environments. Please see - [WHY-OVS.md] for a more detailed description of how Open vSwitch + [WHY-OVS.rst] for a more detailed description of how Open vSwitch relates to the Linux Bridge. ### Q: How is Open vSwitch related to distributed virtual switches like the VMware vNetwork distributed switch or the Cisco Nexus 1000V? @@ -2150,7 +2150,7 @@ b...@openvswitch.org http://openvswitch.org/ [PORTING.rst]:PORTING.rst -[WHY-OVS.md]:WHY-OVS.md +[WHY-OVS.rst]:WHY-OVS.rst [INSTALL.rst]:INSTALL.rst [OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md [INSTALL.DPDK.rst]:INSTALL.DPDK.rst diff --git a/Makefile.am b/Makefile.am index dc92b71..9373a04 100644 --- a/Makefile.am +++ b/Makefile.am @@ -94,7 +94,7 @@ docs = \ README-native-tunneling.md \ REPORTING-BUGS.rst \ SECURITY.md \ - WHY-OVS.md + WHY-OVS.rst EXTRA_DIST = \ $(docs) \ NOTICE \ diff --git a/WHY-OVS.md b/WHY-OVS.md deleted file mode 100644 index d31e69e..000 --- a/WHY-OVS.md +++ /dev/null @@ -1,106 +0,0 @@ -Why Open vSwitch? -= - -Hypervisors need the ability to bridge traffic between VMs and with the -outside world. On Linux-based hypervisors, this used to mean using the -built-in L2 switch (the Linux bridge), which is fast and reliable. So, -it is reasonable to ask why Open vSwitch is used. - -The answer is that Open vSwitch is targeted at multi-server -virtualization deployments, a landscape for which the previous stack is -not well suited. These environments are often characterized by highly -dynamic end-points, the maintenance of logical abstractions, and -(sometimes) integration with or offloading to special purpose switching -hardware. - -The following characteristics and design considerations help Open -vSwitch cope with the above requirements. - -* The mobility of state: All network state associated with a network - entity (say a virtual machine) should be easily identifiable and - migratable between different hosts. This may include traditional - "soft state" (such as an entry in an L2 learning table), L3 forwarding - state, policy routing state, ACLs, QoS policy, monitoring - configuration (e.g. NetFlow, IPFIX, sFlow), etc. - - Open vSwitch has support for both configuring and migrating both slow - (configuration) and fast network state between instances. For - example, if a VM migrates between end-hosts, it is possible to not - only migrate associated configuration (SPAN rules, ACLs, QoS) but any - live network state (including, for example, existing state which - may be difficult to reconstruct). Further, Open vSwitch state is - typed and backed by a real data-model allowing for the development of - structured automation systems. - -* Responding to network dynamics: Virtual environments are often - characterized by high-rates of change. VMs coming and going, VMs - moving backwards and forwards in time, changes to the logical network - environments, and so forth. - - Open vSwitch supports a number of features that allow a network - control system to respond and adapt as the environment changes. - This includes simple accounting and visibility support such as - NetFlow, IPFIX, and sFlow. But perhaps more useful, Open vSwitch - supports a network state database (OVSDB) that supports remote - triggers. Therefore, a piece of orchestration software can "watch" - various aspects of the network and respond if/when they change. - This is used heavily today, for example, to respond to and track VM - migrations. - - Open vSwitch also supports OpenFlow as a method of exporting remote - access to control traffic. There are a number of uses for this - including global network discovery through inspection of discovery - or link-state traffic (e.g. LLDP, CDP, OSPF, etc.). - -* Maintenance of logical tags: Distributed virtual switches (such as - VMware vDS and Cisco's Nexus 1000V) often maintain logical cont
[ovs-dev] [PATCH 09/15] doc: Convert README-lisp to rST
Signed-off-by: Stephen Finucane --- Makefile.am | 2 +- README-lisp.md | 81 README-lisp.rst | 113 3 files changed, 114 insertions(+), 82 deletions(-) delete mode 100644 README-lisp.md create mode 100644 README-lisp.rst diff --git a/Makefile.am b/Makefile.am index 9be391b..42ad5d0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -90,7 +90,7 @@ docs = \ OPENFLOW-1.1+.md \ PORTING.rst \ README.rst \ - README-lisp.md \ + README-lisp.rst \ README-native-tunneling.md \ REPORTING-BUGS.rst \ SECURITY.rst \ diff --git a/README-lisp.md b/README-lisp.md deleted file mode 100644 index f1e1172..000 --- a/README-lisp.md +++ /dev/null @@ -1,81 +0,0 @@ -Using LISP tunneling - - -LISP is a layer 3 tunneling mechanism, meaning that encapsulated packets do -not carry Ethernet headers, and ARP requests shouldn't be sent over the -tunnel. Because of this, there are some additional steps required for setting -up LISP tunnels in Open vSwitch, until support for L3 tunnels will improve. - -This guide assumes tunneling between two VMs connected to OVS bridges on -different hypervisors reachable over IPv4. Of course, more than one VM may be -connected to any of the hypervisors, and a hypervisor may communicate with -several different hypervisors over the same lisp tunneling interface. A LISP -"map-cache" can be implemented using flows, see example at the bottom of this -file. - -There are several scenarios: - - 1) the VMs have IP addresses in the same subnet and the hypervisors are also - in a single subnet (although one different from the VM's); - 2) the VMs have IP addresses in the same subnet but the hypervisors are - separated by a router; - 3) the VMs are in different subnets. - -In cases 1) and 3) ARP resolution can work as normal: ARP traffic is -configured not to go through the LISP tunnel. For case 1) ARP is able to -reach the other VM, if both OVS instances default to MAC address learning. -Case 3) requires the hypervisor be configured as the default router for the -VMs. - -In case 2) the VMs expect ARP replies from each other, but this is not -possible over a layer 3 tunnel. One solution is to have static MAC address -entries preconfigured on the VMs (e.g., `arp -f /etc/ethers` on startup on -Unix based VMs), or have the hypervisor do proxy ARP. In this scenario, the -eth0 interfaces need not be added to the br0 bridge in the examples below. - -On the receiving side, the packet arrives without the original MAC header. -The LISP tunneling code attaches a header with harcoded source and destination -MAC address 02:00:00:00:00:00. This address has all bits set to 0, except the -locally administered bit, in order to avoid potential collisions with existing -allocations. In order for packets to reach their intended destination, the -destination MAC address needs to be rewritten. This can be done using the -flow table. - -See below for an example setup, and the associated flow rules to enable LISP -tunneling. - - +---+ +---+ - |VM1| |VM2| - +---+ +---+ - | | -+--[tap0]--+ +--[tap0]---+ -| | | | -[lisp0] OVS1 [eth0]-[eth0] OVS2 [lisp0] -| | | | -+--+ +---+ - -On each hypervisor, interfaces tap0, eth0, and lisp0 are added to a single -bridge instance, and become numbered 1, 2, and 3 respectively: - -ovs-vsctl add-br br0 -ovs-vsctl add-port br0 tap0 -ovs-vsctl add-port br0 eth0 -ovs-vsctl add-port br0 lisp0 -- set Interface lisp0 type=lisp options:remote_ip=flow options:key=flow - -The last command sets up flow based tunneling on the lisp0 interface. From -the LISP point of view, this is like having the Tunnel Router map cache -implemented as flow rules. - -Flows on br0 should be configured as follows: - -priority=3,dl_dst=02:00:00:00:00:00,action=mod_dl_dst:,output:1 -priority=2,in_port=1,dl_type=0x0806,action=NORMAL - priority=1,in_port=1,dl_type=0x0800,vlan_tci=0,nw_src=,action=set_field:->tun_dst,output:3 -priority=0,action=NORMAL - -The third rule is like a map cache entry: the specified by the -nw_src match field is mapped to the RLOC , which is set as the tunnel -destination for this particular flow. - -Optionally, if you want to use Instance ID in a flow, you can add -"set_tunnel:" to the action list. diff --git a/README-lisp.rst b/README-lisp.rst new file mode 100644 index 000..a65a694 --- /dev/null +++ b/README-lisp.rst @@ -0,0 +1,113 @@ +.. +
[ovs-dev] [PATCH 08/15] doc: Convert SECURITY to rST
This is a top-level document, so plain old rST is preferred. Signed-off-by: Stephen Finucane --- Makefile.am | 2 +- REPORTING-BUGS.rst | 2 +- SECURITY.md => SECURITY.rst | 198 +--- 3 files changed, 95 insertions(+), 107 deletions(-) rename SECURITY.md => SECURITY.rst (55%) diff --git a/Makefile.am b/Makefile.am index 9373a04..9be391b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -93,7 +93,7 @@ docs = \ README-lisp.md \ README-native-tunneling.md \ REPORTING-BUGS.rst \ - SECURITY.md \ + SECURITY.rst \ WHY-OVS.rst EXTRA_DIST = \ $(docs) \ diff --git a/REPORTING-BUGS.rst b/REPORTING-BUGS.rst index 73e0df3..85b60ea 100644 --- a/REPORTING-BUGS.rst +++ b/REPORTING-BUGS.rst @@ -31,7 +31,7 @@ they can be fixed as quickly as possible. Please report bugs by sending email to b...@openvswitch.org. -For reporting security vulnerabilities, please read SECURITY.md. +For reporting security vulnerabilities, please read SECURITY.rst. The most important parts of your bug report are the following: diff --git a/SECURITY.md b/SECURITY.rst similarity index 55% rename from SECURITY.md rename to SECURITY.rst index 4cc4ed6..31155a5 100644 --- a/SECURITY.md +++ b/SECURITY.rst @@ -1,23 +1,22 @@ + Security Process -This is a proposed security vulnerability reporting and handling -process for Open vSwitch. It is based on the OpenStack vulnerability -management process described at -https://wiki.openstack.org/wiki/Vulnerability_Management. +This is a proposed security vulnerability reporting and handling process for +Open vSwitch. It is based on the OpenStack vulnerability management process +described at https://wiki.openstack.org/wiki/Vulnerability\_Management. The OVS security team coordinates vulnerability management using the -ovs-security mailing list. Membership in the security team and -subscription to its mailing list consists of a small number of -trustworthy people, as determined by rough consensus of the Open -vSwitch committers on the ovs-committers mailing list. The Open -vSwitch security team should include Open vSwitch committers, to -ensure prompt and accurate vulnerability assessments and patch review. - -We encourage everyone involved in the security process to GPG-sign -their emails. We additionally encourage GPG-encrypting one-on-one -conversations as part of the security process. +ovs-security mailing list. Membership in the security team and subscription to +its mailing list consists of a small number of trustworthy people, as +determined by rough consensus of the Open vSwitch committers on the +ovs-committers mailing list. The Open vSwitch security team should include Open +vSwitch committers, to ensure prompt and accurate vulnerability assessments and +patch review. +We encourage everyone involved in the security process to GPG-sign their +emails. We additionally encourage GPG-encrypting one-on-one conversations as +part of the security process. What is a vulnerability? @@ -25,92 +24,87 @@ What is a vulnerability? All vulnerabilities are bugs, but not every bug is a vulnerability. Vulnerabilities compromise one or more of: -* Confidentiality (personal or corporate confidential data). -* Integrity (trustworthiness and correctness). -* Availability (uptime and service). +* Confidentiality (personal or corporate confidential data). + +* Integrity (trustworthiness and correctness). -Here are some examples of vulnerabilities to which one would expect to -apply this process: +* Availability (uptime and service). -* A crafted packet that causes a kernel or userspace crash - (Availability). +Here are some examples of vulnerabilities to which one would expect to apply +this process: -* A flow translation bug that misforwards traffic in a way likely - to hop over security boundaries (Integrity). +* A crafted packet that causes a kernel or userspace crash (Availability). -* An OpenFlow protocol bug that allows a controller to read - arbitrary files from the file system (Confidentiality). +* A flow translation bug that misforwards traffic in a way likely to hop over + security boundaries (Integrity). -* Misuse of the OpenSSL library that allows bypassing certificate - checks (Integrity). +* An OpenFlow protocol bug that allows a controller to read arbitrary files + from the file system (Confidentiality). -* A bug (memory corruption, overflow, ...) that allows one to - modify the behaviour of OVS through external configuration - interfaces such as OVSDB (Integrity). +* Misuse of the OpenSSL library that allows bypassing certificate checks + (Integrity). -* Privileged information is exposed to unprivileged users - (Confidentiality). +* A bug (memory corruption, overflow, ...) that allows one to modify the + behavi
[ovs-dev] [PATCH 10/15] doc: Convert README-native-tunneling to rST
Signed-off-by: Stephen Finucane --- Makefile.am | 2 +- README-native-tunneling.md | 85 --- README-native-tunneling.rst | 176 debian/openvswitch-common.docs | 2 +- ofproto/ofproto-tnl-unixctl.man | 2 +- rhel/openvswitch.spec.in| 2 +- utilities/ovs-sim.1.xml | 2 +- 7 files changed, 181 insertions(+), 90 deletions(-) delete mode 100644 README-native-tunneling.md create mode 100644 README-native-tunneling.rst diff --git a/Makefile.am b/Makefile.am index 42ad5d0..c1eba48 100644 --- a/Makefile.am +++ b/Makefile.am @@ -91,7 +91,7 @@ docs = \ PORTING.rst \ README.rst \ README-lisp.rst \ - README-native-tunneling.md \ + README-native-tunneling.rst \ REPORTING-BUGS.rst \ SECURITY.rst \ WHY-OVS.rst diff --git a/README-native-tunneling.md b/README-native-tunneling.md deleted file mode 100644 index 985deb3..000 --- a/README-native-tunneling.md +++ /dev/null @@ -1,85 +0,0 @@ -Native Tunneling in Open vSwitch userspace --- - -Open vSwitch supports tunneling in userspace. Tunneling is implemented in -platform independent way. - -Setup: -== -Setup physical bridges for all physical interfaces. Create integration bridge. -Add VXLAN port to int-bridge. Assign IP address to physical bridge where -VXLAN traffic is expected. - -Example: - -Connect to VXLAN tunnel endpoint logical ip: 192.168.1.2 and 192.168.1.1. - -Configure OVS bridges as follows. - -1. Lets assume 172.168.1.2/24 network is reachable via eth1 create physical bridge br-eth1 - assign ip address (172.168.1.1/24) to br-eth1, Add eth1 to br-eth1 -2. Check ovs cached routes using appctl command - ovs-appctl ovs/route/show - Add tunnel route if not present in OVS route table. - ovs-appctl ovs/route/add 172.168.1.1/24 br-eth1 -3. Add integration bridge int-br and add tunnel port using standard syntax. - ovs-vsctl add-port int-br vxlan0 -- set interface vxlan0 type=vxlan options:remote_ip=172.168.1.2 -4. Assign IP address to int-br, So final topology looks like: - - 192.168.1.1/24 -+--+ -|int-br| 192.168.1.2/24 -+--+ +--+ -|vxlan0| |vxlan0 | -+--+ +--+ - | | - | | - | | - 172.168.1.1/24 | -+--+ | -|br-eth1 | 172.168.1.2/24 -+--+ +---+ -|eth1 |--| eth1 | -+--+ +---+ - -Host A with OVS. Remote host. - -With this setup, ping to VXLAN target device (192.168.1.2) should work -There are following commands that shows internal tables: - -Tunneling related commands: -=== -Tunnel routing table: -To Add route: - ovs-appctl ovs/route/add / -To see all routes configured: - ovs-appctl ovs/route/show -To del route: - ovs-appctl ovs/route/del / -To look up and display the route for a destination: - ovs-appctl ovs/route/lookup - -ARP: -To see arp cache content: - ovs-appctl tnl/arp/show -To flush arp cache: - ovs-appctl tnl/arp/flush - -To check tunnel ports listening in vswitchd: - ovs-appctl tnl/ports/show - -To set range for VxLan udp source port: - To set: - ovs-appctl tnl/egress_port_range - Shows Current range: - ovs-appctl tnl/egress_port_range - -To check datapath ports: - ovs-appctl dpif/show - -To check datapath flows: - ovs-appctl dpif/dump-flows - -Contact -=== -b...@openvswitch.org diff --git a/README-native-tunneling.rst b/README-native-tunneling.rst new file mode 100644 index 000..78eee5b --- /dev/null +++ b/README-native-tunneling.rst @@ -0,0 +1,176 @@ +.. + 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
[ovs-dev] [PATCH 15/15] trivial: Resolve whitespace issues with acinclude
Completely unrelated, but annoying. Let's fix it up. Signed-off-by: Stephen Finucane --- acinclude.m4 | 14 +++--- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/acinclude.m4 b/acinclude.m4 index 353519d..40d92ce 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -27,7 +27,7 @@ AC_DEFUN([OVS_ENABLE_WERROR], dnl OVS_CHECK_LINUX dnl -dnl Configure linux kernel source tree +dnl Configure linux kernel source tree AC_DEFUN([OVS_CHECK_LINUX], [ AC_ARG_WITH([linux], [AC_HELP_STRING([--with-linux=/path/to/linux], @@ -298,15 +298,15 @@ AC_DEFUN([OVS_GREP_IFELSE], [ grep '$2' $1 >/dev/null 2>&1 status=$? case $status in - 0) + 0) AC_MSG_RESULT([yes]) m4_if([$3], [], [OVS_DEFINE([HAVE_]m4_toupper([$2]))], [$3]) ;; - 1) + 1) AC_MSG_RESULT([no]) $4 ;; - *) + *) AC_MSG_ERROR([grep exited with status $status]) ;; esac @@ -471,7 +471,7 @@ AC_DEFUN([OVS_CHECK_LINUX_COMPAT], [ [label], [OVS_GREP_IFELSE([$KSRC/include/net/ip_tunnels.h], [iptunnel_pull_offloads], - [OVS_GREP_IFELSE([$KSRC/include/net/dst_cache.h], [dst_cache], +[OVS_GREP_IFELSE([$KSRC/include/net/dst_cache.h], [dst_cache], [OVS_DEFINE([USE_UPSTREAM_TUNNEL])])])]) OVS_GREP_IFELSE([$KSRC/include/linux/net.h], [sock_create_kern.*net], @@ -550,7 +550,7 @@ AC_DEFUN([OVS_CHECK_LINUX_COMPAT], [ [OVS_GREP_IFELSE([$KSRC/include/linux/rtnetlink.h], [rcu_read_lock_held])]) OVS_GREP_IFELSE([$KSRC/include/linux/rtnetlink.h], [lockdep_rtnl_is_held]) - + # Check for the proto_data_valid member in struct sk_buff. The [^@] # is necessary because some versions of this header remove the # member but retain the kerneldoc comment that describes it (which @@ -568,7 +568,7 @@ AC_DEFUN([OVS_CHECK_LINUX_COMPAT], [ [OVS_DEFINE([HAVE_U16_RXHASH])]) OVS_GREP_IFELSE([$KSRC/include/linux/skbuff.h], [skb_dst(], [OVS_DEFINE([HAVE_SKB_DST_ACCESSOR_FUNCS])]) - OVS_GREP_IFELSE([$KSRC/include/linux/skbuff.h], + OVS_GREP_IFELSE([$KSRC/include/linux/skbuff.h], [skb_copy_from_linear_data_offset]) OVS_GREP_IFELSE([$KSRC/include/linux/skbuff.h], [skb_reset_tail_pointer]) -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 13/15] doc: Convert DESIGN to rST
This is a top-level document, so plain old rST is preferred. Signed-off-by: Stephen Finucane --- DESIGN.md | 1093 - DESIGN.rst | 1151 +++ Makefile.am |2 +- include/openvswitch/ofp-util.h |2 +- lib/ofp-util.c |2 +- ovn/controller/pinctrl.c|2 +- ovn/ovn-architecture.7.xml |2 +- rhel/openvswitch-fedora.spec.in |2 +- rhel/openvswitch.spec.in|2 +- 9 files changed, 1158 insertions(+), 1100 deletions(-) delete mode 100644 DESIGN.md create mode 100644 DESIGN.rst diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index a330312..000 --- a/DESIGN.md +++ /dev/null @@ -1,1093 +0,0 @@ -Design Decisions In Open vSwitch - - -This document describes design decisions that went into implementing -Open vSwitch. While we believe these to be reasonable decisions, it is -impossible to predict how Open vSwitch will be used in all environments. -Understanding assumptions made by Open vSwitch is critical to a -successful deployment. The end of this document contains contact -information that can be used to let us know how we can make Open vSwitch -more generally useful. - -Asynchronous Messages -= - -Over time, Open vSwitch has added many knobs that control whether a -given controller receives OpenFlow asynchronous messages. This -section describes how all of these features interact. - -First, a service controller never receives any asynchronous messages -unless it changes its miss_send_len from the service controller -default of zero in one of the following ways: - - - Sending an OFPT_SET_CONFIG message with nonzero miss_send_len. - - - Sending any NXT_SET_ASYNC_CONFIG message: as a side effect, this -message changes the miss_send_len to -OFP_DEFAULT_MISS_SEND_LEN (128) for service controllers. - -Second, OFPT_FLOW_REMOVED and NXT_FLOW_REMOVED messages are generated -only if the flow that was removed had the OFPFF_SEND_FLOW_REM flag -set. - -Third, OFPT_PACKET_IN and NXT_PACKET_IN messages are sent only to -OpenFlow controller connections that have the correct connection ID -(see "struct nx_controller_id" and "struct nx_action_controller"): - - - For packet-in messages generated by a NXAST_CONTROLLER action, -the controller ID specified in the action. - - - For other packet-in messages, controller ID zero. (This is the -default ID when an OpenFlow controller does not configure one.) - -Finally, Open vSwitch consults a per-connection table indexed by the -message type, reason code, and current role. The following table -shows how this table is initialized by default when an OpenFlow -connection is made. An entry labeled "yes" means that the message is -sent, an entry labeled "---" means that the message is suppressed. - -``` - master/ - message and reason code other slave - ---- - OFPT_PACKET_IN / NXT_PACKET_IN -OFPR_NO_MATCH yes --- -OFPR_ACTIONyes --- -OFPR_INVALID_TTL --- --- -OFPR_ACTION_SET (OF1.4+) yes --- -OFPR_GROUP (OF1.4+)yes --- - - OFPT_FLOW_REMOVED / NXT_FLOW_REMOVED -OFPRR_IDLE_TIMEOUT yes --- -OFPRR_HARD_TIMEOUT yes --- -OFPRR_DELETE yes --- -OFPRR_GROUP_DELETE (OF1.4+)yes --- -OFPRR_METER_DELETE (OF1.4+)yes --- -OFPRR_EVICTION (OF1.4+)yes --- - - OFPT_PORT_STATUS -OFPPR_ADD yes yes -OFPPR_DELETE yes yes -OFPPR_MODIFY yes yes - - OFPT_ROLE_REQUEST / OFPT_ROLE_REPLY (OF1.4+) -OFPCRR_MASTER_REQUEST --- --- -OFPCRR_CONFIG --- --- -OFPCRR_EXPERIMENTER--- --- - - OFPT_TABLE_STATUS (OF1.4+) -OFPTR_VACANCY_DOWN --- --- -OFPTR_VACANCY_UP --- --- - - OFPT_REQUESTFORWARD (OF1.4+) -OFPRFR_GROUP_MOD --- --- -OFPRFR_METER_MOD --- --- -``` - -The NXT_SET_ASYNC_CONFIG message directly sets all of the values in -this table for the current connection. The -OFPC_INVALID_TTL_TO_CONTROLLER bit in the OFPT_SET_CONFIG message -controls the setting for OFPR_INVALID_TTL for the "master" role. - - -OFPAT_ENQUEUE -= - -The O
[ovs-dev] [PATCH 12/15] doc: Convert OPENFLOW-1.1+ to rST
Rename it to OPENFLOW. Signed-off-by: Stephen Finucane --- FAQ.md | 4 +- Makefile.am | 2 +- OPENFLOW-1.1+.md | 317 -- OPENFLOW.rst | 415 +++ 4 files changed, 418 insertions(+), 320 deletions(-) delete mode 100644 OPENFLOW-1.1+.md create mode 100644 OPENFLOW.rst diff --git a/FAQ.md b/FAQ.md index 420e40e..19c230c 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1609,7 +1609,7 @@ A: The following table lists the versions of OpenFlow supported by (Open vSwitch 2.2 had an experimental implementation of OpenFlow 1.4 that could cause crashes. We don't recommend enabling it.) - [OPENFLOW-1.1+.md] in the Open vSwitch source tree tracks support for + [OPENFLOW.rst] in the Open vSwitch source tree tracks support for OpenFlow 1.1 and later features. When support for OpenFlow 1.4 and 1.5 is solidly implemented, Open vSwitch will enable those version by default. @@ -2152,7 +2152,7 @@ http://openvswitch.org/ [PORTING.rst]:PORTING.rst [WHY-OVS.rst]:WHY-OVS.rst [INSTALL.rst]:INSTALL.rst -[OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md +[OPENFLOW.rst]:OPENFLOW.rst [INSTALL.DPDK.rst]:INSTALL.DPDK.rst [Tutorial.md]:tutorial/Tutorial.md [release-process.md]:Documentation/release-process.md diff --git a/Makefile.am b/Makefile.am index ba10ee8..f674b7e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -87,7 +87,7 @@ docs = \ INSTALL.Windows.rst \ IntegrationGuide.rst \ MAINTAINERS.rst \ - OPENFLOW-1.1+.md \ + OPENFLOW.rst \ PORTING.rst \ README.rst \ README-lisp.rst \ diff --git a/OPENFLOW-1.1+.md b/OPENFLOW-1.1+.md deleted file mode 100644 index c57b295..000 --- a/OPENFLOW-1.1+.md +++ /dev/null @@ -1,317 +0,0 @@ -OpenFlow 1.1+ support in Open vSwitch -= - -Open vSwitch support for OpenFlow 1.1 and beyond is a work in -progress. This file describes the work still to be done. - -The Plan - - -OpenFlow version support is not a build-time option. A single build -of Open vSwitch must be able to handle all supported versions of -OpenFlow. Ideally, even at runtime it should be able to support all -protocol versions at the same time on different OpenFlow bridges (and -perhaps even on the same bridge). - -At the same time, it would be a shame to litter the core of the OVS -code with lots of ugly code concerned with the details of various -OpenFlow protocol versions. - -The primary approach to compatibility is to abstract most of the -details of the differences from the core code, by adding a protocol -layer that translates between OF1.x and a slightly higher-level -abstract representation. The core of this approach is the many struct -ofputil_* structures in include/openvswitch/ofp-util.h. - -As a consequence of this approach, OVS cannot use OpenFlow protocol -definitions that closely resemble those in the OpenFlow specification, -because openflow.h in different versions of the OpenFlow specification -defines the same identifier with different values. Instead, -openflow-common.h contains definitions that are common to all the -specifications and separate protocol version-specific headers contain -protocol-specific definitions renamed so as not to conflict, -e.g. OFPAT10_ENQUEUE and OFPAT11_ENQUEUE for the OpenFlow 1.0 and 1.1 -values for OFPAT_ENQUEUE. Generally, in cases of conflict, the -protocol layer will define a more abstract OFPUTIL_* or struct -ofputil_*. - -Here are the current approaches in a few tricky areas: - - * Port numbering. OpenFlow 1.0 has 16-bit port numbers and later -OpenFlow versions have 32-bit port numbers. For now, OVS -support for later protocol versions requires all port numbers to -fall into the 16-bit range, translating the reserved OFPP_* port -numbers. - - * Actions. OpenFlow 1.0 and later versions have very different -ideas of actions. OVS reconciles by translating all the -versions' actions (and instructions) to and from a common -internal representation. - -OpenFlow 1.1 - - -The list of remaining work items for OpenFlow 1.1 is below. It is -probably incomplete. - - * Match and set double-tagged VLANs (QinQ). This requires kernel -work for reasonable performance. -[optional for OF1.1+] - - * VLANs tagged with 88a8 Ethertype. This requires kernel work for -reasonable performance. -[required for OF1.1+] - -OpenFlow 1.2 - - -OpenFlow 1.2 support requires OpenFlow 1.1 as a prerequisite. All the -additional work specific to Openflow 1.2 are complete. (This is based -on the change log at the end of the OF1.2 spec. I didn't compare the -specs carefully yet.) - -OpenFlow 1.3 - - -OpenFlow 1.3 support requires OpenFlow 1.2 as a prerequisite, plus the -following additional work. (This is based on the change log at the -end of the OF1.3 spec, reusing most of the
[ovs-dev] [PATCH 11/15] doc: Convert CONTRIBUTING to rST
Signed-off-by: Stephen Finucane --- CONTRIBUTING.md | 414 -- CONTRIBUTING.rst| 444 Documentation/committer-responsibilities.md | 4 +- Makefile.am | 2 +- OPENFLOW-1.1+.md| 2 +- SECURITY.rst| 2 +- 6 files changed, 449 insertions(+), 419 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f848536..000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,414 +0,0 @@ -How to Submit Patches for Open vSwitch -== - -Send changes to Open vSwitch as patches to dev@openvswitch.org. -One patch per email, please. More details are included below. - -If you are using Git, then `git format-patch` takes care of most of -the mechanics described below for you. - -Before You Start - - -Before you send patches at all, make sure that each patch makes sense. -In particular: - - - A given patch should not break anything, even if later -patches fix the problems that it causes. The source tree -should still build and work after each patch is applied. -(This enables `git bisect` to work best.) - - - A patch should make one logical change. Don't make -multiple, logically unconnected changes to disparate -subsystems in a single patch. - - - A patch that adds or removes user-visible features should -also update the appropriate user documentation or manpages. -Check "Feature Deprecation Guidelines" section in this document -if you intend to remove user-visible feature. - -Testing is also important: - - - A patch that modifies existing code should be tested with `make -check` before submission. Please see INSTALL.rst, under -"Self-Tests", for more information. - - - A patch that adds or deletes files should also be tested with -`make distcheck` before submission. - - - A patch that modifies Linux kernel code should be at least -build-tested on various Linux kernel versions before -submission. I suggest versions 3.10 and whatever -the current latest release version is at the time. - - - A patch that modifies the ofproto or vswitchd code should be -tested in at least simple cases before submission. - - - A patch that modifies xenserver code should be tested on -XenServer before submission. - -If you are using GitHub, then you may utilize the travis-ci.org CI build -system by linking your GitHub repository to it. This will run some of -the above tests automatically when you push changes to your repository. -See the "Continuous Integration with Travis-CI" in the [INSTALL.rst] file -for details on how to set it up. - -Email Subject -- - -The subject line of your email should be in the following format: -`[PATCH /] : ` - - - `[PATCH /]` indicates that this is the nth of a series -of m patches. It helps reviewers to read patches in the -correct order. You may omit this prefix if you are sending -only one patch. - - - `:` indicates the area of the Open vSwitch to which the -change applies (often the name of a source file or a -directory). You may omit it if the change crosses multiple -distinct pieces of code. - - - `` briefly describes the change. - -The subject, minus the `[PATCH /]` prefix, becomes the first line -of the commit's change log message. - -Description - -The body of the email should start with a more thorough description of -the change. This becomes the body of the commit message, following -the subject. There is no need to duplicate the summary given in the -subject. - -Please limit lines in the description to 79 characters in width. - -The description should include: - - - The rationale for the change. - - - Design description and rationale (but this might be better -added as code comments). - - - Testing that you performed (or testing that should be done -but you could not for whatever reason). - - - Tags (see below). - -There is no need to describe what the patch actually changed, if the -reader can see it for himself. - -If the patch refers to a commit already in the Open vSwitch -repository, please include both the commit number and the subject of -the patch, e.g. 'commit 632d136c (vswitch: Remove restriction on -datapath names.)'. - -If you, the person sending the patch, did not write the patch -yourself, then the very first line of the body should take the form -`From: `, followed by a blank line. This -will automatically cause the named author to be credited with -authorship in the repository. - -Tags - - -The description ends with a series of tags, written one to a line as -the last paragraph of the email. Each tag indicates some property o
Re: [ovs-dev] [PATCH] doc: fix bad link to dpdk advance installation guide
On 2016-10-18 22:23, Mauricio Vasquez B wrote:
The link was pointing to a wrong place after the file was converted to
rst.
Fixes: 167703d664fc ("doc: Convert INSTALL.DPDK to rST")
Signed-off-by: Mauricio Vasquez B
I don't know the custom on the OVS dev mailing list, but...
Reviewed-by: Stephen Finucane
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH 01/15] doc: Convert CodingStyle to rST
On 2016-10-20 01:25, Russell Bryant wrote: On Tue, Oct 18, 2016 at 4:03 PM, Stephen Finucane wrote: Signed-off-by: Stephen Finucane --- CONTRIBUTING.md | 4 +- CodingStyle.md | 578 - CodingStyle.rst | 642 +++ Makefile.am | 4 +- OPENFLOW-1.1+.md | 6 +- 5 files changed, 649 insertions(+), 585 deletions(-) delete mode 100644 CodingStyle.md create mode 100644 CodingStyle.rst Unfortunately this patch needs a rebase. Can you take a look? The issue seems to be a merge conflict on Makefile.am owing to the changes introduced with 'c4977b6'. There are similar merge conflicts with later patches. I can resubmit or you could use a three-way merge which auto-resolves conflicts for all but two of these patches. curl https://patchwork.ozlabs.org/patch/683845/mbox/ | git am -3 The two unresolved conflicts are trivial to resolve (keep the '.rst' suffixes) Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH] DocumentationStyle: Clarify what documentation is
We're going to convert all docs to reStructuredText, so the "legacy documents" warning is going to become outdated rather quickly. Simply remove it. Signed-off-by: Stephen Finucane --- DocumentationStyle.rst | 10 -- 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/DocumentationStyle.rst b/DocumentationStyle.rst index 4b36618..d563284 100644 --- a/DocumentationStyle.rst +++ b/DocumentationStyle.rst @@ -28,7 +28,9 @@ Open vSwitch Documentation Style This file describes the documentation style used in all documentation found in -Open vSwitch. All documents should follow this guide. +Open vSwitch. Documentation includes any documents found in ``Documentation`` +along with any ``README``, ``INSTALL``, or generally ``rst`` suffixed documents +found in the project tree. reStructuredText vs. Sphinx --- @@ -53,10 +55,6 @@ guide `__. Sphinx extensions can be used, but only for documentation in the ``Documentation`` folder. - .. note:: -Some legacy documents may exist in other formats. When time allows, these -should be converted to reST. - - Limit lines at 79 characters. .. note:: @@ -169,7 +167,7 @@ Graphic tables +--+---+ .. note:: - The ``table`` role (`` .. table:: ``) can be safely omitted. + The ``table`` role - ``.. table:: `` - can be safely omitted. List tables +++ -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH] doc: fix duplicated colons in rst documents
On 2016-10-21 04:40, Mauricio Vasquez B wrote: Signed-off-by: Mauricio Vasquez B --- INSTALL.DPDK.rst | 148 +- INSTALL.Debian.rst| 20 +-- INSTALL.Docker.rst| 76 +++--- INSTALL.KVM.rst | 24 ++-- INSTALL.Windows.rst | 136 ++ INSTALL.XenServer.rst | 32 --- INSTALL.userspace.rst | 12 +++- 7 files changed, 336 insertions(+), 112 deletions(-) diff --git a/INSTALL.DPDK.rst b/INSTALL.DPDK.rst index c4b9167..5780909 100644 --- a/INSTALL.DPDK.rst +++ b/INSTALL.DPDK.rst @@ -66,7 +66,9 @@ Installing DPDK -1. Download the `DPDK sources`_, extract the file and set ``DPDK_DIR``::: +1. Download the `DPDK sources`_, extract the file and set ``DPDK_DIR``: + +:: Not quite right. For this to work, this needs to be aligned under the bullet point like so: 1. Download the `DPDK sources`__, extract the file and set ``DPDK_DIR``: :: $ cd /usr/src/ Alternatively (and preferably) we could just drop the extra ':'. I made this mistake in a couple of other files, I'd say. Could you fix those too, either here or in separate patches? Stephen PS: The online viewer at http://rst.ninjs.org/ is helpful for previewing these things. ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH v2] doc: v2: fix bad link to dpdk advance installation guide
On 2016-10-21 04:51, Mauricio Vasquez B wrote:
Previous fix was also wrong.
Fixes: 167703d ("doc: Convert INSTALL.DPDK to rST")
Signed-off-by: Mauricio Vasquez B
Drat - case sensitivity.
Acked-by: Stephen Finucane
...for the immediate fix, but maybe we should switch to a reference
style link instead like so:
`advanced installation guide`_
.. _advanced installation guide: INSTALL.DPDK-ADVANCED.md
Stephen
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH RFC v4 2/3] netdev-dpdk: Arbitrary 'dpdk' port naming
On 28 Oct 15:45, Ciara Loftus wrote: > 'dpdk' ports no longer have naming restrictions. Now, instead > of specifying the dpdk port ID as part of the name, the PCI > address of the device must be specified via the 'dpdk-devargs' > option. eg. > > ovs-vsctl add-port br0 my-port > ovs-vsctl set Interface my-port type=dpdk > ovs-vsctl set Interface my-port options:dpdk-devargs=:06:00.3 > > The user must no longer hotplug DPDK ports by issuing specific > ovs-appctl commands. The hotplug is now automatically invoked when a > valid PCI address is set in the dpdk-devargs. > > Signed-off-by: Ciara Loftus > --- > INSTALL.DPDK-ADVANCED.md | 9 +-- > INSTALL.DPDK.rst | 14 +++-- > NEWS | 2 + > lib/netdev-dpdk.c| 153 > ++- > vswitchd/vswitch.xml | 8 +++ > 5 files changed, 77 insertions(+), 109 deletions(-) > > diff --git a/INSTALL.DPDK-ADVANCED.md b/INSTALL.DPDK-ADVANCED.md > index 7d90219..577e412 100644 > --- a/INSTALL.DPDK-ADVANCED.md > +++ b/INSTALL.DPDK-ADVANCED.md > @@ -892,14 +892,7 @@ dpdk_nic_bind.py script: > > Then it can be attached to OVS: > > -`ovs-appctl netdev-dpdk/port-attach :01:00.0` > - > -At this point, the user can create a ovs port using the add-port command. > - > -It is also possible to detach a port from ovs, the user has to remove the > -port using the del-port command, then it can be detached using: > - > -`ovs-appctl netdev-dpdk/port-detach dpdk0` > +`ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk > options:dpdk-devargs=:01:00.0` > > This feature is not supported with VFIO and could not work with some NICs, > please refer to the [DPDK Port Hotplug Framework] in order to get more > diff --git a/INSTALL.DPDK.rst b/INSTALL.DPDK.rst > index b917828..2f41f40 100644 > --- a/INSTALL.DPDK.rst > +++ b/INSTALL.DPDK.rst > @@ -249,12 +249,14 @@ Bridges should be created with a > ``datapath_type=netdev``::: > > $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev > > -Now you can add DPDK devices. OVS expects DPDK device names to start with > -``dpdk`` and end with a portid. ovs-vswitchd should print the number of dpdk > -devices found in the log file::: > - > -$ ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk > -$ ovs-vsctl add-port br0 dpdk1 -- set Interface dpdk1 type=dpdk > +Now you can add dpdk devices. The PCI address of the device needs to be > +set using the 'dpdk-devargs' option. vswitchd should print (in the log file) > +the PCI addresses of dpdk devices found during initialisation. > + > +``` > +ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk > options:dpdk-devargs=:06:00.0 > +ovs-vsctl add-port br0 dpdk1 -- set Interface dpdk1 type=dpdk > options:dpdk-devargs=:06:00.1 > +``` I won't review the rest of this (I've no idea what I'm looking at), but this is not a reStructuredText document so some changes are needed. For this to display correctly, you need to precede commands with a '$' symbol, use the rST-style code block formatting and wrap at < 80 characters, where possible. For example: :: $ ovs-vsctl add-port br0 dpdk0 \ -- set Interface dpdk0 type=dpdk options:dpdk-devargs=:06:00.0 See the DocumentationStyle doc for more info. ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH 10/15] doc: Convert README-native-tunneling to rST
On 28 Oct 23:25, Russell Bryant wrote: > On Tue, Oct 18, 2016 at 10:03 PM, Stephen Finucane > wrote: > > > Signed-off-by: Stephen Finucane > > --- > > Makefile.am | 2 +- > > README-native-tunneling.md | 85 --- > > README-native-tunneling.rst | 176 ++ > > ++ > > debian/openvswitch-common.docs | 2 +- > > ofproto/ofproto-tnl-unixctl.man | 2 +- > > rhel/openvswitch.spec.in| 2 +- > > utilities/ovs-sim.1.xml | 2 +- > > 7 files changed, 181 insertions(+), 90 deletions(-) > > delete mode 100644 README-native-tunneling.md > > create mode 100644 README-native-tunneling.rst > > > > I've applied patches 9 and 10 to master. Excellent. You'll be delighted to hear I've the next batch lined up and waiting :) I do have a question though: there are READMEs in both the RHEL and Debian packaging directories. I'm not sure should/can these be converted to rST nor if they're something worth indexing for the docs. Would you know what the custom is here? Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH v2] doc: Convert DESIGN to rST
This is a top-level document, so plain old rST is preferred. Signed-off-by: Stephen Finucane --- v2: - Split the OF message table into multiple tables - Resolve some issues with table headers not displaying --- DESIGN.md | 1093 DESIGN.rst | 1163 +++ Makefile.am |2 +- include/openvswitch/ofp-util.h |2 +- lib/ofp-util.c |2 +- ovn/controller/pinctrl.c|2 +- ovn/ovn-architecture.7.xml |2 +- rhel/openvswitch-fedora.spec.in |2 +- rhel/openvswitch.spec.in|2 +- 9 files changed, 1170 insertions(+), 1100 deletions(-) delete mode 100644 DESIGN.md create mode 100644 DESIGN.rst diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index a330312..000 --- a/DESIGN.md +++ /dev/null @@ -1,1093 +0,0 @@ -Design Decisions In Open vSwitch - - -This document describes design decisions that went into implementing -Open vSwitch. While we believe these to be reasonable decisions, it is -impossible to predict how Open vSwitch will be used in all environments. -Understanding assumptions made by Open vSwitch is critical to a -successful deployment. The end of this document contains contact -information that can be used to let us know how we can make Open vSwitch -more generally useful. - -Asynchronous Messages -= - -Over time, Open vSwitch has added many knobs that control whether a -given controller receives OpenFlow asynchronous messages. This -section describes how all of these features interact. - -First, a service controller never receives any asynchronous messages -unless it changes its miss_send_len from the service controller -default of zero in one of the following ways: - - - Sending an OFPT_SET_CONFIG message with nonzero miss_send_len. - - - Sending any NXT_SET_ASYNC_CONFIG message: as a side effect, this -message changes the miss_send_len to -OFP_DEFAULT_MISS_SEND_LEN (128) for service controllers. - -Second, OFPT_FLOW_REMOVED and NXT_FLOW_REMOVED messages are generated -only if the flow that was removed had the OFPFF_SEND_FLOW_REM flag -set. - -Third, OFPT_PACKET_IN and NXT_PACKET_IN messages are sent only to -OpenFlow controller connections that have the correct connection ID -(see "struct nx_controller_id" and "struct nx_action_controller"): - - - For packet-in messages generated by a NXAST_CONTROLLER action, -the controller ID specified in the action. - - - For other packet-in messages, controller ID zero. (This is the -default ID when an OpenFlow controller does not configure one.) - -Finally, Open vSwitch consults a per-connection table indexed by the -message type, reason code, and current role. The following table -shows how this table is initialized by default when an OpenFlow -connection is made. An entry labeled "yes" means that the message is -sent, an entry labeled "---" means that the message is suppressed. - -``` - master/ - message and reason code other slave - ---- - OFPT_PACKET_IN / NXT_PACKET_IN -OFPR_NO_MATCH yes --- -OFPR_ACTIONyes --- -OFPR_INVALID_TTL --- --- -OFPR_ACTION_SET (OF1.4+) yes --- -OFPR_GROUP (OF1.4+)yes --- - - OFPT_FLOW_REMOVED / NXT_FLOW_REMOVED -OFPRR_IDLE_TIMEOUT yes --- -OFPRR_HARD_TIMEOUT yes --- -OFPRR_DELETE yes --- -OFPRR_GROUP_DELETE (OF1.4+)yes --- -OFPRR_METER_DELETE (OF1.4+)yes --- -OFPRR_EVICTION (OF1.4+)yes --- - - OFPT_PORT_STATUS -OFPPR_ADD yes yes -OFPPR_DELETE yes yes -OFPPR_MODIFY yes yes - - OFPT_ROLE_REQUEST / OFPT_ROLE_REPLY (OF1.4+) -OFPCRR_MASTER_REQUEST --- --- -OFPCRR_CONFIG --- --- -OFPCRR_EXPERIMENTER--- --- - - OFPT_TABLE_STATUS (OF1.4+) -OFPTR_VACANCY_DOWN --- --- -OFPTR_VACANCY_UP --- --- - - OFPT_REQUESTFORWARD (OF1.4+) -OFPRFR_GROUP_MOD --- --- -OFPRFR_METER_MOD --- --- -``` - -The NXT_SET_ASYNC_CONFIG message directly sets all of the values in -this table for the current connection. The -OFPC_INVALID_TTL_TO_CONTROLLER bit in the OFPT_SET_CONFIG message -contr
[ovs-dev] [PATCH 00/23] Convert next batch of docs to rST
This is the third conversion series. This one is larger yet again,
though many of the docs are rather small. After this series, only the
two tutorial docs in 'tutorial' require conversion (along with any
unsuffixed files I may have missed).
/me didn't realize there was quite this much documentation in the repo.
Stephen Finucane (23):
doc: Convert ovs-command-bashcomp.INSTALL to rST
doc: Convert committer-grant-revocation to rST
doc: Convert committer-responsibilities to rST
doc: Convert release-process to rST
doc: Convert OVSDB-replication to rST
doc: Convert rhel/README.RHEL to rST
doc: Convert third-party/README to rST
doc: Convert README.ovs-vtep to rST
doc: Convert INSTALL.Fedora to rST
doc: Convert INSTALL.SSL to rST
doc: Convert INSTALL.Libvirt to rST
doc: Convert INSTALL.NetBSD to rST
doc: Convert INSTALL.RHEL to rST
doc: Convert INSTALL.SELinux to rST
doc: Convert INSTALL.DPDK-ADVANCED to rST
doc: Convert datapath/README to rST
doc: Convert xenserver/README to rST
doc: Update windows/README
doc: Convert datapath-windows/CodingStyle to rST
doc: Convert datapath-windows/DESIGN to rST
doc: Convert CONTAINERS.OpenStack to rST
doc: Convert OVS-GW-HA to rST
doc: Convert vswitchd/INTERNALS to rST
Documentation/OVSDB-replication.md | 152 -
Documentation/OVSDB-replication.rst | 172 +
Documentation/automake.mk| 8 +-
Documentation/committer-grant-revocation.md | 356 --
Documentation/committer-grant-revocation.rst | 398
Documentation/committer-responsibilities.md | 78 ---
Documentation/committer-responsibilities.rst | 96 +++
Documentation/release-process.md | 99 ---
Documentation/release-process.rst| 117
FAQ.rst | 2 +-
INSTALL.DPDK-ADVANCED.md | 898 -
INSTALL.DPDK-ADVANCED.rst| 938 +++
INSTALL.DPDK.rst | 10 +-
INSTALL.Docker.rst | 2 +-
INSTALL.Fedora.md| 130
INSTALL.Fedora.rst | 144
INSTALL.Libvirt.md | 72 --
INSTALL.Libvirt.rst | 93 +++
INSTALL.NetBSD.md| 38 --
INSTALL.NetBSD.rst | 62 ++
INSTALL.RHEL.md | 171 -
INSTALL.RHEL.rst | 208 ++
INSTALL.SELinux.md | 173 -
INSTALL.SELinux.rst | 174 +
INSTALL.SSL.md | 314 -
INSTALL.SSL.rst | 338 ++
INSTALL.rst | 6 +-
MAINTAINERS.rst | 4 +-
Makefile.am | 14 +-
README.rst | 10 +-
datapath-windows/CodingStyle | 154 -
datapath-windows/CodingStyle.rst | 183 ++
datapath-windows/{DESIGN => DESIGN.rst} | 503 +++---
datapath-windows/automake.mk | 4 +-
datapath/Modules.mk | 2 +-
datapath/README.md | 265
datapath/README.rst | 265
lib/dpif.h | 2 +-
lib/mac-learning.c | 3 +-
lib/mac-learning.h | 2 +-
ovn/CONTAINERS.OpenStack.md | 122
ovn/CONTAINERS.OpenStack.rst | 135
ovn/{OVN-GW-HA.md => OVN-GW-HA.rst} | 309 +
ovn/TODO | 2 +-
ovn/automake.mk | 4 +-
rhel/README.RHEL | 267
rhel/README.rst | 302 +
rhel/automake.mk | 2 +-
rhel/openvswitch-fedora.spec.in | 4 +-
rhel/openvswitch.spec.in | 4 +-
third-party/README.md| 38 --
third-party/README.rst | 66 ++
third-party/automake.mk | 2 +-
utilities/automake.mk| 4 +-
utilities/ovs-command-bashcomp.INSTALL.md| 88 ---
utilities/ovs-command-bashcomp.INSTALL.rst | 111
vswitchd/INTERNALS | 239 ---
vswitchd/INTERNALS.rst | 244 +++
vswitchd/automake.mk | 2 +-
vtep/README.ovs-vtep.md | 205 --
vtep/README.ovs-vtep.rst | 231 +++
vtep/automake.mk | 2 +-
windows/README.rst | 72 +-
xenserver/README | 186 --
[ovs-dev] [PATCH 02/23] doc: Convert committer-grant-revocation to rST
Signed-off-by: Stephen Finucane --- Documentation/automake.mk| 2 +- Documentation/committer-grant-revocation.md | 356 Documentation/committer-grant-revocation.rst | 398 +++ MAINTAINERS.rst | 2 +- 4 files changed, 400 insertions(+), 358 deletions(-) delete mode 100644 Documentation/committer-grant-revocation.md create mode 100644 Documentation/committer-grant-revocation.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index d709e77..2f728bd 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -1,6 +1,6 @@ docs += \ Documentation/committer-responsibilities.md \ - Documentation/committer-grant-revocation.md \ + Documentation/committer-grant-revocation.rst \ Documentation/group-selection-method-property.txt \ Documentation/OVSDB-replication.md \ Documentation/release-process.md diff --git a/Documentation/committer-grant-revocation.md b/Documentation/committer-grant-revocation.md deleted file mode 100644 index 83b703c..000 --- a/Documentation/committer-grant-revocation.md +++ /dev/null @@ -1,356 +0,0 @@ -OVS Committer Grant/Revocation Policy -= - -An OVS committer is a participant in the project with the ability -to commit code directly to the master repository. Commit access -grants a broad ability to affect the progress of the project as -presented by its most important artifact, the code and related -resources that produce working binaries of Open vSwitch. As such -it represents a significant level of trust in an individual's -commitment to working with other committers and the community at -large for the benefit of the project. It can not be granted -lightly and, in the worst case, must be revocable if the trust -placed in an individual was inappropriate. - -This document suggests guidelines for granting and revoking commit -access. It is intended to provide a framework for evaluation of such -decisions without specifying deterministic rules that wouldn't be -sensitive to the nuance of specific situations. In the end the -decision to grant or revoke committer privileges is a judgment call -made by the existing set of committers. - -Granting Commit Access --- - -Granting commit access should be considered when a candidate has -demonstrated the following in their interaction with the project: - -* Contribution of significant new features through the patch - submission process where: - * Submissions are free of obvious critical defects - * Submissions do not typically require many iterations of -improvement to be accepted -* Consistent participation in code review of other's patches, - including existing committers, with comments consistent with the - overall project standards -* Assistance to those in the community who are less knowledgeable - through active participation in project forums such as the - ovs-discuss mailing list. -* Plans for sustained contribution to the project compatible with - the project's direction as viewed by current committers. -* Commitment to meet the expectations described in the - "Expectations of Developer's with Open vSwitch Access" - -The process to grant commit access to a candidate is simple: - -* An existing committer nominates the candidate by sending an - email to all existing committers with information - substantiating the contributions of the candidate in the areas - described above. -* All existing committers discuss the pros and cons of granting - commit access to the candidate in the email thread. -* When the discussion has converged or a reasonable time has - elapsed without discussion developing (e.g. a few business days) - the nominator calls for a final decision on the candidate with a - followup email to the thread. -* Each committer may vote yes, no, or abstain by replying to the - email thread. A failure to reply is an implicit abstention. -* After votes from all existing committers have been collected or a - reasonable time has elapsed for them to be provided (e.g. a - couple of business days) the votes are evaluated. To be granted - commit access the candidate must receive yes votes from a - majority of the existing committers and zero no votes. Since a - no vote is effectively a veto of the candidate it should be - accompanied by a reason for the vote. -* The nominator summarizes the result of the vote in an email to - all existing committers. -* If the vote to grant commit access passed, the candidate is - contacted with an invitation to become a committer to the project - which asks them to agree to the committer expectations - documented on the project web site. -* If the candidate agrees access is granted by setting up commit - access to the repos on github. - -Revoking Commit Access --- - -There are two situ
[ovs-dev] [PATCH 01/23] doc: Convert ovs-command-bashcomp.INSTALL to rST
Signed-off-by: Stephen Finucane --- utilities/automake.mk | 4 +- utilities/ovs-command-bashcomp.INSTALL.md | 88 --- utilities/ovs-command-bashcomp.INSTALL.rst | 111 + 3 files changed, 113 insertions(+), 90 deletions(-) delete mode 100644 utilities/ovs-command-bashcomp.INSTALL.md create mode 100644 utilities/ovs-command-bashcomp.INSTALL.rst diff --git a/utilities/automake.mk b/utilities/automake.mk index 380418a..014e477 100644 --- a/utilities/automake.mk +++ b/utilities/automake.mk @@ -37,11 +37,11 @@ noinst_SCRIPTS += utilities/ovs-sim utilities/ovs-lib: $(top_builddir)/config.status -docs += utilities/ovs-command-bashcomp.INSTALL.md +docs += utilities/ovs-command-bashcomp.INSTALL.rst EXTRA_DIST += \ utilities/ovs-appctl-bashcomp.bash \ utilities/ovs-check-dead-ifs.in \ - utilities/ovs-command-bashcomp.INSTALL.md \ + utilities/ovs-command-bashcomp.INSTALL.rst \ utilities/ovs-ctl.in \ utilities/ovs-dev.py \ utilities/ovs-docker \ diff --git a/utilities/ovs-command-bashcomp.INSTALL.md b/utilities/ovs-command-bashcomp.INSTALL.md deleted file mode 100644 index 9bdef40..000 --- a/utilities/ovs-command-bashcomp.INSTALL.md +++ /dev/null @@ -1,88 +0,0 @@ -Using bash command-line completion scripts --- - -There are two completion scripts available, ovs-appctl-bashcomp.bash -and ovs-vsctl-bashcomp.bash respectively. - -ovs-appctl-bashcomp - - ovs-appctl-bashcomp.bash adds bash command-line completion support - for ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands. - - Features: - - - - display available completion or complete on unfinished user input - (long option, subcommand, and argument). - - once the subcommand (e.g. ofproto/trace) has been given, the - script will print the subcommand format. - - the script can convert between keywords like 'bridge/port/interface/dp' - and the available record in ovsdb. - - Limitations: - - - only support small set of important keywords - (dp, datapath, bridge, switch, port, interface, iface). - - does not support parsing of nested options - (e.g. ovsdb-tool create [db [schema]]). - - does not support expansion on repeatitive argument - (e.g. ovs-dpctl show [dp...]). - - only support matching on long options, and only in the format - (--option [arg], i.e. should not use --option=[arg]). - -ovs-vsctl-bashcomp - - ovs-vsctl-bashcomp.bash adds bash command-line completion support - for ovs-vsctl command. - - Features: - - - - display available completion and complete on user input for - global/local options, command, and argument. - - query database and expand keywords like 'table/record/column/key' - to available completions. - - deal with argument relations like 'one and more', 'zero or one'. - - complete multiple ovs-vsctl commands cascaded via '--'. - - Limitations: - - - completion of very long ovs-vsctl command can take up to several - seconds. - -How to use: - - The bashcomp scripts should be placed at /etc/bash_completion.d/ - to be available for all bash sessions. Running 'make install' - will place the scripts to $(sysconfdir)/bash_completion.d/. So user - should specify --sysconfdir=/etc at configuration. Meanwhile, if OVS is - installed from packages, the scripts will automatically be placed inside - /etc/bash_completion.d/. - - If you just want to run the scripts in one bash, you can remove them from - /etc/bash_completion.d/ and run the scripts via '. ovs-appctl-bashcomp.bash' - or '. ovs-vsctl-bashcomp.bash'. - -Test: -- - - Unit tests are added in tests/completion.at and integrated into autotest - framework. To run the tests, just do make check. - -Bug Reporting: --- - -Please report problems to b...@openvswitch.org. \ No newline at end of file diff --git a/utilities/ovs-command-bashcomp.INSTALL.rst b/utilities/ovs-command-bashcomp.INSTALL.rst new file mode 100644 index 000..6df60c6 --- /dev/null +++ b/utilities/ovs-command-bashcomp.INSTALL.rst @@ -0,0 +1,111 @@ +.. + 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 permissi
[ovs-dev] [PATCH 04/23] doc: Convert release-process to rST
Signed-off-by: Stephen Finucane --- Documentation/automake.mk | 2 +- Documentation/release-process.md | 99 Documentation/release-process.rst | 117 ++ FAQ.rst | 2 +- 4 files changed, 119 insertions(+), 101 deletions(-) delete mode 100644 Documentation/release-process.md create mode 100644 Documentation/release-process.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 9008ee2..d6849e8 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -3,4 +3,4 @@ docs += \ Documentation/committer-grant-revocation.rst \ Documentation/group-selection-method-property.txt \ Documentation/OVSDB-replication.md \ - Documentation/release-process.md + Documentation/release-process.rst diff --git a/Documentation/release-process.md b/Documentation/release-process.md deleted file mode 100644 index 0f8f49d..000 --- a/Documentation/release-process.md +++ /dev/null @@ -1,99 +0,0 @@ -Open vSwitch Release Process - - -This document describes the process ordinarily used for Open vSwitch -development and release. Exceptions are sometimes necessary, so all -of the statements here should be taken as subject to change through -rough consensus of Open vSwitch contributors, obtained through public -discussion on, e.g., ovs-dev or the #openvswitch IRC channel. - -Release Strategy - - -Open vSwitch feature development takes place on the "master" branch. -Ordinarily, new features are rebased against master and applied -directly. For features that take significant development, sometimes -it is more appropriate to merge a separate branch into master; please -discuss this on ovs-dev in advance. - -Periodically, the OVS developers fork a branch from master to become -an official release. These release branches are named for expected -release number, e.g. "branch-2.3" for the branch that will yield Open -vSwitch 2.3.x. Release branches should receive only bug fixes, not -new features. Bug fixes applied to release branches should be -backports of corresponding bug fixes to the master branch, except for -bugs present only on release branches (which are rare in practice). - -Sometimes there can be exceptions to the rule that a release branch -receives only bug fixes. In particular, after a release branch is -created, but before the first actual release from that branch, it can -be appropriate to add features. Like bug fixes, new features on -release branches should be backports of the corresponding commits on -the master branch. Features to be added to release branches should be -limited in scope and risk and discussed on ovs-dev before creating the -branch. - -After a period of testing and stabilization, and rough consensus -obtained from contributors that the release is ready, the developers -release the .0 release on its branch, e.g. 2.3.0 for branch-2.3. To -make the actual release, a developer pushes a signed tag named, -e.g. v2.3.0, to the Open vSwitch repository, makes a release tarball -available on openvswitch.org, and posts a release announcement to -ovs-announce. - -As a number of bug fixes accumulate, or after important bugs or -vulnerabilities are fixed, the OVS developers may make additional -releases from a branch: 2.3.1, 2.3.2, and so on. The process is the -same for these additional release as for a .0 release. - -At most two release branches are formally maintained at any given -time: the latest release and the latest release designed as LTS. An -LTS release is one that the OVS project has designated as being -maintained for a longer period of time. Currently, an LTS release is -maintained until the next LTS is chosen. There is not currently a -strict guideline on how often a new LTS release is chosen, but so far -it has been about every 2 years. That could change based on the -current state of OVS development. For example, we do not want to -designate a new release as LTS that includes disruptive internal -changes, as that may make it harder to support for a longer period of -time. Discussion about choosing the next LTS release occurs on the -OVS development mailing list. - -Release Numbering -- - -The version number on master should normally end in .90. This -indicates that the Open vSwitch version is "almost" the next version -to branch. - -Forking master into branch-x.y requires two commits to master. The -first is titled "Prepare for x.y.0" and increments the version number -to x.y. This is the initial commit on branch-x.y. The second is -titled "Prepare for post-x.y.0 (x.y.90)" and increments the version -number to x.y.90. - -The version number on a release branch is x.y.z, where z is initially -0. Making a release requires two commits. The first is titled "Set -release dates for x.y.z." a
[ovs-dev] [PATCH 05/23] doc: Convert OVSDB-replication to rST
Signed-off-by: Stephen Finucane --- Documentation/OVSDB-replication.md | 152 --- Documentation/OVSDB-replication.rst | 172 Documentation/automake.mk | 2 +- 3 files changed, 173 insertions(+), 153 deletions(-) delete mode 100644 Documentation/OVSDB-replication.md create mode 100644 Documentation/OVSDB-replication.rst diff --git a/Documentation/OVSDB-replication.md b/Documentation/OVSDB-replication.md deleted file mode 100644 index a9ab5cc..000 --- a/Documentation/OVSDB-replication.md +++ /dev/null @@ -1,152 +0,0 @@ -OVSDB replication implementation - - -Overview - - -Given two Open vSwitch databases with the same schema, OVSDB -replication keeps these databases in the same state, i.e. each of the -databases have the same contents at any given time even if they are -not running in the same host. This document elaborates on the -implementation details to provide this functionality. - -Terminology -=== - -- Source of truth database: database whose content will be replicated - to another database. - -- Active server: ovsdb-server providing RPC interface to the source of - truth database. - -- Standby server: ovsdb-server providing RPC interface to the database - that is not the source of truth. - -Design -== - -The overall design of replication consists of one ovsdb-server (active server) -communicating the state of its databases to another ovsdb-server -(standby server) so that the latter keep its own databases in that same state. -To achieve this, the standby server acts as a client of the active -server, in the sense that it sends a monitor request to keep up to date with -the changes in the active server databases. When a notification from the -active server arrives, the standby server executes the necessary set of -operations so its databases reach the same state as the the active server -databases. Below is the design represented as a diagram. - -+--+replication +--+ -|Active|<---| Standby| -| OVSDB-server || OVSDB-server | -+--++--+ -| | -| | -+---+ +---+ -| SoT | | | -| OVSDB | | OVSDB | -+---+ +---+ - -Setting up the replication -== - -To initiate the replication process, the standby server must be executed -indicating the location of the active server via the command line option -"--sync-from=server", where server can take any form described in the -ovsdb-client manpage and it must specify an active connection type (tcp, unix, -ssl). This option will cause the standby server to attempt to send a monitor -request to the active server in every main loop iteration, until the active -server responds. - -When sending a monitor request the standby server is doing the following: - -1. Erase the content of the databases for which it is providing a RPC -interface. - -2. Open the jsonrpc channel to communicate with the active server. - -3. Fetch all the databases located in the active server. - -4. For each database with the same schema in both the active and - standby servers: construct and send a monitor request message - specifying the tables that will be monitored (i.e all the tables on - the database except the ones blacklisted*). - -5. Set the standby database to the current state of the active - database. - -Once the monitor request message is sent, the standby server will continuously -receive notifications of changes occurring to the tables specified in the -request. The process of handling this notifications is detailed in the next -section. - -*A set of tables that will be excluded from replication can be -configure as a blacklist of tables via the command line option -"--sync-exclude-tables=db:table[,db:table]...", where db corresponds -to the database where the table resides. - -Replication process -=== - -The replication process consists on handling the update notifications received -in the standby server caused by the monitor request that was previously sent to -the active server. In every loop iteration, the standby server attempts to -receive a message from the active server which can be an error, an echo -message (used to keep the connection alive) or an update notification. In case -the message is a fatal error, the standby server will disconnect from the -active without dropping the replicated data. If it is an echo message, the -standby server will reply with an echo message as well. If the message is an -update notification, the following process occurs: - -1. Create a new transaction. - -2. Ge
[ovs-dev] [PATCH 06/23] doc: Convert rhel/README.RHEL to rST
This is a top-level document, so plain old rST is preferred. Signed-off-by: Stephen Finucane --- INSTALL.Fedora.md | 2 +- INSTALL.RHEL.md | 6 +- rhel/README.RHEL| 267 --- rhel/README.rst | 302 rhel/automake.mk| 2 +- rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- 7 files changed, 309 insertions(+), 274 deletions(-) delete mode 100644 rhel/README.RHEL create mode 100644 rhel/README.rst diff --git a/INSTALL.Fedora.md b/INSTALL.Fedora.md index d2e55b2..a9eba08 100644 --- a/INSTALL.Fedora.md +++ b/INSTALL.Fedora.md @@ -127,4 +127,4 @@ Please report problems to b...@openvswitch.org. [INSTALL.rst]:INSTALL.rst [FAQ.rst]:FAQ.rst -[README.RHEL]:rhel/README.RHEL +[README.RHEL]:rhel/README.RHEL.rst diff --git a/INSTALL.RHEL.md b/INSTALL.RHEL.md index c7343ce..7c39029 100644 --- a/INSTALL.RHEL.md +++ b/INSTALL.RHEL.md @@ -157,8 +157,8 @@ Red Hat Network Scripts Integration --- Simple integration with Red Hat network scripts has been implemented. -Please read [rhel/README.RHEL] in the source tree or -/usr/share/doc/openvswitch/README.RHEL in the installed openvswitch +Please read [rhel/README.RHEL.rst] in the source tree or +/usr/share/doc/openvswitch/README.RHEL.rst in the installed openvswitch package for details. Reporting Bugs @@ -168,4 +168,4 @@ Please report problems to b...@openvswitch.org. [INSTALL.rst]:INSTALL.rst [INSTALL.Fedora.md]:INSTALL.Fedora.md -[rhel/README.RHEL]:rhel/README.RHEL +[rhel/README.RHEL.rst]:rhel/README.RHEL.rst diff --git a/rhel/README.RHEL b/rhel/README.RHEL deleted file mode 100644 index fec9c75..000 --- a/rhel/README.RHEL +++ /dev/null @@ -1,267 +0,0 @@ -Red Hat network scripts integration - -The RPM packages for Open vSwitch provide some integration with Red -Hat's network scripts. Using this integration is optional. - -To use the integration for a Open vSwitch bridge or interface named -, create or edit /etc/sysconfig/network-scripts/ifcfg-. -This is a shell script that consists of a series of VARIABLE=VALUE -assignments. The following OVS-specific variable names are supported: - -- DEVICETYPE: Always set to "ovs". - -- TYPE: If this is "OVSBridge", then this file represents an OVS - bridge named . Otherwise, it represents a port on an OVS - bridge and TYPE must have one of the following values: - -* "OVSPort", if is a physical port (e.g. eth0) or - virtual port (e.g. vif1.0). - -* "OVSIntPort", if is an internal port (e.g. a tagged - VLAN). - -* "OVSBond", if is an OVS bond. - -* "OVSTunnel", if is an OVS tunnel. - -* "OVSPatchPort", if is a patch port - - Additionally the following DPDK port types may be available, - depends on OVS build- and runtime configuration: - -* "OVSDPDKPort", if is a physical DPDK NIC port (name - must start with "dpdk" and end with portid, eg "dpdk0") - -* "OVSDPDKRPort", if is a DPDK ring port (name must - start with dpdkr and end with portid, eg "dpdkr0") - -* "OVSDPDKVhostUserPort" if is a DPDK vhost-user port - -* "OVSDPDKBond" if is an OVS DPDK bond. - -- OVS_BRIDGE: If TYPE is anything other than "OVSBridge", set to - the name of the OVS bridge to which the port should be attached. - -- OVS_OPTIONS: Optionally, extra options to set in the "Port" - table when adding the port to the bridge, as a sequence of - column[:key]=value options. For example, "tag=100" to make the - port an access port for VLAN 100. See the documentation of - "add-port" in ovs-vsctl(8) for syntax and the section on the - Port table in ovs-vswitchd.conf.db(5) for available options. - -- OVS_EXTRA: Optionally, additional ovs-vsctl commands, separated - by "--" (double dash). - -- BOND_IFACES: For "OVSBond" and "OVSDPDKBond" interfaces, a list of - physical interfaces to bond together. - -- OVS_TUNNEL_TYPE: For "OVSTunnel" interfaces, the type of the tunnel. - For example, "gre", "vxlan", etc. - -- OVS_TUNNEL_OPTIONS: For "OVSTunnel" interfaces, this field should be - used to specify the tunnel options like remote_ip, key, etc. - -- OVS_PATCH_PEER: For "OVSPatchPort" devices, this field specifies - the patch's peer on the other bridge. - -Note - - -* "ifdown" on a bridge will not bring individual ports on the bridge -down. "ifup" on a bridge will not add ports to the b
[ovs-dev] [PATCH 08/23] doc: Convert README.ovs-vtep to rST
Expand on the definition of VTEP (it took me a bit of Googling). Signed-off-by: Stephen Finucane --- vtep/README.ovs-vtep.md | 205 - vtep/README.ovs-vtep.rst | 231 +++ vtep/automake.mk | 2 +- 3 files changed, 232 insertions(+), 206 deletions(-) delete mode 100644 vtep/README.ovs-vtep.md create mode 100644 vtep/README.ovs-vtep.rst diff --git a/vtep/README.ovs-vtep.md b/vtep/README.ovs-vtep.md deleted file mode 100644 index e08c8e6..000 --- a/vtep/README.ovs-vtep.md +++ /dev/null @@ -1,205 +0,0 @@ -How to Use the VTEP Emulator - - -This document explains how to use ovs-vtep, a VTEP emulator that uses -Open vSwitch for forwarding. - -Requirements - - -The VTEP emulator is a Python script that invokes calls to tools like -vtep-ctl and ovs-vsctl and is useful only when OVS daemons like ovsdb-server -and ovs-vswitchd are running. So those components should be installed. This -can be done by either of the following methods. - -1. Follow the instructions in the INSTALL.md file of the Open vSwitch repository -(don't start any daemons yet). - -2. Follow the instructions in INSTALL.Debian.rst file and then install the -"openvswitch-vtep" package (if operating on a debian based machine). This -will automatically start the daemons. - -Design -== - -At the end of this process, you should have the following setup: - - - +---+ - | Host Machine | - | | - | | - | +-+ +-+ | - | | | | | | - | | VM1 | | VM2 | | - | | | | | | - | +o+ +o+ | - || | | - | br0 +--o---oo--+ | - |p0 p1 br0| - | | - | | - | +--+ +--+ | - +--| eth0 |---| eth1 |--+ - +--+ +--+ - 10.1.1.1 10.2.2.1 -MANAGEMENT | | - +-o+ | - | - DATA/TUNNEL | - +-o---+ - -Notes: - -1. We will use Open vSwitch to create our "physical" switch labeled br0 - -2. Our "physical" switch br0 will have one internal port also named br0 - and two "physical" ports, namely p0 and p1. - -3. The host machine may have two external interfaces. We will use eth0 - for management traffic and eth1 for tunnel traffic (One can use - a single interface to achieve both). Please take note of their IP - addresses in the diagram. You do not have to use exactly - the same IP addresses. Just know that the above will be used in the - steps below. - -4. You can optionally connect physical machines instead of virtual - machines to switch br0. In that case: - - 4.1. Make sure you have two extra physical interfaces in your host -machine, eth2 and eth3. - - 4.2. In the rest of this doc, replace p0 with eth2 and p1 with eth3. - -5. In addition to implementing p0 and p1 as physical interfaces, you can - also optionally implement them as standalone TAP devices, or VM - interfaces for simulation. - -6. Creating and attaching the VMs is outside the scope of this document - and is included in the diagram for reference purposes only. - -Startup - -These instructions describe how to run with a single ovsdb-server -instance that handles both the OVS and VTEP schema. You can skip -steps 1-3 if you installed using the debian packages as mentioned in -step 2 of the "Requirements" section. - -1. Create the initial OVS and VTEP schemas: - - ``` -ovsdb-tool create /etc/openvswitch/ovs.db vswitchd/vswitch.ovsschema -ovsdb-tool create /etc/openvswitch/vtep.db vtep/vtep.ovsschema - ``` - -2. Start ovsdb-server and have it handle both databases: - - ``` -ovsdb-server --pidfile --detach --log-file \ ---remote punix:/var/run/openvswitch/db.sock \ ---remote=db:hardware_vtep,Global,managers \ -/etc/openvswitch/ovs.db /etc/openvswitch/vtep.db - ``` - -3. Start OVS as normal: - - ``` -ovs-vswitchd --log-file --detach --pidfile \ -unix:/var/run/openvswitch/db.sock - ``` - -4. Create a "physical" switch and it
[ovs-dev] [PATCH 09/23] doc: Convert INSTALL.Fedora to rST
Signed-off-by: Stephen Finucane --- INSTALL.Fedora.md | 130 --- INSTALL.Fedora.rst | 144 + INSTALL.RHEL.md| 4 +- INSTALL.SELinux.md | 4 +- INSTALL.rst| 2 +- Makefile.am| 2 +- README.rst | 2 +- 7 files changed, 151 insertions(+), 137 deletions(-) delete mode 100644 INSTALL.Fedora.md create mode 100644 INSTALL.Fedora.rst diff --git a/INSTALL.Fedora.md b/INSTALL.Fedora.md deleted file mode 100644 index a9eba08..000 --- a/INSTALL.Fedora.md +++ /dev/null @@ -1,130 +0,0 @@ -How to Install Open vSwitch on Fedora Linux -=== - -This document provides instructions for building and installing Open vSwitch -RPM packages on a Fedora Linux host. Instructions for the installation of -Open vSwitch on a Fedora Linux host without using RPM packages can be found -in [INSTALL.rst]. - -These instructions have been tested with Fedora 23, and are also applicable -for RHEL 7.x and its derivatives, including CentOS 7.x and Scientific Linux -7.x. - -Build Requirements --- -The tools and packages that are required for building Open vSwitch are -documented in [INSTALL.rst]. Specific packages (by package name) include: - - - rpm-build - - autoconf automake libtool - - systemd-units openssl openssl-devel - - python python-twisted-core python-zope-interface python-six - - desktop-file-utils - - groff graphviz - - procps-ng - -And (optionally): - - - libcap-ng libcap-ng-devel - - dpdk-devel - -Building Open vSwitch RPMs for Fedora -- - -RPMs may be built from an Open vSwitch distribution tarball or from an -Open vSwitch Git tree. The build procedure for each scenario is described -below. - -### Preparing to Build Open vSwitch RPMs with a GIT Tree -From the top-level directory of the git tree, execute the following -commands: - -``` -./boot.sh -./configure -``` - -### Preparing to Build Open vSwitch RPMs from a Tarball -From a directory with appropriate permissions, execute the following commands -(substituting the relevant Open vSwitch release version for "x.y.z"): - -``` -tar xzf openvswitch-x.y.z.tar.gz -cd openvswitch-x.y.z -./configure -``` - -### Building the User-Space RPMs -To build Open vSwitch user-space RPMs, after having completed the appropriate -preparation steps described above, execute the following from the directory -in which `./configure` was executed: - -``` -make rpm-fedora -``` - -This will create the RPMs `openvswitch`, `python-openvswitch`, -`openvswitch-test`, `openvswitch-devel`, `openvswitch-ovn-common`, -`openvswitch-ovn-central`, `openvswitch-ovn-host`, `openvswitch-ovn-vtep`, -`openvswitch-ovn-docker`, and `openvswitch-debuginfo`. - -To enable DPDK support in the openvswitch package, -the `--with dpdk` option can be added: - -``` -make rpm-fedora RPMBUILD_OPT="--with dpdk" -``` - -The above commands automatically run the Open vSwitch unit tests, -which can take several minutes. To reduce the build time by -disabling the execution of these tests, the `--without check` -option can be added: - -``` -make rpm-fedora RPMBUILD_OPT="--without check" -``` - -### Building the Kernel OVS Tree Datapath RPM -To build the Open vSwitch kernel module for the currently running -kernel version, execute: - -``` -make rpm-fedora-kmod -``` - -To build the Open vSwitch kernel module for another kernel version, -the desired kernel version can be specified via the `kversion` macro. -For example: - -``` -make rpm-fedora-kmod \ - RPMBUILD_OPT='-D "kversion 4.3.4-300.fc23.x86_64"' -``` - -Installing Open vSwitch RPMs - -RPM packages can be installed by using the command `rpm -i`. Package -installation requires superuser privileges. - -The openvswitch-kmod RPM should be installed first if the Linux OVS tree datapath -module is to be used. The openvswitch-kmod RPM should not be installed if -only the in-tree Linux datapath or user-space datapath is needed. See [FAQ.rst] -for more information about the various Open vSwitch datapath options. - -In most cases only the `openvswitch` RPM will need to be installed. The -`python-openvswitch`, `openvswitch-test`, `openvswitch-devel`, and -`openvswitch-debuginfo` RPMs are optional unless required for a specific -purpose. - -The `openvswitch-ovn-*` packages are only needed when using OVN. - -See [rhel/README.RHEL] for additional usage and configuration information. - -Reporting Bugs --- - -Please report problems to b...@openvswitch.org. - -[INSTALL.rst]:INSTALL.rst -[FAQ.rst]:FAQ.rst -[README.RHEL]:rhel/README.RHEL.rst diff --git a/INSTALL.Fedora.rst b/INSTALL.Fedora.rst new file mode 100644 index 000..64e7167 --- /dev/null +++ b/INSTALL.Fedora.rst @@ -0,0 +1,144 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License")
[ovs-dev] [PATCH 10/23] doc: Convert INSTALL.SSL to rST
Signed-off-by: Stephen Finucane --- INSTALL.SSL.md | 314 - INSTALL.SSL.rst | 338 Makefile.am | 2 +- README.rst | 2 +- rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in| 2 +- 6 files changed, 342 insertions(+), 318 deletions(-) delete mode 100644 INSTALL.SSL.md create mode 100644 INSTALL.SSL.rst diff --git a/INSTALL.SSL.md b/INSTALL.SSL.md deleted file mode 100644 index e341524..000 --- a/INSTALL.SSL.md +++ /dev/null @@ -1,314 +0,0 @@ -Configuring Open vSwitch for SSL - - -If you plan to configure Open vSwitch to connect across the network to -an OpenFlow controller, then we recommend that you build Open vSwitch -with OpenSSL. SSL support ensures integrity and confidentiality of -the OpenFlow connections, increasing network security. - -This file explains how to configure an Open vSwitch to connect to an -OpenFlow controller over SSL. Refer to [INSTALL.rst] for instructions -on building Open vSwitch with SSL support. - -Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by -RFC 2246, which is very similar to SSL version 3.0. TLSv1 was -released in January 1999, so all current software and hardware should -implement it. - -This document assumes basic familiarity with public-key cryptography -and public-key infrastructure. - -SSL Concepts for OpenFlow -- - -This section is an introduction to the public-key infrastructure -architectures that Open vSwitch supports for SSL authentication. - -To connect over SSL, every Open vSwitch must have a unique -private/public key pair and a certificate that signs that public key. -Typically, the Open vSwitch generates its own public/private key pair. -There are two common ways to obtain a certificate for a switch: - - * Self-signed certificates: The Open vSwitch signs its certificate -with its own private key. In this case, each switch must be -individually approved by the OpenFlow controller(s), since there -is no central authority. - -This is the only switch PKI model currently supported by NOX -(http://noxrepo.org). - - * Switch certificate authority: A certificate authority (the -"switch CA") signs each Open vSwitch's public key. The OpenFlow -controllers then check that any connecting switches' -certificates are signed by that certificate authority. - -This is the only switch PKI model supported by the simple -OpenFlow controller included with Open vSwitch. - -Each Open vSwitch must also have a copy of the CA certificate for the -certificate authority that signs OpenFlow controllers' keys (the -"controller CA" certificate). Typically, the same controller CA -certificate is installed on all of the switches within a given -administrative unit. There are two common ways for a switch to obtain -the controller CA certificate: - - * Manually copy the certificate to the switch through some secure -means, e.g. using a USB flash drive, or over the network with -"scp", or even FTP or HTTP followed by manual verification. - - * Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and -saves the controller CA certificate that it obtains from the -OpenFlow controller on its first connection. Thereafter the -switch will only connect to controllers signed by the same CA -certificate. - -Establishing a Public Key Infrastructure - - -Open vSwitch can make use of your existing public key infrastructure. -If you already have a PKI, you may skip forward to the next section. -Otherwise, if you do not have a PKI, the ovs-pki script included with -Open vSwitch can help. To create an initial PKI structure, invoke it -as: - -% ovs-pki init - -to create and populate a new PKI directory. The default location for -the PKI directory depends on how the Open vSwitch tree was configured -(to see the configured default, look for the --dir option description -in the output of "ovs-pki --help"). - -The pki directory contains two important subdirectories. The -controllerca subdirectory contains controller CA files, including the -following: - - - cacert.pem: Root certificate for the controller certificate -authority. Each Open vSwitch must have a copy of this file to -allow it to authenticate valid controllers. - - - private/cakey.pem: Private signing key for the controller -certificate authority. This file must be kept secret. There is -no need for switches or controllers to have a copy of it. - -The switchca subdirectory contains switch CA files, analogous to those -in the controllerca subdirectory: - - - cacert.pem: Root certificate for the switch certificate -authority. The OpenFlow controller must have this file
[ovs-dev] [PATCH 11/23] doc: Convert INSTALL.Libvirt to rST
Signed-off-by: Stephen Finucane --- INSTALL.Libvirt.md | 72 - INSTALL.Libvirt.rst | 93 + Makefile.am | 2 +- README.rst | 2 +- 4 files changed, 95 insertions(+), 74 deletions(-) delete mode 100644 INSTALL.Libvirt.md create mode 100644 INSTALL.Libvirt.rst diff --git a/INSTALL.Libvirt.md b/INSTALL.Libvirt.md deleted file mode 100644 index 3b36503..000 --- a/INSTALL.Libvirt.md +++ /dev/null @@ -1,72 +0,0 @@ -How to Use Open vSwitch with Libvirt - - -This document describes how to use Open vSwitch with Libvirt 0.9.11 or -later. This document assumes that you followed [INSTALL.rst] or installed -Open vSwitch from distribution packaging such as a .deb or .rpm. The Open -vSwitch support is included by default in Libvirt 0.9.11. Consult -www.libvirt.org for instructions on how to build the latest Libvirt, if your -Linux distribution by default comes with an older Libvirt release. - -Limitations -Currently there is no Open vSwitch support for networks that are managed -by libvirt (e.g. NAT). As of now, only bridged networks are supported (those -where the user has to manually create the bridge). - -Setup -- - -First, create the Open vSwitch bridge by using the ovs-vsctl utility (this -must be done with administrative privileges): - -% ovs-vsctl add-br ovsbr - -Once that is done, create a VM, if necessary, and edit its Domain XML file: - -% virsh edit - -Lookup in the Domain XML file the `` section. There should be one -such XML section for each interface the VM has. - -``` - - - - - -``` - -And change it to something like this: - -``` - - - - - - - ``` - -The interface type must be set to "bridge". The `` XML element -specifies to which bridge this interface will be attached to. The -`` element indicates that the bridge in `` element is an -Open vSwitch bridge. - -Then (re)start the VM and verify if the guest's vnet interface is attached to -the ovsbr bridge. - -% ovs-vsctl show - -Troubleshooting -If the VM does not want to start, then try to run the libvirtd process either -from the terminal, so that all errors are printed in console, or inspect -Libvirt/Open vSwitch log files for possible root cause. - -Bug Reporting -- - -Please report problems to b...@openvswitch.org. - -[INSTALL.rst]:INSTALL.rst diff --git a/INSTALL.Libvirt.rst b/INSTALL.Libvirt.rst new file mode 100644 index 000..b32944c --- /dev/null +++ b/INSTALL.Libvirt.rst @@ -0,0 +1,93 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + += +Open vSwitch with Libvirt += + +This document describes how to use Open vSwitch with Libvirt 0.9.11 or later. +This document assumes that you followed the `general installation guide +`__ or installed Open vSwitch from distribution packaging such as +a .deb or .rpm. The Open vSwitch support is included by default in Libvirt +0.9.11. Consult www.libvirt.org for instructions on how to build the latest +Libvirt, if your Linux distribution by default comes with an older Libvirt +release. + +Limitations +--- + +Currently there is no Open vSwitch support for networks that are managed by +libvirt (e.g. NAT). As of now, only bridged networks are supported (those where +the user has to manually create the bridge). + +Setup +- + +First, create the Open vSwitch bridge by using the ovs-vsctl utility (this must +be done with administrative privileges):: + +$ ovs-vsctl add-br ovsbr + +Once that is done, create a VM, if necessary, and edit its Domain XML file:: + +$ virsh edit + +Lookup in the Domain XML file the section. There should be one +such XML section for each interface the VM has:: + + + + + + + +And change it to something like this:: + + + + + + + + +The interface type must be set to ``bridge``. The XML element +specifies to which bridge this interfa
[ovs-dev] [PATCH 12/23] doc: Convert INSTALL.NetBSD to rST
Signed-off-by: Stephen Finucane --- INSTALL.NetBSD.md | 38 - INSTALL.NetBSD.rst | 62 ++ INSTALL.rst| 2 +- Makefile.am| 2 +- 4 files changed, 64 insertions(+), 40 deletions(-) delete mode 100644 INSTALL.NetBSD.md create mode 100644 INSTALL.NetBSD.rst diff --git a/INSTALL.NetBSD.md b/INSTALL.NetBSD.md deleted file mode 100644 index b89201a..000 --- a/INSTALL.NetBSD.md +++ /dev/null @@ -1,38 +0,0 @@ -How to Install Open vSwitch on NetBSD -= - -On NetBSD, you might want to install requirements from pkgsrc. -In that case, you need at least the following packages. - - * automake - * libtool-base - * gmake - * python27 - * py27-six - * py27-xml - * pkg_alternatives - -Some components have additional requirements. (See [INSTALL.rst]) - -Assuming you are running NetBSD/amd64 6.1.2, you can download and -install pre-built binary packages as the following. -(You might get some warnings about minor version mismatch. Don't care.) - -``` -# PKG_PATH=http://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/amd64/6.1.2/All/ -# export PKG_PATH -# pkg_add automake libtool-base gmake python27 py27-six py27-xml pkg_alternatives -``` - -NetBSD's `/usr/bin/make` is not GNU make. GNU make is installed as -`/usr/pkg/bin/gmake` by the above mentioned `gmake` package. - -As all executables installed with pkgsrc are placed in `/usr/pkg/bin/` -directory, it might be a good idea to add it to your PATH. - -Open vSwitch on NetBSD is currently "userspace switch" implementation -in the sense described in [INSTALL.userspace.rst] and [PORTING.rst]. - -[INSTALL.rst]:INSTALL.rst -[INSTALL.userspace.rst]:INSTALL.userspace.rst -[PORTING.rst]:PORTING.rst diff --git a/INSTALL.NetBSD.rst b/INSTALL.NetBSD.rst new file mode 100644 index 000..e204c57 --- /dev/null +++ b/INSTALL.NetBSD.rst @@ -0,0 +1,62 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +== +Open vSwitch on NetBSD +== + +On NetBSD, you might want to install requirements from pkgsrc. In that case, +you need at least the following packages. + +- automake +- libtool-base +- gmake +- python27 +- py27-six +- py27-xml +- pkg_alternatives + +Some components have additional requirements. Refer to the `general +installation guide `__. + +Assuming you are running NetBSD/amd64 6.1.2, you can download and install +pre-built binary packages as the following:: + +$ PKG_PATH=http://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/amd64/6.1.2/All/ +$ export PKG_PATH +$ pkg_add automake libtool-base gmake python27 py27-six py27-xml \ +pkg_alternatives + +.. note:: + You might get some warnings about minor version mismatch. These can be safely + ignored. + +NetBSD's ``/usr/bin/make`` is not GNU make. GNU make is installed as +``/usr/pkg/bin/gmake`` by the above mentioned ``gmake`` package. + +As all executables installed with pkgsrc are placed in ``/usr/pkg/bin/`` +directory, it might be a good idea to add it to your PATH. + +Open vSwitch on NetBSD is currently "userspace switch" implementation in the +sense described in the `userspace installation guide `__ +and `porting guide `__. diff --git a/INSTALL.rst b/INSTALL.rst index 19da164..5c40ab9 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -33,7 +33,7 @@ platform, refer to one of these installation guides: - `Fedora `__ - `RHEL `__ - `XenServer `__ -- `NetBSD `__ +- `NetBSD `__ - `Windows `__ - `DPDK `__ diff --git a/Makefile.am b/Makefile.am index 15846d9..d032cb7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -79,7 +79,7 @@ docs = \ INSTALL.Fedora.rst \ INSTALL.KVM.rst \ INSTALL.Libvirt.rst \ - INSTALL.NetBSD.md \ + INSTALL.NetBSD.rst \ INSTALL.RHEL.md \ INSTALL.SELinux.md \ INSTALL.SSL.rst \ -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 03/23] doc: Convert committer-responsibilities to rST
Signed-off-by: Stephen Finucane
---
Documentation/automake.mk| 2 +-
Documentation/committer-responsibilities.md | 78 --
Documentation/committer-responsibilities.rst | 96
MAINTAINERS.rst | 2 +-
4 files changed, 98 insertions(+), 80 deletions(-)
delete mode 100644 Documentation/committer-responsibilities.md
create mode 100644 Documentation/committer-responsibilities.rst
diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 2f728bd..9008ee2 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -1,5 +1,5 @@
docs += \
- Documentation/committer-responsibilities.md \
+ Documentation/committer-responsibilities.rst \
Documentation/committer-grant-revocation.rst \
Documentation/group-selection-method-property.txt \
Documentation/OVSDB-replication.md \
diff --git a/Documentation/committer-responsibilities.md
b/Documentation/committer-responsibilities.md
deleted file mode 100644
index 40ffb51..000
--- a/Documentation/committer-responsibilities.md
+++ /dev/null
@@ -1,78 +0,0 @@
-Expectations for Developers with Open vSwitch Repo Access
-=
-
-Prerequisites
--
-
-Be familiar with [CodingStyle.md](../CodingStyle.md) and
-[CONTRIBUTING.rst](../CONTRIBUTING.rst).
-
-Review
---
-
-Code (yours or others') must be reviewed publicly (by you or others)
-before you push it to the repository. With one exception (see below),
-every change needs at least one review.
-
-If one or more people know an area of code particularly well, code
-that affects that area should ordinarily get a review from one of
-them.
-
-The riskier, more subtle, or more complicated the change, the more
-careful the review required. When a change needs careful review, use
-good judgment regarding the quality of reviews. If a change adds 1000
-lines of new code, and a review posted 5 minutes later says just
-"Looks good," then this is probably not a quality review.
-
-(The size of a change is correlated with the amount of care needed in
-review, but it is not strictly tied to it. A search and replace
-across many files may not need much review, but one-line optimization
-changes can have widespread implications.)
-
-Your own small changes to fix a recently broken build ("make") or
-tests ("make check"), that you believe to be visible to a large number
-of developers, may be checked in without review. If you are not sure,
-ask for review. If you do push a build fix without review, send the
-patch to ovs-dev afterward as usual, indicating in the email that you
-have already pushed it.
-
-Regularly review submitted code in areas where you have expertise.
-Consider reviewing other code as well.
-
-Git conventions
-
-Do not push merge commits to the Git repository without prior
-discussion on ovs-dev.
-
-If you apply a change (yours or another's) then it is your
-responsibility to handle any resulting problems, especially broken
-builds and other regressions. If it is someone else's change, then
-you can ask the original submitter to address it. Regardless, you
-need to ensure that the problem is fixed in a timely way. The
-definition of "timely" depends on the severity of the problem.
-
-If a bug is present on master and other branches, fix it on master
-first, then backport the fix to other branches. Straightforward
-backports do not require additional review (beyond that for the fix on
-master).
-
-Feature development should be done only on master. Occasionally it
-makes sense to add a feature to the most recent release branch, before
-the first actual release of that branch. These should be handled in
-the same way as bug fixes, that is, first implemented on master and
-then backported.
-
-Keep the authorship of a commit clear by maintaining a correct list of
-"Signed-off-by:"s. If a confusing situation comes up, as it
-occasionally does, bring it up on the mailing list. If you explain
-the use of "Signed-off-by:" to a new developer, explain not just how but
-why, since the intended meaning of "Signed-off-by:" is more important
-than the syntax. As part of your explanation, quote or provide a URL
-to the Developer's Certificate of Origin in
-[CONTRIBUTING.rst](../CONTRIBUTING.rst).
-
-Use Reported-by: and Tested-by: tags in commit messages to indicate
-the source of a bug report.
-
-Keep the [AUTHORS](../AUTHORS) file up to date.
diff --git a/Documentation/committer-responsibilities.rst
b/Documentation/committer-responsibilities.rst
new file mode 100644
index 000..2b0ff6d
--- /dev/null
+++ b/Documentation/committer-responsibilities.rst
@@ -0,0 +1,96 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance
[ovs-dev] [PATCH 14/23] doc: Convert INSTALL.SELinux to rST
Refer to 'dnf' and not the deprecated 'yum'. Signed-off-by: Stephen Finucane --- INSTALL.SELinux.md | 173 --- INSTALL.SELinux.rst | 174 Makefile.am | 2 +- README.rst | 2 +- 4 files changed, 176 insertions(+), 175 deletions(-) delete mode 100644 INSTALL.SELinux.md create mode 100644 INSTALL.SELinux.rst diff --git a/INSTALL.SELinux.md b/INSTALL.SELinux.md deleted file mode 100644 index 7aa048f..000 --- a/INSTALL.SELinux.md +++ /dev/null @@ -1,173 +0,0 @@ -Running Open vSwitch under SELinux -== - -Security-Enhanced Linux (SELinux) is a Linux kernel security -module that limits "the malicious things" that certain processes, -including OVS, can do to the system in case they get compromised. -In our case SELinux basically serves as the "second line of defense" -that limits the things that OVS processes are allowed to do. The -"first line of defense" is proper input validation that eliminates -code paths that could be used by attacker to do any sort of -"escape attacks" (e.g. file name escape, shell escape, command -line argument escape, buffer escape). Since developers don't -always implement proper input validation, then SELinux Access -Control's goal is to confine damage of such attacks, if they -turned out to be possible. - -Besides Type Enforcement there are other SELinux -features, but they are out of scope for this document. - -Currently there are two SELinux policies for Open vSwitch: -1. the one that ships with your Linux distribution (i.e. - selinux-policy-targeted package); And -2. the one that ships with OVS (i.e. openvswitch-selinux-policy - package). - - -Limitations - -If Open vSwitch is directly started from command line, then it -will run under "unconfined_t" SELinux domain that basically lets -daemon to do whatever it likes. This is very important for developers -to understand, because they might introduced code in OVS that invokes -new system calls that SELinux policy did not anticipate. This means -that their feature may have worked out just fine for them. However, -if someone else would try to run the same code when Open vSwitch is -started through systemctl, then Open vSwitch would get Permission Denied -errors. - -Currently the only distributions that enforce SELinux on OVS by -default are RHEL, CentOS and Fedora. While Ubuntu and Debian also -have some SELinux support, they run Open vSwitch under the unrestricted -"unconfined" domain. Also, it seems that Ubuntu is leaning towards -Apparmor that works slightly differently than SELinux. - -SELinux and Open vSwitch are moving targets. What this means -is that, if you solely rely on your Linux distribution's SELinux policy, -then this policy might not have correctly anticipated that a newer -Open vSwitch version needs extra white list rules. However, if you -solely rely on SELinux policy that ships with Open vSwitch, then -Open vSwitch developers might not have correctly anticipated the -feature set that your SELinux implementation supports. - - -Installation - - -Refer to [INSTALL.Fedora.rst] for instructions on how to build all -Open vSwitch rpm packages. - -Once the package is built, install it on your Linux distribution with: - - # yum install openvswitch-selinux-policy-2.4.1-1.el7.centos.noarch.rpm - -And, then restart Open vSwitch: - - # systemctl restart openvswitch - - -Troubleshooting - -When SELinux was implemented some of the standard system utilities -acquired "-Z" flag (e.g. "ps -Z", "ls -Z"). For example, to find out -under which SELinux security domain process runs, use: - - # ps -AZ | grep ovs-vswitchd - system_u:system_r:openvswitch_t:s0 854 ?ovs-vswitchd - -To find out the SELinux label of file or directory, use: - - # ls -Z /etc/openvswitch/conf.db - system_u:object_r:openvswitch_rw_t:s0 /etc/openvswitch/conf.db - - -If, for example, SELinux policy for Open vSwitch is too strict, -then you might see in Open vSwitch log files "Permission Denied" -errors: - -# cat /var/log/openvswitch/ovs-vswitchd.log -vlog|INFO|opened log file /var/log/openvswitch/ovs-vswitchd.log -ovs_numa|INFO|Discovered 2 CPU cores on NUMA node 0 -ovs_numa|INFO|Discovered 1 NUMA nodes and 2 CPU cores -reconnect|INFO|unix:/var/run/openvswitch/db.sock: connecting... -reconnect|INFO|unix:/var/run/openvswitch/db.sock: connected -netlink_socket|ERR|fcntl: Permission denied -dpif_netlink|ERR|Generic Netlink family 'ovs_datapath' does not exist. - The Open vSwitch kernel module is probably not loaded. -dpif|WARN|failed to enumerate system datapaths: Permission denied -dpif|WARN|failed to create datapath ovs-system: Permissio
[ovs-dev] [PATCH 18/23] doc: Update windows/README
This is already in rST (whut?), but we should add a license and make the formatting a little more consistent. Signed-off-by: Stephen Finucane --- windows/README.rst | 72 +- 1 file changed, 50 insertions(+), 22 deletions(-) diff --git a/windows/README.rst b/windows/README.rst index 37fb98d..bdf063a 100644 --- a/windows/README.rst +++ b/windows/README.rst @@ -1,48 +1,76 @@ -Open vSwitch Windows installer -== +.. + 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 -This project generates a MSI installer for Open vSwitch on Windows, including -CLI executables, services and the Hyper-V vswitch forwarding extension. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +== +Windows README +== + +This directory contains tooling to generate an MSI installer for Open vSwitch +on Windows, including CLI executables, services and the Hyper-V vswitch +forwarding extension. Requirements -Visual Studio 2013 community, professional, premium or ultimate edition -^^^ +* Visual Studio 2013 + + Community, Professional, Premium or Ultimate editions can be used. -Visual Studio Community 2013 is freely available at: -https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx + Visual Studio Community 2013 is freely available from `visualstudio.com + <https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx>`__ -WiX Toolset 3.9 -^^^ +* WiX Toolset 3.9 -Download and install from: -http://wixtoolset.org/releases/v3.9/stable + Download and install from `wixtoolset.org + <http://wixtoolset.org/releases/v3.9/stable>`__ -Microsoft_VC120_CRT_x86.msm -^^^ +* ``Microsoft_VC120_CRT_x86.msm`` -This Windows merge module is available with Visual Studio and contains the -Visual C++ 2013 x86 runtime redistributables files. -Copy the file in the *Redist* directory. + This Windows merge module is available with Visual Studio and contains the + Visual C++ 2013 x86 runtime redistributables files. Copy the file in the + ``Redist`` directory. Open vSwitch installer -- -The installer will be generated under the following path: -* windows\ovs-windows-installer\bin\Release\OpenvSwitch.msi +The installer will be generated under the following path:: -Note: the kernel driver needs to be signed. +windows\ovs-windows-installer\bin\Release\OpenvSwitch.msi +.. note:: -Build instructions + The kernel driver needs to be signed. + +Build Instructions -- -Build the solution in the Visual Studio IDE or via command line: +Build the solution in the Visual Studio IDE or via command line:: msbuild ovs-windows-installer.sln /p:Platform=x86 /p:Configuration=Release Silent installation --- +:: + msiexec /i OpenvSwitch.msi ADDLOCAL=OpenvSwitchCLI,OpenvSwitchDriver /l*v log.txt -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 15/23] doc: Convert INSTALL.DPDK-ADVANCED to rST
Signed-off-by: Stephen Finucane --- INSTALL.DPDK-ADVANCED.md | 898 INSTALL.DPDK-ADVANCED.rst | 938 ++ INSTALL.DPDK.rst | 10 +- Makefile.am | 2 +- 4 files changed, 944 insertions(+), 904 deletions(-) delete mode 100644 INSTALL.DPDK-ADVANCED.md create mode 100644 INSTALL.DPDK-ADVANCED.rst diff --git a/INSTALL.DPDK-ADVANCED.md b/INSTALL.DPDK-ADVANCED.md deleted file mode 100644 index 0d6bcfa..000 --- a/INSTALL.DPDK-ADVANCED.md +++ /dev/null @@ -1,898 +0,0 @@ -OVS DPDK ADVANCED INSTALL GUIDE -=== - -## Contents - -1. [Overview](#overview) -2. [Building Shared Library](#build) -3. [System configuration](#sysconf) -4. [Performance Tuning](#perftune) -5. [OVS Testcases](#ovstc) -6. [Vhost Walkthrough](#vhost) -7. [QOS](#qos) -8. [Rate Limiting](#rl) -9. [Flow Control](#fc) -10. [Pdump](#pdump) -11. [Jumbo Frames](#jumbo) -12. [Vsperf](#vsperf) - -## 1. Overview - -The Advanced Install Guide explains how to improve OVS performance using -DPDK datapath. This guide also provides information on tuning, system configuration, -troubleshooting, static code analysis and testcases. - -## 2. Building Shared Library - -DPDK can be built as static or shared library and shall be linked by applications -using DPDK datapath. The section lists steps to build shared library and dynamically -link DPDK against OVS. - -Note: Minor performance loss is seen with OVS when using shared DPDK library as -compared to static library. - -Check section [INSTALL DPDK], [INSTALL OVS] of INSTALL.DPDK on download instructions -for DPDK and OVS. - - * Configure the DPDK library - - Set `CONFIG_RTE_BUILD_SHARED_LIB=y` in `config/common_base` - to generate shared DPDK library - - - * Build and install DPDK - -For Default install (without IVSHMEM), set `export DPDK_TARGET=x86_64-native-linuxapp-gcc` -For IVSHMEM case, set `export DPDK_TARGET=x86_64-ivshmem-linuxapp-gcc` - -``` -export DPDK_DIR=/usr/src/dpdk-16.07 -export DPDK_BUILD=$DPDK_DIR/$DPDK_TARGET -make install T=$DPDK_TARGET DESTDIR=install -``` - - * Build, Install and Setup OVS. - - Export the DPDK shared library location and setup OVS as listed in - section 3.3 of INSTALL.DPDK. - - `export LD_LIBRARY_PATH=$DPDK_DIR/x86_64-native-linuxapp-gcc/lib` - -## 3. System Configuration - -To achieve optimal OVS performance, the system can be configured and that includes -BIOS tweaks, Grub cmdline additions, better understanding of NUMA nodes and -apt selection of PCIe slots for NIC placement. - -### 3.1 Recommended BIOS settings - - ``` - | Settings | values| comments - |---|---|--- - | C3 power state| Disabled | - - | C6 power state| Disabled | - - | MLC Streamer | Enabled | - - | MLC Spacial prefetcher| Enabled | - - | DCU Data prefetcher | Enabled | - - | DCA | Enabled | - - | CPU power and performance | Performance - - | Memory RAS and perf | | - -config-> NUMA optimized | Enabled | - - ``` - -### 3.2 PCIe Slot Selection - -The fastpath performance also depends on factors like the NIC placement, -Channel speeds between PCIe slot and CPU, proximity of PCIe slot to the CPU -cores running DPDK application. Listed below are the steps to identify -right PCIe slot. - -- Retrieve host details using cmd `dmidecode -t baseboard | grep "Product Name"` -- Download the technical specification for Product listed eg: S2600WT2. -- Check the Product Architecture Overview on the Riser slot placement, - CPU sharing info and also PCIe channel speeds. - - example: On S2600WT, CPU1 and CPU2 share Riser Slot 1 with Channel speed between - CPU1 and Riser Slot1 at 32GB/s, CPU2 and Riser Slot1 at 16GB/s. Running DPDK app - on CPU1 cores and NIC inserted in to Riser card Slots will optimize OVS performance - in this case. - -- Check the Riser Card #1 - Root Port mapping information, on the available slots - and individual bus speeds. In S2600WT slot 1, slot 2 has high bus speeds and are - potential slots for NIC placement. - -### 3.3 Advanced Hugepage setup - - Allocate and mount 1G Huge pages: - - - For persistent allocation of huge pages, add the following options to the kernel bootline - - Add `default_hugepagesz=1GB hugepagesz=1G hugepages=N` - - For platforms supporting multiple huge page sizes, Add options - - `default_hugepagesz= hugepagesz= hugepages=N` - where 'N' = Number of huge pages requested, 'size' = huge page size, - optional suffix [kKmMgG] - - - For run-time allocation of huge pages - - `echo N > /sys/devices/system/node/nodeX/hugepages/hugepages-1048576kB/nr_hugepages` - where 'N' = Number of huge pages requested, 'X' = NUM
[ovs-dev] [PATCH 17/23] doc: Convert xenserver/README to rST
Signed-off-by: Stephen Finucane --- xenserver/README | 186 -- xenserver/README.rst | 175 +++ xenserver/automake.mk | 2 +- 3 files changed, 176 insertions(+), 187 deletions(-) delete mode 100644 xenserver/README create mode 100644 xenserver/README.rst diff --git a/xenserver/README b/xenserver/README deleted file mode 100644 index 87378d0..000 --- a/xenserver/README +++ /dev/null @@ -1,186 +0,0 @@ -This directory contains files for seamless integration of Open vSwitch on -Citrix XenServer hosts managed by the Citrix management tools. - -Files in this directory are licensed on a file-by-file basis. Please -refer to each file for details. - -Most of the files in this directory are installed on a XenServer system -under the same name; underscores are replaced by slashes. The files are: - -etc_init.d_openvswitch - -Initializes Open vSwitch at boot and shuts it down at shutdown. - -etc_init.d_openvswitch-xapi-update - -Init script to ensure openvswitch-cfg-update is called for the -current host at boot. - -etc_logrotate.d_openvswitch - -Ensures that logs in /var/log/openvswitch are rotated -periodically and that appropriate daemons reopen their log -files at that point. - -etc_profile.d_openvswitch.sh - -Open vSwitch-related shell functions for the administrator's -convenience. - -etc_xapi.d_plugins_openvswitch-cfg-update - -xapi plugin script to update the cache of configuration items -in the ovs-vswitchd configuration that are managed in the -xapi database when integrated with Citrix management tools. - -etc_xensource_scripts_vif - -Open vSwitch-aware replacement for Citrix script of the same name. - -openvswitch-xen.spec - -spec file for building RPMs to install on a XenServer host. - -opt_xensource_libexec_interface-reconfigure -opt_xensource_libexec_InterfaceReconfigureBridge.py -opt_xensource_libexec_InterfaceReconfigure.py -opt_xensource_libexec_InterfaceReconfigureVswitch.py - -Open vSwitch-aware replacements for Citrix script of the same -names. - -usr_lib_xsconsole_plugins-base_XSFeatureVSwitch.py - -xsconsole plugin to configure the pool-wide configuration keys -used to control Open vSwitch when integrated with Citrix -management tools. - -usr_share_openvswitch_scripts_ovs-xapi-sync - -Daemon to monitor the external_ids columns of the Bridge and -Interface OVSDB tables for changes that require interrogating -XAPI. - -usr_share_openvswitch_scripts_sysconfig.template - -Template for Open vSwitch's /etc/sysconfig/openvswitch -configuration file. - -Open vSwitch installs a number of xen-bugtool extensions in -/etc/xensource/bugtool to gather additional information useful for -debugging. The sources for the extensions are in -../utilities/bugtool/plugins: - -kernel-info/openvswitch.xml - -Collect kernel information relevant to Open vSwitch, such as -slabinfo. - -network-status/openvswitch.xml - -Collect networking information relevant to Open vSwitch. Runs -the following scripts, which are described below: - -* ovs-bugtool-bfd-show -* ovs-bugtool-cfm-show -* ovs-bugtool-fdb-show -* ovs-bugtool-lacp-show -* ovs-bugtool-list-dbs -* ovs-bugtool-ovsdb-dump -* ovs-bugtool-tc-class-show -* ovs-bugtool-bond-show -* ovs-bugtool-ovs-ofctl-show -* ovs-bugtool-ovs-ofctl-dump-flows -* ovs-bugtool-ovs-appctl-dpif -* ovs-bugtool-coverage-show -* ovs-bugtool-memory-show -* ovs-bugtool-vsctl-show -* ovs-bugtool-conntrack-dump - -system-configuration/openvswitch.xml - -Collect system configuration information relevant to Open vSwitch, -including timezone. Runs the following script which is described -below: - -* ovs-bugtool-daemons-ver - -system-configuration.xml - -Collect system configuration data. This category is configured -to collect up to 1Mb of data, take up to 60 seconds to collect -data, run every time and is hidden from display in XenCenter. - -A number of scripts are installed in /usr/share/openvswitch/scripts to -assist Open vSwitch's xen-bugtool extensions. The sources for the -scripts are located in ../utilities/bugtool: - -ovs-bugtool-bfd-show - -Script to dump detailed BFD information for all enabled interfaces. - -ovs-bugtool-cfm-show - -Script to dump detailed CFM information for all enabled interfaces. - -ovs-bugtool-fdb-show - -Script to collect a summary of learned MACs for each bridge. - -ovs-bugtool-lacp-show -
[ovs-dev] [PATCH 07/23] doc: Convert third-party/README to rST
Signed-off-by: Stephen Finucane --- third-party/README.md | 38 third-party/README.rst | 66 + third-party/automake.mk | 2 +- 3 files changed, 67 insertions(+), 39 deletions(-) delete mode 100644 third-party/README.md create mode 100644 third-party/README.rst diff --git a/third-party/README.md b/third-party/README.md deleted file mode 100644 index d351d77..000 --- a/third-party/README.md +++ /dev/null @@ -1,38 +0,0 @@ -Third-party software integration - - -This directory contains third-party software that may be useful for -debugging. - -tcpdump -The "ofp-tcpdump.patch" patch adds the ability to parse OpenFlow -messages to tcpdump. These instructions assume that tcpdump 4.3.0 -is going to be used, but it should work with other versions that are not -substantially different. To begin, download tcpdump and apply the -patch: - -wget http://www.tcpdump.org/release/tcpdump-4.3.0.tar.gz -tar xzf tcpdump-4.3.0.tar.gz -ln -s tcpdump-4.3.0 tcpdump -patch -p0 < ofp-tcpdump.patch - -Then build the new version of tcpdump: - -cd tcpdump -./configure -make - -Clearly, tcpdump can only parse unencrypted packets, so you will need to -connect the controller and datapath using plain TCP. To look at the -traffic, tcpdump will be started in a manner similar to the following: - -sudo ./tcpdump -s0 -i eth0 port 6653 - -The "-s0" flag indicates that tcpdump should capture the entire packet. -If the OpenFlow message is not received in its entirety, "[|openflow]" will -be printed instead of the OpenFlow message contents. - -The verbosity of the output may be increased by adding additional "-v" -flags. If "-vvv" is used, the raw OpenFlow data is also printed in -hex and ASCII. diff --git a/third-party/README.rst b/third-party/README.rst new file mode 100644 index 000..9d536c3 --- /dev/null +++ b/third-party/README.rst @@ -0,0 +1,66 @@ +.. + 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. + + Convention for heading levels in Open vSwitch documentation: + + === Heading 0 (reserved for the title in a document) + --- Heading 1 + ~~~ Heading 2 + +++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + + +Third-party software integration + + +This directory contains third-party software that may be useful for debugging. + +tcpdump +--- + +The ``ofp-tcpdump.patch`` patch adds the ability to parse OpenFlow messages to +tcpdump. These instructions assume that tcpdump 4.3.0 is going to be used, but +it should work with other versions that are not substantially different. To +begin, download tcpdump and apply the patch: + +:: + +$ wget http://www.tcpdump.org/release/tcpdump-4.3.0.tar.gz +$ tar xzf tcpdump-4.3.0.tar.gz +$ ln -s tcpdump-4.3.0 tcpdump +$ patch -p0 < ofp-tcpdump.patch + +Then build the new version of tcpdump: + +:: + +$ cd tcpdump +$ ./configure +$ make + +Clearly, tcpdump can only parse unencrypted packets, so you will need to +connect the controller and datapath using plain TCP. To look at the traffic, +tcpdump will be started in a manner similar to the following: + +:: + +$ sudo ./tcpdump -s0 -i eth0 port 6653 + +The ``-s0`` flag indicates that tcpdump should capture the entire packet. If +the OpenFlow message is not received in its entirety, ``[|openflow]`` will be +printed instead of the OpenFlow message contents. + +The verbosity of the output may be increased by adding additional ``-v`` flags. +If ``-vvv`` is used, the raw OpenFlow data is also printed in hex and ASCII. diff --git a/third-party/automake.mk b/third-party/automake.mk index fea5ac7..9eaf02f 100644 --- a/third-party/automake.mk +++ b/third-party/automake.mk @@ -1,2 +1,2 @@ -docs += third-party/README.md +docs += third-party/README.rst EXTRA_DIST += third-party/ofp-tcpdump.patch -- 2.7.4 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 19/23] doc: Convert datapath-windows/CodingStyle to rST
Signed-off-by: Stephen Finucane
---
datapath-windows/CodingStyle | 154
datapath-windows/CodingStyle.rst | 183 +++
datapath-windows/automake.mk | 2 +-
3 files changed, 184 insertions(+), 155 deletions(-)
delete mode 100644 datapath-windows/CodingStyle
create mode 100644 datapath-windows/CodingStyle.rst
diff --git a/datapath-windows/CodingStyle b/datapath-windows/CodingStyle
deleted file mode 100644
index 40873e8..000
--- a/datapath-windows/CodingStyle
+++ /dev/null
@@ -1,154 +0,0 @@
- Open vSwitch Windows Datapath Coding Style
- ==
-
-The coding style described in the Open vSwitch distribution gives the
-flexiblity for each platform to use its own coding style for the kernel
-datapath. This file describes the specific coding style used in most
-of the C files in the Windows kernel datapath of the Open vSwitch distribution.
-
-Most of the coding conventions applicable for the Open vSwitch distribution are
-applicable to the Windows kernel datapath as well. There are some exceptions
-and new guidlines owing to the commonly followed practices in Windows
-kernel/driver code. They are noted as follows:
-
-
-BASICS
-
- Limit lines to 79 characters. Many times, this is not possible due to long
-names of functions and it is fine to go beyond the characters limit. One
-common example is when calling into NDIS functions.
-
-
-TYPES
- Use data types defined by Windows for most of the code. This is a common
-practice in Windows driver code, and it makes integrating with the data
-structures and functions defined by Windows easier. Example: DWORD and
-BOOLEAN.
-
- Use caution in portions of the code that interface with the OVS userspace.
-OVS userspace does not use Windows specific data types, and when copying data
-back and forth between kernel and userspace, care should be exercised.
-
-
-NAMING
-
- It is common practice to use camel casing for naming variables, functions
-and files in Windows. For types, especially structures, unions and enums,
-using all upper case letters with words seprated by '_' is common. These
-practices can be used for OVS Windows datapath. However, use the following
-guidelines:
-
- Use lower case to begin the name of a variable.
-
- Do not use '_' to begin the name of the variable. '_' is to be used to begin
- the parameters of a pre-processor macro.
-
- Use upper case to begin the name of a function, enum, file name etc.
-
- Static functions whose scope is limited to the file they are defined in can
- be prefixed with '_'. This is not mandatory though.
-
- For types, use all upper case for all letters with words separated by '_'. If
- camel casing is preferred, use upper case for the first letter.
-
- It is a common practice to define a pointer type by prefixing the letter
-'P' to a data type. The same practice can be followed here as well.
-
- Example:
-
-static __inline BOOLEAN
-OvsDetectTunnelRxPkt(POVS_FORWARDING_CONTEXT ovsFwdCtx,
- POVS_FLOW_KEY flowKey)
-{
-POVS_VPORT_ENTRY tunnelVport = NULL;
-
-if (!flowKey->ipKey.nwFrag &&
-flowKey->ipKey.nwProto == IPPROTO_UDP &&
-flowKey->ipKey.l4.tpDst == VXLAN_UDP_PORT_NBO) {
-tunnelVport = OvsGetTunnelVport(OVSWIN_VPORT_TYPE_VXLAN);
-ovsActionStats.rxVxlan++;
-} else {
-return FALSE;
-}
-
-if (tunnelVport) {
-ASSERT(ovsFwdCtx->tunnelRxNic == NULL);
-ovsFwdCtx->tunnelRxNic = tunnelVport;
-return TRUE;
-}
-
-return FALSE;
-}
-
- For declaring variables of pointer type, use of the pointer data type
-prefixed with 'P' is preferred over using '*'. This is not mandatory though,
-and is only prescribed since it is a common practice in Windows.
-
- Example, #1 is preferred over #2 though #2 is also equally correct:
- 1. PNET_BUFFER_LIST curNbl;
- 2. NET_BUFFER_LIST *curNbl;
-
-COMMENTS
-
- Comments should be written as full sentences that start with a
-capital letter and end with a period. Putting two spaces between sentances is
-not necessary.
-
- // can be used for comments as long as the comment is a single line comment.
-For block comments, use /* */ comments
-
-
-FUNCTIONS
-
- Put the return type, function name, and the braces that surround the
-function's code on separate lines, all starting in column 0.
-
- Before each function definition, write a comment that describes the
-function's purpose, including each parameter, the return value, and
-side effects. References to argument names should be given in
-single-quotes, e.g. 'arg'. The comment should not include the
-function name, nor need it follow any formal structure. The comment
-does not need to describe how a function does its work, unless this
-information is needed to
[ovs-dev] [PATCH 20/23] doc: Convert datapath-windows/DESIGN to rST
Signed-off-by: Stephen Finucane
---
datapath-windows/{DESIGN => DESIGN.rst} | 503 ++--
datapath-windows/automake.mk| 2 +-
2 files changed, 279 insertions(+), 226 deletions(-)
rename datapath-windows/{DESIGN => DESIGN.rst} (54%)
diff --git a/datapath-windows/DESIGN b/datapath-windows/DESIGN.rst
similarity index 54%
rename from datapath-windows/DESIGN
rename to datapath-windows/DESIGN.rst
index 6d30adc..81c1da5 100644
--- a/datapath-windows/DESIGN
+++ b/datapath-windows/DESIGN.rst
@@ -1,38 +1,57 @@
- OVS-on-Hyper-V Design Document
- ==
-There has been a community effort to develop Open vSwitch on Microsoft Hyper-V.
-In this document, we provide details of the development effort. We believe this
-document should give enough information to understand the overall design.
-
-The userspace portion of the OVS has been ported to Hyper-V in a separate
-effort, and committed to the openvswitch repo. So, this document will mostly
-emphasize on the kernel driver, though we touch upon some of the aspects of
-userspace as well.
-
-We cover the following topics:
-1. Background into relevant Hyper-V architecture
-2. Design of the OVS Windows implementation
- a. Kernel module (datapath)
- b. Userspace components
- c. Kernel-Userspace interface
- d. Flow of a packet
-3. Build/Deployment environment
-
-For more questions, please contact dev@openvswitch.org
-
-1) Background into relevant Hyper-V architecture
-
-Microsoft’s hypervisor solution - Hyper-V[1] implements a virtual switch that
-is extensible and provides opportunities for other vendors to implement
-functional extensions[2]. The extensions need to be implemented as NDIS drivers
-that bind within the extensible switch driver stack provided. The extensions
-can broadly provide the functionality of monitoring, modifying and forwarding
-packets to destination ports on the Hyper-V extensible switch. Correspondingly,
-the extensions can be categorized into the following types and provide the
-functionality noted:
- * Capturing extensions: monitoring packets
- * Filtering extensions: monitoring, modifying packets
- * Forwarding extensions: monitoring, modifying, forwarding packets
+..
+ 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.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ === Heading 0 (reserved for the title in a document)
+ --- Heading 1
+ ~~~ Heading 2
+ +++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+=
+OVS-on-Hyper-V Design
+=
+
+This document provides details of the effort to develop Open vSwitch on
+Microsoft Hyper-V. This document should give enough information to understand
+the overall design.
+
+.. note::
+ The userspace portion of the OVS has been ported to Hyper-V in a separate
+ effort, and committed to the openvswitch repo. This document will mostly
+ emphasize on the kernel driver, though we touch upon some of the aspects of
+ userspace as well.
+
+Background Info
+---
+
+Microsoft’s hypervisor solution - Hyper-V [1]_ implements a virtual switch
+that is extensible and provides opportunities for other vendors to implement
+functional extensions [2]_. The extensions need to be implemented as NDIS
+drivers that bind within the extensible switch driver stack provided. The
+extensions can broadly provide the functionality of monitoring, modifying and
+forwarding packets to destination ports on the Hyper-V extensible switch.
+Correspondingly, the extensions can be categorized into the following types and
+provide the functionality noted:
+
+* Capturing extensions: monitoring packets
+
+* Filtering extensions: monitoring, modifying packets
+
+* Forwarding extensions: monitoring, modifying, forwarding packets
As can be expected, the kernel portion (datapath) of OVS on Hyper-V solution
will be implemented as a forwarding extension.
@@ -44,68 +63,69 @@ is used for packets being sent out of a port, and egress is
used for packet
being received on a port. By design, NDIS provides a layered interface. In this
layered interface, higher level layers call into lower level layers, in the
ingress path. In the egress pat
[ovs-dev] [PATCH 21/23] doc: Convert CONTAINERS.OpenStack to rST
Signed-off-by: Stephen Finucane --- ovn/CONTAINERS.OpenStack.md | 122 -- ovn/CONTAINERS.OpenStack.rst | 135 +++ ovn/automake.mk | 2 +- 3 files changed, 136 insertions(+), 123 deletions(-) delete mode 100644 ovn/CONTAINERS.OpenStack.md create mode 100644 ovn/CONTAINERS.OpenStack.rst diff --git a/ovn/CONTAINERS.OpenStack.md b/ovn/CONTAINERS.OpenStack.md deleted file mode 100644 index 8f74e6f..000 --- a/ovn/CONTAINERS.OpenStack.md +++ /dev/null @@ -1,122 +0,0 @@ -Integration of Containers with OVN and OpenStack - - -Isolation between containers is weaker than isolation between VMs, so -some environments deploy containers for different tenants in separate -VMs as an additional security measure. This document describes creation of -containers inside VMs and how they can be made part of the logical networks -securely. The created logical network can include VMs, containers and -physical machines as endpoints. To better understand the proposed integration -of containers with OVN and OpenStack, this document describes the end to end -workflow with an example. - -* A OpenStack tenant creates a VM (say VM-A) with a single network interface -that belongs to a management logical network. The VM is meant to host -containers. OpenStack Nova chooses the hypervisor on which VM-A is created. - -* A Neutron port may have been created in advance and passed in to Nova -with the request to create a new VM. If not, Nova will issue a request -to Neutron to create a new port. The ID of the logical port from -Neutron will also be used as the vif-id for the virtual network -interface (VIF) of VM-A. - -* When VM-A is created on a hypervisor, its VIF gets added to the -Open vSwitch integration bridge. This creates a row in the Interface table -of the Open_vSwitch database. As explained in the [IntegrationGuide.rst], -the vif-id associated with the VM network interface gets added in the -external_ids:iface-id column of the newly created row in the Interface table. - -* Since VM-A belongs to a logical network, it gets an IP address. This IP -address is used to spawn containers (either manually or through container -orchestration systems) inside that VM and to monitor the health of the -created containers. - -* The vif-id associated with the VM's network interface can be obtained by -making a call to Neutron using tenant credentials. - -* This flow assumes a component called a "container network plugin". -If you take Docker as an example for containers, you could envision -the plugin to be either a wrapper around Docker or a feature of Docker itself -that understands how to perform part of this workflow to get a container -connected to a logical network managed by Neutron. The rest of the flow -refers to this logical component that does not yet exist as the -"container network plugin". - -* All the calls to Neutron will need tenant credentials. These calls can -either be made from inside the tenant VM as part of a container network plugin -or from outside the tenant VM (if the tenant is not comfortable using temporary -Keystone tokens from inside the tenant VMs). For simplicity, this document -explains the work flow using the former method. - -* The container hosting VM will need Open vSwitch installed in it. The only -work for Open vSwitch inside the VM is to tag network traffic coming from -containers. - -* When a container needs to be created inside the VM with a container network -interface that is expected to be attached to a particular logical switch, the -network plugin in that VM chooses any unused VLAN (This VLAN tag only needs to -be unique inside that VM. This limits the number of container interfaces to -4096 inside a single VM). This VLAN tag is stripped out in the hypervisor -by OVN and is only useful as a context (or metadata) for OVN. - -* The container network plugin then makes a call to Neutron to create a -logical port. In addition to all the inputs that a call to create a port in -Neutron that are currently needed, it sends the vif-id and the VLAN tag as -inputs. - -* Neutron in turn will verify that the vif-id belongs to the tenant in question -and then uses the OVN specific plugin to create a new row in the -Logical_Switch_Port table of the OVN Northbound Database. Neutron -responds back with an IP address and MAC address for that network -interface. So Neutron becomes the IPAM system and provides unique IP -and MAC addresses across VMs and containers in the same logical network. - -* The Neutron API call above to create a logical port for the container -could add a relatively significant amount of time to container creation. -However, an optimization is possible here. Logical ports could be -created in advance and reused by the container system doing container -orchestration. Additional Neutron API calls would only be
[ovs-dev] [PATCH 23/23] doc: Convert vswitchd/INTERNALS to rST
Signed-off-by: Stephen Finucane
---
lib/mac-learning.c | 3 +-
lib/mac-learning.h | 2 +-
vswitchd/INTERNALS | 239
vswitchd/INTERNALS.rst | 244 +
vswitchd/automake.mk | 2 +-
5 files changed, 248 insertions(+), 242 deletions(-)
delete mode 100644 vswitchd/INTERNALS
create mode 100644 vswitchd/INTERNALS.rst
diff --git a/lib/mac-learning.c b/lib/mac-learning.c
index 5509f22..57b81f4 100644
--- a/lib/mac-learning.c
+++ b/lib/mac-learning.c
@@ -411,7 +411,8 @@ update_learning_table__(struct mac_learning *ml, struct
eth_addr src,
* packet was received over a non-bond interface and refrain from
* learning from gratuitous ARP packets that arrive over bond
* interfaces for this entry while the lock is in effect. See
- * vswitchd/INTERNALS for more in-depth discussion on this topic. */
+ * vswitchd/INTERNALS.rst for more in-depth discussion on this
+ * topic. */
if (!is_bond) {
mac_entry_set_grat_arp_lock(mac);
} else if (mac_entry_is_grat_arp_locked(mac)) {
diff --git a/lib/mac-learning.h b/lib/mac-learning.h
index d380690..e427815 100644
--- a/lib/mac-learning.h
+++ b/lib/mac-learning.h
@@ -47,7 +47,7 @@
* Second, the implementation has the ability to "lock" a MAC table entry
* updated by a gratuitous ARP. This is a simple feature but the rationale for
* it is complicated. Please refer to the description of SLB bonding in
- * vswitchd/INTERNALS for an explanation.
+ * vswitchd/INTERNALS.rst for an explanation.
*
* Third, the implementation expires entries that are idle for longer than a
* configurable amount of time. This is implemented by keeping all of the
diff --git a/vswitchd/INTERNALS b/vswitchd/INTERNALS
deleted file mode 100644
index 994353d..000
--- a/vswitchd/INTERNALS
+++ /dev/null
@@ -1,239 +0,0 @@
-
-ovs-vswitchd Internals
-
-
-This document describes some of the internals of the ovs-vswitchd
-process. It is not complete. It tends to be updated on demand, so if
-you have questions about the vswitchd implementation, ask them and
-perhaps we'll add some appropriate documentation here.
-
-Most of the ovs-vswitchd implementation is in vswitchd/bridge.c, so
-code references below should be assumed to refer to that file except
-as otherwise specified.
-
-Bonding
-===
-
-Bonding allows two or more interfaces (the "slaves") to share network
-traffic. From a high-level point of view, bonded interfaces act like
-a single port, but they have the bandwidth of multiple network
-devices, e.g. two 1 GB physical interfaces act like a single 2 GB
-interface. Bonds also increase robustness: the bonded port does not
-go down as long as at least one of its slaves is up.
-
-In vswitchd, a bond always has at least two slaves (and may have
-more). If a configuration error, etc. would cause a bond to have only
-one slave, the port becomes an ordinary port, not a bonded port, and
-none of the special features of bonded ports described in this section
-apply.
-
-There are many forms of bonding of which ovs-vswitchd implements only
-a few. The most complex bond ovs-vswitchd implements is called
-"source load balancing" or SLB bonding. SLB bonding divides traffic
-among the slaves based on the Ethernet source address. This is useful
-only if the traffic over the bond has multiple Ethernet source
-addresses, for example if network traffic from multiple VMs are
-multiplexed over the bond.
-
-Enabling and Disabling Slaves
--
-
-When a bond is created, a slave is initially enabled or disabled based
-on whether carrier is detected on the NIC (see iface_create()). After
-that, a slave is disabled if its carrier goes down for a period of
-time longer than the downdelay, and it is enabled if carrier comes up
-for longer than the updelay (see bond_link_status_update()). There is
-one exception where the updelay is skipped: if no slaves at all are
-currently enabled, then the first slave on which carrier comes up is
-enabled immediately.
-
-The updelay should be set to a time longer than the STP forwarding
-delay of the physical switch to which the bond port is connected (if
-STP is enabled on that switch). Otherwise, the slave will be enabled,
-and load may be shifted to it, before the physical switch starts
-forwarding packets on that port, which can cause some data to be
-"blackholed" for a time. The exception for a single enabled slave
-does not cause any problem in this regard because when no slaves are
-enabled all output packets are blackholed anyway.
-
-When a slave becomes disabled, the vswitch immediately chooses a new
-output port for traffic that was destined for that slave (see
-bond_enable_sl
[ovs-dev] [PATCH 22/23] doc: Convert OVS-GW-HA to rST
Signed-off-by: Stephen Finucane
---
ovn/{OVN-GW-HA.md => OVN-GW-HA.rst} | 309 +---
ovn/TODO| 2 +-
ovn/automake.mk | 2 +-
3 files changed, 182 insertions(+), 131 deletions(-)
rename ovn/{OVN-GW-HA.md => OVN-GW-HA.rst} (71%)
diff --git a/ovn/OVN-GW-HA.md b/ovn/OVN-GW-HA.rst
similarity index 71%
rename from ovn/OVN-GW-HA.md
rename to ovn/OVN-GW-HA.rst
index b26ee68..5b21b64 100644
--- a/ovn/OVN-GW-HA.md
+++ b/ovn/OVN-GW-HA.rst
@@ -1,6 +1,34 @@
+..
+ 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.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ === Heading 0 (reserved for the title in a document)
+ --- Heading 1
+ ~~~ Heading 2
+ +++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+==
OVN Gateway High Availability Plan
==
-```
+
+::
+
+OVN Gateway
+
+---+
| |
| External Network |
@@ -22,9 +50,6 @@ OVN Gateway High Availability Plan
| |
+---+
-OVN Gateway
-```
-
The OVN gateway is responsible for shuffling traffic between the tunneled
overlay network (governed by ovn-northd), and the legacy physical network. In
a naive implementation, the gateway is a single x86 server, or hardware VTEP.
@@ -43,6 +68,7 @@ proposal, not a set-in-stone decree.
Basic Architecture
--
+
In an OVN deployment, the set of hypervisors and network elements operating
under the guidance of ovn-northd are in what's called "logical space". These
servers use VXLAN, STT, or Geneve to communicate, oblivious to the details of
@@ -52,45 +78,46 @@ OVN controlled tunnel traffic, to raw physical network
traffic.
Since the gateway is typically the only system with a connection to the
physical network all traffic between logical space and the WAN must travel
-through it. This makes it a critical single point of failure -- if
-the gateway dies, communication with the WAN ceases for all systems in logical
-space.
+through it. This makes it a critical single point of failure -- if the gateway
+dies, communication with the WAN ceases for all systems in logical space.
To mitigate this risk, multiple gateways should be run in a "High Availability
Cluster" or "HA Cluster". The HA cluster will be responsible for performing
the duties of a gateways, while being able to recover gracefully from
individual member failures.
-```
- +---+
- | |
- | External Network |
- | |
- +-^-+
- |
- |
-+--v--+
-| |
-| High Availability Cluster |
-| |
-| +---+ +---+ +---+ |
-| | | | | | | |
-| | Gateway | | Gateway | | Gateway | |
-| | | | | | | |
-| +---+ +---+ +---+ |
-+--^--+
- |
- |
- +-v-+
- | |
- |OVN Virtual Network|
- | |
- +---+
+::
+
+OVN Gateway HA Cluster
+
+ +---+
+ | |
+ | External Network |
+ | |
+ +-^-+
+ |
+ |
++--v--+
+| |
+| High Availability Cluster |
+| |
+| +---+ +---+ +---+ |
+
[ovs-dev] [PATCH 13/23] doc: Convert INSTALL.RHEL to rST
Signed-off-by: Stephen Finucane
---
INSTALL.Docker.rst | 2 +-
INSTALL.RHEL.md| 171 ---
INSTALL.RHEL.rst | 208 +
INSTALL.rst| 2 +-
Makefile.am| 2 +-
README.rst | 2 +-
6 files changed, 212 insertions(+), 175 deletions(-)
delete mode 100644 INSTALL.RHEL.md
create mode 100644 INSTALL.RHEL.rst
diff --git a/INSTALL.Docker.rst b/INSTALL.Docker.rst
index 35dcce2..236857a 100644
--- a/INSTALL.Docker.rst
+++ b/INSTALL.Docker.rst
@@ -290,7 +290,7 @@ The "underlay" mode
Depending on your VM, you can make the above step persistent across reboots.
For example, if your VM is Debian/Ubuntu-based, read
`openvswitch-switch.README.Debian` found in `debian` folder. If your VM is
- RHEL-based, refer to the `RHEL install guide <../../INSTALL.RHEL.md>`__.
+ RHEL-based, refer to the `RHEL install guide <../../INSTALL.RHEL.rst>`__.
3. Start the Open vSwitch network driver
diff --git a/INSTALL.RHEL.md b/INSTALL.RHEL.md
deleted file mode 100644
index de33a46..000
--- a/INSTALL.RHEL.md
+++ /dev/null
@@ -1,171 +0,0 @@
-How to Install Open vSwitch on Red Hat Enterprise Linux
-===
-
-This document describes how to build and install Open vSwitch on a Red
-Hat Enterprise Linux (RHEL) host. If you want to install Open vSwitch
-on a generic Linux host, see [INSTALL.rst] instead.
-
-We have tested these instructions with RHEL 5.6 and RHEL 6.0.
-
-For RHEL 7.x (or derivatives, such as CentOS 7.x), you should follow
-the instructions in [INSTALL.Fedora.rst]. The Fedora spec files are
-used for RHEL 7.x.
-
-Building Open vSwitch for RHEL
---
-
-You may build from an Open vSwitch distribution tarball or from an
-Open vSwitch Git tree.
-
-The default RPM build directory (_topdir) has five directories in
-the top-level:
-1. BUILD/ Where the software is unpacked and built.
-2. RPMS/ Where the newly created binary package files are written.
-3. SOURCES/ Contains the original sources, patches, and icon files.
-4. SPECS/ Contains the spec files for each package to be built.
-5. SRPMS/ Where the newly created source package files are written.
-
-Before you begin, note the RPM sources directory on your version of
-RHEL. The command "rpmbuild --showrc" will show the configuration
-for each of those directories. Alternatively, the command "rpm --eval
- '%{_topdir}'" shows the current configuration for the top level
-directory and the command "rpm --eval '%{_sourcedir}'" does the same
-for the sources directory. On RHEL 5, the default RPM _topdir is
-/usr/src/redhat and the default RPM sources directory is
-/usr/src/redhat/SOURCES. On RHEL 6, the default _topdir is
-$HOME/rpmbuild and the default RPM sources directory is
-$HOME/rpmbuild/SOURCES.
-
-1. Install build prerequisites:
-
- ```
- yum install gcc make python-devel openssl-devel kernel-devel graphviz \
- kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \
- libtool
- ```
-
-2. If you are building from a distribution tarball, skip to step 3.
- Otherwise, you must be building from an Open vSwitch Git tree.
- Determine what version of Autoconf is installed (e.g. run "autoconf
- --version"). If it is not at least version 2.63, then you have two
- choices:
-
- a. Install Autoconf 2.63 or later, one way or another.
-
- b. Create a distribution tarball on some other machine, by
-running "./boot.sh; ./configure; make dist" in the Git tree.
-You must run this on a machine that has the tools listed in
-[INSTALL.rst] as prerequisites for building from a Git tree.
-Afterward, proceed with the rest of the instructions using
- the distribution tarball.
-
-3. Some versions of the RHEL 6 kernel-devel package contain a broken
- "build" symlink. If you are using such a version, you must fix
- the problem before continuing.
-
- To find out whether you are affected, run:
-
- ```
- cd /lib/modules/
- ls -l build/
- ```
-
- where `` is the version number of the RHEL 6 kernel. (The
- trailing slash in the final command is important. Be sure to include
- it.) If the "ls" command produces a directory listing, your
- kernel-devel package is OK. If it produces a "No such file or
- directory" error, your kernel-devel package is buggy.
-
- If your kernel-devel package is buggy, then you can fix it with:
-
- ```
- cd /lib/modules/
- rm build
- ln -s /usr/src/kernels/ build
- ```
-
- where `` is the name of an existing directory under
- /usr/src/kernels, whose name should be similar to `` but may
- contain some extra parts. Once you have done this, verify the fix with
- the sam
[ovs-dev] [PATCH 16/23] doc: Convert datapath/README to rST
Signed-off-by: Stephen Finucane --- datapath/Modules.mk | 2 +- datapath/README.md | 265 --- datapath/README.rst | 265 +++ lib/dpif.h | 2 +- vtep/README.ovs-vtep.rst | 2 +- 5 files changed, 268 insertions(+), 268 deletions(-) delete mode 100644 datapath/README.md create mode 100644 datapath/README.rst diff --git a/datapath/Modules.mk b/datapath/Modules.mk index 8e9a169..2ffab2b 100644 --- a/datapath/Modules.mk +++ b/datapath/Modules.mk @@ -46,7 +46,7 @@ openvswitch_headers = \ vport-netdev.h openvswitch_extras = \ - README.md + README.rst dist_sources = $(foreach module,$(dist_modules),$($(module)_sources)) dist_headers = $(foreach module,$(dist_modules),$($(module)_headers)) diff --git a/datapath/README.md b/datapath/README.md deleted file mode 100644 index 8faecc0..000 --- a/datapath/README.md +++ /dev/null @@ -1,265 +0,0 @@ -Open vSwitch datapath developer documentation -= - -The Open vSwitch kernel module allows flexible userspace control over -flow-level packet processing on selected network devices. It can be -used to implement a plain Ethernet switch, network device bonding, -VLAN processing, network access control, flow-based network control, -and so on. - -The kernel module implements multiple "datapaths" (analogous to -bridges), each of which can have multiple "vports" (analogous to ports -within a bridge). Each datapath also has associated with it a "flow -table" that userspace populates with "flows" that map from keys based -on packet headers and metadata to sets of actions. The most common -action forwards the packet to another vport; other actions are also -implemented. - -When a packet arrives on a vport, the kernel module processes it by -extracting its flow key and looking it up in the flow table. If there -is a matching flow, it executes the associated actions. If there is -no match, it queues the packet to userspace for processing (as part of -its processing, userspace will likely set up a flow to handle further -packets of the same type entirely in-kernel). - - -Flow key compatibility --- - -Network protocols evolve over time. New protocols become important -and existing protocols lose their prominence. For the Open vSwitch -kernel module to remain relevant, it must be possible for newer -versions to parse additional protocols as part of the flow key. It -might even be desirable, someday, to drop support for parsing -protocols that have become obsolete. Therefore, the Netlink interface -to Open vSwitch is designed to allow carefully written userspace -applications to work with any version of the flow key, past or future. - -To support this forward and backward compatibility, whenever the -kernel module passes a packet to userspace, it also passes along the -flow key that it parsed from the packet. Userspace then extracts its -own notion of a flow key from the packet and compares it against the -kernel-provided version: - - - If userspace's notion of the flow key for the packet matches the -kernel's, then nothing special is necessary. - - - If the kernel's flow key includes more fields than the userspace -version of the flow key, for example if the kernel decoded IPv6 -headers but userspace stopped at the Ethernet type (because it -does not understand IPv6), then again nothing special is -necessary. Userspace can still set up a flow in the usual way, -as long as it uses the kernel-provided flow key to do it. - - - If the userspace flow key includes more fields than the -kernel's, for example if userspace decoded an IPv6 header but -the kernel stopped at the Ethernet type, then userspace can -forward the packet manually, without setting up a flow in the -kernel. This case is bad for performance because every packet -that the kernel considers part of the flow must go to userspace, -but the forwarding behavior is correct. (If userspace can -determine that the values of the extra fields would not affect -forwarding behavior, then it could set up a flow anyway.) - -How flow keys evolve over time is important to making this work, so -the following sections go into detail. - - -Flow key format - -A flow key is passed over a Netlink socket as a sequence of Netlink -attributes. Some attributes represent packet metadata, defined as any -information about a packet that cannot be extracted from the packet -itself, e.g. the vport on which the packet was received. Most -attributes, however, are extracted from headers within the packet, -e.g. source and destination addresses from Ethernet, IP, or TCP -headers. - -The header file defines the exact format of the -flow key attributes. For informal explanatory purposes here,
Re: [ovs-dev] [PATCH 00/23] Convert next batch of docs to rST
On 2016-11-02 17:57, Joe Stringer wrote: On 30 October 2016 at 06:29, Stephen Finucane wrote: This is the third conversion series. This one is larger yet again, though many of the docs are rather small. After this series, only the two tutorial docs in 'tutorial' require conversion (along with any unsuffixed files I may have missed). /me didn't realize there was quite this much documentation in the repo. Hi Stephen, I was wanting to make a (very minor) doc change but since this much larger series is on the list I thought it's best for this to go in first. I tried to rebase my doc change against this series so it could go in after this does and save you any effort of rebasing this series and potentially losing my change. Unfortunately I had a bit of trouble trying to apply this series, starting with "doc: Convert rhel/README.RHEL to rST". Just to be sure, you've applied the remaining patch from the second series first, yes? http://openvswitch.org/pipermail/dev/2016-October/081065.html After that, this series should still apply cleanly: http://openvswitch.org/pipermail/dev/2016-October/081066.html I did a quick rebase and it still applied cleanly for me. Perhaps you could apply the patches using three-way merge to auto-resolve any conflicts? curl https://patchwork.ozlabs.org/patch/688927/mbox/ | git am -3 However... I think that maybe the series needs a rebase against latest master. Is this series also available via git somewhere? That would make it a little easier for me to base my change on top. I'll also push my working branches to GitHub when this evening. You'll find them here once I do: https://github.com/stephenfin/ovs Hope this helps :) Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
Re: [ovs-dev] [PATCH 23/23] doc: Convert vswitchd/INTERNALS to rST
On 2016-11-04 00:43, Russell Bryant wrote: On Sun, Oct 30, 2016 at 2:30 PM, Stephen Finucane wrote: Signed-off-by: Stephen Finucane --- lib/mac-learning.c | 3 +- lib/mac-learning.h | 2 +- vswitchd/INTERNALS | 239 vswitchd/INTERNALS.rst | 244 + vswitchd/automake.mk [1] | 2 +- 5 files changed, 248 insertions(+), 242 deletions(-) delete mode 100644 vswitchd/INTERNALS create mode 100644 vswitchd/INTERNALS.rst This whole series has been applied to master. Thanks! That was fast. Thanks :) Tutorial docs incoming, followed by the first pass at the Sphinx integration. Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 2/4] doc: Convert tutorial/OVN-Tutorial to rST
There's a mismash of absolute and relative URLs, but these will be
resolved by the move to Sphinx.
In addition, the URLs pointing to the test scripts are removed as they
will break when we move to Sphinx. This is because they won't be
published with the Sphinx docs, ruling out relative links, and OVS
evolves too fast to rely on non-breaking links to GitHub. Better to
rely on shell examples like we do elsewhere and let the user figure it
out.
Signed-off-by: Stephen Finucane
---
tutorial/automake.mk | 2 +-
tutorial/{OVN-Tutorial.md => ovn-tutorial.rst} | 721 +++--
tutorial/ovn/env1/setup.sh | 2 +-
tutorial/ovn/env6/setup.sh | 2 +-
4 files changed, 333 insertions(+), 394 deletions(-)
rename tutorial/{OVN-Tutorial.md => ovn-tutorial.rst} (59%)
diff --git a/tutorial/automake.mk b/tutorial/automake.mk
index cd7baec..79f9b68 100644
--- a/tutorial/automake.mk
+++ b/tutorial/automake.mk
@@ -1,6 +1,6 @@
docs += \
tutorial/tutorial.rst \
- tutorial/OVN-Tutorial.md
+ tutorial/ovn-tutorial.rst
EXTRA_DIST += \
tutorial/ovs-sandbox \
tutorial/t-setup \
diff --git a/tutorial/OVN-Tutorial.md b/tutorial/ovn-tutorial.rst
similarity index 59%
rename from tutorial/OVN-Tutorial.md
rename to tutorial/ovn-tutorial.rst
index a9f591f..8d9fc1a 100644
--- a/tutorial/OVN-Tutorial.md
+++ b/tutorial/ovn-tutorial.rst
@@ -1,42 +1,65 @@
+..
+ 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.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ === Heading 0 (reserved for the title in a document)
+ --- Heading 1
+ ~~~ Heading 2
+ +++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+
OVN Tutorial
This tutorial is intended to give you a tour of the basic OVN features using
-`ovs-sandbox` as a simulated test environment. It’s assumed that you have an
+``ovs-sandbox`` as a simulated test environment. It's assumed that you have an
understanding of OVS before going through this tutorial. Detail about OVN is
-covered in [ovn-architecture(7)], but this tutorial lets you quickly see it in
+covered in ovn-architecture_, but this tutorial lets you quickly see it in
action.
Getting Started
---
-For some general information about `ovs-sandbox`, see the “Getting Started”
-section of [Tutorial.md].
+For some general information about ``ovs-sandbox``, see the "Getting Started"
+section of the tutorial_.
-`ovs-sandbox` does not include OVN support by default. To enable OVN, you must
-pass the `--ovn` flag. For example, if running it straight from the ovs git
-tree you would run:
+``ovs-sandbox`` does not include OVN support by default. To enable OVN, you
+must pass the ``--ovn`` flag. For example, if running it straight from the ovs
+git tree you would run::
$ make sandbox SANDBOXFLAGS="--ovn"
Running the sandbox with OVN enabled does the following additional steps to the
environment:
- 1. Creates the `OVN_Northbound` and `OVN_Southbound` databases as described
in
- [ovn-nb(5)] and [ovn-sb(5)].
+1. Creates the ``OVN_Northbound`` and ``OVN_Southbound`` databases as
described in
+ `ovn-nb(5)`_ and `ovn-sb(5)`_.
- 2. Creates a backup server for `OVN_Southbond` database. Sandbox launch
- screen provides the instructions on accessing the backup database.
- However access to the backup server is not required to go through the
- tutorial.
+2. Creates a backup server for ``OVN_Southbond`` database. Sandbox launch
+ screen provides the instructions on accessing the backup database. However
+ access to the backup server is not required to go through the tutorial.
- 3. Creates the `hardware_vtep` database as described in [vtep(5)].
+3. Creates the ``hardware_vtep`` database as described in `vtep(5)`_.
- 4. Runs the [ovn-northd(8)], [ovn-controller(8)], and
[ovn-controller-vtep(8)]
- daemons.
+4. Runs the `ovn-northd(8)`_, `ovn-controller(8)`_, and
+ `ovn-controller-vtep(8)`_ daemons.
- 5. Makes OVN and VTEP utilities available for use in the environment,
- including [vtep-ctl(8)], [ovn-nbctl(8)], and [ovn-sbctl(8)].
+5. Makes OVN and VTEP utilities available for use in the envir
[ovs-dev] [PATCH 0/4] Convert remaining docs to rST
This is the fourth and final conversion series. This was kept separate
due to the size and complexity of the tutorial guides. There are also
ancillary changes to a previously unformatted TODO file (missed
previously due to the lack of an extension) and the AUTHORS file.
Stephen Finucane (4):
doc: Convert tutorial/Tutorial to rST
doc: Convert tutorial/OVN-Tutorial to rST
doc: Convert ovn/TODO to rST
AUTHORS: Add Stephen Finucane
AUTHORS| 1 +
FAQ.rst| 2 +-
README.rst | 2 +-
ovn/TODO | 213 --
ovn/TODO.rst | 233 +++
tutorial/Tutorial.md | 859
tutorial/automake.mk | 4 +-
tutorial/{OVN-Tutorial.md => ovn-tutorial.rst} | 721 ++--
tutorial/ovn/env1/setup.sh | 2 +-
tutorial/ovn/env6/setup.sh | 2 +-
tutorial/tutorial.rst | 870 +
11 files changed, 1440 insertions(+), 1469 deletions(-)
delete mode 100644 ovn/TODO
create mode 100644 ovn/TODO.rst
delete mode 100644 tutorial/Tutorial.md
rename tutorial/{OVN-Tutorial.md => ovn-tutorial.rst} (59%)
create mode 100644 tutorial/tutorial.rst
--
2.7.4
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH 3/4] doc: Convert ovn/TODO to rST
This might not be of much value, but let's be consistent where we can. Signed-off-by: Stephen Finucane --- ovn/TODO | 213 -- ovn/TODO.rst | 233 +++ 2 files changed, 233 insertions(+), 213 deletions(-) delete mode 100644 ovn/TODO create mode 100644 ovn/TODO.rst diff --git a/ovn/TODO b/ovn/TODO deleted file mode 100644 index 5972ce5..000 --- a/ovn/TODO +++ /dev/null @@ -1,213 +0,0 @@ --*- outline -*- - -* Work out database for clustering or HA properly. - -* Compromised chassis mitigation. - -Possibly depends on database solution. - -Latest discussion: -http://openvswitch.org/pipermail/dev/2016-August/078106.html - -* Get incremental updates in ovn-controller and ovn-northd in some - sensible way. - -* Testing improvements, possibly heavily based on ovn-trace. - -Justin Pettit: "I'm planning to write some ovn-trace tests for IPv6. -Hopefully we can get those into 2.6." - -* Self-managing HA for ovn-northd (avoiding the need to set up - independent tooling for fail-over). - -Russell Bryant: "For bonus points, increasing N would scale out -ovn-northd if it was under too much load, but that's a secondary -concern." - -* Live migration. - -Russell Bryant: "When you're ready to have the destination take -over, you have to remove the iface-id from the source and add it at -the destination and i think it'd typically be configured on both -ends, since it's a clone of the source VM (and it's config)." - -* VLAN trunk ports. - -Russell Bryant: "Today that would require creating 4096 ports for -the VM and attach to 4096 OVN networks, so doable, but not quite -ideal." - -* Native DNS support - -Russell Bryant: "This is an OpenStack requirement to fully eliminate -the DHCP agent." - -* Service function chaining. - -* MAC learning. - -Han Zhou: "To support VMs that hosts workloads with their own macs, -e.g. containers, if not using OVN native container support." - -* Finish up ARP/ND support: re-checking bindings, expiring bindings. - -* Hitless upgrade, especially for data plane. - -* Use OpenFlow "bundles" for transactional data plane updates. - -* L3 support - -** Logical routers should send RST replies to TCP packets. - -** IPv6 router ports should periodically send ND Router Advertisements. - -* Dynamic IP to MAC binding enhancements. - -OVN has basic support for establishing IP to MAC bindings dynamically, -using ARP. - -** Ratelimiting. - -From casual observation, Linux appears to generate at most one ARP per -second per destination. - -This might be supported by adding a new OVN logical action for -rate-limiting. - -** Tracking queries - -It's probably best to only record in the database responses to queries -actually issued by an L3 logical router, so somehow they have to be -tracked, probably by putting a tentative binding without a MAC address -into the database. - -** Renewal and expiration. - -Something needs to make sure that bindings remain valid and expire -those that become stale. - -One way to do this might be to add some support for time to the -database server itself. - -** Table size limiting. - -The table of MAC bindings must not be allowed to grow unreasonably -large. - -** MTU handling (fragmentation on output) - -* Security - -** Limiting the impact of a compromised chassis. - -Every instance of ovn-controller has the same full access to the central -OVN_Southbound database. This means that a compromised chassis can -interfere with the normal operation of the rest of the deployment. Some -specific examples include writing to the logical flow table to alter -traffic handling or updating the port binding table to claim ports that are -actually present on a different chassis. In practice, the compromised host -would be fighting against ovn-northd and other instances of ovn-controller -that would be trying to restore the correct state. The impact could include -at least temporarily redirecting traffic (so the compromised host could -receive traffic that it shouldn't) and potentially a more general denial of -service. - -There are different potential improvements to this area. The first would be -to add some sort of ACL scheme to ovsdb-server. A proposal for this should -first include an ACL scheme for ovn-controller. An example policy would -be to make Logical_Flow read-only. Table-level control is needed, but is -not enough. For example, ovn-controller must be able to update the Chassis -and Encap tables, but should only be able to modify the rows associated with -that chassis and no others. - -A more complex example is the Port_Binding table. Currently, ovn-controller -is the source of truth of where a port is located. There seems to be no -policy that can pr
[ovs-dev] [PATCH 1/4] doc: Convert tutorial/Tutorial to rST
Signed-off-by: Stephen Finucane --- FAQ.rst | 2 +- README.rst | 2 +- tutorial/OVN-Tutorial.md | 2 +- tutorial/Tutorial.md | 859 -- tutorial/automake.mk | 2 +- tutorial/tutorial.rst| 870 +++ 6 files changed, 874 insertions(+), 863 deletions(-) delete mode 100644 tutorial/Tutorial.md create mode 100644 tutorial/tutorial.rst diff --git a/FAQ.rst b/FAQ.rst index cc0f1bd..0e53301 100644 --- a/FAQ.rst +++ b/FAQ.rst @@ -2031,7 +2031,7 @@ Q: The "learn" action can't learn the action I want, can you improve it? http://openvswitch.org/pipermail/discuss/2016-June/021694.html - MAC learning in the middle of a pipeline, as described in `the tutorial - `__. + `__. - TCP state based firewalling, by learning outgoing connections based on SYN packets and matching them up with incoming packets. diff --git a/README.rst b/README.rst index a9eb7d9..ff5d3fd 100644 --- a/README.rst +++ b/README.rst @@ -104,7 +104,7 @@ To learn how to set up SSL support for Open vSwitch, see `here `__. To learn about some advanced features of the Open vSwitch software switch, read -the `tutorial `__. +the `tutorial `__. Each Open vSwitch userspace program is accompanied by a manpage. Many of the manpages are customized to your configuration as part of the build process, so diff --git a/tutorial/OVN-Tutorial.md b/tutorial/OVN-Tutorial.md index 129e918..a9f591f 100644 --- a/tutorial/OVN-Tutorial.md +++ b/tutorial/OVN-Tutorial.md @@ -991,7 +991,7 @@ and `lport2`. $ ovn/env8/packet2.sh [ovn-architecture(7)]:http://openvswitch.org/support/dist-docs/ovn-architecture.7.html -[Tutorial.md]:https://github.com/openvswitch/ovs/blob/master/tutorial/Tutorial.md +[Tutorial.md]:https://github.com/openvswitch/ovs/blob/master/tutorial/tutorial.rst [ovn-nb(5)]:http://openvswitch.org/support/dist-docs/ovn-nb.5.html [ovn-sb(5)]:http://openvswitch.org/support/dist-docs/ovn-sb.5.html [vtep(5)]:http://openvswitch.org/support/dist-docs/vtep.5.html diff --git a/tutorial/Tutorial.md b/tutorial/Tutorial.md deleted file mode 100644 index fefa8c8..000 --- a/tutorial/Tutorial.md +++ /dev/null @@ -1,859 +0,0 @@ -Open vSwitch Advanced Features Tutorial -=== - -Many tutorials cover the basics of OpenFlow. This is not such a -tutorial. Rather, a knowledge of the basics of OpenFlow is a -prerequisite. If you do not already understand how an OpenFlow flow -table works, please go read a basic tutorial and then continue reading -here afterward. - -It is also important to understand the basics of Open vSwitch before -you begin. If you have never used `ovs-vsctl` or `ovs-ofctl` before, -you should learn a little about them before proceeding. - -Most of the features covered in this tutorial are Open vSwitch -extensions to OpenFlow. Also, most of the features in this tutorial -are specific to the software Open vSwitch implementation. If you are -using an Open vSwitch port to an ASIC-based hardware switch, this -tutorial will not help you. - -This tutorial does not cover every aspect of the features that it -mentions. You can find the details elsewhere in the Open vSwitch -documentation, especially `ovs-ofctl(8)` and the comments in the -`include/openflow/nicira-ext.h` and `include/openvswitch/meta-flow.h` -header files. - -> In this tutorial, paragraphs set off like this designate notes -> with additional information that readers may wish to skip on a -> first read. - -Getting Started - -This is a hands-on tutorial. To get the most out of it, you will need -Open vSwitch binaries. You do not, on the other hand, need any -physical networking hardware or even supervisor privilege on your -system. Instead, we will use a script called `ovs-sandbox`, which -accompanies the tutorial, that constructs a software simulated network -environment based on Open vSwitch. - -You can use `ovs-sandbox` three ways: - - * If you have already installed Open vSwitch on your system, then -you should be able to just run `ovs-sandbox` from this directory -without any options. - - * If you have not installed Open vSwitch (and you do not want to -install it), then you can build Open vSwitch according to the -instructions in [INSTALL.rst], without installing it. Then run -`./ovs-sandbox -b DIRECTORY` from this directory, substituting -the Open vSwitch build directory for `DIRECTORY`. - - * As a slight variant on the latter, you can run `make sandbox` -from an Open vSwitch build directory. - -When you run `ovs-sandbox`, it does the following: - - 1. **CAUTION:** Deletes any subdirectory of the current directory - named "sandbox" and any files in that directory. - - 2. Creates a new directory "sandbox" in the current directory. - - 3. Sets up special
Re: [ovs-dev] [PATCH 0/4] Convert remaining docs to rST
On 2016-11-04 15:28, Russell Bryant wrote: On Fri, Nov 4, 2016 at 11:03 AM, Stephen Finucane wrote: This is the fourth and final conversion series. This was kept separate due to the size and complexity of the tutorial guides. There are also ancillary changes to a previously unformatted TODO file (missed previously due to the lack of an extension) and the AUTHORS file. Stephen Finucane (4): doc: Convert tutorial/Tutorial to rST doc: Convert tutorial/OVN-Tutorial to rST doc: Convert ovn/TODO to rST AUTHORS: Add Stephen Finucane It seems patch 4 didn't make it to the mailing list. I had checked AUTHORS before and your name is already there. It's your old intel address though, so I suspect you may want to update it to something current. Would you like to use the that.guru address? Yup, I don't know if I need to add an additional entry or to change the existing one. I opted for the former, but do whatever suits. Stephen ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH] tests/ovs_client: Remove broken debug code
There is some debug "logging" code included in the 'ovs_client'
application. This code appears to be broken as it spams stdout with
duplicated "log" messages. Remove this code.
In addition, add the 'ovsclient' executable to the 'tests/.gitignore'
file.
Signed-off-by: Stephen Finucane
---
tests/.gitignore | 1 +
tests/ovs_client/ovs_client.c | 11 ---
2 files changed, 1 insertion(+), 11 deletions(-)
diff --git a/tests/.gitignore b/tests/.gitignore
index 908c50e..02fc822 100644
--- a/tests/.gitignore
+++ b/tests/.gitignore
@@ -7,6 +7,7 @@
/idltest.h
/idltest.ovsidl
/ovstest
+/ovsclient
/ovs-pki.log
/pki/
/test-aes128
diff --git a/tests/ovs_client/ovs_client.c b/tests/ovs_client/ovs_client.c
index 6387624..97d32fc 100644
--- a/tests/ovs_client/ovs_client.c
+++ b/tests/ovs_client/ovs_client.c
@@ -58,9 +58,6 @@
*/
static uint8_t client_id = 0;
-int no_pkt;
-int pkt;
-
/*
* Given the rx queue name template above, get the queue name.
*/
@@ -209,18 +206,10 @@ main(int argc, char *argv[])
}
if (rx_pkts > 0) {
-pkt++;
/* blocking enqueue */
do {
rslt = rte_ring_enqueue_bulk(tx_ring, pkts, rx_pkts);
} while (rslt == -ENOBUFS);
-} else {
- no_pkt++;
-}
-
-if (!(pkt % 10)) {
-printf("pkt %d %d\n", pkt, no_pkt);
-pkt = no_pkt = 0;
}
}
}
--
1.9.3
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH] configure.ac: Enable 'tar-ustar' by default
Automake defaults to the 'v7' legacy tar format in GNU tar, through
passing of the '-o' parameter to GNU tar. Enabling this option results
in errors for users with 32 bit UIDs:
$ make dist
...
tardir=openvswitch-2.3.90 && ${TAR-tar} chof - "$tardir" | GZIP=--best gzip
-c >openvswitch-2.3.90.tar.gz
tar: value 12345678 out of uid_t range 0..2097151
tar: Exiting with failure status due to previous errors
make[1]: Leaving directory `/development/ovs'
...
The 'tar-ustar' format is a 1988 POSIX standard that allow longer file
names and other niceties. It's use is an option in Automake 1.9+.
Enable this option.
Signed-off-by: Stephen Finucane
Reviewed-by: Mark D. Gray
---
configure.ac |2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/configure.ac b/configure.ac
index ebb8b02..6505189 100644
--- a/configure.ac
+++ b/configure.ac
@@ -19,7 +19,7 @@ AC_CONFIG_MACRO_DIR([m4])
AC_CONFIG_AUX_DIR([build-aux])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_TESTDIR([tests])
-AM_INIT_AUTOMAKE
+AM_INIT_AUTOMAKE([tar-ustar])
AC_PROG_CC_C99
AM_PROG_CC_C_O
--
1.7.4.1
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [PATCH] configure.ac: Enable 'tar-pax' by default
Automake defaults to the 'v7' legacy tar format in GNU tar, through
passing of the '-o' parameter to GNU tar. Enabling this option results
in errors for users with 32 bit UIDs:
$ make dist
...
tardir=openvswitch-2.3.90 && ${TAR-tar} chof - "$tardir" | GZIP=--best gzip
-c >openvswitch-2.3.90.tar.gz
tar: value 12345678 out of uid_t range 0..2097151
tar: Exiting with failure status due to previous errors
make[1]: Leaving directory `/development/ovs'
...
The 'tar-pax' format is a 2001 POSIX standard that allow longer file
names and other niceties. Its use is a configuration option in Automake
1.9+. Enable this option.
Signed-off-by: Stephen Finucane
Reviewed-by: Mark D. Gray
Cc: Panu Matilainen
---
configure.ac |2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/configure.ac b/configure.ac
index ebb8b02..d2d02ca 100644
--- a/configure.ac
+++ b/configure.ac
@@ -19,7 +19,7 @@ AC_CONFIG_MACRO_DIR([m4])
AC_CONFIG_AUX_DIR([build-aux])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_TESTDIR([tests])
-AM_INIT_AUTOMAKE
+AM_INIT_AUTOMAKE([tar-pax])
AC_PROG_CC_C99
AM_PROG_CC_C_O
--
1.7.4.1
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
[ovs-dev] [RFC] make: Add 'lint-docs' target
This provides a quick, easy way to use the 'mdl' executable provided in markdowlinter to validate documentation. This change does not resolve any of the issues this linter raises - these will need to be done in a follow up patch. Signed-off-by: Stephen Finucane --- INSTALL.md | 5 + Makefile.am | 4 2 files changed, 9 insertions(+) diff --git a/INSTALL.md b/INSTALL.md index 906825a..7311915 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -111,6 +111,11 @@ To run the unit tests, you also need: - Perl. Version 5.10.1 is known to work. Earlier versions should also work. +If you are going to modify Open vSwitch documentation, please consider +installing the following to validate your changes: + + - "markdownlint" (https://github.com/mivok/markdownlint) + The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in formats other than plain text, only if you have the following: diff --git a/Makefile.am b/Makefile.am index 966ba27..d58cb59 100644 --- a/Makefile.am +++ b/Makefile.am @@ -377,6 +377,10 @@ dist-docs: VERSION=$(VERSION) $(srcdir)/build-aux/dist-docs $(srcdir) $(docs) .PHONY: dist-docs +lint-docs: + mdl $(docs) +.PHONY: dist-docs + include Documentation/automake.mk include m4/automake.mk include lib/automake.mk -- 2.0.0 ___ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
