From patchwork Tue Oct 18 20:03:37 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 683851 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3sz5gj5sb6z9s2G for ; Wed, 19 Oct 2016 07:06:41 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=WnS6/Bp6; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 0D05F1030A; Tue, 18 Oct 2016 13:06:41 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx1e4.cudamail.com (mx1.cudamail.com [69.90.118.67]) by archives.nicira.com (Postfix) with ESMTPS id D9689102F7 for ; Tue, 18 Oct 2016 13:06:39 -0700 (PDT) Received: from bar5.cudamail.com (unknown [192.168.21.12]) by mx1e4.cudamail.com (Postfix) with ESMTPS id 707BD1E05EE for ; Tue, 18 Oct 2016 14:06:39 -0600 (MDT) X-ASG-Debug-ID: 1476821198-09eadd6af3123930001-byXFYA Received: from mx1-pf2.cudamail.com ([192.168.24.2]) by bar5.cudamail.com with ESMTP id CiHck6dfmHfWOXKc (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 18 Oct 2016 14:06:38 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.24.2 Received: from unknown (HELO butterfly.birch.relay.mailchannels.net) (23.83.209.27) by mx1-pf2.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 18 Oct 2016 20:06:37 -0000 Received-SPF: none (mx1-pf2.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.209.27 X-Barracuda-RBL-IP: 23.83.209.27 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id C8094A070F for ; Tue, 18 Oct 2016 20:06:35 +0000 (UTC) Received: from one.mxroute.com (ip-10-107-69-155.us-west-2.compute.internal [10.107.69.155]) by relay.mailchannels.net (Postfix) with ESMTPA id 463D2A024F for ; Tue, 18 Oct 2016 20:06:34 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([TEMPUNAVAIL]. [10.102.194.57]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Tue, 18 Oct 2016 20:06:35 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1476821194943:309992648 X-MC-Ingress-Time: 1476821194942 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=InerrlWSmHa3ulgvB0Q5MWm3UI6vzo6aWXXdePuw+F8=; b=WnS6/Bp6OjYYS9iAylW0EsXFFh 6cmi9yGieCuehNmD0zUO4KqoviT32tPkvugLYsdFWS5Y0BJsqUJDJcmWW8lXreSlnGwfexBGnNeaE NU+lBkjE229hxfOYkLCFBAonlecM7xIqapvfZzG+J8Aiw/W6GqfgPTAbRmLRi45VKw84772juLJDx JtogftA4gp8wnkejAlIpdu5Odjz1crDUyeB2xeHgzntjPEDVNcZj/UQT0wD6/ewjY/8tbZeXgo4Dx RuJ6JattKsi48ZUcAB3Ije+Y/hXdXrLS5Li9VxGU6a7IV+uSVzvhSZWaStq3ZGuZRPxw/RiCsxcBI q6KAB84g==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-E2-1017071726 X-CudaMail-DTE: 101816 X-CudaMail-Originating-IP: 23.83.209.27 Date: Tue, 18 Oct 2016 21:03:37 +0100 X-ASG-Orig-Subj: [##CM-E2-1017071726##][PATCH 07/15] doc: Convert WHY-OVS to rST Message-Id: <1476821025-4915-8-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1476821025-4915-1-git-send-email-stephen@that.guru> References: <1476821025-4915-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-GBUdb-Analysis: 0, 23.83.209.27, Ugly c=0 p=0 Source New X-MessageSniffer-Rules: 0-0-0-32767-c X-Barracuda-Connect: UNKNOWN[192.168.24.2] X-Barracuda-Start-Time: 1476821198 X-Barracuda-Encrypted: DHE-RSA-AES256-SHA X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 X-Barracuda-Spam-Score: 1.10 X-Barracuda-Spam-Status: No, SCORE=1.10 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.33831 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 07/15] doc: Convert WHY-OVS to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" 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 @@ bugs@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..0000000 --- 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 context - within the network through appending or manipulating tags in network - packets. This can be used to uniquely identify a VM (in a manner - resistant to hardware spoofing), or to hold some other context that - is only relevant in the logical domain. Much of the problem of - building a distributed virtual switch is to efficiently and correctly - manage these tags. - - Open vSwitch includes multiple methods for specifying and maintaining - tagging rules, all of which are accessible to a remote process for - orchestration. Further, in many cases these tagging rules are stored - in an optimized form so they don't have to be coupled with a - heavyweight network device. This allows, for example, thousands of - tagging or address remapping rules to be configured, changed, and - migrated. - - In a similar vein, Open vSwitch supports a GRE implementation that can - handle thousands of simultaneous GRE tunnels and supports remote - configuration for tunnel creation, configuration, and tear-down. - This, for example, can be used to connect private VM networks in - different data centers. - -* Hardware integration: Open vSwitch's forwarding path (the in-kernel - datapath) is designed to be amenable to "offloading" packet processing - to hardware chipsets, whether housed in a classic hardware switch - chassis or in an end-host NIC. This allows for the Open vSwitch - control path to be able to both control a pure software - implementation or a hardware switch. - - There are many ongoing efforts to port Open vSwitch to hardware - chipsets. These include multiple merchant silicon chipsets (Broadcom - and Marvell), as well as a number of vendor-specific platforms. (The - PORTING file discusses how one would go about making such a port.) - - The advantage of hardware integration is not only performance within - virtualized environments. If physical switches also expose the Open - vSwitch control abstractions, both bare-metal and virtualized hosting - environments can be managed using the same mechanism for automated - network control. - -In many ways, Open vSwitch targets a different point in the design space -than previous hypervisor networking stacks, focusing on the need for -automated and dynamic network control in large-scale Linux-based -virtualization environments. - -The goal with Open vSwitch is to keep the in-kernel code as small as -possible (as is necessary for performance) and to re-use existing -subsystems when applicable (for example Open vSwitch uses the existing -QoS stack). As of Linux 3.3, Open vSwitch is included as a part of the -kernel and packaging for the userspace utilities are available on most -popular distributions. diff --git a/WHY-OVS.rst b/WHY-OVS.rst new file mode 100644 index 0000000..161889d --- /dev/null +++ b/WHY-OVS.rst @@ -0,0 +1,128 @@ +.. + 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. + +================= +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 context within the network through appending or manipulating +tags in network packets. This can be used to uniquely identify a VM (in a +manner resistant to hardware spoofing), or to hold some other context that is +only relevant in the logical domain. Much of the problem of building a +distributed virtual switch is to efficiently and correctly manage these tags. + +Open vSwitch includes multiple methods for specifying and maintaining tagging +rules, all of which are accessible to a remote process for orchestration. +Further, in many cases these tagging rules are stored in an optimized form so +they don't have to be coupled with a heavyweight network device. This allows, +for example, thousands of tagging or address remapping rules to be configured, +changed, and migrated. + +In a similar vein, Open vSwitch supports a GRE implementation that can handle +thousands of simultaneous GRE tunnels and supports remote configuration for +tunnel creation, configuration, and tear-down. This, for example, can be used +to connect private VM networks in different data centers. + +Hardware integration +-------------------- + +Open vSwitch's forwarding path (the in-kernel datapath) is designed to be +amenable to "offloading" packet processing to hardware chipsets, whether housed +in a classic hardware switch chassis or in an end-host NIC. This allows for the +Open vSwitch control path to be able to both control a pure software +implementation or a hardware switch. + +There are many ongoing efforts to port Open vSwitch to hardware chipsets. These +include multiple merchant silicon chipsets (Broadcom and Marvell), as well as a +number of vendor-specific platforms. (The PORTING file discusses how one would +go about making such a port.) + +The advantage of hardware integration is not only performance within +virtualized environments. If physical switches also expose the Open vSwitch +control abstractions, both bare-metal and virtualized hosting environments can +be managed using the same mechanism for automated network control. + +In many ways, Open vSwitch targets a different point in the design space than +previous hypervisor networking stacks, focusing on the need for automated and +dynamic network control in large-scale Linux-based virtualization environments. + +The goal with Open vSwitch is to keep the in-kernel code as small as possible +(as is necessary for performance) and to re-use existing subsystems when +applicable (for example Open vSwitch uses the existing QoS stack). As of Linux +3.3, Open vSwitch is included as a part of the kernel and packaging for the +userspace utilities are available on most popular distributions. diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in index d3b03e1..3213864 100644 --- a/rhel/openvswitch-fedora.spec.in +++ b/rhel/openvswitch-fedora.spec.in @@ -478,7 +478,7 @@ fi %{_mandir}/man8/ovs-vswitchd.8* %{_mandir}/man8/ovs-parse-backtrace.8* %{_mandir}/man8/ovs-testcontroller.8* -%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.md +%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst %doc FAQ.md NEWS INSTALL.DPDK.rst rhel/README.RHEL /var/lib/openvswitch /var/log/openvswitch diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index 1b4c757..be6449b 100644 --- a/rhel/openvswitch.spec.in +++ b/rhel/openvswitch.spec.in @@ -247,7 +247,7 @@ exit 0 /usr/share/openvswitch/scripts/sysconfig.template /usr/share/openvswitch/vswitch.ovsschema /usr/share/openvswitch/vtep.ovsschema -%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.md FAQ.md NEWS +%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst FAQ.md NEWS %doc INSTALL.DPDK.rst rhel/README.RHEL README-native-tunneling.md /var/lib/openvswitch /var/log/openvswitch diff --git a/tests/run-oftest b/tests/run-oftest index 32cc6d2..ecfd783 100755 --- a/tests/run-oftest +++ b/tests/run-oftest @@ -21,7 +21,7 @@ case $srcdir in /*) ;; *) srcdir=`pwd`/$srcdir ;; esac -if test ! -e "$srcdir"/WHY-OVS.md; then +if test ! -e "$srcdir"/WHY-OVS.rst; then echo >&2 'source directory not found, please set $srcdir or run via \"make check-oftest' exit 1 fi diff --git a/tests/run-ryu b/tests/run-ryu index 58ee781..0be6c01 100755 --- a/tests/run-ryu +++ b/tests/run-ryu @@ -19,7 +19,7 @@ case $srcdir in /*) ;; *) srcdir=`pwd`/$srcdir ;; esac -if test ! -e "$srcdir"/WHY-OVS.md; then +if test ! -e "$srcdir"/WHY-OVS.rst; then echo >&2 'source directory not found, please set $srcdir or run via \"make check-ryu' exit 1 fi diff --git a/tutorial/ovs-sandbox b/tutorial/ovs-sandbox index 6f03ede..4372da4 100755 --- a/tutorial/ovs-sandbox +++ b/tutorial/ovs-sandbox @@ -223,7 +223,7 @@ if $built; then case $srcdir in '') srcdir=$builddir - if test ! -e "$srcdir"/WHY-OVS.md; then + if test ! -e "$srcdir"/WHY-OVS.rst; then srcdir=`cd $builddir/.. && pwd` fi ;; diff --git a/utilities/ovs-dev.py b/utilities/ovs-dev.py index 31621f4..9188d73 100755 --- a/utilities/ovs-dev.py +++ b/utilities/ovs-dev.py @@ -24,7 +24,7 @@ ENV = os.environ HOME = ENV["HOME"] PWD = os.getcwd() OVS_SRC = HOME + "/ovs" -if os.path.exists(PWD + "/WHY-OVS.md"): +if os.path.exists(PWD + "/WHY-OVS.rst"): OVS_SRC = PWD # Use current directory as OVS source tree RUNDIR = OVS_SRC + "/_run" BUILD_GCC = OVS_SRC + "/_build-gcc" diff --git a/utilities/ovs-sim.in b/utilities/ovs-sim.in index 7f60815..7e43c96 100755 --- a/utilities/ovs-sim.in +++ b/utilities/ovs-sim.in @@ -63,8 +63,8 @@ if test ! -e "$sim_builddir"/vswitchd/ovs-vswitchd; then echo "$sim_builddir/vswitchd/ovs-vswitchd does not exist (need to run \"make\"?)" >&2 exit 1 fi -if test ! -e "$sim_srcdir"/WHY-OVS.md; then - echo "$sim_srcdir/WHY-OVS.md does not exist" >&2 +if test ! -e "$sim_srcdir"/WHY-OVS.rst; then + echo "$sim_srcdir/WHY-OVS.rst does not exist" >&2 exit 1 fi