How to build OpenAFS RPMs
[openafs-wiki.git] / devel / HowToBuildOpenAfsRpmPackages.mdwn
index fd7d0af..2ebb0bf 100644 (file)
-# Building RPM packages for OpenAFS
+[[!toc  levels=2]]
 
-This pages describes how to build OpenAFS client and server packages for RHEL
-and CentOS using the contributed RPM spec file available in the OpenAFS source
-tree.  Packages may be build from the OpenAFS release tar files or from a clone
-of the OpenAFS git repository.  It is recommended to use Fedora `mock` to build
-packages, especially if you are building packages for multiple kernel versions.
-This page describes how to build packages with and without `mock`.
+# Introduction
 
-The general process is:
+This guide shows how to build OpenAFS RPM packages for Red Hat Enterprise
+Linux, CentOS, and Fedora, using the contributed RPM spec file provided with
+the OpenAFS source code.
 
-* Set up the RPM build directories
-* Download or extract the RPM sources
-   - Release Notes
-   - CellServDB file
-   - Source code tar file
-   - Documentation tar file
-* Extract the openafs.spec file from the openafs code tree
-   - Set the OpenAFS version and package release versions
-* Run rpmbuild -bs to create a source RPM
-* Run rpmbuild with options to create RPM package files
+## Prerequisites
 
-Available resources for building RPM packages:
+Upgrade your kernel to the most recent version:
 
-* The OpenAFS makefile has targets to build the source RPM
-* The OpenAFS src/packaging/RedHat/makesrpm.pl script may be used to build the source RPM (This script is used by the makefile)
-* The OpenAFS-contrib [afsutil package][1] script will build RPMs in a local git repo, and has options to support building packages with `mock`.
+    $ sudo yum update kernel
+    $ sudo reboot                   # if updated
 
+Install the kernel-devel package for your running kernel.
 
-## How to build release packages from git
+    $ sudo yum install "kernel-devel-uname-r == $(uname -r)"
 
-The following commands show how to build RPM packages from a git checkout of a
-released version of OpenAFS.  The following commands build RPM packages from a
-release tag.
+Install the packages required to build the OpenAFS source RPM (SRPM):
 
-    $ git clone git://git.openafs.org/openafs.git
-    $ cd openafs
-    $ git checkout <openafs-release-tag>  # e.g., openafs-stable-1_8_5
+    $ sudo yum install rpm-build yum-utils make perl libtool bzip2 wget
+
+Additional build dependencies will be installed after the spec file is
+generated.
+
+# Building OpenAFS RPMs
+
+This section describes how to build RPMs for OpenAFS release or pre-release.
+See "Advanced topics" below to build packages based on the `master` branch for
+development and testing.
+
+## Method 1: Building from source code distribution
+
+The OpenAFS Release Team provides software releases as source code
+distributions. A source RPM (SRPM) file can easily be built from a source
+distribution release with the `makesrpm.pl` script provided in the source tree.
+After creating the SRPM, run `rpmbuild --rebuild` with the SRPM to build the
+binary OpenAFS RPMs.
+
+Download the source distribution files from [openafs.org][3].  Four files are
+provided in a release; a source tarball, a documentation tarball, release
+notes, and a change log. Extract the `makesrpm.pl` script from the source
+tarball and then run `makesrpm.pl` to build the source RPM (SRPM). The
+resulting SRPM will be placed in the current directory. Run `rpmbuild` to build
+the binary RPMs. The resulting RPMs will be placed in `~/rpmbuild/RPMS`.
+
+    # Download source release.
+    $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-src.tar.bz2
+    $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-doc.tar.bz2
+    $ wget https://www.openafs.org/dl/openafs/1.8.5/RELNOTES-1.8.5
+    $ wget https://www.openafs.org/dl/openafs/1.8.5/ChangeLog
 
