diff --git a/INSTALL.KVM.md b/INSTALL.KVM.md deleted file mode 100644 index 99f481dc0d1..00000000000 --- 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 00000000000..9e0b2bdd943 --- /dev/null +++ b/INSTALL.KVM.rst @@ -0,0 +1,104 @@ +.. + 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. + +Bug Reporting +------------- + +Please report problems to bugs@openvswitch.org. diff --git a/Makefile.am b/Makefile.am index cf8aa4321b8..a4842c10882 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 8ff5f5d1bba..f824581440f 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