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