From patchwork Sun Oct 30 13:29:59 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 688948 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3t6JRK3SXcz9t1T for ; Mon, 31 Oct 2016 00:35:56 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=jwpBUhGR; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 7B250105DE; Sun, 30 Oct 2016 06:35:48 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx1e3.cudamail.com (mx1.cudamail.com [69.90.118.67]) by archives.nicira.com (Postfix) with ESMTPS id 5535F10569 for ; Sun, 30 Oct 2016 06:35:47 -0700 (PDT) Received: from bar5.cudamail.com (localhost [127.0.0.1]) by mx1e3.cudamail.com (Postfix) with ESMTPS id 767054203AA for ; Sun, 30 Oct 2016 07:35:46 -0600 (MDT) X-ASG-Debug-ID: 1477834545-09eadd0f98243af0001-byXFYA Received: from mx1-pf1.cudamail.com ([192.168.24.1]) by bar5.cudamail.com with ESMTP id x8DFwps8Mk3GwGRH (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Sun, 30 Oct 2016 07:35:45 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.24.1 Received: from unknown (HELO nov-007-i610.relay.mailchannels.net) (46.232.183.164) by mx1-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 30 Oct 2016 13:35:44 -0000 Received-SPF: none (mx1-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 46.232.183.164 X-Barracuda-RBL-IP: 46.232.183.164 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 02E201BC90A for ; Sun, 30 Oct 2016 13:33:30 +0000 (UTC) Received: from one.mxroute.com (ip-10-27-139-41.us-west-2.compute.internal [10.27.139.41]) by relay.mailchannels.net (Postfix) with ESMTPA id 43FAA1BC3B5 for ; Sun, 30 Oct 2016 13:33:29 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.107.128.240]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sun, 30 Oct 2016 13:33:29 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1477834409620:1306132337 X-MC-Ingress-Time: 1477834409620 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=ozn7WK4mQnFjgd2Na4iwGremS+cTbrW8wpfRehMhPpY=; b=jwpBUhGRd1Bnnw5/StdsRyN3gu e37pK4BTdsiqbnORKMe2BC9WSBcF5MYYwkxTEnyr/2qoQepqEak/Ci+VHdDnCodEaxofkJr2gdb4T CNtQj1aumR6yzThzkuAVDg3l9Q7Yg3kguYRjWZ+La214+4Y0xvR9Nes1/5epT3T6FyVAeuHZQUT5c nsZyTmv5e16k/k6OeKAufuTErsTy0jZp25J2xZrcdH0J1gVR2MhdgHbOZEQCs/HXWkWUmZAFxnIpz 0lJcdhziIDWBhGLq3yrjEYxg7LQR/eYXPcm1uYnJmBox/5B94TwNX7hBtfXj8h903tHsOFODSKeBX f+4aUcbg==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-E1-1029006676 X-CudaMail-DTE: 103016 X-CudaMail-Originating-IP: 46.232.183.164 Date: Sun, 30 Oct 2016 13:29:59 +0000 X-ASG-Orig-Subj: [##CM-E1-1029006676##][PATCH 13/23] doc: Convert INSTALL.RHEL to rST Message-Id: <1477834209-11414-14-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1477834209-11414-1-git-send-email-stephen@that.guru> References: <1477834209-11414-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-Barracuda-Connect: UNKNOWN[192.168.24.1] X-Barracuda-Start-Time: 1477834545 X-Barracuda-Encrypted: ECDHE-RSA-AES256-GCM-SHA384 X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 X-Barracuda-Spam-Score: 1.10 X-Barracuda-Spam-Status: No, SCORE=1.10 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.34168 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 13/23] doc: Convert INSTALL.RHEL to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Signed-off-by: Stephen Finucane --- INSTALL.Docker.rst | 2 +- INSTALL.RHEL.md | 171 ------------------------------------------- INSTALL.RHEL.rst | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL.rst | 2 +- Makefile.am | 2 +- README.rst | 2 +- 6 files changed, 212 insertions(+), 175 deletions(-) delete mode 100644 INSTALL.RHEL.md create mode 100644 INSTALL.RHEL.rst diff --git a/INSTALL.Docker.rst b/INSTALL.Docker.rst index 35dcce2..236857a 100644 --- a/INSTALL.Docker.rst +++ b/INSTALL.Docker.rst @@ -290,7 +290,7 @@ The "underlay" mode Depending on your VM, you can make the above step persistent across reboots. For example, if your VM is Debian/Ubuntu-based, read `openvswitch-switch.README.Debian` found in `debian` folder. If your VM is - RHEL-based, refer to the `RHEL install guide <../../INSTALL.RHEL.md>`__. + RHEL-based, refer to the `RHEL install guide <../../INSTALL.RHEL.rst>`__. 3. Start the Open vSwitch network driver diff --git a/INSTALL.RHEL.md b/INSTALL.RHEL.md deleted file mode 100644 index de33a46..0000000 --- a/INSTALL.RHEL.md +++ /dev/null @@ -1,171 +0,0 @@ -How to Install Open vSwitch on Red Hat Enterprise Linux -======================================================= - -This document describes how to build and install Open vSwitch on a Red -Hat Enterprise Linux (RHEL) host. If you want to install Open vSwitch -on a generic Linux host, see [INSTALL.rst] instead. - -We have tested these instructions with RHEL 5.6 and RHEL 6.0. - -For RHEL 7.x (or derivatives, such as CentOS 7.x), you should follow -the instructions in [INSTALL.Fedora.rst]. The Fedora spec files are -used for RHEL 7.x. - -Building Open vSwitch for RHEL ------------------------------- - -You may build from an Open vSwitch distribution tarball or from an -Open vSwitch Git tree. - -The default RPM build directory (_topdir) has five directories in -the top-level: -1. BUILD/ Where the software is unpacked and built. -2. RPMS/ Where the newly created binary package files are written. -3. SOURCES/ Contains the original sources, patches, and icon files. -4. SPECS/ Contains the spec files for each package to be built. -5. SRPMS/ Where the newly created source package files are written. - -Before you begin, note the RPM sources directory on your version of -RHEL. The command "rpmbuild --showrc" will show the configuration -for each of those directories. Alternatively, the command "rpm --eval - '%{_topdir}'" shows the current configuration for the top level -directory and the command "rpm --eval '%{_sourcedir}'" does the same -for the sources directory. On RHEL 5, the default RPM _topdir is -/usr/src/redhat and the default RPM sources directory is -/usr/src/redhat/SOURCES. On RHEL 6, the default _topdir is -$HOME/rpmbuild and the default RPM sources directory is -$HOME/rpmbuild/SOURCES. - -1. Install build prerequisites: - - ``` - yum install gcc make python-devel openssl-devel kernel-devel graphviz \ - kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \ - libtool - ``` - -2. If you are building from a distribution tarball, skip to step 3. - Otherwise, you must be building from an Open vSwitch Git tree. - Determine what version of Autoconf is installed (e.g. run "autoconf - --version"). If it is not at least version 2.63, then you have two - choices: - - a. Install Autoconf 2.63 or later, one way or another. - - b. Create a distribution tarball on some other machine, by - running "./boot.sh; ./configure; make dist" in the Git tree. - You must run this on a machine that has the tools listed in - [INSTALL.rst] as prerequisites for building from a Git tree. - Afterward, proceed with the rest of the instructions using - the distribution tarball. - -3. Some versions of the RHEL 6 kernel-devel package contain a broken - "build" symlink. If you are using such a version, you must fix - the problem before continuing. - - To find out whether you are affected, run: - - ``` - cd /lib/modules/ - ls -l build/ - ``` - - where `` is the version number of the RHEL 6 kernel. (The - trailing slash in the final command is important. Be sure to include - it.) If the "ls" command produces a directory listing, your - kernel-devel package is OK. If it produces a "No such file or - directory" error, your kernel-devel package is buggy. - - If your kernel-devel package is buggy, then you can fix it with: - - ``` - cd /lib/modules/ - rm build - ln -s /usr/src/kernels/ build - ``` - - where `` is the name of an existing directory under - /usr/src/kernels, whose name should be similar to `` but may - contain some extra parts. Once you have done this, verify the fix with - the same procedure you used above to check for the problem. - -4. If you are building from a distribution tarball, skip to step 5. - Otherwise, create a distribution tarball from the root of the Git - tree by running: - - ``` - ./boot.sh - ./configure - make dist - ``` - -5. Now you have a distribution tarball, named something like - openvswitch-x.y.z.tar.gz. Copy this file into the RPM sources - directory, e.g.: - - `cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES` - -6. Make another copy of the distribution tarball in a temporary - directory. Then unpack the tarball and "cd" into its root, e.g.: - - ``` - tar xzf openvswitch-x.y.z.tar.gz - cd openvswitch-x.y.z - ``` - -7. To build Open vSwitch userspace, run: - - `rpmbuild -bb rhel/openvswitch.spec` - - This produces two RPMs: "openvswitch" and "openvswitch-debuginfo". - - The above command automatically runs the Open vSwitch unit tests. - To disable the unit tests, run: - - `rpmbuild -bb --without check rhel/openvswitch.spec` - - If the build fails with "configure: error: source dir - /lib/modules/2.6.32-279.el6.x86_64/build doesn't exist" or similar, - then the kernel-devel package is missing or buggy. Go back to step - 1 or 2 and fix the problem. - -8. On RHEL 6, to build the Open vSwitch kernel module, copy - rhel/openvswitch-kmod.files into the RPM sources directory and run: - - `rpmbuild -bb rhel/openvswitch-kmod-rhel6.spec` - - You might have to specify a kernel version and/or variants, e.g.: - - ``` - rpmbuild -bb \ - -D "kversion 2.6.32-131.6.1.el6.x86_64" \ - -D "kflavors default debug kdump" \ - rhel/openvswitch-kmod-rhel6.spec - ``` - - This produces an "kmod-openvswitch" RPM for each kernel variant, in - this example: "kmod-openvswitch", "kmod-openvswitch-debug", and - "kmod-openvswitch-kdump". - -A RHEL host has default firewall rules that prevent any Open vSwitch tunnel -traffic from passing through. If a user configures Open vSwitch tunnels like -Geneve, GRE, VXLAN, LISP etc., they will either have to manually add iptables -firewall rules to allow the tunnel traffic or add it through a startup script -(Please refer to the "enable-protocol" command in the ovs-ctl(8) manpage). - -Red Hat Network Scripts Integration ------------------------------------ - -Simple integration with Red Hat network scripts has been implemented. -Please read [rhel/README.RHEL.rst] in the source tree or -/usr/share/doc/openvswitch/README.RHEL.rst in the installed openvswitch -package for details. - -Reporting Bugs --------------- - -Please report problems to bugs@openvswitch.org. - -[INSTALL.rst]:INSTALL.rst -[INSTALL.Fedora.rst]:INSTALL.Fedora.rst -[rhel/README.RHEL.rst]:rhel/README.RHEL.rst diff --git a/INSTALL.RHEL.rst b/INSTALL.RHEL.rst new file mode 100644 index 0000000..125c55d --- /dev/null +++ b/INSTALL.RHEL.rst @@ -0,0 +1,208 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +======================================== +Open vSwitch on Red Hat Enterprise Linux +======================================== + +This document describes how to build and install Open vSwitch on a Red Hat +Enterprise Linux (RHEL) host. If you want to install Open vSwitch on a generic +Linux host, see the `general installation guide `__ instead. + +We have tested these instructions with RHEL 5.6 and RHEL 6.0. + +For RHEL 7.x (or derivatives, such as CentOS 7.x), you should follow the +instructions in the `Fedora installation guide `__. The +Fedora spec files are used for RHEL 7.x. + +Prerequisites +------------- + +You may build from an Open vSwitch distribution tarball or from an Open vSwitch +Git tree. + +The default RPM build directory, ``_topdir``, has five directories in the +top-level. + +BUILD/ + where the software is unpacked and built +RPMS/ + where the newly created binary package files are written +SOURCES/ + contains the original sources, patches, and icon files +SPECS/ + contains the spec files for each package to be built +SRPMS/ + where the newly created source package files are written + +Before you begin, note the RPM sources directory on your version of RHEL. The +command ``rpmbuild --showrc`` will show the configuration for each of those +directories. Alternatively, the command ``rpm --eval '%{_topdir}'`` shows the +current configuration for the top level directory and the command ``rpm --eval +'%{_sourcedir}'`` does the same for the sources directory. On RHEL 5, the +default RPM ``_topdir`` is ``/usr/src/redhat`` and the default RPM sources +directory is ``/usr/src/redhat/SOURCES``. On RHEL 6, the default ``_topdir`` is +``$HOME/rpmbuild`` and the default RPM sources directory is +``$HOME/rpmbuild/SOURCES``. + +Build Requirements +------------------ + +To compile the RPMs, you will need to install the packages described in the +`general installation guide `__ along with some additional +packages. These can be installed with the below command:: + + $ yum install gcc make python-devel openssl-devel kernel-devel graphviz \ + kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \ + libtool + +Bootstrapping and Configuring +----------------------------- + +If you are building from a distribution tarball, skip to *Building*. If not, +you must be building from an Open vSwitch Git tree. Determine what version of +Autoconf is installed (e.g. run ``autoconf --version``). If it is not at least +version 2.63, then you must upgrade or use another machine to build the +packages. + +Assuming all requirements have been met, build the tarball by running:: + + $ ./boot.sh + $ ./configure + $ make dist + +You must run this on a machine that has the tools listed in the `general +installation guide `__ as prerequisites for building from a Git +tree. Afterward, proceed with the rest of the instructions using the +distribution tarball. + +Now you have a distribution tarball, named something like +``openvswitch-x.y.z.tar.gz``. Copy this file into the RPM sources directory, +e.g.:: + + $ cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES + +Broken ``build`` symlink +~~~~~~~~~~~~~~~~~~~~~~~~ + +Some versions of the RHEL 6 kernel-devel package contain a broken ``build`` +symlink. If you are using such a version, you must fix the problem before +continuing. + +To find out whether you are affected, run:: + + $ cd /lib/modules/ + $ ls -l build/ + +where ```` is the version number of the RHEL 6 kernel. + +.. note:: + The trailing slash in the final command is important. Be sure to include + it. + +If the ``ls`` command produces a directory listing, your kernel-devel package +is OK. If it produces a ``No such file or directory`` error, your kernel-devel +package is buggy. + +If your kernel-devel package is buggy, then you can fix it with:: + + $ cd /lib/modules/ + $ rm build + $ ln -s /usr/src/kernels/ build + +where ```` is the name of an existing directory under +``/usr/src/kernels``, whose name should be similar to ```` but may +contain some extra parts. Once you have done this, verify the fix with the +same procedure you used above to check for the problem. + +Building +-------- + +You should have a distribution tarball named something like +openvswitch-x.y.z.tar.gz. Copy this file into the RPM sources directory:: + + $ cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES + +Make another copy of the distribution tarball in a temporary directory. Then +unpack the tarball and ``cd`` into its root:: + + $ tar xzf openvswitch-x.y.z.tar.gz + $ cd openvswitch-x.y.z + +Userspace +~~~~~~~~~ + +To build Open vSwitch userspace, run:: + + $ rpmbuild -bb rhel/openvswitch.spec + +This produces two RPMs: "openvswitch" and "openvswitch-debuginfo". + +The above command automatically runs the Open vSwitch unit tests. To disable +the unit tests, run:: + + $ rpmbuild -bb --without check rhel/openvswitch.spec + +.. note:: + If the build fails with ``configure: error: source dir + /lib/modules/2.6.32-279.el6.x86_64/build doesn't exist`` or similar, then + the kernel-devel package is missing or buggy. + +Kernel Module +~~~~~~~~~~~~~ + +On RHEL 6, to build the Open vSwitch kernel module, copy +rhel/openvswitch-kmod.files into the RPM sources directory and run:: + + $ rpmbuild -bb rhel/openvswitch-kmod-rhel6.spec + +You might have to specify a kernel version and/or variants, e.g.: + + $ rpmbuild -bb \ + -D "kversion 2.6.32-131.6.1.el6.x86_64" \ + -D "kflavors default debug kdump" \ + rhel/openvswitch-kmod-rhel6.spec + +This produces an "kmod-openvswitch" RPM for each kernel variant, in this +example: "kmod-openvswitch", "kmod-openvswitch-debug", and +"kmod-openvswitch-kdump". + +Red Hat Network Scripts Integration +----------------------------------- + +A RHEL host has default firewall rules that prevent any Open vSwitch tunnel +traffic from passing through. If a user configures Open vSwitch tunnels like +Geneve, GRE, VXLAN, LISP etc., they will either have to manually add iptables +firewall rules to allow the tunnel traffic or add it through a startup script +Refer to the "enable-protocol" command in the ovs-ctl(8) manpage for more +information. + +In addition, simple integration with Red Hat network scripts has been +implemented. Refer to `README.RHEL.rst `__ in the source +tree or /usr/share/doc/openvswitch/README.RHEL.rst in the installed openvswitch +package for details. + +Reporting Bugs +-------------- + +Report problems to bugs@openvswitch.org. diff --git a/INSTALL.rst b/INSTALL.rst index 5c40ab9..2aafbde 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -31,7 +31,7 @@ platform, refer to one of these installation guides: - `Debian `__ - `Fedora `__ -- `RHEL `__ +- `RHEL `__ - `XenServer `__ - `NetBSD `__ - `Windows `__ diff --git a/Makefile.am b/Makefile.am index d032cb7..80ac7aa 100644 --- a/Makefile.am +++ b/Makefile.am @@ -80,7 +80,7 @@ docs = \ INSTALL.KVM.rst \ INSTALL.Libvirt.rst \ INSTALL.NetBSD.rst \ - INSTALL.RHEL.md \ + INSTALL.RHEL.rst \ INSTALL.SELinux.md \ INSTALL.SSL.rst \ INSTALL.XenServer.rst \ diff --git a/README.rst b/README.rst index 979852b..ff8ad88 100644 --- a/README.rst +++ b/README.rst @@ -79,7 +79,7 @@ specific platform, please see one of the below installation guides: - `Debian `__ - `Fedora `__ -- `RHEL `__ +- `RHEL `__ - `XenServer `__ - `Windows `__