INSTALL

= 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 drbd-0.7.5.
   It is correct for both 0.6.10 and later,
   and 0.7.x.

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.6.x kernel, you need to use DRBD-0.7.;
 0.6 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.

 Note: for a 2.2.x kernel, you need to add a line to kernel/ksyms.c,
 see debian/kernel-export-wup.patch . But who cares for 2.2, nowadays?

 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.4

   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.4.some-thing.config  .config
        or   # cp configs/kernel-2.4.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.4.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.
    Make sure that you do not compile NBD
    into the kernel, since DRBD uses the same major device
    number. Having it as module is ok, but you cannot use both
    at the same time. (well, starting with 0.7.1, you can...)

    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.4.20custom/", when you want it
    in "/lib/modules/2.4.20/" ), 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.
    For 2.4 kernels, don't forget to "make dep" in /usr/src/linux,
    it sometimes helps, too.
    (you could of course edit .kernelversion in the drbd directory,
    or copy by hand, too)

      Update:
      since we now (0.7.1 and later) have an officially assigned
      device major number (147) and device nodes (/dev/drbd), we no longer
      hijack NBDs major numbers. You now in fact _can_ use NBD in parallel
      with DRBD, if it makes any sense in your setup...

   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 dep	# no longer neccessary with 2.6.x
       all# make include/linux/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.6.12.tar.gz
          # or 0.7.x.tar.gz, of course

   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.

   Since 0.7.3, we have script/adjust_drbd_config_h.sh, which helps you 
   with this, and gets called during the normal build process,
   so you "should" no longer need to adjust it by hand.

       all# cd drbd-0.6.12/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.6.12/user
       all# make

   or with drbd-0.7 simply
       all# make tools

== Install it ==

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

       all# cd /usr/src/drbd-0.6.12
       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 seem to be too stupid to get my docbook environment
   right, and I don't want to screw up the precompiled
   documentation and man-pages that come with the .tar.gz ...

   Note: since 0.7, to rebuild the documentation, you need to
   explicitly ask for it: "make doc"

== 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.

	From: Jens Benecke
	Subject: [DRBD-dev] Re: RFC: new ./INSTALL hints
	Date: Wed, 24 Dec 2003 13:14:23 +0100
	See: http://article.gmane.org/gmane.comp.linux.drbd/5616

   For Debian, IMHO it makes a lot of sense to make a .deb package:

	/tmp/drbd-0.6.12# dpkg-buildpackage -us -uc -b

   creates drbd_*.deb, drbd-source_*.deb and kernel-patch-wup_*.deb.
   drbd-source_*.deb only contains /usr/src/linux/drbd.tar.gz, which must be
   unpacked and recompiled with the target kernel.

	/tmp# dpkg -i drbd*deb  # install them all
	/tmp# cd /usr/src/linux ; tar xvzf drbd.tar.gz
	/usr/src/linux# make menuconfig
	/usr/src/linux# make-kpkg --bzimage --revision $FOO \
		binary-arch modules_image

   creates kernel-image*deb, kernel-headers*deb, and drbd-module*deb,
   in my case (applied reiserfs data-logging patches and changed
   EXTRAVERSION in the Makefile to my initials, also used
   --revision $FOO on the make-kpkg command line :)

	drbd-module-2.4.23-jb-gr+r_0.6.12-1+jb1_i386.deb
	kernel-headers-2.4.23-jb-gr+r_jb1_i386.deb
	kernel-image-2.4.23-jb-gr+r_jb1_i386.deb

   These can be installed on any computer now.

   $FOO can be anything you want, like '01' or 'jb1' (which I use). It's the
   kernel revision number for your build. If you build later .deb packages
   with the same kernel version, you can use

	# dch -i 'added $foo patches/configure items/whatever'

   to update the Debian changelog in the kernel source directory and then just
   rebuild the kernel image. It will auto-replace the running kernel on
   installation.

   If you build another .deb with a different _version_, it will
   not replace the running kernel. See kernel-package
   documentation for that.

   Trust me, it's much cleaner and easier (also to upgrade)
   machines this way.  Especially if you have several machines to
   upgrade, which is _always_ the case when running drbd, as
   that's the whole point. :)

----

Hope this helped, cheers and have fun ...


	Lars Ellenberg


Last modified: Wed Sep 29 20:33:23 UTC 2004