devel/HowToBuildOpenAfsRpmPackages.mdwn

   1 [[!toc  levels=2]]
   2
   3 # Introduction
   4
   5 This guide shows how to build OpenAFS RPM packages for Red Hat Enterprise
   6 Linux, CentOS, and Fedora, using the contributed RPM spec file provided with
   7 the OpenAFS source code.
   8
   9 ## Prerequisites
  10
  11 Upgrade your kernel to the most recent version:
  12
  13     $ sudo yum update kernel
  14     $ sudo reboot                   # if updated
  15
  16 Install the packages required to build the OpenAFS source RPM (SRPM):
  17
  18     $ sudo yum install rpm-build yum-utils make perl libtool bzip2 wget
  19
  20 Additional build dependencies will be installed after the spec file is
  21 generated.
  22
  23 # Building OpenAFS RPMs
  24
  25 This section describes how to build RPMs for OpenAFS release or pre-release.
  26 See "Advanced topics" below to build packages based on the `master` branch for
  27 development and testing.
  28
  29 ## Method 1: Building from source code distribution
  30
  31 The OpenAFS Release Team provides software releases as source code
  32 distributions. A source RPM (SRPM) file can easily be built from a source
  33 distribution release with the `makesrpm.pl` script provided in the source tree.
  34
  35 Download the source distribution files from [openafs.org][3].  Four files are
  36 provided in a release; a source tarball, a documentation tarball, release
  37 notes, and a change log. Extract the `makesrpm.pl` script from the source
  38 tarball and then run `makesrpm.pl` to build the source RPM (SRPM). The
  39 resulting SRPM will be placed in the current directory.  Install the build
  40 dependencies with `yum-builddeps`, plus the kernel module build dependencies
  41 (which will not be installed with `yum-builddeps` due to some quirks of the
  42 OpenAFS spec file.) Finally, run `rpmbuild` to build the binary RPMs.  The
  43 resulting RPMs will be placed in `~/rpmbuild/RPMS`.
  44
  45     # Download source release.
  46     $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-src.tar.bz2
  47     $ wget https://www.openafs.org/dl/openafs/1.8.5/openafs-1.8.5-doc.tar.bz2
  48     $ wget https://www.openafs.org/dl/openafs/1.8.5/RELNOTES-1.8.5
  49     $ wget https://www.openafs.org/dl/openafs/1.8.5/ChangeLog
  50
  51     # Build the source RPM.
  52     $ tar xf openafs-1.8.5-src.tar.bz2 --strip-components=4 '*/makesrpm.pl'
  53     $ perl makesrpm.pl openafs-1.8.5-src.tar.bz2 openafs-1.8.5-doc.tar.bz2 RELNOTES-1.8.5 ChangeLog
  54
  55     # Install build dependencies.
  56     $ sudo yum-builddep openafs-1.8.5-1.src.rpm
  57     $ sudo yum install "kernel-devel-uname-r == $(uname -r)"
  58     $ sudo yum install elfutils-devel                         # if RHEL/CentOS 8
  59
  60     # Build RPMs.
  61     $ rpmbuild --rebuild openafs-1.8.5-1.src.rpm
  62
  63 ## Method 2: Building from a git checkout
  64
  65 The OpenAFS makefile has a target (`make srpm`) to build a source RPM (SRPM) from a git
  66 checkout of a release or pre-release tag.  A downside to this method is the
  67 release notes and change log provided in the OpenAFS source distribution
  68 releases are not included in the generated SRPM. This method can also be used
  69 to build RPMs from a local branch based on an OpenAFS stable branch, such as
  70 `openafs-stable-1_8_x`. See "Advanced topics" below to see how to build packages for testing
  71 based on the `master` branch.
  72
  73 To build packages from a git checkout, clone the repository, then checkout the
  74 release or pre-release tag, or a commit based on a stable branch.  Run the
  75 `regen.sh` tool to generate the `configure` script, then run `configure` to
  76 generate the makefile. (The `configure` options given in this step are not used
  77 to generate the binaries; those are defined in the spec file.)  The resulting
  78 source RPM will be placed in the `./packages` directory.  Install the build
  79 dependencies with `yum-builddep` and then build the binary RPMs with
  80 `rpmbuild`.
  81
  82     $ sudo yum install git make krb5-devel
  83
  84     $ git clone git://git.openafs.org/openafs.git
  85     $ cd openafs
  86     $ git checkout openafs-stable-1_8_5
  87
  88     $ ./regen.sh -q
  89     $ ./configure --disable-kernel-module
  90     $ make dist
  91     $ make srpm
  92
  93     # Install build dependencies.
  94     $ sudo yum-builddep packages/openafs-1.8.5-1.src.rpm
  95     $ sudo yum install "kernel-devel-uname-r == $(uname -r)"
  96     $ sudo yum install elfutils-devel                         # if RHEL/CentOS 8
  97
  98     # Build RPMs.
  99     $ rpmbuild --rebuild packages/openafs-1.8.5-1.src.rpm
 100
 101 ## Build options
 102
 103 The OpenAFS spec file provides several options to select which packages are to
 104 be  built by `rpmbuild` and to enable certain build-time features in the
 105 binaries. These options are specified as `rpmbuild`  command line arguments.
 106
 107 The `build_userspace` and `build_modules` defines control when the kernel
 108 module packages are to be built. Userspace packages includes all of the
 109 packages except the kernel module package, including the servers and the
 110 OpenAFS client Dynamic Kernel Module System (DKMS) package. By default,
 111 both the userspace and kernel modules are built.
 112
 113 To build all of the packages except the OpenAFS kernel module:
 114
 115     $ rpmbuild \
 116       --rebuild \
 117       --define "build_userspace 1" \
 118       --define "build_modules 0" \
 119       openafs-<version>-<release>.src.rpm
 120
 121 To build only the OpenAFS kernel module for the currently running kernel:
 122
 123     $ rpmbuild \
 124       --rebuild \
 125       --define "build_userspace 0" \
 126       --define "build_modules 1" \
 127       openafs-<version>-<release>.src.rpm
 128
 129 Specify the `kernvers` option to build kernel modules for specific kernel
 130 versions.  Install `kernel-devel` packages for the versions you wish to build.
 131 You may need to configure and enable the CentOS Vault "update" repositories for
 132 older kernel versions.
 133
 134     # Install an older kernel-devel version.
 135     $ sudo yum install kernel-devel-uname-r == "3.10.0-957.27.2.el7.x86_64"
 136
 137     $ rpm -qa kernel-devel
 138     kernel-devel-3.10.0-957.27.2.el7.x86_64
 139     kernel-devel-3.10.0-1062.12.1.el7.x86_64
 140
 141     $ rpm -i openafs-<version>-<release>.src.rpm
 142
 143     $ rpmbuild \
 144       -bb \
 145       --define "build_userspace 0" \
 146       --define "build_modules 1" \
 147       --define "kernvers 3.10.0-957.27.2.el7.x86_64" \
 148       ~/rpmbuild/SPECS/openafs.spec
 149
 150     $ rpmbuild \
 151       --bb \
 152       --define "build_userspace 0" \
 153       --define "build_modules 1" \
 154       --define "kernvers 3.10.0-1062.12.1.el7.x86_64" \
 155       ~/rpmbuild/SPECS/openafs.spec
 156
 157 Additional `rpmbuild` options provided by the OpenAFS spec file are:
 158
 159 * `--without authlibs`  Disable authlibs package
 160 * `--without krb5`  Disable krb5 support
 161 * `--with bitmap-later` Enable "bitmap later" support
 162 * `--with bos-restricted` Enable "bos restricted" mode
 163 * `--with supergroups`   Enable "supergroups"
 164 * `--with kauth`  Build the obsolete kaserver and related programs
 165
 166 ## Common errors
 167
 168 Avoid kernel module build errors by ensuring you have a kernel-devel package
 169 installed which matches the running kernel.
 170
 171     $ uname -r
 172     4.18.0-147.5.1.el8_1.x86_64
 173     $ rpm -qP kernel-devel | grep uname
 174     kernel-devel-uname-r = 4.18.0-147.5.1.el8_1.x86_64
 175
 176 Your build may fail with the error:
 177
 178     + /usr/lib/rpm/check-rpaths
 179     ...
 180     ERROR   0001: file '/usr/lib64/libafsauthent.so.2.0.0' contains a standard rpath '/usr/lib64' in [/usr/lib64]
 181
 182 This check fails because the OpenAFS spec hardcoded the `/usr/lib64` standard
 183 paths for some binaries. The Linux dynamic loader automatically loads shared
 184 objects from this system default path, so the path specified in the spec file is
 185 redundant.
 186
 187 To disable this `check-rpath` check, set the `QA_RPATHS` environment variable
 188 to `0x0001` before running rpmbuild.
 189
 190     $ export QA_RPATHS=0x0001
 191     $ rpmbuild -bb ~/rpmbuild/SPECS/openafs.spec
 192
 193 # Installing OpenAFS RPMs
 194
 195 ## Installing client RPMs with the Dynamic Kernel Module System (DKMS)
 196
 197 The Dynamic Kernel Module System (DKMS) kernel modules take longer to install,
 198 but are automatically rebuilt after the kernel is upgraded. Unless you are
 199 maintaining, or have access to, a yum repository which tracks kernel updates
 200 and builds matching OpenAFS kernel modules for each update, you will want to
 201 use the DKMS method to install the OpenAFS kernel module.
 202
 203 Add the EPEL yum repository, which provides the DKMS system.  Install the
 204 Kerberos5 workstation package, which provides the `kinit` program. Install the
 205 OpenAFS DKMS and openafs Kerberos5 support packages with `yum`. This will take
 206 some time as the kernel-module is built from source.  Be sure to install
 207 the openafs-client and dkms-openafs packages in a single `yum install`
 208 invocation.
 209
 210     $ cd ~/rpmbuild/RPMS/x86_64
 211     $ sudo yum install epel-release
 212     $ sudo yum install \
 213         krb5-workstation \
 214         openafs-1.8.5-1.el8.x86_64.rpm \
 215         openafs-docs-1.8.5-1.el8.x86_64.rpm \
 216         openafs-krb5-1.8.5-1.el8.x86_64.rpm \
 217         openafs-client-1.8.5-1.el8.x86_64.rpm \
 218         dkms-openafs-1.8.5-1.el8.x86_64.rpm
 219
 220 ## Installing client RPMs with a pre-built kernel module (kmod)
 221
 222 Install the kmod which matches your currently running kernel version.  Be sure
 223 to install the openafs-client and kmod-openafs packages in a single `yum
 224 install` invocation.
 225
 226     $ cd ~/rpmbuild/RPMS/x86_64
 227     $ sudo yum install \
 228         krb5-workstation \
 229         openafs-1.8.5-1.el8.x86_64.rpm \
 230         openafs-docs-1.8.5-1.el8.x86_64.rpm \
 231         openafs-krb5-1.8.5-1.el8.x86_64.rpm \
 232         openafs-client-1.8.5-1.el8.x86_64.rpm \
 233         kmod-openafs-1.8.5-1.4.18.0_147.5.1.el8_1.x86_64.rpm
 234
 235 ## Installing server RPMs
 236
 237 Install the server package with:
 238
 239     $ cd ~/rpmbuild/RPMS/x86_64
 240     $ sudo yum install \
 241         openafs-1.8.5-1.el8.x86_64.rpm \
 242         openafs-docs-1.8.5-1.el8.x86_64.rpm \
 243         openafs-server-1.8.5-1.el8.x86_64.rpm
 244
 245 # Advanced topics
 246
 247 ## Building RPMs with mock
 248
 249 [Mock][4] is a tool for building packages in a chroot. The mock chroot
 250 isolation makes it makes it easier to build a large number of kernel module
 251 versions on a single build host. In addition, mock provides a clean build
 252 environment for each build, and mock will automatically install the build
 253 requirements specified by the openafs.spec file in the temporary mock chroot.
 254
 255 Mock also provides the ability to build RPMs for different distributions on one
 256 machine. For example, one could build RPMs targeted for CentOS 6, 7, and 8 on
 257 one CentOS 8 build host. Although it is possible to build RPMs for other
 258 distributions with mock, it not possible to build RPMs for other architectures,
 259 since mock does not support cross-compiling.
 260
 261 Install mock and add yourself to the 'mock' group.
 262
 263     $ sudo yum install mock
 264     $ sudo usermod -a -G mock $USER
 265     $ newgrp - mock
 266
 267 To build OpenAFS rpms with mock, first create the OpenAFS source RPM as shown above,
 268 then run the mock commands to build the packages using the mock system.
 269
 270     $ mock --rebuild openafs-1.8.5-1.src.rpm
 271
 272 ## Building RPMs with afsutil
 273
 274 [afsutil][5] is a python tool to facilitate OpenAFS development.  The `afsutil
 275 package` command is a front-end tool for building RPMs from a git checkout,
 276 with or without mock. The main advantages of using `afsutil package` to build
 277 packages is that it makes it easy to build a source RPM (SRPM) from a git
 278 commit based on the master branch (as well as stable branches). This can be
 279 helpful to build packages for testing or to make changes to the master branch
 280 version of the spec file.
 281
 282 When used with mock, `afsutil` will, by default, build kernel modules for
 283 every kernel-devel version discovered in the enabled yum repositories within
 284 the mock chroot.
 285
 286 OpenAFS packages require a copy of the CellServDB client configuration file.
 287 `afsutil package` will automatically download the CellServDB version specified
 288 in the spec file from grand.central.org. An alternate CellServDB file can be
 289 specified by url or local path with the `--csdb` option.
 290
 291 RPM packages for `afsutil` are available. This is the preferred installation
 292 method on CentOS.  Alternatively, `aftutil` may be installed with `pip`, or from
 293 source.
 294
 295 ### Method 1: Installing afsutil with yum
 296
 297     $ sudo yum install https://download.sinenomine.net/openafs/repo/sna-openafs-release-latest.noarch.rpm
 298     $ sudo yum install afsutil
 299
 300 ### Method 2: Installing afsutil with pip
 301
 302     $ sudo yum install epel-release   # if RHEL/CentOS
 303     $ sudo yum install python2-pip    # if RHEL/CentOS 8
 304     $ sudo yum install python-pip     # if RHEL/CentOS 7 or earlier
 305     $ sudo pip install afsutil
 306
 307 ### Method 2: Installing afsutil from source
 308
 309     $ git clone https://github.com/openafs-contrib/afsutil
 310     $ cd afsutil
 311     $ python configure.py  # or, python2 configure.py on RHEL/CentOS 8
 312     $ sudo make install
 313
 314 ### Building RPMs with afsutil
 315
 316 To build OpenAFS packages from a git checkout:
 317
 318     $ sudo afsutil getdeps  # Install build dependencies
 319     $ git clone git://git.openafs.org/openafs.git
 320     $ cd openafs
 321     $ afsutil package
 322
 323 The `afsutil package` command will build packages for the userspace and kernel
 324 modules by default. See the `--build` option to build these separately.
 325
 326 If you installed `mock` (see above), specify the `--mock` option to build the
 327 packages in the mock chroot. Mock will automatically install the build
 328 dependencies.
 329
 330 Build the server, client, and kernel module for the local machine with:
 331
 332     $ afsutil package --mock --kernel="$(uname -r)"
 333
 334 `afsutil package --mock` will query the yum repositories configured for the
 335 mock chroot to discover the kernel-devel kernel versions available.  You can
 336 add local yum repositories to your mock configurations in `/etc/mock/` to
 337 provide kernel-devel packages for older kernel versions.
 338
 339 To list kernel versions available in the mock chroot:
 340
 341     $ afsutil package --mock --list 2>/tmp/error
 342     3.10.0-1062.4.2.el7
 343     3.10.0-1062.4.3.el7
 344     3.10.0-1062.9.1.el7
 345     3.10.0-1062.12.1.el7
 346     ...
 347
 348 Specify the --kernel option to build a kmod for specific kernel version. This
 349 option may be given more than once to build multiple kernel modules.
 350
 351    $ afsutil package --mock --build=kmods --kernel=3.10.0-1062.4.3.el7
 352
 353 To build all kernel module versions:
 354
 355     $ afsutil package --mock --build=kmods
 356
 357 If the afsutil package command is interrupted and then restarted, builds for
 358 any already completed kmod-openafs RPMs will be skipped. Use the the --clobber
 359 option to override this and force all of the RPMs to be rebuilt.
 360
 361 See `afsutil package --help` for the available options.  Default values for
 362 options may be specified in the `.afsutil.cfg` configuration file. See
 363 the [afsutil README][5] for more information.
 364
 365 # See also
 366
 367 * [RPM Packaging Guide][6]
 368
 369
 370 [1]: https://github.com/openafs-contrib/afsutil
 371 [2]: https://pypi.org/project/afsutil/
 372 [3]: https://www.openafs.org/release/
 373 [4]: https://github.com/rpm-software-management/mock/wiki
 374 [5]: https://github.com/openafs-contrib/afsutil
 375 [6]: https://rpm-packaging-guide.github.io/