| 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 |
///////////////////////////// |