INSTALL.KVM.md

   1 How to Use Open vSwitch with KVM
   2 =================================
   3
   4 This document describes how to use Open vSwitch with the Kernel-based
   5 Virtual Machine (KVM). This document assumes that you have read and
   6 followed [INSTALL](INSTALL.md) to get Open vSwitch setup on your Linux
   7 system.
   8
   9 Setup
  10 -----
  11
  12 First, follow the setup instructions in [INSTALL](INSTALL.md) to get a
  13 working Open vSwitch installation.
  14
  15 KVM uses tunctl to handle various bridging modes, which you can
  16 install with the Debian/Ubuntu package uml-utilities.
  17
  18       % apt-get install uml-utilities
  19
  20 Next, you will need to modify or create custom versions of the qemu-ifup
  21 and qemu-ifdown scripts. In this guide, we'll create custom versions
  22 that make use of example Open vSwitch bridges that we'll describe in this
  23 guide.
  24
  25 Create the following two files and store them in known locations.
  26
  27 For example /etc/ovs-ifup and /etc/ovs-ifdown
  28
  29 /etc/ovs-ifup
  30
  31 ```
  32 #!/bin/sh
  33
  34 switch='br0'
  35 /sbin/ifconfig $1 0.0.0.0 up
  36 ovs-vsctl add-port ${switch} $1
  37 ```
  38
  39 /etc/ovs-ifdown
  40
  41 ```
  42 #!/bin/sh
  43
  44 switch='br0'
  45 /sbin/ifconfig $1 0.0.0.0 down
  46 ovs-vsctl del-port ${switch} $1
  47 ```
  48
  49 At the end of [INSTALL](INSTALL.md), it describes basic usage of creating
  50 bridges and ports. If you haven't already, create a bridge named
  51 br0 with the following command:
  52
  53       % ovs-vsctl add-br br0
  54
  55 Then, add a port to the bridge for the NIC that you want your guests
  56 to communicate over (e.g. eth0):
  57
  58       % ovs-vsctl add-port br0 eth0
  59
  60 Please refer to ovs-vsctl(8) for more details.
  61
  62 Next, we'll start a guest that will use our ifup and ifdown scripts.
  63
  64       % kvm -m 512 -net nic,macaddr=00:11:22:EE:EE:EE -net \
  65         tap,script=/etc/ovs-ifup,downscript=/etc/ovs-ifdown -drive \
  66         file=/path/to/disk-image,boot=on
  67
  68 This will start the guest and associate a tap device with it. The
  69 ovs-ifup script will add a port on the br0 bridge so that the
  70 guest will be able to communicate over that bridge.
  71
  72 To get some more information and for debugging you can use Open
  73 vSwitch utilities such as ovs-dpctl and ovs-ofctl, For example:
  74
  75       % ovs-dpctl show
  76       % ovs-ofctl show br0
  77
  78 You should see tap devices for each KVM guest added as ports to
  79 the bridge (e.g. tap0)
  80
  81 Please refer to ovs-dpctl(8) and ovs-ofctl(8) for more details.
  82
  83 Bug Reporting
  84 -------------
  85
  86 Please report problems to bugs@openvswitch.org.