From: Paul Clements <Paul.Clements@SteelEye.com>
Modernise the nbd.txt a bit.
25-akpm/Documentation/nbd.txt | 92 ++++++++++++++++++------------------------
1 files changed, 41 insertions(+), 51 deletions(-)
diff -puN Documentation/nbd.txt~nbd-docco-update Documentation/nbd.txt
--- 25/Documentation/nbd.txt~nbd-docco-update Wed Jul 2 14:38:56 2003
+++ 25-akpm/Documentation/nbd.txt Wed Jul 2 14:38:56 2003
@@ -1,57 +1,47 @@
Network Block Device (TCP version)
- Note: Network Block Device is now experimental, which approximately
- means, that it works on my computer, and it worked on one of school
- computers.
+ What is it: With this compiled in the kernel (or as a module), Linux
+ can use a remote server as one of its block devices. So every time
+ the client computer wants to read, e.g., /dev/nb0, it sends a
+ request over TCP to the server, which will reply with the data read.
+ This can be used for stations with low disk space (or even diskless -
+ if you boot from floppy) to borrow disk space from another computer.
+ Unlike NFS, it is possible to put any filesystem on it, etc. It should
+ even be possible to use NBD as a root filesystem (I've never tried),
+ but it requires a user-level program to be in the initrd to start.
+ It also allows you to run block-device in user land (making server
+ and client physically the same computer, communicating using loopback).
- What is it: With this compiled in the kernel, Linux can use a remote
- server as one of its block devices. So every time the client computer
- wants to read /dev/nd0, it sends a request over TCP to the server, which
- will reply with the data read. This can be used for stations with
- low disk space (or even diskless - if you boot from floppy) to
- borrow disk space from another computer. Unlike NFS, it is possible to
- put any filesystem on it etc. It is impossible to use NBD as a root
- filesystem, since it requires a user-level program to start. It also
- allows you to run block-device in user land (making server and client
- physically the same computer, communicating using loopback).
+ Current state: It currently works. Network block device is stable.
+ I originally thought that it was impossible to swap over TCP. It
+ turned out not to be true - swapping over TCP now works and seems
+ to be deadlock-free, but it requires heavy patches into Linux's
+ network layer.
- Current state: It currently works. Network block device looks like
- being pretty stable. I originally thought that it is impossible to swap
- over TCP. It turned out not to be true - swapping over TCP now works
- and seems to be deadlock-free, but it requires heavy patches into
- Linux's network layer.
-
- Devices: Network block device uses major 43, minors 0..n (where n is
- configurable in nbd.h). Create these files by mknod when needed. After
- that, your ls -l /dev/ should look like:
-
-brw-rw-rw- 1 root root 43, 0 Apr 11 00:28 nd0
-brw-rw-rw- 1 root root 43, 1 Apr 11 00:28 nd1
-...
-
- Protocol: Userland program passes file handle with connected TCP
- socket to actual kernel driver. This way, the kernel does not have to
- care about connecting etc. Protocol is rather simple: If the driver is
- asked to read from block device, it sends packet of following form
- "request" (all data are in network byte order):
-
- __u32 magic; must be equal to 0x12560953
- __u32 from; position in bytes to read from / write at
- __u32 len; number of bytes to be read / written
- __u64 handle; handle of operation
- __u32 type; 0 = read
- 1 = write
- ... in case of write operation, this is
- immediately followed len bytes of data
+ For more information, or to download the nbd-client and nbd-server
+ tools, go to http://nbd.sf.net/.
- When operation is completed, server responds with packet of following
- structure "reply":
-
- __u32 magic; must be equal to
- __u64 handle; handle copied from request
- __u32 error; 0 = operation completed successfully,
- else error code
- ... in case of read operation with no error,
- this is immediately followed len bytes of data
+ Howto: To setup nbd, you can simply do the following:
+
+ First, serve a device or file from a remote server:
+
+ nbd-server <port-number> <device-or-file-to-serve-to-client>
+
+ e.g.,
+ root@server1 # nbd-server 1234 /dev/sdb1
+
+ (serves sdb1 partition on TCP port 1234)
+
+ Then, on the local (client) system:
+
+ nbd-client <server-name-or-IP> <server-port-number> /dev/nb[0-n]
+
+ e.g.,
+ root@client1 # nbd-client server1 1234 /dev/nb0
+
+ (creates the nb0 device on client1)
- For more information, look at http://nbd.sf.net/.
+ The nbd kernel module need only be installed on the client
+ system, as the nbd-server is completely in userspace. In fact,
+ the nbd-server has been successfully ported to other operating
+ systems, including Windows.
_