-    $ ./regen.sh
-    $ ./configure  # configure options are not required here.
-    $ make dist    # creates the source distribution in ./packages
-    $ make srpm    # get the source rpm name from the output
+    # Build the source RPM.
+    $ tar xf openafs-1.8.5-src.tar.bz2 --strip-components=4 '*/makesrpm.pl'
+    $ perl makesrpm.pl openafs-1.8.5-src.tar.bz2 openafs-1.8.5-doc.tar.bz2 RELNOTES-1.8.5 ChangeLog
 
-    $ rpmbuild --rebuild -ba --define "_topdir $(pwd)/packages/rpmbuild" packages/<name>.src.rpm
+    # Install build dependencies and build the binary RPMs.
+    $ rpm -iv openafs-1.8.5-1.src.rpm
+    $ sudo yum-builddep ~/rpmbuild/SPECS/openafs.spec
+    $ rpmbuild -bb ~/rpmbuild/SPECS/openafs.spec
 
-The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.  See
-the RPM spec file in src/packaging/RedHat for `--define` options for optional
-features and packages.
+If the build dependencies are already installed, you can let rpmbuild install
+the source RPM and build the packages in one step:
 
-Note: One downside to this method is the RELNOTES and ChangeLog from the
-OpenAFS release download page are not included in the build packages.
+    $ rpmbuild --rebuild openafs-1.8.5-1.src.rpm
 
-## How to build release packages with afsutil
+## Method 2: Building from a git checkout
 
-The contributed `afsutil`[1] script can be used to build packages from a git
-checkout. This tool is a front-end with various options to support building
-client and server packages from release tags as well as non-release commits.
-`afsutil` is available on [PyPI][2] and [github][1]
+The OpenAFS makefile has a targets to build a source RPM (SRPM) from a git
+checkout of a release or pre-release tag.  A downside to this method is the
+release notes and change log provided in the OpenAFS source distribution
+releases are not included in the generated SRPM. This method can also be used
+to build RPMs from a local branch based on an OpenAFS stable branch, such as
+`openafs-stable-1_8_x`. See "Advanced topics" below to see how to build packages for testing
+based on the `master` branch.
 
+To build packages from a git checkout, clone the repository, then checkout the
+release or pre-release tag, or a commit based on a stable branch.  Run the
+`regen.sh` tool to generate the `configure` script, then run `configure` to
+generate the makefile. (The `configure` options given in this step are not used
+to generate the binaries; those are defined in the spec file.)  The resulting
+source RPM will be placed in the `./packages` directory.
 
-    $ pip install afsutil
+    $ sudo yum install git make krb5-devel
 
     $ git clone git://git.openafs.org/openafs.git
     $ cd openafs
-    $ git checkout <tag>  # e.g., openafs-stable-1_8_5
+    $ git checkout openafs-stable-1_8_5
 
-    $ afsutil package [options]
+    $ ./regen.sh -q
+    $ ./configure --disable-kernel-module
+    $ make dist
+    $ make srpm
 
-The RPM packages will be created in the `packages/rpmbuild/RPMS` directory.
+    # Install build dependencies and build the binary RPMs.
+    $ rpm -iv packages/openafs-1.8.5-1.src.rpm
+    $ sudo yum-builddep ~/rpmbuild/SPECS/openafs.spec
+    $ rpmbuild -bb ~/rpmbuild/SPECS/openafs.spec
 
-Some commonly used `afsutil package` options are:
+If the build dependencies have already been installed, you can let rpmbuild
+install the source RPM and build the packages in one step:
 
-    --version=<custom-version> # for testing or building custom versions
-    --csdb=<path-to-custom-CellServDB-file>
-    --spec=<path-to-custom-openafs-spec-file>
-    --build=<what to build, one of: all, sources, srpm, userspace, kmods>
-    --kernel-version=<kernel-version> # may be given more than once
+    $ rpmbuild --rebuild packages/openafs-1.8.5-1.src.rpm
 
-See `afsutil package --help` for a complete list of options.
+## Build options
 
