Debian Codegraph @

UG9/en/build-install-from-source.adoc

raw
1
2 /////////////////////////////
3 [[ch-build-install-from-source]]
4 == Building and installing DRBD from source
5
6 [[s-downloading-drbd-sources]]
7 === Downloading the DRBD sources
8
9 The source tarballs for both current and historic DRBD releases are
10 available for download from http://oss.linbit.com/drbd/. Source
11 tarballs, by convention, are named `drbd-__x__.__y__.__z__.tar.gz`
12 resp. `drbd-utils-__x__.__y__.__z__.tar.gz`, where _x_, _y_ and
13 _z_ refer to the major, minor and bugfix release numbers.
14
15 DRBD's compressed source archive is less than half a megabyte in
16 size. To download and uncompress into your current working directory,
17 issue the following commands:
18
19 -------------------------------------
20 $ wget http://oss.linbit.com/drbd/9.0/drbd-latest.tar.gz
21 $ tar -xzf drbd-latest.tar.gz
22 -------------------------------------
23
24 NOTE: The use of `wget` for downloading the source tarball is purely
25 an example. Of course, you may use any downloader you prefer.
26
27 It is recommended to uncompress DRBD into a directory normally used
28 for keeping source code, such as `/usr/src` or `/usr/local/src`. The
29 examples in this guide assume `/usr/src`.
30
31 [[s-checking-out-git]]
32 === Checking out sources from the public DRBD source repository
33
34 DRBD's source code is kept in a public Gitfootnote:[See http://git.or.cz]
35 repository, which may be browsed on-line at http://git.drbd.org/. The DRBD
36 software consists of 3 projects:
37
38 . The DRBD kernel module
39 . The DRBD utilities
40 . Drbdmanage (optional)
41
42 Source code can be obtained by either cloning `git` repositories or downloading
43 release tarballs. There are actually two minor differences between an unpacked
44 source tarball and a Git checkout of the same release:
45
46 * The Git checkout contains a `debian/` subdirectoy, while the source
47 tarball does not. This is due to a request from Debian maintainers,
48 who prefer to add their own Debian build configuration to a pristine
49 upstream tarball.
50
51 * The source tarball contains preprocessed man pages, the Git checkout
52 does not. Thus, building DRBD from a Git checkout requires a
53 complete Docbook toolchain for building the man pages, while this is
54 not a requirement for building from a source tarball.
55
56 [[s-drbd_kernel_module]]
57 ==== DRBD kernel module
58 To check out a specific DRBD release from the repository, you must first
59 _clone_ the DRBD repository:
60
61 -------------------------------------
62 $ git clone --recursive git://git.drbd.org/drbd-9.0.git
63 -------------------------------------
64
65 If your firewall does not permit TCP connections to port 9418, you may
66 also check out via HTTP (please note that using Git via HTTP is much
67 slower than its native protocol, so native Git is usually preferred
68 whenever possible):
69
70 -------------------------------------
71 $ git clone --recursive http://git.drbd.org/drbd-9.0.git
72 -------------------------------------
73
74 Either command will create a Git checkout subdirectory, named
75 `drbd-9.0`. To now move to a source code state equivalent to a
76 specific DRBD release (here 9.0.0), issue the following commands:
77
78 -------------------------------------
79 $ cd drbd-9.0
80 $ git checkout drbd-9.0.0
81 $ git submodule update
82 -------------------------------------
83
84
85 [[s-drbd_utilities]]
86 ==== DRBD utilities
87 To check out `drbd-utils` issue the following command:
88
89 -------------------------------------
90 $ git clone --recursive http://git.drbd.org/drbd-utils.git
91 -------------------------------------
92
93 `Drbd-utils` from version 8.9.x onward supports DRBD kernel modules versions 8.3, 8.4, and 9.0.
94
95 [[s-drbdmanage]]
96 ==== Drbdmanage
97 To check out `drbdmanage` issue the following command:
98
99 -------------------------------------
100 $ git clone --recursive http://git.drbd.org/drbdmanage.git
101 -------------------------------------
102
103
104 [[s-build-from-source]]
105 === Building DRBD from source
106
107 [[s-build-prereq]]
108 ==== Checking build prerequisites
109
110 Before being able to build DRBD from source, your build host must
111 fulfill the following prerequisites:
112
113 * `make`, `gcc`, the glibc development libraries, and the `flex` scanner
114 generator must be installed.
115
116 NOTE: You should make sure that the `gcc` you use to compile the
117 module is the same which was used to build the kernel you are
118 running. If you have multiple `gcc` versions available on your system,
119 DRBD's build system includes a facility to <<s-build-customcc,select
120 a specific `gcc` version>>.
121
122 * For building directly from a git checkout, GNU Autoconf is also
123 required. This requirement does not apply when building from a
124 tarball.
125
126 * If you are running a stock kernel supplied by your distribution, you
127 should install a matching kernel headers package. These
128 are typically named `kernel-devel`, `kernel-headers`, `linux-headers` or
129 similar. In this case, you can skip <<s-build-prepare-kernel-tree>>
130 and continue with <<s-build-prepare-checkout>>.
131
132 * If you are not running a distribution stock kernel (i.e. your system
133 runs on a kernel built from source with a custom configuration),
134 your kernel source files must be installed.
135 +
136 --
137
138 NOTE: On RPM-based systems, these packages will be named similar to
139 `kernel-source-__version__.rpm`, which is easily confused with
140 `kernel-__version__.src.rpm`. The former is the correct package to
141 install for building DRBD.
142 --
143
144 "Vanilla" kernel tarballs from the http://kernel.org/ archive are simply named
145 `linux-__version__.tar.bz2` and should be unpacked in
146 `/usr/src/linux-__version__`, with the symlink `/usr/src/linux` pointing
147 to that directory.
148
149 In this case of building DRBD against kernel sources (not headers),
150 you must continue with <<s-build-prepare-kernel-tree>>.
151
152 [[s-build-prepare-kernel-tree]]
153 ==== Preparing the kernel source tree
154
155 To prepare your source tree for building DRBD, you must first enter
156 the directory where your unpacked kernel sources are
157 located. Typically this is `/usr/src/linux-__version__`, or simply a
158 symbolic link named `/usr/src/linux`:
159
160 -------------------------------------
161 # cd /usr/src/linux
162 -------------------------------------
163
164 The next step is recommended, though not strictly necessary. *Be sure
165 to copy your existing `.config` file to a safe location before
166 performing it*. This step essentially reverts your kernel source tree
167 to its original state, removing any leftovers from an earlier build or
168 configure run:
169
170 -------------------------------------
171 # make mrproper
172 -------------------------------------
173
174 Now it is time to _clone_ your currently running kernel configuration
175 into the kernel source tree. There are a few possible options for
176 doing this:
177
178 * Many reasonably recent kernel builds export the currently-running
179 configuration, in compressed form, via the `/proc` filesystem,
180 enabling you to copy from there:
181
182 -------------------------------------
183 # zcat /proc/config.gz > .config
184 -------------------------------------
185
186 * SUSE kernel Makefiles include a `cloneconfig` target, so on those
187 systems, you can issue:
188
189 -------------------------------------
190 # make cloneconfig
191 -------------------------------------
192
193 * Some installs put a copy of the kernel config into `/boot`, which
194 allows you to do this:
195
196 -------------------------------------
197 # cp /boot/config-$(uname -r).config
198 -------------------------------------
199
200 * Finally, you may simply use a backup copy of a `.config` file which
201 has been used for building the currently-running
202 kernel.
203
204 [[s-build-prepare-checkout]]
205 ==== Preparing the DRBD userspace utilities build tree
206
207 The DRBD userspace compilation requires that you first configure your
208 source tree with the included `configure` script.
209
210 NOTE: When building from a git checkout, the `configure` script does
211 not yet exist. You must create it by simply typing `autoconf` from the
212 top directory of the checkout.
213
214 Invoking the configure script with the `--help` option returns a full
215 list of supported options. The table below summarizes the most
216 important ones:
217
218 [[t-configure-options]]
219 .Options supported by DRBD's `configure` script
220 [format="csv",separator=";",options="header"]
221 |===================================
222 Option;Description;Default;Remarks
223 +--prefix+;Installation directory prefix;`/usr/local`;This is the default to maintain Filesystem Hierarchy Standard compatibility for locally installed, unpackaged software. In packaging, this is typically overridden with `/usr`.
224 +--localstatedir+;Local state directory;`/usr/local/var`;Even with a default `prefix`, most users will want to override this with `/var`.
225 +--sysconfdir+;System configuration directory;`/usr/local/etc`;Even with a default `prefix`, most users will want to override this with `/etc`.
226 +--with-udev+;Copy a rules file into your `udev(7)` configuration, to get symlinks named like the resources.;yes;Disable for non-``udev`` installations.
227 +--with-heartbeat+;Build DRBD Heartbeat integration;yes;You may disable this option unless you are planning to use DRBD's Heartbeat v1 resource agent or `dopd`.
228 +--with-pacemaker+;Build DRBD Pacemaker integration;yes;You may disable this option if you are not planning to use the Pacemaker cluster resource manager.
229 +--with-rgmanager+;Build DRBD Red Hat Cluster Suite integration;no;You should enable this option if you are planning to use DRBD with `rgmanager`, the Red Hat Cluster Suite cluster resource manager. Please note that you will need to pass `--with rgmanager` to +rpmbuild+ to actually get the rgmanager-package built.
230 +--with-xen+;Build DRBD Xen integration;yes (on x86 architectures);You may disable this option if you don't need the `block-drbd` helper script for Xen integration.
231 +--with-bashcompletion+;Installs a bash completion script for `drbdadm`;yes;You may disable this option if you are using a shell other than bash, or if you do not want to utilize programmable completion for the `drbdadm` command.
232 +--with-initscripttype+;Type of your init system;auto;Type of init script to install (sysv, systemd, or both).
233 +--enable-spec+;Create a distribution specific RPM spec file;no;For package builders only: you may use this option if you want to create an RPM spec file adapted to your distribution. See also <<s-build-rpm>>.
234 |===================================
235
236 Most users will want the following configuration options:
237
238 -------------------------------------
239 $ ./configure --prefix=/usr --localstatedir=/var --sysconfdir=/etc
240 -------------------------------------
241
242
243 The configure script will adapt your DRBD build to distribution
244 specific needs. It does so by auto-detecting which distribution it is
245 being invoked on, and setting defaults accordingly. When overriding
246 defaults, do so with caution.
247
248 The configure script creates a log file, `config.log`, in the
249 directory where it was invoked. When reporting build issues on the
250 mailing list, it is usually wise to either attach a copy of that file
251 to your email, or point others to a location from where it may be
252 viewed or downloaded.
253
254
255 [[s-build-userland]]
256 ==== Building DRBD userspace utilities
257
258 To build DRBD's userspace utilities, invoke the following commands
259 from the top of your git checkout or expanded tarball:
260
261 -------------------------------------
262 $ make
263 $ sudo make install
264 -------------------------------------
265
266 This will build the management utilities (`drbdadm`, `drbdsetup`, and
267 `drbdmeta`), and install them in the appropriate locations. Based on
268 the other `--with` options selected during the
269 <<s-build-prepare-checkout,configure stage>>, it will also install
270 scripts to integrate DRBD with other applications.
271
272
273 [[s-build-compile-kernel-module]]
274 ==== Compiling the DRBD kernel module
275 The kernel module does not use `GNU` `autotools`, therefore building and
276 installing the kernel module is usually a simple two step process.
277
278 [[s-build-against-running-kernel]]
279 ===== Building the DRBD kernel module for the currently-running kernel
280
281 After changing into your unpacked DRBD kernel module sources directory, you
282 can now build the module:
283
284 -------------------------------------
285 $ cd drbd-9.0
286 $ make clean all
287 -------------------------------------
288
289 This will build the DRBD kernel module to match your currently-running
290 kernel, whose kernel source is expected to be accessible via the
291 `/lib/modules/`uname -r`/build` symlink.
292
293
294 [[s-build-against-kernel-headers]]
295 ===== Building against prepared kernel headers
296
297 If the `/lib/modules/`uname -r`/build` symlink does not exist, and you
298 are building against a running stock kernel (one that was shipped
299 pre-compiled with your distribution), you may also set the `KDIR`
300 variable to point to the _matching_ kernel headers (as opposed to
301 kernel sources) directory. Note that besides the actual kernel headers
302 -- commonly found in `/usr/src/linux-__version__/include` -- the
303 DRBD build process also looks for the kernel `Makefile` and
304 configuration file (`.config`), which pre-built kernel headers
305 packages commonly include.
306
307 To build against prepared kernel headers, issue, for example:
308
309 -------------------------------------
310 $ cd drbd-9.0
311 $ make clean
312 $ make KDIR=/usr/src/linux-headers-3.2.0-4-amd64/
313 -------------------------------------
314
315
316 [[s-build-against-source-tree]]
317 ===== Building against a kernel source tree
318
319 If you are building DRBD against a kernel _other_ than your currently
320 running one, and you do not have prepared kernel sources for your
321 target kernel available, you need to build DRBD against a complete
322 target kernel source tree. To do so, set the KDIR variable to point to
323 the kernel sources directory:
324
325 -------------------------------------
326 $ cd drbd-9.0
327 $ make clean
328 $ make KDIR=/root/linux-3.6.6/
329 -------------------------------------
330
331
332 [[s-build-customcc]]
333 ===== Using a non-default C compiler
334
335 You also have the option of setting the compiler explicitly via the CC
336 variable. This is known to be necessary on some Fedora versions, for
337 example:
338
339 -------------------------------------
340 $ cd drbd-9.0
341 $ make clean
342 $ make CC=gcc32
343 -------------------------------------
344
345
346 [[s-build-modinfo]]
347 ===== Checking for successful build completion
348
349 If the module build completes successfully, you should see a kernel
350 module file named `drbd.ko` in the `drbd` directory. You may
351 interrogate the newly-built module with `/sbin/modinfo drbd.ko` if you
352 are so inclined.
353
354
355 [[s-kabi-warning]]
356 ===== kABI warning for some distributions
357
358 Please note that some distributions (like RHEL 6 and derivatives) claim
359 to have a stable kABI, i.e. the kernel API should stay consistent during minor
360 releases (i.e., for kernels published in the RHEL 6.3 series).
361
362 In practice this is not working all of the time; there are some known cases
363 (even within a minor release) where things got changed incompatibly. In these
364 cases external modules (like DRBD) can fail to load, cause a kernel panic, or
365 break in even more subtle waysfootnote:[One favorite way was when loading the DRBD
366 module reported "Out of memory" on a freshly booted machine with 32GiB RAM...],
367 and need to be
368 rebuilt against the _matching_ kernel headers.
369
370 [[s-build-drbdmanage]]
371 ==== Building Drbdmanage
372
373 -------------------------------------
374 $ cd drbdmanage
375 $ make
376 -------------------------------------
377
378 [[s-build-install]]
379 === Installing DRBD
380
381 Provided your DRBD build completed successfully, you will be able to
382 install DRBD by issuing the command:
383
384 -------------------------------------
385 $ cd drbd-9.0 && sudo make install && cd ..
386 $ cd drbd-utils && sudo make install && cd ..
387 $ cd drbdmanage && sudo make install && cd ..
388 -------------------------------------
389
390 The DRBD userspace management tools (`drbdadm`, `drbdsetup`, and
391 `drbdmeta`) will now be installed in the `prefix` path that was passed to
392 `configure`, typically `/sbin/`.
393
394 Note that any kernel upgrade will require you to rebuild and reinstall
395 the DRBD kernel module to match the new kernel.
396
397 Some distributions allow to register kernel module source directories, so that
398 rebuilds are done as necessary. See e.g. `dkms(8)` on Debian.
399
400 The DRBD userspace tools, in contrast, need only to be rebuilt
401 and reinstalled when upgrading to a new DRBD version. If at any
402 time you upgrade to a new kernel _and_ new DRBD
403 version, you will need to upgrade both components.
404
405
406 [[s-build-rpm]]
407 === Building the DRBD userspace RPM packages
408
409 The DRBD build system contains a facility to build RPM packages
410 directly out of the DRBD source tree. For building RPMs,
411 <<s-build-prereq>> applies essentially in the same way as for building
412 and installing with `make`, except that you also need the RPM build
413 tools, of course.
414
415 Also, see <<s-build-prepare-kernel-tree>> if you are not building
416 against a running kernel with precompiled headers available.
417
418 The build system offers two approaches for building RPMs. The simpler
419 approach is to simply invoke the `rpm` target in the top-level
420 Makefile:
421
422 -------------------------------------
423 $ ./configure
424 $ make rpm
425 -------------------------------------
426
427 This approach will auto-generate spec files from pre-defined
428 templates, and then use those spec files to build binary RPM packages.
429
430 The `make rpm` approach generates a number of RPM packages:
431
432 [[t-rpm-packages]]
433 .DRBD userland RPM packages
434 [format="csv",separator=";",options="header"]
435 |===================================
436 Package name;Description;Dependencies;Remarks
437 +drbd+;DRBD meta-package;All other `drbd-*` packages;Top-level virtual package. When installed, this pulls in all other userland packages as dependencies.
438 +drbd-utils+;Binary administration utilities;;Required for any DRBD enabled host
439 +drbd-udev+;udev integration facility;`drbd-utils`, `udev`;Enables `udev` to manage user-friendly symlinks to DRBD devices
440 +drbd-xen+;Xen DRBD helper scripts;`drbd-utils`, `xen`;Enables `xend` to auto-manage DRBD resources
441 +drbd-heartbeat+;DRBD Heartbeat integration scripts;`drbd-utils`, `heartbeat`;Enables DRBD management by legacy v1-style Heartbeat clusters
442 +drbd-pacemaker+;DRBD Pacemaker integration scripts;`drbd-utils`, `pacemaker`;Enables DRBD management by Pacemaker clusters
443 +drbd-rgmanager+;DRBD RedHat Cluster Suite integration scripts;`drbd-utils`, `rgmanager`;Enables DRBD management by `rgmanager`, the Red Hat Cluster Suite resource manager
444 +drbd-bashcompletion+;Programmable bash completion;`drbd-utils`, `bash-completion`;Enables Programmable bash completion for the `drbdadm` utility
445 |===================================
446
447 The other, more flexible approach is to have `configure` generate the
448 spec file, make any changes you deem necessary, and then use the
449 `rpmbuild` command:
450
451 -------------------------------------
452 $ ./configure --enable-spec
453 $ make tgz
454 $ cp drbd*.tar.gz `rpm -E %sourcedir`
455 $ rpmbuild -bb drbd.spec
456 -------------------------------------
457
458
459
460 The RPMs will be created wherever your system RPM configuration (or
461 your personal `~/.rpmmacros` configuration) dictates.
462
463 After you have created these packages, you can install, upgrade, and
464 uninstall them as you would any other RPM package in your system.
465
466 Note that any kernel upgrade will require you to generate a new
467 `kmod-drbd` package to match the new kernel; see also <<s-kabi-warning>>.
468
469 The DRBD userland packages, in contrast, need only be recreated when
470 upgrading to a new DRBD version. If at any time you upgrade to a new
471 kernel _and_ new DRBD version, you will need to upgrade both packages.
472
473
474 [[s-build-deb]]
475 === Building a DRBD Debian package
476
477 The DRBD build system contains a facility to build Debian packages
478 directly out of the DRBD source tree. For building Debian packages,
479 <<s-build-prereq>> applies essentially in the same way as for building
480 and installing with `make`, except that you of course also need the
481 `dpkg-dev` package containing the Debian packaging tools, and
482 `fakeroot` if you want to build DRBD as a non-root user (highly
483 recommended). All three DRBD sub-projects (kernel module, `drbd-utils`, and
484 `drbdmanage`) support Debian package building.
485
486 Also, see <<s-build-prepare-kernel-tree>> if you are not building
487 against a running kernel with precompiled headers available.
488
489 The DRBD source tree includes a `debian` subdirectory containing the
490 required files for Debian packaging. That subdirectory, however, is
491 not included in the DRBD source tarballs -- instead, you will
492 need to <<s-checking-out-git,create a Git checkout>> of a _tag_
493 associated with a specific DRBD release.
494
495 Once you have created your checkout in this fashion, you can issue the
496 following commands to build DRBD Debian packages:
497
498 -------------------------------------
499 $ dpkg-buildpackage -rfakeroot -b -uc
500 -------------------------------------
501
502 NOTE: This (example) `drbd-buildpackage` invocation enables a
503 binary-only build (`-b`) by a non-root user (`-rfakeroot`),
504 disabling cryptographic signature for the changes file (`-uc`). Of
505 course, you may prefer other build options, see the
506 `dpkg-buildpackage` man page for details.
507
508 This build process will create the following Debian packages:
509
510 * A package containing the DRBD userspace tools, named
511 `drbd-utils___x__.__y__.__z__-__ARCH__.deb`;
512
513 * A module source package suitable for `module-assistant` named
514 `drbd-module-source___x__.__y__.__z__-BUILD_all.deb`.
515
516 * A dkms package suitable for `dkms` named
517 `drbd-dkms___x__.__y__.__z__-BUILD_all.deb`.
518
519 * A drbdmanage package named
520 `python-drbdmanage___x__.__y__.__z__-BUILD_all.deb`.
521
522 After you have created these packages, you can install, upgrade, and
523 uninstall them as you would any other Debian package in your system.
524
525 The `drbd-utils` packages supports Debian's `dpkg-reconfigure` facility, which
526 can be used to switch which versions of the man-pages are shown by default
527 (8.3, 8.4, or 9.0).
528
529 Building and installing the actual kernel module from the installed
530 module source package is easily accomplished via Debian's
531 `module-assistant` facility:
532
533 -------------------------------------
534 # module-assistant auto-install drbd-module
535 -------------------------------------
536
537 You may also use the shorthand form of
538 the above command:
539
540 -------------------------------------
541 # m-a a-i drbd-module
542 -------------------------------------
543
544 Note that any kernel upgrade will require you to rebuild the kernel
545 module (with `module-assistant`, as just described) to match the new
546 kernel. The `drbd-utils` and `drbd-module-source` packages, in
547 contrast, only need to be recreated when upgrading to a new DRBD
548 version. If at any time you upgrade to a new kernel _and_ new DRBD
549 version, you will need to upgrade both packages.
550
551 Starting from DRBD9, automatic updates of the DRBD kernel module are possible
552 with the help of `dkms(8)`. All that is needed is to install the `drbd-dkms`
553 Debian package.
554 /////////////////////////////