From patchwork Sat Oct 8 16:30:31 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 679920 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 3srsNP0KMYz9ryv for ; Sun, 9 Oct 2016 03:31:48 +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=BSpWLUyz; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id A14B610ABA; Sat, 8 Oct 2016 09:31:06 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx3v3.cudamail.com (mx3.cudamail.com [64.34.241.5]) by archives.nicira.com (Postfix) with ESMTPS id 239C110ABA for ; Sat, 8 Oct 2016 09:31:06 -0700 (PDT) Received: from bar6.cudamail.com (localhost [127.0.0.1]) by mx3v3.cudamail.com (Postfix) with ESMTPS id B0672162BDB for ; Sat, 8 Oct 2016 10:31:05 -0600 (MDT) X-ASG-Debug-ID: 1475944264-0b32374d4a01220001-byXFYA Received: from mx3-pf2.cudamail.com ([192.168.14.1]) by bar6.cudamail.com with ESMTP id tznH5UPCgKcox8mF (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 08 Oct 2016 10:31:04 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.14.1 Received: from unknown (HELO bonobo.birch.relay.mailchannels.net) (23.83.209.22) by mx3-pf2.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 8 Oct 2016 16:31:03 -0000 Received-SPF: none (mx3-pf2.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.209.22 X-Barracuda-RBL-IP: 23.83.209.22 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 16535101631 for ; Sat, 8 Oct 2016 16:31:02 +0000 (UTC) Received: from one.mxroute.com (ip-10-220-3-24.us-west-2.compute.internal [10.220.3.24]) by relay.mailchannels.net (Postfix) with ESMTPA id 78C5A10164B for ; Sat, 8 Oct 2016 16:30:55 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.135.9.54]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sat, 08 Oct 2016 16:31:01 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1475944255736:2380016253 X-MC-Ingress-Time: 1475944255736 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=lwn3E7ztAaU0N7Te0VbeQXRsdudWf8KCj8LZ6099PgU=; b=BSpWLUyz7Bs3fCVHaxzzN/nbJT vX8g2pCrQxjGw89VxFRFicPpK8Z1YhInYGT2smSOczLmfKDGIil4CT7egGiUWwOB9YwGOK02vn3uj otJSoBJMo+o64Drrqz4gZvMZytvmpRcHSWIzOfbSQmS7GFjxa8vwcK5j0yMTdSLsJdxS37hoTtUH9 jgsL/sWCHV4O379fSmIkeEWGBJ01DtPm/6sXG/EgcNxtRiSd/QdQgWCmS7rVWg1wacrPt3fvC8wnQ mAH3TJcjStRZJZ+DdtANtj6laV2EQqKHz1rVXiiFIGtniw/eE+FymgCI2tOgb8o9H/4cyiIOOSeux Kl3qXZ+w==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-V2-1007010167 X-CudaMail-DTE: 100816 X-CudaMail-Originating-IP: 23.83.209.22 Date: Sat, 8 Oct 2016 17:30:31 +0100 X-ASG-Orig-Subj: [##CM-V2-1007010167##][PATCH 9/9] doc: Convert INSTALL.KVM to rST Message-Id: <1475944231-25192-10-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1475944231-25192-1-git-send-email-stephen@that.guru> References: <1475944231-25192-1-git-send-email-stephen@that.guru> X-AuthUser: stephen@that.guru X-GBUdb-Analysis: 0, 23.83.209.22, Ugly c=0.165853 p=-0.2 Source Normal X-MessageSniffer-Rules: 0-0-0-17275-c X-Barracuda-Connect: UNKNOWN[192.168.14.1] X-Barracuda-Start-Time: 1475944264 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.33578 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 9/9] doc: Convert INSTALL.KVM 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 --- 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..0000000 --- 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 bugs@openvswitch.org. - -[INSTALL.rst]:INSTALL.rst diff --git a/INSTALL.KVM.rst b/INSTALL.KVM.rst new file mode 100644 index 0000000..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 + #!/bin/sh + + switch='br0' + /sbin/ifconfig $1 0.0.0.0 up + ovs-vsctl add-port ${switch} $1 + EOF + +:: + + echo << EOF > /etc/ovs-ifdown + #!/bin/sh + + switch='br0' + /sbin/ifconfig $1 0.0.0.0 down + ovs-vsctl del-port ${switch} $1 + +The basic usage of Open vSwitch is described at the end of the `installation +guide `__. 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 + +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) + +Refer to ovs-dpctl(8) and ovs-ofctl(8) for more details. diff --git a/Makefile.am b/Makefile.am index cf8aa43..a4842c1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -76,7 +76,7 @@ docs = \ INSTALL.DPDK-ADVANCED.md \ INSTALL.DPDK.rst \ INSTALL.Fedora.md \ - INSTALL.KVM.md \ + INSTALL.KVM.rst \ INSTALL.Libvirt.md \ INSTALL.NetBSD.md \ INSTALL.RHEL.md \ diff --git a/README.md b/README.md index 8ff5f5d..f824581 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ To use Open vSwitch... - ...with Docker on Linux, read [INSTALL.Docker.rst] -- ...with KVM on Linux, read [INSTALL.rst], read [INSTALL.KVM.md] +- ...with KVM on Linux, read [INSTALL.rst], read [INSTALL.KVM.rst] - ...with Libvirt, read [INSTALL.Libvirt.md]. @@ -120,7 +120,7 @@ bugs@openvswitch.org [INSTALL.Docker.rst]:INSTALL.Docker.rst [INSTALL.DPDK.rst]:INSTALL.DPDK.rst [INSTALL.Fedora.md]:INSTALL.Fedora.md -[INSTALL.KVM.md]:INSTALL.KVM.md +[INSTALL.KVM.rst]:INSTALL.KVM.rst [INSTALL.Libvirt.md]:INSTALL.Libvirt.md [INSTALL.RHEL.md]:INSTALL.RHEL.md [INSTALL.SELinux.md]:INSTALL.SELinux.md