Documentation/intro/install/rhel.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 RHEL 5.6, 6.x Packaging for Open vSwitch
  26 ========================================
  27
  28 This document describes how to build and install Open vSwitch on a Red Hat
  29 Enterprise Linux (RHEL) host.  If you want to install Open vSwitch on a generic
  30 Linux host, refer to :doc:`general` instead.
  31
  32 We have tested these instructions with RHEL 5.6 and RHEL 6.0.
  33
  34 For RHEL 7.x (or derivatives, such as CentOS 7.x), you should follow the
  35 instructions in the :doc:`fedora`.  The Fedora spec files are used for RHEL
  36 7.x.
  37
  38 .. _rhel-prerequisites:
  39
  40 Prerequisites
  41 -------------
  42
  43 You may build from an Open vSwitch distribution tarball or from an Open vSwitch
  44 Git tree.
  45
  46 The default RPM build directory, ``_topdir``, has five directories in the
  47 top-level.
  48
  49 BUILD/
  50   where the software is unpacked and built
  51 RPMS/
  52   where the newly created binary package files are written
  53 SOURCES/
  54   contains the original sources, patches, and icon files
  55 SPECS/
  56   contains the spec files for each package to be built
  57 SRPMS/
  58   where the newly created source package files are written
  59
  60 Before you begin, note the RPM sources directory on your version of RHEL.  The
  61 command ``rpmbuild --showrc`` will show the configuration for each of those
  62 directories. Alternatively, the command ``rpm --eval '%{_topdir}'`` shows the
  63 current configuration for the top level directory and the command ``rpm --eval
  64 '%{_sourcedir}'`` does the same for the sources directory. On RHEL 5, the
  65 default RPM ``_topdir`` is ``/usr/src/redhat`` and the default RPM sources
  66 directory is ``/usr/src/redhat/SOURCES``. On RHEL 6, the default ``_topdir`` is
  67 ``$HOME/rpmbuild`` and the default RPM sources directory is
  68 ``$HOME/rpmbuild/SOURCES``.
  69
  70 Build Requirements
  71 ------------------
  72
  73 You will need to install all required packages to build the RPMs.
  74 The command below will install RPM tools and generic build dependencies::
  75
  76     $ yum install @'Development Tools' rpm-build yum-utils
  77
  78 Then it is necessary to install Open vSwitch specific build dependencies.
  79 The dependencies are listed in the SPEC file, but first it is necessary
  80 to replace the VERSION tag to be a valid SPEC.
  81
  82 The command below will create a temporary SPEC file::
  83
  84     $ sed -e 's/@VERSION@/0.0.1/' rhel/openvswitch.spec.in > /tmp/ovs.spec
  85
  86 And to install specific dependencies, use yum-builddep tool::
  87
  88     $ yum-builddep /tmp/ovs.spec
  89
  90 Once that is completed, remove the file ``/tmp/ovs.spec``.
  91
  92 If python3-sphinx package is not available in your version of RHEL, you can
  93 install it via pip with 'pip install sphinx'.
  94
  95 Open vSwitch requires python 3.4 or newer which is not available in older
  96 distributions. In the case of RHEL 6.x and its derivatives, one option is
  97 to install python34 from `EPEL`_.
  98
  99 .. _EPEL: https://fedoraproject.org/wiki/EPEL
 100
 101 .. _rhel-bootstrapping:
 102
 103 Bootstrapping and Configuring
 104 -----------------------------
 105
 106 If you are building from a distribution tarball, skip to :ref:`rhel-building`.
 107 If not, you must be building from an Open vSwitch Git tree.  Determine what
 108 version of Autoconf is installed (e.g. run ``autoconf --version``).  If it is
 109 not at least version 2.63, then you must upgrade or use another machine to
 110 build the packages.
 111
 112 Assuming all requirements have been met, build the tarball by running::
 113
 114     $ ./boot.sh
 115     $ ./configure
 116     $ make dist
 117
 118 You must run this on a machine that has the tools listed in
 119 :ref:`general-build-reqs` as prerequisites for building from a Git tree.
 120 Afterward, proceed with the rest of the instructions using the distribution
 121 tarball.
 122
 123 Now you have a distribution tarball, named something like
 124 ``openvswitch-x.y.z.tar.gz``.  Copy this file into the RPM sources directory,
 125 e.g.::
 126
 127     $ cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES
 128
 129 Broken ``build`` symlink
 130 ~~~~~~~~~~~~~~~~~~~~~~~~
 131
 132 Some versions of the RHEL 6 kernel-devel package contain a broken ``build``
 133 symlink.  If you are using such a version, you must fix the problem before
 134 continuing.
 135
 136 To find out whether you are affected, run::
 137
 138     $ cd /lib/modules/<version>
 139     $ ls -l build/
 140
 141 where ``<version>`` is the version number of the RHEL 6 kernel.
 142
 143 .. note::
 144   The trailing slash in the final command is important.  Be sure to include
 145   it.
 146
 147 If the ``ls`` command produces a directory listing, your kernel-devel package
 148 is OK.  If it produces a ``No such file or directory`` error, your kernel-devel
 149 package is buggy.
 150
 151 If your kernel-devel package is buggy, then you can fix it with::
 152
 153     $ cd /lib/modules/<version>
 154     $ rm build
 155     $ ln -s /usr/src/kernels/<target> build
 156
 157 where ``<target>`` is the name of an existing directory under
 158 ``/usr/src/kernels``, whose name should be similar to ``<version>`` but may
 159 contain some extra parts.  Once you have done this, verify the fix with the
 160 same procedure you used above to check for the problem.
 161
 162 .. _rhel-building:
 163
 164 Building
 165 --------
 166
 167 You should have a distribution tarball named something like
 168 openvswitch-x.y.z.tar.gz.  Copy this file into the RPM sources directory::
 169
 170     $ cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES
 171
 172 Make another copy of the distribution tarball in a temporary directory.  Then
 173 unpack the tarball and ``cd`` into its root::
 174
 175     $ tar xzf openvswitch-x.y.z.tar.gz
 176     $ cd openvswitch-x.y.z
 177
 178 Userspace
 179 ~~~~~~~~~
 180
 181 To build Open vSwitch userspace, run::
 182
 183     $ rpmbuild -bb rhel/openvswitch.spec
 184
 185 This produces two RPMs: "openvswitch" and "openvswitch-debuginfo".
 186
 187 The above command automatically runs the Open vSwitch unit tests.  To disable
 188 the unit tests, run::
 189
 190     $ rpmbuild -bb --without check rhel/openvswitch.spec
 191
 192 .. note::
 193    If the build fails with ``configure: error: source dir
 194    /lib/modules/2.6.32-279.el6.x86_64/build doesn't exist`` or similar, then
 195    the kernel-devel package is missing or buggy.
 196
 197 Kernel Module
 198 ~~~~~~~~~~~~~
 199
 200 On RHEL 6, to build the Open vSwitch kernel module run::
 201
 202     $ rpmbuild -bb rhel/kmod-openvswitch-rhel6.spec
 203
 204 You might have to specify a kernel version and/or variants, e.g.:
 205
 206     $ rpmbuild -bb \
 207         -D "kversion 2.6.32-131.6.1.el6.x86_64" \
 208         -D "kflavors default debug kdump" \
 209         rhel/kmod-openvswitch-rhel6.spec
 210
 211 This produces an "kmod-openvswitch" RPM for each kernel variant, in this
 212 example: "kmod-openvswitch", "kmod-openvswitch-debug", and
 213 "kmod-openvswitch-kdump".
 214
 215 .. _rhel-script-integrations:
 216
 217 Red Hat Network Scripts Integration
 218 -----------------------------------
 219
 220 A RHEL host has default firewall rules that prevent any Open vSwitch tunnel
 221 traffic from passing through. If a user configures Open vSwitch tunnels like
 222 Geneve, GRE, VXLAN, LISP etc., they will either have to manually add iptables
 223 firewall rules to allow the tunnel traffic or add it through a startup script
 224 Refer to the "enable-protocol" command in the ovs-ctl(8) manpage for more
 225 information.
 226
 227 In addition, simple integration with Red Hat network scripts has been
 228 implemented.  Refer to `README.RHEL.rst`__ in the source tree or
 229 /usr/share/doc/openvswitch/README.RHEL.rst in the installed openvswitch package
 230 for details.
 231
 232 __ https://github.com/openvswitch/ovs/blob/master/rhel/README.RHEL.rst
 233
 234 Reporting Bugs
 235 --------------
 236
 237 Report problems to bugs@openvswitch.org.