-## How to build release packages from OpenAFS source distributions
+The OpenAFS spec file provides several options to select which packages are to
+be  built by `rpmbuild` and to enable certain build-time features in the
+binaries. These options are specified as `rpmbuild`  command line arguments.
 
-The OpenAFS project provides [source code distributions of releases][3]. These
-files are, of course, available via AFS3 at
-`/afs/grand.central.org/software/openafs` The source RPM file can be built from
-the source distribution releases without external tools.
+The `build_userspace` and `build_modules` defines control when the the kernel
+module packages are to be built. Userspace packages includes all of the
+packages except the kernel module package, including the servers and the
+OpenAFS client Dynamic Kernel Module System (DKMS) package. By default,
+both the userspace and kernel modules are built.
 
-Step 1. Download the source distribution files.
+To build all of the packages except the OpenAFS kernel module:
 
-Four files are provided; source tarball, documentation tarball, release notes,
-and a change log.
+    $ rpmbuild --rebuild \
+      --define "build_userspace 1" \
+      --define "build_modules 0" \
+      openafs-1.8.5-1.src.rpm
 
-    $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-src.tar.bz2
-    $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-doc.tar.bz2
-    $ wget https://www.openafs.org/dl/openafs/1.8.5/RELNOTES-1.8.5
-    $ wget https://www.openafs.org/dl/openafs/1.8.5/ChangeLog
+To build only the OpenAFS kernel module for the currently running kernel:
+
+    $ rpmbuild \
+      --rebuild \
+      --define "build_userspace 0" \
+      --define "build_modules 1" \
+      openafs-1.8.5-1.src.rpm
+
+Specify the `kervers` option to build kernel modules for specific kernel
+versions.  Install `kernel-devel` packages for the versions you wish to build.
+You may need to configure and enable the CentOS Vault "update" repositories for
+older kernel versions.
+
+    # Install an older kernel-devel version.
+    $ sudo yum install kernel-devel-uname-r == "3.10.0-957.27.2.el7.x86_64"
+
+    $ rpm -qa kernel-devel
+    kernel-devel-3.10.0-957.27.2.el7.x86_64
+    kernel-devel-3.10.0-1062.12.1.el7.x86_64
+
+    $ rpmbuild \
+      --rebuild \
+      --define "build_userspace 0" \
+      --define "build_modules 1" \
+      --define "kernvers 3.10.0-957.27.2.el7.x86_64" \
+      openafs-1.8.5-1.src.rpm
+
+    $ rpmbuild \
+      --rebuild \
+      --define "build_userspace 0" \
+      --define "build_modules 1" \
+      --define "kernvers 3.10.0-1062.12.1.el7.x86_64" \
+      openafs-1.8.5-1.src.rpm
+
+Additional `rpmbuild` options provided by the OpenAFS spec file are:
+
+* `--without authlibs`  Disable authlibs package
+* `--without krb5`  Disable krb5 support
+* `--with bitmap-later` Enable "bitmap later" support
+* `--with bos-restricted` Enable "bos restricted" mode
+* `--with supergroups`   Enable "supergroups"
+* `--with kauth`  Build the obsolete kaserver and related programs
+
+## Common errors
 
-Step 2. Extract the packaging files.
+Avoid kernel module build errors by ensuring you have a kernel-devel package
+installed which matches the running kernel.
 
-The packaging files are contained in the source tarball.
+    $ uname -r
+    4.18.0-147.5.1.el8_1.x86_64
+    $ rpm -qP kernel-devel | grep uname
+    kernel-devel-uname-r = 4.18.0-147.5.1.el8_1.x86_64
 
-    $ tar -x -j -f openafs-1.8.5-src.tar.bz2 openafs-1.8.5/src/packaging/RedHat
+Your build may fail with the error:
 
