Network Block Devices » DNBD

_*This software is still beta - you use it at your own risk. Please create a ticket if you encounter bugs!*_

h1. DNBD

h2. Introduction

DNBD (Distributed Network Block Device) is a read-only and caching network

block device and supports following main features:

* replication of servers for robustness

* multicast communication and caching of network traffic for scalability

These characteristics make it suitable especially for use in wireless networks,

e.g. for diskless clients or to share multimedia files in such an environment.

The servers can export a file or block device equipped with a operating system,

movies, music, etc. Several clients can import the block device and access it

like a local hard disk. However, each block transfer over the network can be

cached by all clients: If several users on each client start to watch a movie

within a certain time interval, the movie data has to be transmitted only once

(depending on the cache size). The network is not burdened with unnecessary

traffic. 

DNBD can be used together with "cowloop":http://www.atconsultancy.nl/cowloop/ or "unionfs":http://www.fsl.cs.sunysb.edu/project-unionfs.html in order to get local

write semantics, e.g. for diskless clients. Especially in wireless environments

with limited bandwidth, caching can increase boot-up time enormously.

h2. Question, problems etc.

If you encounter any difficulties, please use search to find out if the problem is 

already known. Also, the [[FAQ|FAQ]] will contain typical problems.

h2. Download

The source code can be retrieved from the subversion repository.

<pre>

$ svn co http://svn.OpenSLX.org/svn/openslx/contrib/dnbd

</pre>

h2. Compilation

DNBD was developed for kernel 2.6.13 and later releases. For kernels later than 2.6.16 you will need to remove the "devfs" source from _kernel/main.c_ (simply search for "devfs" and remove all calls and includes). Kernel 2.4 is not supported. The kernel sources and common tools (gcc, make, etc.) have to be installed.

h3. Server and Client

Compiling:

<pre>

$ cd dnbd; make

</pre>

h2. USAGE

h3. Server

To show available command line parameters, start the server without

arguments:

<pre>

$ ./server/dnbd-server

dnbd-server, version 0.9.0

Usage: dnbd-server -m <address> -d <device/file> -i <number> 

                  [-t <threads>]

description:

  -m|--mcast     <multicast address>

  -d|--device    <block device or file>

  -i|--id        <unique identification number>

  -t|--threads   <number of threads>

</pre>

With the following command, the server will be started for the multicast

network with address 239.0.0.1 and export the given file or block device.

Its unique id is 1:

<pre>

root@server1 $ ./server/dnbd-server -m 239.0.0.1 -d <partition/file> -i 1

</pre>

To start a server on another computer, the used file or block device must have

the same content and size as on the first server. However, the id has to be

changed:

<pre>

root@server2 $ ./server/dnbd-server -m 239.0.0.1 -d <partition/file> -i 2

</pre>

If DNBD is used for wired networks and on multi-processor machines, the

number of threads should be increased to the number of CPUs.

To access the exported file or block device, another computer is used as 

client.

h3. Client

The kernel module has to be loaded, before the client application can be used:

<pre>

root@client1 $ insmod ./kernel/dnbd.ko

</pre>

There should be an entry in syslog after successful loading. With no command

line arguments the client gives available options:

<pre>

root@client1 $ ./client/dnbd-client

dnbd-client, version 0.9.0

Usage: dnbd-client -d device -b <address> [-c <file>]

    or dnbd-client -d device -u

    or dnbd-client -d device -c <file>

description:

  -d|--device    <device>

  -b|--bind      <multicast-address>

  -u|--unbind    

  -c|--cache     <file>

</pre>

We will now import the block device of the server, e.g.:

<pre>

root@client1 $ ./client/dnbd-client -d /dev/dnbd0 -b 239.0.0.1

</pre>

The client should tell you that it found a server with id "1". If you exported

a CDROM with a movie, you can watch it on the client over the network, e.g.

with mplayer (usually after mounting).

If someone else wants to watch the movie on a different client, you should

enable caching either during operation

<pre>

root@client1 $ ./client/dnbd-client -d /dev/dnbd0 -c <cachefile>

</pre>

or at the beginning

<pre>

root@client2 $ ./client/dnbd-client -d /dev/dnbd0 -b 239.0.0.1 -c <cachefile>

</pre>

To create a cache with, e.g. 32M use

<pre>

root@client1$ dd if=/dev/zero of=/tmp/cachefile bs=1M count=32

</pre>

Cache statistics are shown with

<pre>

root@client1$ cat /proc/driver/dnbd/dnbd0

</pre>

The block device has to be unbound before the module can be unloaded:

<pre>

root@client1 $ ./client/dnbd-client -d /dev/dnbd0 -u

root@client1 $ rmmod dnbd

</pre>

h2. Files

h3. Client

<pre>

./client

   client.c		# client application

</pre>

h3. Server

<pre>

./server

   net.c		# network routines

   query.c		# server request handling

   filer.c		# file/device I/O

   server.c		# server application (main file)

</pre>

h3. Kernel module

<pre>

./kernel

   net.c		# server management

   queue.c		# queue handling for requests

   cache.c		# cache implementation (red-black trees)

   main.c		# module and block device (un)registration, threads

</pre>

h2. License

DNBD is available through the GNU General Public License (GPL).

This distribution is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The programs in this distribution are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See the file COPYING that is also included with this distribution for more details.