[mirror_ubuntu-bionic-kernel.git] / Documentation / nbd.txt

                      Network Block Device (TCP version)
                                       
   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).
   
   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.
   
   For more information, or to download the nbd-client and nbd-server
   tools, go to http://nbd.sf.net/.

   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)

   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.
Commit	Line	Data
1da177e4 LT	1	Network Block Device (TCP version)
	2
	3	What is it: With this compiled in the kernel (or as a module), Linux
	4	can use a remote server as one of its block devices. So every time
	5	the client computer wants to read, e.g., /dev/nb0, it sends a
	6	request over TCP to the server, which will reply with the data read.
	7	This can be used for stations with low disk space (or even diskless -
	8	if you boot from floppy) to borrow disk space from another computer.
	9	Unlike NFS, it is possible to put any filesystem on it, etc. It should
	10	even be possible to use NBD as a root filesystem (I've never tried),
	11	but it requires a user-level program to be in the initrd to start.
	12	It also allows you to run block-device in user land (making server
	13	and client physically the same computer, communicating using loopback).
	14
	15	Current state: It currently works. Network block device is stable.
	16	I originally thought that it was impossible to swap over TCP. It
	17	turned out not to be true - swapping over TCP now works and seems
	18	to be deadlock-free, but it requires heavy patches into Linux's
	19	network layer.
	20
	21	For more information, or to download the nbd-client and nbd-server
	22	tools, go to http://nbd.sf.net/.
	23
	24	Howto: To setup nbd, you can simply do the following:
	25
	26	First, serve a device or file from a remote server:
	27
	28	nbd-server <port-number> <device-or-file-to-serve-to-client>
	29
	30	e.g.,
	31	root@server1 # nbd-server 1234 /dev/sdb1
	32
	33	(serves sdb1 partition on TCP port 1234)
	34
	35	Then, on the local (client) system:
	36
	37	nbd-client <server-name-or-IP> <server-port-number> /dev/nb[0-n]
	38
	39	e.g.,
	40	root@client1 # nbd-client server1 1234 /dev/nb0
	41
	42	(creates the nb0 device on client1)
	43
	44	The nbd kernel module need only be installed on the client
	45	system, as the nbd-server is completely in userspace. In fact,
	46	the nbd-server has been successfully ported to other operating
	47	systems, including Windows.