+    + /usr/lib/rpm/check-rpaths
+    ...
+    ERROR   0001: file '/usr/lib64/libafsauthent.so.2.0.0' contains a standard rpath '/usr/lib64' in [/usr/lib64]
+
+This check fails because the OpenAFS spec hardcoded the `/usr/lib64` standard
+paths for some binaries. The Linux dynamic loader automatically loads shared
+objects from this system default path, so the path specified in the spec file is
+redundant.
+
+To disable this `check-rpath` check, set the `QA_RPATHS` environment variable
+to `0x0001` before running rpmbuild.
+
+    $ export QA_RPATHS=0x0001
+    $ rpmbuild -bb ~/rpmbuild/SPECS/openafs.spec
+
+# Installing OpenAFS RPMs
+
+## Installing client RPMs with the Dynamic Kernel Module System (DKMS)
+
+The Dynamic Kernel Module System (DKMS) kernel modules take longer to install,
+but are automatically rebuilt after the kernel is upgraded. Unless you are
+maintaining, or have access to, a yum repository which tracks kernel updates
+and builds matching OpenAFS kernel modules for each update, you will want to
+use the DKMS method to install the OpenAFS kernel module.
+
+Add the EPEL yum repository, which provides the DKMS system.  Install the
+Kerberos5 workstation package, which provides the `kinit` program. Install the
+OpenAFS DKMS and openafs Kerberos5 support packages with `yum`. This will take
+some time as the kernel-module is built from source.  Be sure to install
+the openafs-client and dkms-openafs packages in a single `yum install`
+invocation.
+
+    $ cd ~/rpmbuild/RPMS/x86_64
+    $ sudo yum install epel-release
+    $ sudo yum install \
+        krb5-workstation \
+        openafs-1.8.5-1.el8.x86_64.rpm \
+        openafs-docs-1.8.5-1.el8.x86_64.rpm \
+        openafs-krb5-1.8.5-1.el8.x86_64.rpm \
+        openafs-client-1.8.5-1.el8.x86_64.rpm \
+        dkms-openafs-1.8.5-1.el8.x86_64.rpm
+
+## Installing client RPMs with a pre-built kernel module (kmod)
+
+Install the kmod which matches your currently running kernel version.  Be sure
+to install the openafs-client and kmod-openafs packages in a single `yum
+install` invocation.
+
+    $ cd ~/rpmbuild/RPMS/x86_64
+    $ sudo yum install \
+        krb5-workstation \
+        openafs-1.8.5-1.el8.x86_64.rpm \
+        openafs-docs-1.8.5-1.el8.x86_64.rpm \
+        openafs-krb5-1.8.5-1.el8.x86_64.rpm \
+        openafs-client-1.8.5-1.el8.x86_64.rpm \
+        kmod-openafs-1.8.5-1.4.18.0_147.5.1.el8_1.x86_64.rpm
+
+## Installing server RPMs
+
+Install the server package with:
+
+    $ cd ~/rpmbuild/RPMS/x86_64
+    $ sudo yum install \
+        openafs-1.8.5-1.el8.x86_64.rpm \
+        openafs-docs-1.8.5-1.el8.x86_64.rpm \
+        openafs-server-1.8.5-1.el8.x86_64.rpm
 
-Step 3. Set the version strings.
+# Advanced topics
 
-The version being built must be set in the spec file. Replace the following
-three version placeholders to create a spec file.
+## Building RPMs with mock
 
-    $ sed \
-      -e s/@PACKAGE_VERSION@/1.8.5/ \
-      -e s/@LINUX_PKGVER@/1.8.5/ \
-      -e s/@LINUX_PKGREL@/1/  \
-      openafs-1.8.5/packaging/RedHat/openafs.spec.in > openafs.spec
+[Mock][4] is a tool for building packages in a chroot. The mock chroot
+isolation makes it makes it easier to build a large number of kernel module
+versions on a single build host. In addition, mock provides a clean build
+environment for each build, and mock will automatically install the build
+requirements specified by the openafs.spec file in the temporary mock chroot.
 
