= Howto Build and Install DRBD =

These are the steps to build and install DRBD on your system.
It should work for SuSE, Debian, RH and other distros with slight
modifications.

   This was last reviewed for 0.8.0-pre1.

I tried to indicate what you should type by the prompt-prefix
on the below command lines. "all#", when it is the same for
all distros, and e.g. "suse#", when I think this is specific for
suse, in which case I try to point out the alternatives for the
different distributions in turn.

For FAQs, publications and other stuff see also the documentation
subdirectory, and of course http://www.drbd.org .

Other helpful links:

	http://www.drbd.org
	http://www.drbd.org/drbd-article.html
	http://www.linux-mag.com/2003-11/toc.html
	http://www.linux-ha.org/DRBD , and of course,
	http://www.drbd.org/support.html

== Prerequisites ==

 You need to install the kernel-source package. Or, if you run the default
 distribution kernel, and there is some "precompiled kernel headers"
 directory, you can skip this, and compile against that directory of header
 files. If so, skip the "Prepare" section, and just jump to "Build DRBD".

       rpm.distros# rpm -Uhv kernel-source-2.4.XX-YYY.rpm
            debian# apt-get install kernel-source
        kernel.org# tar --bzip2 -xvf linux-2.4.XX.tar.bz2

 Note: this is really kernel-source.rpm, NOT kernel.src.rpm.
 You don't want to use the latter, unless you know _exactly_ why...

 If you want to use a 2.4.x kernel, you need to use DRBD-0.7.;
 DRBD-0.8 just won't compile.

 Obviously you should have a build-system installed, i.e. gcc, make, etc. ;)

 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.
 On recent SuSE this is gcc-3.2, and the default gcc anyways --
 just mentioned here in case you installed gcc 2.9x for some other
 thingy, and then wonder why kernel modules no longer work properly.

 So what next?

== Prepare the kernel source tree ==

       all# cd /usr/src/linux
   or wherever your kernel source happens to be, e.g.
    fedora# cd /usr/src/linux-2.6

   The next step is just to be sure. If you know what it does,
   you probably can judge on your own whether it is necessary or
   not, anyways. If you get strange results on your first try,
   please do this first. It sometimes really helps!

       all# make mrproper

   This clones the configuration of the currently running kernel
   into the kernel source configuration.

       suse# make cloneconfig

   If this did not work, you do not run a shipped version of the
   SuSE kernel, so you should know how to cope with it...
   As a hint: copy in the configuration you used to build the
   running kernel into ./.config, then do two times
   "yes '' | make -s oldconfig"
   and continue as below. If nothing helps, build a new
   kernel, or revert to the shipped ones!
   (If you want to compile your own kernel, you should be
   using debian or gentoo or rock or something, anyways...)

   On some distros this step is basically:

       some# zcat /proc/config.gz > .config
           # yes "" | make -s oldconfig ; yes "" | make -s oldconfig

   The redhat way seems to be:

       redhat# cp /boot/kernel-2.6.some-thing.config  .config
        or   # cp configs/kernel-2.6.some-thing.config .config
             # make -s oldconfig_nonint ; make -s oldconfig_nonint
             # vi Makefile # mod EXTRAVERSION to match installed kernel
                           # (remove "custom" if neccessary)

       fedora# cp /boot/config-2.6.some-thing  .config
             # export CC=gcc32
             # yes "" | { make oldconfig ; make oldconfig ; }
             # vi Makefile # mod EXTRAVERSION to match installed kernel
                           # (remove "custom" if neccessary)

    Note:
    If you consider to not run some vendor kernel, but compile
    your own kernel, you need to build in module support, since
    DRBD is a module (but see below for in kernel builds).
    DRBD depends on procfs, but you want to have that anyways.

    If you do not run a selfcompiled kernel, but the binary shipped
    distro kernel, and after "make install" the drbd module ends up in
    the wrong place (e.g. "/lib/modules/2.6.6custom/", when you want it
    in "/lib/modules/2.6.6/" ), edit the top-level Makefile of your kernel
    source tree and remove "custom" from the EXTRAVERSION.  Make sure you
    copied in the .config corresponding to the kernel you use.

   So if necessary, "make menuconfig" and adapt to your own
   preferences, but then you need to compile and install this
   kernel.  Modules compiled against this kernel source tree
   will only work properly with a matching kernel.

       all# make linux/include/version.h
          # and since kernel 2.6.6 (some distros 2.6.5-something):
       all# make modules_prepare

