INSTALL.RHEL

   1        How to Install Open vSwitch on Red Hat Enterprise Linux
   2        =======================================================
   3
   4 This document describes how to build and install Open vSwitch on a Red
   5 Hat Enterprise Linux (RHEL) host.  If you want to install Open vSwitch
   6 on a generic Linux host, see INSTALL instead.
   7
   8 We have tested these instructions with RHEL 5.6 and RHEL 6.0.
   9
  10 Building Open vSwitch for RHEL
  11 ------------------------------
  12
  13 You may build from an Open vSwitch distribution tarball or from an
  14 Open vSwitch Git tree.
  15
  16 The default RPM build directory (_topdir) has five directories in
  17 the top-level:
  18 1. BUILD/ Where the software is unpacked and built.
  19 2. RPMS/ Where the newly created binary package files are written.
  20 3. SOURCES/ Contains the original sources, patches, and icon files.
  21 4. SPECS/ Contains the spec files for each package to be built.
  22 5. SRPMS/ Where the newly created source package files are written.
  23
  24 Before you begin, note the RPM sources directory on your version of
  25 RHEL.  The command "rpmbuild --showrc" will show the configuration
  26 for each of those directories. Alternatively, the command "rpm --eval
  27  '%{_topdir}'" shows the current configuration for the top level
  28 directory and the command "rpm --eval '%{_sourcedir}'" does the same
  29 for the sources directory. On RHEL 5, the default RPM _topdir is
  30 /usr/src/redhat and the default RPM sources directory is
  31 /usr/src/redhat/SOURCES. On RHEL 6, the default _topdir is
  32 $HOME/rpmbuild and the default RPM sources directory is
  33 $HOME/rpmbuild/SOURCES.
  34
  35 1. If you are building from a distribution tarball, proceed to step 2.
  36    Otherwise, if you are building from an Open vSwitch Git tree,
  37    determine the version of Autoconf available in the RHEL version you
  38    are using.  If it is not at least version 2.63, then you have two
  39    choices:
  40
  41      a. Install Autoconf 2.63 or later, one way or another.
  42
  43      b. Create a distribution tarball on some other machine, by
  44         running "./boot.sh; ./configure; make dist" in the Git tree.
  45         You must run this on a machine that has the tools listed in
  46         INSTALL as prerequisites for building from a Git tree.
  47         Afterward, proceed with the rest of the instructions using the
  48         distribution tarball.
  49
  50 2. Install build prerequisites:
  51
  52    yum install gcc make python-devel openssl-devel kernel-devel graphviz \
  53        kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \
  54        libtool
  55
  56 3. Some versions of the RHEL 6 kernel-devel package contain a broken
  57    "build" symlink.  If you are using such a version, you must fix
  58    the problem before continuing.
  59
  60    To find out whether you are affected, run:
  61
  62        cd /lib/modules/<version>
  63        ls -l build/
  64
  65    where <version> is the version number of the RHEL 6 kernel.  (The
  66    trailing slash in the final command is important.  Be sure to include
  67    it.)  If the "ls" command produces a directory listing, your
  68    kernel-devel package is OK.  If it produces a "No such file or
  69    directory" error, your kernel-devel package is buggy.
  70
  71    If your kernel-devel package is buggy, then you can fix it with:
  72
  73        cd /lib/modules/<version>
  74        rm build
  75        ln -s /usr/src/kernels/<target> build
  76
  77    where <target> is the name of an existing directory under
  78    /usr/src/kernels, whose name should be similar to <version> but may
  79    contain some extra parts.  Once you have done this, verify the fix with
  80    the same procedure you used above to check for the problem.
  81
  82 4. If you are building from an Open vSwitch Git tree, then you will
  83    need to first create a distribution tarball by running "./boot.sh;
  84    ./configure; make dist" in the Git tree.
  85
  86 5. Copy the distribution tarball into the RPM sources directory.
  87
  88 6. Unpack the distribution tarball into a temporary directory and "cd"
  89    into the root of the distribution tarball.
  90
  91 7. To build Open vSwitch userspace, run:
  92
  93        rpmbuild -bb rhel/openvswitch.spec
  94
  95    This produces two RPMs: "openvswitch" and "openvswitch-debuginfo".
  96
  97    The above command automatically runs the Open vSwitch unit tests.
  98    To disable the unit tests, run:
  99
 100        rpmbuild -bb --without check rhel/openvswitch.spec
 101
 102    If the build fails with "configure: error: source dir
 103    /lib/modules/2.6.32-279.el6.x86_64/build doesn't exist" or similar,
 104    then the kernel-devel package is missing or buggy.  Go back to step
 105    1 or 2 and fix the problem.
 106
 107 8. On RHEL 6, to build the Open vSwitch kernel module, copy
 108     rhel/openvswitch-kmod.files into the RPM sources directory and run:
 109
 110         rpmbuild -bb rhel/openvswitch-kmod-rhel6.spec
 111
 112     You might have to specify a kernel version and/or variants, e.g.:
 113
 114         rpmbuild -bb \
 115                 -D "kversion 2.6.32-131.6.1.el6.x86_64" \
 116                 -D "kflavors default debug kdump" \
 117                 rhel/openvswitch-kmod-rhel6.spec
 118
 119     This produces an "kmod-openvswitch" RPM for each kernel variant,
 120     in this example: "kmod-openvswitch", "kmod-openvswitch-debug", and
 121     "kmod-openvswitch-kdump".
 122
 123 A RHEL host has default firewall rules that prevent any Open vSwitch tunnel
 124 traffic from passing through. If a user configures Open vSwitch tunnels like
 125 Geneve, GRE, VXLAN, LISP etc., they will either have to manually add iptables
 126 firewall rules to allow the tunnel traffic or add it through a startup script
 127 (Please refer to the "enable-protocol" command in the ovs-ctl(8) manpage).
 128
 129 Red Hat Network Scripts Integration
 130 -----------------------------------
 131
 132 Simple integration with Red Hat network scripts has been implemented.
 133 Please read rhel/README.RHEL in the source tree or
 134 /usr/share/doc/openvswitch/README.RHEL in the installed openvswitch
 135 package for details.
 136
 137 Reporting Bugs
 138 --------------
 139
 140 Please report problems to bugs@openvswitch.org.