+Mock also provides the ability to build RPMs for different distributions on one
+machine. For example, one could build RPMs targeted for CentOS 6, 7, and 8 on
+one CentOS 8 build host. Although it is possible to build RPMs for other
+distributions with mock, it not possible to build RPMs for other architectures,
+since mock does not support cross-compiling.
 
-Step 4: Download the CellServDB file.
+Install mock and add yourself to the 'mock' group.
 
-The CellServDB file is maintained at grand.central.org. Download the expected
-version specified in the spec file.  The path is set in the spec file as
-`Source20` in existing spec files. This could change in the future.
+    $ sudo yum install mock
+    $ sudo usermod -a -G mock $USER
+    $ newgrp - mock
 
-     $ grep '^Source20' openafs.spec
-     Source20: https://www.central.org/dl/cellservdb/CellServDB.2018-05-14
+To build OpenAFS rpms with mock, first create the OpenAFS RPM as shown above.
+Then run the mock commands to build the packages using the mock system.
 
-     $ wget https://www.central.org/dl/cellservdb/CellServDB.2018-05-14
+    $ mock --rebuild openafs-1.8.5-1.src.rpm
 
+## Building RPMs with afsutil
 
-Step 5. Populate the build directories.
+[afsutil][5] is a python tool to facilitate OpenAFS development.  The `afsutil
+package` command is a front-end tool for building RPMs from a git checkout,
+with or without mock. The main advantages of using `afsutil package` to build
+packages is that it makes it easy to build a source RPM (SRPM) from a git
+commit based on the master branch (as well as stable branches). This can be
+helpful to build packages for testing or to make changes to the master branch
+version of the spec file.
 
-    $ mkdir -p rpmbuild/{SOURCES,SPECS,SRPMS}
+When used with mock, `afsutil` will, by default, build kernel modules for
+every kernel-devel version discovered in the enabled yum repositories within
+the mock chroot.
 
-    $ cp openafs.spec rpmbuild/SPECS/
+OpenAFS packages require a copy of the CellServDB client configuration file.
+`afsutil package` will automatically download the CellServDB version specified
+in the spec file from grand.central.org. An alternate CellServDB file can be
+specified by url or local path with the `--csdb` option.
 
-    $ cp openafs-1.8.5-src.tar.bz2 rpmbuild/SOURCES/
-    $ cp openafs-1.8.5-doc.tar.bz2 rpmbuild/SOURCES/
-    $ cp RELNOTES-1.8.5 rpmbuild/SOURCES/
-    $ cp ChangeLog rpmbuild/SOURCES/
+RPM packages for `afsutil` are available. This is the preferred installation
+method on CentOS.  Alternatively, `aftutil` may be installed with `pip`, or from
+source.
 
-    $ cp CellServDB.2018-05-14 rpmbuild/SOURCES/
+### Method 1: Installing afsutil with yum
 
-    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-kvers-is.sh rpmbuild/SOURCES/
-    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-buildfedora.pl rpmbuild/SOURCES/
-    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-buildall.sh rpmbuild/SOURCES/
-    $ cp openafs-1.8.5/src/packaging/RedHat/openafs-kmodtool rpmbuild/SOURCES/
+    $ sudo yum install https://download.sinenomine.net/openafs/repo/sna-openafs-release-latest.noarch.rpm
+    $ sudo yum install afsutil
 
-At this point your rpmbuild tree should look like:
+### Method 2: Installing afsutil with pip
 
-    rpmbuild
-    ├── SOURCES
-    │   ├── CellServDB.2018-05-14
-    │   ├── ChangeLog
-    │   ├── openafs-1.8.5-doc.tar.bz2
-    │   ├── openafs-1.8.5-src.tar.bz2
-    │   ├── openafs-buildall.sh
-    │   ├── openafs-buildfedora.pl
-    │   ├── openafs-kmodtool
-    │   ├── openafs-kvers-is.sh
-    │   └── RELNOTES-1.8.5
-    ├── SPECS
-    │   └── openafs.spec
-    └── SRPMS
+    $ sudo yum install epel-release   # if RHEL/CentOS
+    $ sudo yum install python2-pip    # if RHEL/CentOS 8
+    $ sudo yum install python-pip     # if RHEL/CentOS 7 or earlier
+    $ sudo pip install afsutil
 
