INSTALL.RHEL.md

   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.md] 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. Install build prerequisites:
  36
  37    ```
  38    yum install gcc make python-devel openssl-devel kernel-devel graphviz \
  39        kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \
  40        libtool
  41    ```
  42
  43 2. If you are building from a distribution tarball, skip to step 3.
  44    Otherwise, you must be building from an Open vSwitch Git tree.
  45    Determine what version of Autoconf is installed (e.g. run "autoconf
  46    --version").  If it is not at least version 2.63, then you have two
  47    choices:
  48
  49      a. Install Autoconf 2.63 or later, one way or another.
  50
  51      b. Create a distribution tarball on some other machine, by
  52         running "./boot.sh; ./configure; make dist" in the Git tree.
  53         You must run this on a machine that has the tools listed in
  54         [INSTALL.md] as prerequisites for building from a Git tree.
  55         Afterward, proceed with the rest of the instructions using
  56                 the distribution tarball.
  57
  58 3. Some versions of the RHEL 6 kernel-devel package contain a broken
  59    "build" symlink.  If you are using such a version, you must fix
  60    the problem before continuing.
  61
  62    To find out whether you are affected, run:
  63
  64        ```
  65        cd /lib/modules/<version>
  66        ls -l build/
  67            ```
  68
  69    where `<version>` is the version number of the RHEL 6 kernel.  (The
  70    trailing slash in the final command is important.  Be sure to include
  71    it.)  If the "ls" command produces a directory listing, your
  72    kernel-devel package is OK.  If it produces a "No such file or
  73    directory" error, your kernel-devel package is buggy.
  74
  75    If your kernel-devel package is buggy, then you can fix it with:
  76
  77        ```
  78        cd /lib/modules/<version>
  79        rm build
  80        ln -s /usr/src/kernels/<target> build
  81            ```
  82
  83    where `<target>` is the name of an existing directory under
  84    /usr/src/kernels, whose name should be similar to `<version>` but may
  85    contain some extra parts.  Once you have done this, verify the fix with
  86    the same procedure you used above to check for the problem.
  87
  88 4. If you are building from a distribution tarball, skip to step 5.
  89    Otherwise, create a distribution tarball from the root of the Git
  90    tree by running:
  91
  92        ```
  93        ./boot.sh
  94        ./configure
  95        make dist
  96            ```
  97
  98 5. Now you have a distribution tarball, named something like
  99    openvswitch-x.y.z.tar.gz.  Copy this file into the RPM sources
 100    directory, e.g.:
 101
 102        `cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES`
 103
 104 6. Make another copy of the distribution tarball in a temporary
 105    directory.  Then unpack the tarball and "cd" into its root, e.g.:
 106
 107        ```
 108        tar xzf openvswitch-x.y.z.tar.gz
 109        cd openvswitch-x.y.z
 110            ```
 111
 112 7. To build Open vSwitch userspace, run:
 113
 114        `rpmbuild -bb rhel/openvswitch.spec`
 115
 116    This produces two RPMs: "openvswitch" and "openvswitch-debuginfo".
 117
 118    The above command automatically runs the Open vSwitch unit tests.
 119    To disable the unit tests, run:
 120
 121        `rpmbuild -bb --without check rhel/openvswitch.spec`
 122
 123    If the build fails with "configure: error: source dir
 124    /lib/modules/2.6.32-279.el6.x86_64/build doesn't exist" or similar,
 125    then the kernel-devel package is missing or buggy.  Go back to step
 126    1 or 2 and fix the problem.
 127
 128 8. On RHEL 6, to build the Open vSwitch kernel module, copy
 129    rhel/openvswitch-kmod.files into the RPM sources directory and run:
 130
 131         `rpmbuild -bb rhel/openvswitch-kmod-rhel6.spec`
 132
 133    You might have to specify a kernel version and/or variants, e.g.:
 134
 135     ```
 136         rpmbuild -bb \
 137                 -D "kversion 2.6.32-131.6.1.el6.x86_64" \
 138                 -D "kflavors default debug kdump" \
 139                 rhel/openvswitch-kmod-rhel6.spec
 140         ```
 141
 142    This produces an "kmod-openvswitch" RPM for each kernel variant, in
 143    this example: "kmod-openvswitch", "kmod-openvswitch-debug", and
 144    "kmod-openvswitch-kdump".
 145
 146 A RHEL host has default firewall rules that prevent any Open vSwitch tunnel
 147 traffic from passing through. If a user configures Open vSwitch tunnels like
 148 Geneve, GRE, VXLAN, LISP etc., they will either have to manually add iptables
 149 firewall rules to allow the tunnel traffic or add it through a startup script
 150 (Please refer to the "enable-protocol" command in the ovs-ctl(8) manpage).
 151
 152 Red Hat Network Scripts Integration
 153 -----------------------------------
 154
 155 Simple integration with Red Hat network scripts has been implemented.
 156 Please read [rhel/README.RHEL] in the source tree or
 157 /usr/share/doc/openvswitch/README.RHEL in the installed openvswitch
 158 package for details.
 159
 160 Reporting Bugs
 161 --------------
 162
 163 Please report problems to bugs@openvswitch.org.
 164
 165 [INSTALL.md]:INSTALL.md
 166 [rhel/README.RHEL]:rhel/README.RHEL