INSTALL

This file explains how to build the WinDRBD kernel driver from the
sources. If you just want to try WinDRBD you probably want to
get an officially signed installable binary from the linbit
website (www.linbit.com), because the build process requires
lots of more work (and still the driver won't be officially signed).

Having said that, this is what you need:

Build environment setup:

You need two virtual machines (of course physical machines are
also fine): 
	1.) One Linux box with spatch installed (in addition to 
		the usual development tools like make, gcc, ...)
		On Ubuntu this is installed by:

			sudo apt-get install coccinelle

	2.) A Windows 7 WM with Service Pack 1 (at least) installed.
	    (Windows 10 and Windows Server 2016 also work).

	    Download and Install cygwin 
	    Download and Install Development tools of cygwin (there is
		a GUI for that, please don't expect screenshots in here)
		You need (at least): 
			autoconf, automake, flex, gcc-core, gcc-g++, git, make

	    Download and install the EWDK as described in:

		https://docs.microsoft.com/en-us/windows-hardware/drivers/develop/installing-the-enterprise-wdk

	   	If possible, install it to 
			C:\ewdk 
		This saves you from too many makefile edits later

		Newer ewdk's come as ISO file, mount it (by double-clicking
		it) to a drive.

		Edit Makefile.win and add a build environment (since
		there is no configure one has to do that manually).
		See the jt-* samples there (which work for my Ewdk
		installation but most likely not for yours).		

		Also copy one of the ms-*.cmd scripts to ms-<my-buildenv>.cmd
		and adapt as needed.

		When running make on windows you must specify your
		build enviroment (see below) or you hard code it
		to Makefile.win.

		Run make copy on one of the boxes (Linux or Windows)
		whenever you change the Makefile.win or the ms-*.cmd
		scripts.

	3.) Optional: To create installable packages (make package), you need
	    inno-setup in addition to the above. You can download it
	    from: 

	    http://www.jrsoftware.org

	    Make sure the command line compiler iscc.exe is in the
	    PATH (ususally "/cygdrive/c/Program Files (x86)/Inno Setup 5")
	    (it is a 32-bit application on an 64 bit system, hence x86)

git clone windrbd with:

bash$ git clone --recursive git@github.com:LINBIT/windrbd.git

on your Linux box. windrbd uses drbd as a submodule that's why --recursive
is needed.

Share the windrbd folder via Samba, so that your Windows VM can access it
(we are not keeping any important data on the Windows VM since it will
crash frequently). You can use the GNOME Files utility to do so (for
example).

Or use (on Linux)

sudo net usershare add home ~ "Home" johannes:F

where johannes is your samba user (create with:
sudo smbpasswd -a johannes
)

you might have to restart samba (shown here for Ubuntu):

service smbd stop
service smbd start

Mount the shared folder in your windows box:
	net use z: \\<ip-of-linux-box>\windrbd
(assuming the share name is windrbd)

Note on git: some git versions put absolute paths into the
.git file of the submodules. Change that to relative paths
else git commands on your Windows box will not work.
(drbd/.git, drbd/drbd-headers/.git, drbd/drbd/drbd-kernel-compat/.git)

Note on crypto: Even though I start Windows with driver signature verification
off it still needs to be signed. The crypto directory, for obvious reasons
doesn't contain our (Linbit) keys so you have to create your own. Please
consult google and/or the enclosed README about how to do this.

To disable Windows driver signature checking, execute

bcdedit /set TESTSIGNING ON

as Windows Administrator on your Windows box and reboot. Then it should
not be neccessary to press F8 and select disable signature check manually.

Once you are here, you're almost done.

Building and "insmod" DRBD windows driver:

	1.) cd into root directory of windrbd on your Linux box

        2.) Run
                make
        on the Linux box

	3.) cd into root directory of windrbd on your Windows box

        4.) Run
                make BUILD_ENV=<your-build-env>
        on the Windows box

        5.) Run (as Administrator in cygwin bash) 
                make install
        on the Windows box

	starting with (roughly 0.8.5) no reboot is required for installation.

        6.) (optional) To load the driver, do (from Adminstrator Console)
                sc start windrbd

	starting with (roughly 0.8.5) this is done automatically when
	calling drbdadm/drbdsetup.

Be sure to also build and install also the drbd-utils from
https://github.com/LINBIT/drbd-utils
else you won't be able to use the driver.

To make packages (installable exe using inno-setup), edit the
inno-setup/windrbd.iss file to change the pathes of windrbd
and drbd-utils and do:

	make package

The resulting EXE (with version number appended) will be placed
in the inno-setup directory.

------------

Note on logging: You will find the kernel logs in the file
C:\windrbd\windrbd-kernel.log . It currently does not logrotate
so from time to time, do a

        sc stop windrbdlog
        del c:\windrbd\windrbd-kernel.log
        sc start windrbdlog

in a cmd shell (rm /cygdrive/c/windrbd/windrbd-kernel.log if in a
CygWin shell). If you want to dig deeper into logging, please read
on.

windrbd currently sends UDP packets to a logging host
for logging. This is meant for use with syslog.

If you don't want to log remotely, you can simply start

windrbd log-server

in a shell (cmd or cygwin is fine) and watch the logs (note that
you don't get logs on driver startup only when the first drbdadm
command is invoked). However you will lose logs when the system
blue screens.

To enable UDP logging in rsyslogd put (or uncomment) following lines
into /etc/rsyslog.conf:

module(load="imudp")
input(type="imudp" port="514")

then do a 
bash$ sudo service syslog restart

Logging now uses a kernel ring buffer, much like Linux does. So
you should be able to view the log messages in order. The only
exception is when Windows crashes with interrupts disabled
Then you wouldn't see the last messages starting from when
interrupts got disabled.

Currently you also only see the DRBD driver's boot messages
only after you configure a DRBD resource.

To configure the log host set a Registry key (string value):

	Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\drbd\syslog_ip

and assign it the IP address (you might have to reload the WinDRBD driver
after setting this).

You can also use the dbgview.exe tool (please google it) and enable 
Capture Kernel on Windows to see some log messages. It must be run as
Administrator on the Windows machine. But if windows blue screens 
you are screwed.

--------------

Note on drbd-utils: windrbd branch is now merged into master (should
appear as version 9.7.0 in the next few days on github). Please clone
with:

git clone --recursive https://github.com/LINBIT/drbd-utils.git

and follow the build instruction in README-windrbd.md file of the
repo.

---------------

Note on cocinelle on Windows:

Install autotools, ocaml, ocamlfind, ocamldoc, opam via cygwin setup (TODO: what else?)

opam init
opam install stdcompat
opam install pyml	(?)

Need to install pyml (and stdcompat) from github sources
	(else win_fd something is not found)

git clone https://github.com/coccinelle/coccinelle.git

./autogen
./configure --disable-python
# configure
make
make install

----------

Building DRBD:

(need spatch --version at least 1.0.8 something see above for howto)

git clone --recursive https://github.com/linbit/drbd-9.0
cd drbd-9.0
git checkout drbd-9.0
git submodule update --checkout
# DRBD 9.0.22
git checkout fe2b59836bd
git checkout -b jt/use-after-free
git submodule update --checkout
# DRBD 9.0.22 end
make