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