INSTALL.Libvirt.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 =========================
  25 Open vSwitch with Libvirt
  26 =========================
  27
  28 This document describes how to use Open vSwitch with Libvirt 0.9.11 or later.
  29 This document assumes that you followed the `general installation guide
  30 <INSTALL.rst>`__ or installed Open vSwitch from distribution packaging such as
  31 a .deb or .rpm.  The Open vSwitch support is included by default in Libvirt
  32 0.9.11. Consult www.libvirt.org for instructions on how to build the latest
  33 Libvirt, if your Linux distribution by default comes with an older Libvirt
  34 release.
  35
  36 Limitations
  37 -----------
  38
  39 Currently there is no Open vSwitch support for networks that are managed by
  40 libvirt (e.g. NAT). As of now, only bridged networks are supported (those where
  41 the user has to manually create the bridge).
  42
  43 Setup
  44 -----
  45
  46 First, create the Open vSwitch bridge by using the ovs-vsctl utility (this must
  47 be done with administrative privileges)::
  48
  49     $ ovs-vsctl add-br ovsbr
  50
  51 Once that is done, create a VM, if necessary, and edit its Domain XML file::
  52
  53     $ virsh edit <vm>
  54
  55 Lookup in the Domain XML file the ``<interface>`` section. There should be one
  56 such XML section for each interface the VM has::
  57
  58     <interface type='network'>
  59      <mac address='52:54:00:71:b1:b6'/>
  60      <source network='default'/>
  61      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/>
  62     </interface>
  63
  64 And change it to something like this::
  65
  66     <interface type='bridge'>
  67      <mac address='52:54:00:71:b1:b6'/>
  68      <source bridge='ovsbr'/>
  69      <virtualport type='openvswitch'/>
  70      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/>
  71     </interface>
  72
  73 The interface type must be set to ``bridge``. The ``<source>`` XML element
  74 specifies to which bridge this interface will be attached to. The
  75 ``<virtualport>`` element indicates that the bridge in ``<source>`` element is
  76 an Open vSwitch bridge.
  77
  78 Then (re)start the VM and verify if the guest's vnet interface is attached to
  79 the ovsbr bridge::
  80
  81     $ ovs-vsctl show
  82
  83 Troubleshooting
  84 ---------------
  85
  86 If the VM does not want to start, then try to run the libvirtd process either
  87 from the terminal, so that all errors are printed in console, or inspect
  88 Libvirt/Open vSwitch log files for possible root cause.
  89
  90 Bug Reporting
  91 -------------
  92
  93 Report problems to bugs@openvswitch.org.