///////////////////////////// [[ch-build-install-from-source]] == Building and installing DRBD from source [[s-downloading-drbd-sources]] === Downloading the DRBD sources The source tarballs for both current and historic DRBD releases are available for download from http://oss.linbit.com/drbd/. Source tarballs, by convention, are named `drbd-__x__.__y__.__z__.tar.gz` resp. `drbd-utils-__x__.__y__.__z__.tar.gz`, where _x_, _y_ and _z_ refer to the major, minor and bugfix release numbers. DRBD's compressed source archive is less than half a megabyte in size. To download and uncompress into your current working directory, issue the following commands: ------------------------------------- $ wget http://oss.linbit.com/drbd/9.0/drbd-latest.tar.gz $ tar -xzf drbd-latest.tar.gz ------------------------------------- NOTE: The use of `wget` for downloading the source tarball is purely an example. Of course, you may use any downloader you prefer. It is recommended to uncompress DRBD into a directory normally used for keeping source code, such as `/usr/src` or `/usr/local/src`. The examples in this guide assume `/usr/src`. [[s-checking-out-git]] === Checking out sources from the public DRBD source repository DRBD's source code is kept in a public Gitfootnote:[See http://git.or.cz] repository, which may be browsed on-line at http://git.drbd.org/. The DRBD software consists of 3 projects: . The DRBD kernel module . The DRBD utilities . Drbdmanage (optional) Source code can be obtained by either cloning `git` repositories or downloading release tarballs. There are actually two minor differences between an unpacked source tarball and a Git checkout of the same release: * The Git checkout contains a `debian/` subdirectoy, while the source tarball does not. This is due to a request from Debian maintainers, who prefer to add their own Debian build configuration to a pristine upstream tarball. * The source tarball contains preprocessed man pages, the Git checkout does not. Thus, building DRBD from a Git checkout requires a complete Docbook toolchain for building the man pages, while this is not a requirement for building from a source tarball. [[s-drbd_kernel_module]] ==== DRBD kernel module To check out a specific DRBD release from the repository, you must first _clone_ the DRBD repository: ------------------------------------- $ git clone --recursive git://git.drbd.org/drbd-9.0.git ------------------------------------- If your firewall does not permit TCP connections to port 9418, you may also check out via HTTP (please note that using Git via HTTP is much slower than its native protocol, so native Git is usually preferred whenever possible): ------------------------------------- $ git clone --recursive http://git.drbd.org/drbd-9.0.git ------------------------------------- Either command will create a Git checkout subdirectory, named `drbd-9.0`. To now move to a source code state equivalent to a specific DRBD release (here 9.0.0), issue the following commands: ------------------------------------- $ cd drbd-9.0 $ git checkout drbd-9.0.0 $ git submodule update ------------------------------------- [[s-drbd_utilities]] ==== DRBD utilities To check out `drbd-utils` issue the following command: ------------------------------------- $ git clone --recursive http://git.drbd.org/drbd-utils.git ------------------------------------- `Drbd-utils` from version 8.9.x onward supports DRBD kernel modules versions 8.3, 8.4, and 9.0. [[s-drbdmanage]] ==== Drbdmanage To check out `drbdmanage` issue the following command: ------------------------------------- $ git clone --recursive http://git.drbd.org/drbdmanage.git ------------------------------------- [[s-build-from-source]] === Building DRBD from source [[s-build-prereq]] ==== Checking build prerequisites Before being able to build DRBD from source, your build host must fulfill the following prerequisites: * `make`, `gcc`, the glibc development libraries, and the `flex` scanner generator must be installed. NOTE: You should make sure that the `gcc` you use to compile the module is the same which was used to build the kernel you are running. If you have multiple `gcc` versions available on your system, DRBD's build system includes a facility to <>. * For building directly from a git checkout, GNU Autoconf is also required. This requirement does not apply when building from a tarball. * If you are running a stock kernel supplied by your distribution, you should install a matching kernel headers package. These are typically named `kernel-devel`, `kernel-headers`, `linux-headers` or similar. In this case, you can skip <> and continue with <>. * If you are not running a distribution stock kernel (i.e. your system runs on a kernel built from source with a custom configuration), your kernel source files must be installed. + -- NOTE: On RPM-based systems, these packages will be named similar to `kernel-source-__version__.rpm`, which is easily confused with `kernel-__version__.src.rpm`. The former is the correct package to install for building DRBD. -- "Vanilla" kernel tarballs from the http://kernel.org/ archive are simply named `linux-__version__.tar.bz2` and should be unpacked in `/usr/src/linux-__version__`, with the symlink `/usr/src/linux` pointing to that directory. In this case of building DRBD against kernel sources (not headers), you must continue with <>. [[s-build-prepare-kernel-tree]] ==== Preparing the kernel source tree To prepare your source tree for building DRBD, you must first enter the directory where your unpacked kernel sources are located. Typically this is `/usr/src/linux-__version__`, or simply a symbolic link named `/usr/src/linux`: ------------------------------------- # cd /usr/src/linux ------------------------------------- The next step is recommended, though not strictly necessary. *Be sure to copy your existing `.config` file to a safe location before performing it*. This step essentially reverts your kernel source tree to its original state, removing any leftovers from an earlier build or configure run: ------------------------------------- # make mrproper ------------------------------------- Now it is time to _clone_ your currently running kernel configuration into the kernel source tree. There are a few possible options for doing this: * Many reasonably recent kernel builds export the currently-running configuration, in compressed form, via the `/proc` filesystem, enabling you to copy from there: ------------------------------------- # zcat /proc/config.gz > .config ------------------------------------- * SUSE kernel Makefiles include a `cloneconfig` target, so on those systems, you can issue: ------------------------------------- # make cloneconfig ------------------------------------- * Some installs put a copy of the kernel config into `/boot`, which allows you to do this: ------------------------------------- # cp /boot/config-$(uname -r).config ------------------------------------- * Finally, you may simply use a backup copy of a `.config` file which has been used for building the currently-running kernel. [[s-build-prepare-checkout]] ==== Preparing the DRBD userspace utilities build tree The DRBD userspace compilation requires that you first configure your source tree with the included `configure` script. NOTE: When building from a git checkout, the `configure` script does not yet exist. You must create it by simply typing `autoconf` from the top directory of the checkout. Invoking the configure script with the `--help` option returns a full list of supported options. The table below summarizes the most important ones: [[t-configure-options]] .Options supported by DRBD's `configure` script [format="csv",separator=";",options="header"] |=================================== Option;Description;Default;Remarks +--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`. +--localstatedir+;Local state directory;`/usr/local/var`;Even with a default `prefix`, most users will want to override this with `/var`. +--sysconfdir+;System configuration directory;`/usr/local/etc`;Even with a default `prefix`, most users will want to override this with `/etc`. +--with-udev+;Copy a rules file into your `udev(7)` configuration, to get symlinks named like the resources.;yes;Disable for non-``udev`` installations. +--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`. +--with-pacemaker+;Build DRBD Pacemaker integration;yes;You may disable this option if you are not planning to use the Pacemaker cluster resource manager. +--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. +--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. +--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. +--with-initscripttype+;Type of your init system;auto;Type of init script to install (sysv, systemd, or both). +--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 <>. |=================================== Most users will want the following configuration options: ------------------------------------- $ ./configure --prefix=/usr --localstatedir=/var --sysconfdir=/etc ------------------------------------- The configure script will adapt your DRBD build to distribution specific needs. It does so by auto-detecting which distribution it is being invoked on, and setting defaults accordingly. When overriding defaults, do so with caution. The configure script creates a log file, `config.log`, in the directory where it was invoked. When reporting build issues on the mailing list, it is usually wise to either attach a copy of that file to your email, or point others to a location from where it may be viewed or downloaded. [[s-build-userland]] ==== Building DRBD userspace utilities To build DRBD's userspace utilities, invoke the following commands from the top of your git checkout or expanded tarball: ------------------------------------- $ make $ sudo make install ------------------------------------- This will build the management utilities (`drbdadm`, `drbdsetup`, and `drbdmeta`), and install them in the appropriate locations. Based on the other `--with` options selected during the <>, it will also install scripts to integrate DRBD with other applications. [[s-build-compile-kernel-module]] ==== Compiling the DRBD kernel module The kernel module does not use `GNU` `autotools`, therefore building and installing the kernel module is usually a simple two step process. [[s-build-against-running-kernel]] ===== Building the DRBD kernel module for the currently-running kernel After changing into your unpacked DRBD kernel module sources directory, you can now build the module: ------------------------------------- $ cd drbd-9.0 $ make clean all ------------------------------------- This will build the DRBD kernel module to match your currently-running kernel, whose kernel source is expected to be accessible via the `/lib/modules/`uname -r`/build` symlink. [[s-build-against-kernel-headers]] ===== Building against prepared kernel headers If the `/lib/modules/`uname -r`/build` symlink does not exist, and you are building against a running stock kernel (one that was shipped pre-compiled with your distribution), you may also set the `KDIR` variable to point to the _matching_ kernel headers (as opposed to kernel sources) directory. Note that besides the actual kernel headers -- commonly found in `/usr/src/linux-__version__/include` -- the DRBD build process also looks for the kernel `Makefile` and configuration file (`.config`), which pre-built kernel headers packages commonly include. To build against prepared kernel headers, issue, for example: ------------------------------------- $ cd drbd-9.0 $ make clean $ make KDIR=/usr/src/linux-headers-3.2.0-4-amd64/ ------------------------------------- [[s-build-against-source-tree]] ===== Building against a kernel source tree If you are building DRBD against a kernel _other_ than your currently running one, and you do not have prepared kernel sources for your target kernel available, you need to build DRBD against a complete target kernel source tree. To do so, set the KDIR variable to point to the kernel sources directory: ------------------------------------- $ cd drbd-9.0 $ make clean $ make KDIR=/root/linux-3.6.6/ ------------------------------------- [[s-build-customcc]] ===== Using a non-default C compiler You also have the option of setting the compiler explicitly via the CC variable. This is known to be necessary on some Fedora versions, for example: ------------------------------------- $ cd drbd-9.0 $ make clean $ make CC=gcc32 ------------------------------------- [[s-build-modinfo]] ===== Checking for successful build completion If the module build completes successfully, you should see a kernel module file named `drbd.ko` in the `drbd` directory. You may interrogate the newly-built module with `/sbin/modinfo drbd.ko` if you are so inclined. [[s-kabi-warning]] ===== kABI warning for some distributions Please note that some distributions (like RHEL 6 and derivatives) claim to have a stable kABI, i.e. the kernel API should stay consistent during minor releases (i.e., for kernels published in the RHEL 6.3 series). In practice this is not working all of the time; there are some known cases (even within a minor release) where things got changed incompatibly. In these cases external modules (like DRBD) can fail to load, cause a kernel panic, or break in even more subtle waysfootnote:[One favorite way was when loading the DRBD module reported "Out of memory" on a freshly booted machine with 32GiB RAM...], and need to be rebuilt against the _matching_ kernel headers. [[s-build-drbdmanage]] ==== Building Drbdmanage ------------------------------------- $ cd drbdmanage $ make ------------------------------------- [[s-build-install]] === Installing DRBD Provided your DRBD build completed successfully, you will be able to install DRBD by issuing the command: ------------------------------------- $ cd drbd-9.0 && sudo make install && cd .. $ cd drbd-utils && sudo make install && cd .. $ cd drbdmanage && sudo make install && cd .. ------------------------------------- The DRBD userspace management tools (`drbdadm`, `drbdsetup`, and `drbdmeta`) will now be installed in the `prefix` path that was passed to `configure`, typically `/sbin/`. Note that any kernel upgrade will require you to rebuild and reinstall the DRBD kernel module to match the new kernel. Some distributions allow to register kernel module source directories, so that rebuilds are done as necessary. See e.g. `dkms(8)` on Debian. The DRBD userspace tools, in contrast, need only to be rebuilt and reinstalled when upgrading to a new DRBD version. If at any time you upgrade to a new kernel _and_ new DRBD version, you will need to upgrade both components. [[s-build-rpm]] === Building the DRBD userspace RPM packages The DRBD build system contains a facility to build RPM packages directly out of the DRBD source tree. For building RPMs, <> applies essentially in the same way as for building and installing with `make`, except that you also need the RPM build tools, of course. Also, see <> if you are not building against a running kernel with precompiled headers available. The build system offers two approaches for building RPMs. The simpler approach is to simply invoke the `rpm` target in the top-level Makefile: ------------------------------------- $ ./configure $ make rpm ------------------------------------- This approach will auto-generate spec files from pre-defined templates, and then use those spec files to build binary RPM packages. The `make rpm` approach generates a number of RPM packages: [[t-rpm-packages]] .DRBD userland RPM packages [format="csv",separator=";",options="header"] |=================================== Package name;Description;Dependencies;Remarks +drbd+;DRBD meta-package;All other `drbd-*` packages;Top-level virtual package. When installed, this pulls in all other userland packages as dependencies. +drbd-utils+;Binary administration utilities;;Required for any DRBD enabled host +drbd-udev+;udev integration facility;`drbd-utils`, `udev`;Enables `udev` to manage user-friendly symlinks to DRBD devices +drbd-xen+;Xen DRBD helper scripts;`drbd-utils`, `xen`;Enables `xend` to auto-manage DRBD resources +drbd-heartbeat+;DRBD Heartbeat integration scripts;`drbd-utils`, `heartbeat`;Enables DRBD management by legacy v1-style Heartbeat clusters +drbd-pacemaker+;DRBD Pacemaker integration scripts;`drbd-utils`, `pacemaker`;Enables DRBD management by Pacemaker clusters +drbd-rgmanager+;DRBD RedHat Cluster Suite integration scripts;`drbd-utils`, `rgmanager`;Enables DRBD management by `rgmanager`, the Red Hat Cluster Suite resource manager +drbd-bashcompletion+;Programmable bash completion;`drbd-utils`, `bash-completion`;Enables Programmable bash completion for the `drbdadm` utility |=================================== The other, more flexible approach is to have `configure` generate the spec file, make any changes you deem necessary, and then use the `rpmbuild` command: ------------------------------------- $ ./configure --enable-spec $ make tgz $ cp drbd*.tar.gz `rpm -E %sourcedir` $ rpmbuild -bb drbd.spec ------------------------------------- The RPMs will be created wherever your system RPM configuration (or your personal `~/.rpmmacros` configuration) dictates. After you have created these packages, you can install, upgrade, and uninstall them as you would any other RPM package in your system. Note that any kernel upgrade will require you to generate a new `kmod-drbd` package to match the new kernel; see also <>. The DRBD userland packages, in contrast, need only be recreated when upgrading to a new DRBD version. If at any time you upgrade to a new kernel _and_ new DRBD version, you will need to upgrade both packages. [[s-build-deb]] === Building a DRBD Debian package The DRBD build system contains a facility to build Debian packages directly out of the DRBD source tree. For building Debian packages, <> applies essentially in the same way as for building and installing with `make`, except that you of course also need the `dpkg-dev` package containing the Debian packaging tools, and `fakeroot` if you want to build DRBD as a non-root user (highly recommended). All three DRBD sub-projects (kernel module, `drbd-utils`, and `drbdmanage`) support Debian package building. Also, see <> if you are not building against a running kernel with precompiled headers available. The DRBD source tree includes a `debian` subdirectory containing the required files for Debian packaging. That subdirectory, however, is not included in the DRBD source tarballs -- instead, you will need to <> of a _tag_ associated with a specific DRBD release. Once you have created your checkout in this fashion, you can issue the following commands to build DRBD Debian packages: ------------------------------------- $ dpkg-buildpackage -rfakeroot -b -uc ------------------------------------- NOTE: This (example) `drbd-buildpackage` invocation enables a binary-only build (`-b`) by a non-root user (`-rfakeroot`), disabling cryptographic signature for the changes file (`-uc`). Of course, you may prefer other build options, see the `dpkg-buildpackage` man page for details. This build process will create the following Debian packages: * A package containing the DRBD userspace tools, named `drbd-utils___x__.__y__.__z__-__ARCH__.deb`; * A module source package suitable for `module-assistant` named `drbd-module-source___x__.__y__.__z__-BUILD_all.deb`. * A dkms package suitable for `dkms` named `drbd-dkms___x__.__y__.__z__-BUILD_all.deb`. * A drbdmanage package named `python-drbdmanage___x__.__y__.__z__-BUILD_all.deb`. After you have created these packages, you can install, upgrade, and uninstall them as you would any other Debian package in your system. The `drbd-utils` packages supports Debian's `dpkg-reconfigure` facility, which can be used to switch which versions of the man-pages are shown by default (8.3, 8.4, or 9.0). Building and installing the actual kernel module from the installed module source package is easily accomplished via Debian's `module-assistant` facility: ------------------------------------- # module-assistant auto-install drbd-module ------------------------------------- You may also use the shorthand form of the above command: ------------------------------------- # m-a a-i drbd-module ------------------------------------- Note that any kernel upgrade will require you to rebuild the kernel module (with `module-assistant`, as just described) to match the new kernel. The `drbd-utils` and `drbd-module-source` packages, in contrast, only need to be recreated when upgrading to a new DRBD version. If at any time you upgrade to a new kernel _and_ new DRBD version, you will need to upgrade both packages. Starting from DRBD9, automatic updates of the DRBD kernel module are possible with the help of `dkms(8)`. All that is needed is to install the `drbd-dkms` Debian package. /////////////////////////////