== Build DRBD kernel module (outside of the kernel source) ==

   unpack the drbd tgz, I suggest to unpack it into /usr/src/drbd-*

       all# cd /usr/src
       all# tar -xvzf where/you/downloaded/it/drbd-0.8.0.tar.gz

   now build the module

   Note:
   On some distros (redhat/fedora typically), you first need to have a
   look into ./drbd_config.h, and (un)comment some of the
   settings appropriately, if not done automagically already.

       all# cd drbd-0.8.0/drbd  # kernel module sub directory
       all# make clean all
    fedora# make clean all CC=gcc32

   BTW, this expects the kernel source to be in
   /lib/modules/`uname -r`/build

   If you want to compile against some other kernel source
   tree, which might be differently configured, or even
   configured for a different architecture, instead try:

       all# make clean ; make KDIR=/path/to/kernel/source

   On some systems you may need to explicitly set the compiler to use
   with e.g. "make ... CC=gcc32".

   Note that it should build against preconfigured kernel-headers, too,
   like in "make KDIR=/usr/src/linux-include/athlon". But then you
   should be very sure that your running kernel matches the
   configuration of that header tree ''exactly''.

== Patching DRBD into the kernel ==

   This is an alternative to the "make all" in the previous section, and
   the only way to compile DRBD as part of the kernel itself (not as
   module).

   Since 0.7, you can "make KDIR=/usr/src/linux-2.6.x kernel-patch",
   and you get a "patch-linux-2.6.x-drbd-0.7_whatever".

   You then can verify this patch, and apply it to the kernel source
   tree: "cd /usr/src/linux-2.6.x ; patch -p1 < some/where/patch-etc...."
   You with "make menuconfig" or "make xconfig", you should find DRBD in
   the block-devices menu, select it as module, or as part of the
   kernel.

   Rebuild the kernel modules ("make modules; make modules_install"),
   or rebuild and install the new kernel
   ("make bzImage" or "make linux ARCH=um" or ...)

== Build DRBD user space tools only ==

   If you took the 'patch kernel' approach, you still need to build the
   user space tools:

       all# cd /usr/src/drbd-0.8.0
       all# make tools

== Install it ==

   If the above steps went ok, you just need to install it.

       all# cd /usr/src/drbd-0.8.0
       all# make install

   If you patched the kernel, you obviously only want to
       all# make install-tools

== Configure it ==

   If you have not used DRBD before, have a browse on http://www.drbd.org .
   You should find some interesting stuff on the "Documentation"
   and "Publications" sub pages.

   In any case, have a look at the example configuration file in
   ./scripts/drbd.conf, which is well commented.
   Maybe we added a new config option, or deprecated an other ;)

== Why ... ? ==

   Why did I not just "make ; make install" in the toplevel
   directory of the drbd source?
   Because I like to do it explicitly step by step.
   Of course you could do it all in one step,
   and most of the time it should just work:

       all# cd /usr/src/drbd-0.8.0
       all# make all install

== Troubleshooting ==

   Added on your feedback and request, if necessary... ;-)

   Also, have a look at http://www.drbd.org , the FAQ at
   http://www.linux-ha.org/DRBD , and the other links mentioned
   at the top of this page.

== Building a .rpm of it ==

   This should be fairly easy, there is an example spec
   file, and you can even "make rpm".

   If it does not work for you out of the box, first get "make install"
   to work properly, see the section titled 'prepare the kernel source tree'
   and 'building a kernel module'.
   You may need to add some packages, or edit the drbd.spec(.in) file,
   or even add a patch if fedora broke something again...

   There are caveats, please have a look at ./README, too,
   you might want/need to edit the ./drbd.spec file.

   Note that it should build against preconfigured kernel-headers, too,
   like in "make rpm KDIR=/usr/src/linux-include/athlon",
   "make rpm KDIR=/usr/src/linux-include/smp", ...

   You then should find packages in "dist/{S,}RPMS/*/*.rpm".

   Note however that your distro most likely handles rpms of kernel modules in
   some special way, so you may want to first ask your ditributor to provide
   some update packages themselves.

== Building a .deb of it ==

   Have a look into the ./debian/* example files in place.
   See also: http://article.gmane.org/gmane.comp.linux.drbd/5616

----

Hope this helped, cheers and have fun ...


	Lars Ellenberg


Last modified: Do Sep 23 23:29:48 UTC 2004