+### Method 2: Installing afsutil from source
 
-Step 6: Build the source rpm:
+    $ git clone https://github.com/openafs-contrib/afsutil
+    $ cd afsutil
+    $ python configure.py  # or, python2 configure.py on RHEL/CentOS 8
+    $ sudo make install
 
-    $ rpmbuild -bs --define "_topdir $(pwd)/rpmbuild" rpmbuild/SPECS/openafs.spec
+### Building RPMs with afsutil
+
+To build OpenAFS packages from a git checkout:
+
+    $ sudo afsutil getdeps  # Install build dependencies
+    $ git clone git://git.openafs.org/openafs.git
+    $ cd openafs
+    $ afsutil package
+    $ ls packages
+
+The `afsutil package` command will build packages for the userspace and kernel
+modules by default. See the `--build` option to build these separately.
+
+If you installed `mock` (see above), specify the `--mock` option to build the
+packages in the mock chroot. Mock will automatically install the build
+dependencies.
+
+Build the server, client, and kernel module for the local machine with:
+
+    $ afsutil package --mock --kernel="$(uname -r)"
+
+`afsutil package --mock` will query the yum repositories configured for the
+mock chroot to discover the kernel-devel kernel versions available.  You can
+add local yum repositories to your mock configurations in `/etc/mock/` to
+provide kernel-devel packages for older kernel versions.
+
+To list kernel versions available in the mock chroot:
+
+    $ afsutil package --mock --list 2>/tmp/error
+    3.10.0-1062.4.2.el7
+    3.10.0-1062.4.3.el7
+    3.10.0-1062.9.1.el7
+    3.10.0-1062.12.1.el7
     ...
-    Wrote: /tmp/bs2/rpmbuild/SRPMS/openafs-1.8.5-1.src.rpm
 
-Step 7: Build the rpm packages
+Specify the --kernel option to build a kmod for specific kernel version. This
+option may be given more than once to build multiple kernel modules.
+
+   $ afsutil package --mock --build=kmods --kernel=3.10.0-1062.4.3.el7
+
+To build all kernel module versions:
 
-    $ rpmbuild -ba --define "_topdir $(pwd)/rpmbuild" rpmbuild/SRPMS/openafs-1.8.5-1.src.rpm
+    $ afsutil package --mock --build=kmods
 
+If the afsutil package command is interrupted and then restarted, builds for
+any already completed kmod-openafs RPMs will be skipped. Use the the --clobber
+option to override this and force all of the RPMs to be rebuilt.
 
-## Version Strings
+See `afsutil package --help` for the available options.  Default values for
+options may be specified in the `.afsutil.cfg` configuration file. See
+the [afsutil README][5] for more information.
 
-A note about version strings. RPM packages require a valid version string and
-package release number.  If you are building packages for version which is not
-a release (or pre-release), for example perhaps you want to make changes and
-build packages for testing, perhaps you wish to deploy packages with custom
-changes or fixes, you will need to set a customized version string in the spec
-file.
+# See also
 
-In the following examples, set the version string the `.version` to generate a
-`openafs.spec` file with your desired version.  If you are using the `afsutil
-package` contributed script, use the `--version` option to specify your custom
-version.
+* [RPM Packaging Guide][6]
 
 
 [1]: https://github.com/openafs-contrib/afsutil
 [2]: https://pypi.org/project/afsutil/
 [3]: https://www.openafs.org/release/
+[4]: https://github.com/rpm-software-management/mock/wiki
+[5]: https://github.com/openafs-contrib/afsutil
+[6]: https://rpm-packaging-guide.github.io/