[doc] setup_dnbd3: Setup howto for dnbd3 server and client. Please add!

1 files changed, 96 insertions, 0 deletions

diff --git a/doc/setup_dnbd3 b/doc/setup_dnbd3
new file mode 100644
index 00000000..3af8f4a7
--- /dev/null
+++ b/doc/setup_dnbd3
@@ -0,0 +1,96 @@
+dnbd3-Setup
+
+1. Sources
+
+The git repository is: http://git.openslx.org/dnbd3.git/. Please take care to 
+check out the 'simon' branch. Compileing as usual.
+
+
+Compilieren wie gewöhnlich, Konfiguration des Servers erfolgt nun über ein  
+Config-Verzeichnis, das man auf der command line angibt:
+
+2. Configuration
+
+To ease debugging it is possible to start the server not as a daemon via 
+the '-n' option.
+
+The dnbd3 server uses a directory for configuration. This directory needs 
+to be given via the '-c' option on the command line:
+# ./dnbd3-server -c config-dir/
+
+A file called 'server conf' needs to be placed in the configuration 
+directory. This file has the following format:
+ 
+| [dnbd3]
+| basePath=/path/to/server/root/directory 
+| serverPenalty=1234
+| clientPenalty=2345
+| isProxy=true
+| uplinkTimeout=1250
+
+basePath	Root directory of server
+serverPenalty	If another dnbd3 server connects, the connection will be 
+		delayed by x Microseconds.
+clientPenalty	If a dnbd3 client connects, the connection will be delayed 
+		by x Microseconds.
+isProxy		The server tries to start replicating from an alternative 
+		dnbd3 server if this value is true and a clients calls an 
+		image which is not stored on the server. The image in case 
+		will be blacklisted for five minutes to reduce AltServer 
+		spamming.
+uplinkTimeout	Time in Milliseconds a read/write from an uplink server may 
+		block. After this time another server will be chosen.
+
+
+The penalty entries are useful to control which servers are preferred by 
+clients and which are preferred by proxies, as this influences RTT 
+measurements only.
+
+The basePath entry should be writable at least in proxy mode.
+
+Alternative servers can be given optionally in a file "alt-servers". The
+format used is [prefix][IP-adress of alternative server] [annotation].
+1.2.3.4 Kommentar
++4.5.6.77 Super Proxy
+-7.6.55.3 Uplink
+
+Prefix:
+"-" denotes a private server which will not be advertized to clients,
+but will be user for uplink connections.
+"+" is the opposite; will be sent to clients, but not be used by the server.
+
+
+2.3 Image configuration
+
+Images do not need any configuration, as the relative directory tree below
+basePath directly reflects image names. These names are not case sensitive,
+as they will be lower cased internally. Therefore it would be wise to not
+use two identically named images.
+
+The images need a file name extension, .r[0-9]+, which will be mapped to the
+revision number: /path/to/rootdir/stage4/some_image.sqfs.r5 will be mapped as        
+stage4/ubuntu.sqfs Revision 5.
+
+RPC is not available currently, but a rescan of basePath can be triggered by
+SIGUSR1.
+
+
+3. CRC checks
+
+CRC checks are used for consistency checks and debugging purposes. Before a
+rescan a crc file can be generated by following command
+# ./dnbd3-server --crc /path/to/rootdir/there/some_image.sqfs.r3
+
+This will be used for consistency checking when replicating via proxies (in
+blocks of 16MiB).
+
+
+4. Client connection
+
+A client can be connected via
+# ./dnbd3-client -d /dev/dnbd0 -h [IP of server] -i stage4/ubuntu.sqfs [-r 5]
+
+Possibly read access to users has to be enabled via appropriate udev rules.
+
+
+This documentation is somewhat rudimentary. It will be updated in the future.