From patchwork Sun Oct 30 13:29:54 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 688932 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 3t6JML49FMz9t1T for ; Mon, 31 Oct 2016 00:32:30 +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=IZMdAlbs; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id C3F6B102D4; Sun, 30 Oct 2016 06:32:29 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx1e3.cudamail.com (mx1.cudamail.com [69.90.118.67]) by archives.nicira.com (Postfix) with ESMTPS id 364A4102CE for ; Sun, 30 Oct 2016 06:32:28 -0700 (PDT) Received: from bar5.cudamail.com (localhost [127.0.0.1]) by mx1e3.cudamail.com (Postfix) with ESMTPS id C27784203AA for ; Sun, 30 Oct 2016 07:32:27 -0600 (MDT) X-ASG-Debug-ID: 1477834346-09eadd0f97242cd0001-byXFYA Received: from mx1-pf1.cudamail.com ([192.168.24.1]) by bar5.cudamail.com with ESMTP id eXIFRQDeusaxFJ0U (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Sun, 30 Oct 2016 07:32:26 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.24.1 Received: from unknown (HELO brown.birch.relay.mailchannels.net) (23.83.209.23) by mx1-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 30 Oct 2016 13:32:26 -0000 Received-SPF: none (mx1-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.209.23 X-Barracuda-RBL-IP: 23.83.209.23 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 EFCDDE1150 for ; Sun, 30 Oct 2016 13:32:24 +0000 (UTC) Received: from one.mxroute.com (ip-10-229-10-199.us-west-2.compute.internal [10.229.10.199]) by relay.mailchannels.net (Postfix) with ESMTPA id 6BE1FE0F82 for ; Sun, 30 Oct 2016 13:32:24 +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); Sun, 30 Oct 2016 13:32:24 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1477834344773:1436559676 X-MC-Ingress-Time: 1477834344773 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=EnyMa4jf3U+qcV3bxklABd5rqE+23K7h9EryzPBu2Os=; b=IZMdAlbsVs1VrKqrVKSvx8iwrn S6QQaClaDfhIbppurRuP5tMa6NeCZTYzgHWAge/FeThkM1gxrBZXa4+DIHciT9uaOK0r2rRZJWhCv bu1VjNd+HMSO2hjlrtZkukyhqoLF9iJe/X/M1DSOOXnopm9mYGtMM/uTCeBpHZgNEDOVLbFi5Qwd8 ajTsFO716/EkC35DMpt0GAXL+iAV+Fj2mUBDB5MCEe6MTKkZ9v1hpM5pta1ZGE2COEZ1WyBg+zFeq 3Jdf0LuD3tr3OYzWpDrJzPrlPlA6YOCAB4EheR60wO9DJAw/ScoiR6r0tLDgNkFPnJJb+T92CD7ZM 7bJ/Prag==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-E1-1029006407 X-CudaMail-DTE: 103016 X-CudaMail-Originating-IP: 23.83.209.23 Date: Sun, 30 Oct 2016 13:29:54 +0000 X-ASG-Orig-Subj: [##CM-E1-1029006407##][PATCH 08/23] doc: Convert README.ovs-vtep to rST Message-Id: <1477834209-11414-9-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1477834209-11414-1-git-send-email-stephen@that.guru> References: <1477834209-11414-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-Barracuda-Connect: UNKNOWN[192.168.24.1] X-Barracuda-Start-Time: 1477834346 X-Barracuda-Encrypted: ECDHE-RSA-AES256-GCM-SHA384 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.34168 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 08/23] doc: Convert README.ovs-vtep 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" 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..0000000 --- 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-----------o--------------------o--+ | - | 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 its ports in OVS: - - ``` -ovs-vsctl add-br br0 -ovs-vsctl add-port br0 p0 -ovs-vsctl add-port br0 p1 - ``` - -5. Configure the physical switch in the VTEP database: - - ``` -vtep-ctl add-ps br0 -vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1 - ``` - -6. Start the VTEP emulator. If you installed the components by reading the - INSTALL.md file, run the following from the same directory as this - README.md: - - ``` -./ovs-vtep --log-file=/var/log/openvswitch/ovs-vtep.log \ ---pidfile=/var/run/openvswitch/ovs-vtep.pid \ ---detach br0 - ``` - - If the installation was done by installing the openvswitch-vtep - package, you can find ovs-vtep at /usr/share/openvswitch/scripts. - -7. Configure the VTEP database's manager to point at an NVC: - - ``` -vtep-ctl set-manager tcp::6640 - ``` - - Where CONTROLLER IP is your controller's IP address that is accessible - via the Host Machine's eth0 interface. - -Simulating an NVC ------------------ - -A VTEP implementation expects to be driven by a Network Virtualization -Controller (NVC), such as NSX. If one does not exist, it's possible to -use vtep-ctl to simulate one: - -1. Create a logical switch: - - ``` -vtep-ctl add-ls ls0 - ``` - -2. Bind the logical switch to a port: - - ``` -vtep-ctl bind-ls br0 p0 0 ls0 -vtep-ctl set Logical_Switch ls0 tunnel_key=33 - ``` - -3. Direct unknown destinations out a tunnel. - - For handling L2 broadcast, multicast and unknown unicast traffic, - packets can be sent to all members of a logical switch referenced by - a physical switch. The "unknown-dst" address below is used to - represent these packets. There are different modes to replicate the - packets. The default mode of replication is to send the traffic to a - service node, which can be a hypervisor, server or appliance, and let - the service node handle replication to other transport nodes - (hypervisors or other VTEP physical switches). This mode is called - _service node_ replication. An alternate mode of replication, called - _source node_ replication, involves the source node sending to all - other transport nodes. Hypervisors are always responsible for doing - their own replication for locally attached VMs in both modes. - Service node mode is the default. Service node replication mode is - considered a basic requirement because it only requires sending the - packet to a single transport node. The following configuration is - for service node replication mode as only a single transport node - destination is specified for the unknown-dst address: - - ``` -vtep-ctl add-mcast-remote ls0 unknown-dst 10.2.2.2 - ``` - -4. Optionally, change the replication mode from a default of -"service\_node" to "source\_node", which can be done at the logical -switch level: - - ``` -vtep-ctl set-replication-mode ls0 source_node - ``` - -5. Direct unicast destinations out a different tunnel: - - ``` -vtep-ctl add-ucast-remote ls0 00:11:22:33:44:55 10.2.2.3 - ``` diff --git a/vtep/README.ovs-vtep.rst b/vtep/README.ovs-vtep.rst new file mode 100644 index 0000000..9e9883b --- /dev/null +++ b/vtep/README.ovs-vtep.rst @@ -0,0 +1,231 @@ +.. + 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 the VTEP Emulator +============================ + +This document explains how to use ovs-vtep, a VXLAN Tunnel Endpoint (VTEP) +emulator that uses Open vSwitch for forwarding. VTEPs are the entities that +handle VXLAN frame encapsulation and decapsulation in a network. + +Requirements +------------ + +The VTEP emulator is a Python script that invokes calls to tools like vtep-ctl +and ovs-vsctl. It is only useful when Open vSwitch daemons like ovsdb-server +and ovs-vswitchd are running and installed. To do this, either: + +- Follow the instructions in the `installation guide <..INSTALL.rst>`__ (don't + start any daemons yet). + +- Follow the instructions in `Debian installation guide + <../INSTALL.Debian.rst>`__ 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: + +:: + + Architecture + + +---------------------------------------------------+ + | Host Machine | + | | + | | + | +---------+ +---------+ | + | | | | | | + | | VM1 | | VM2 | | + | | | | | | + | +----o----+ +----o----+ | + | | | | + | br0 +------o-----------o--------------------o--+ | + | p0 p1 br0 | + | | + | | + | +------+ +------+ | + +------------------------------| eth0 |---| eth1 |--+ + +------+ +------+ + 10.1.1.1 10.2.2.1 + MANAGEMENT | | + +-----------------o----+ | + | + DATA/TUNNEL | + +-----------------o---+ + +Some important points. + +- We will use Open vSwitch to create our "physical" switch labeled ``br0`` + +- Our "physical" switch ``br0`` will have one internal port also named ``br0`` + and two "physical" ports, namely ``p0`` and ``p1``. + +- 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. + +- You can optionally connect physical machines instead of virtual machines to + switch ``br0``. In that case: + + - Make sure you have two extra physical interfaces in your host machine, + ``eth2`` and ``eth3``. + + - 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-vswitchd as normal: + + :: + + $ ovs-vswitchd --log-file --detach --pidfile \ + unix:/var/run/openvswitch/db.sock + +4. Create a "physical" switch and its ports in OVS: + + :: + + $ ovs-vsctl add-br br0 + $ ovs-vsctl add-port br0 p0 + $ ovs-vsctl add-port br0 p1 + +5. Configure the physical switch in the VTEP database: + + :: + + $ vtep-ctl add-ps br0 + $ vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1 + +6. Start the VTEP emulator. If you installed the components following the + `installation guide <../INSTALL.rst>`__ file, run the following from the + same directory as this README.md: + + :: + + $ ./ovs-vtep --log-file=/var/log/openvswitch/ovs-vtep.log \ + --pidfile=/var/run/openvswitch/ovs-vtep.pid \ + --detach br0 + + If the installation was done by installing the openvswitch-vtep package, you + can find ovs-vtep at ``/usr/share/openvswitch/scripts``. + +7. Configure the VTEP database's manager to point at an NVC: + + :: + + $ vtep-ctl set-manager tcp::6640 + + Where ```` is your controller's IP address that is accessible + via the Host Machine's eth0 interface. + +Simulating an NVC +----------------- + +A VTEP implementation expects to be driven by a Network Virtualization +Controller (NVC), such as NSX. If one does not exist, it's possible to use +vtep-ctl to simulate one: + +1. Create a logical switch: + + :: + + $ vtep-ctl add-ls ls0 + +2. Bind the logical switch to a port: + + :: + + $ vtep-ctl bind-ls br0 p0 0 ls0 + $ vtep-ctl set Logical_Switch ls0 tunnel_key=33 + +3. Direct unknown destinations out a tunnel. + + For handling L2 broadcast, multicast and unknown unicast traffic, packets + can be sent to all members of a logical switch referenced by a physical + switch. The "unknown-dst" address below is used to represent these packets. + There are different modes to replicate the packets. The default mode of + replication is to send the traffic to a service node, which can be a + hypervisor, server or appliance, and let the service node handle replication + to other transport nodes (hypervisors or other VTEP physical switches). + This mode is called *service node* replication. An alternate mode of + replication, called *source node* replication, involves the source node + sending to all other transport nodes. Hypervisors are always responsible + for doing their own replication for locally attached VMs in both modes. + Service node mode is the default. Service node replication mode is + considered a basic requirement because it only requires sending the packet + to a single transport node. The following configuration is for service node + replication mode as only a single transport node destination is specified + for the unknown-dst address: + + :: + + $ vtep-ctl add-mcast-remote ls0 unknown-dst 10.2.2.2 + +4. Optionally, change the replication mode from a default of ``service_node`` + to ``source_node``, which can be done at the logical switch level: + + :: + + $ vtep-ctl set-replication-mode ls0 source_node + +5. Direct unicast destinations out a different tunnel: + + :: + + $ vtep-ctl add-ucast-remote ls0 00:11:22:33:44:55 10.2.2.3 diff --git a/vtep/automake.mk b/vtep/automake.mk index 2645f30..6a98144 100644 --- a/vtep/automake.mk +++ b/vtep/automake.mk @@ -40,7 +40,7 @@ vtep_vtep_ctl_LDADD = vtep/libvtep.la lib/libopenvswitch.la scripts_SCRIPTS += \ vtep/ovs-vtep -docs += vtep/README.ovs-vtep.md +docs += vtep/README.ovs-vtep.rst EXTRA_DIST += vtep/ovs-vtep FLAKE8_PYFILES += vtep/ovs-vtep