README
1********************************
2RDMA Network Block Device (RNBD)
3********************************
4
5Introduction
6------------
7
8RNBD (RDMA Network Block Device) is a pair of kernel modules
9(client and server) that allow for remote access of a block device on
10the server over RTRS protocol using the RDMA (InfiniBand, RoCE, iWARP)
11transport. After being mapped, the remote block devices can be accessed
12on the client side as local block devices.
13
14I/O is transferred between client and server by the RTRS transport
15modules. The administration of RNBD and RTRS modules is done via
16sysfs entries.
17
18Requirements
19------------
20
21 RTRS kernel modules
22
23Quick Start
24-----------
25
26Server side:
27 # modprobe rnbd_server
28
29Client side:
30 # modprobe rnbd_client
31 # echo "sessname=blya path=ip:10.50.100.66 device_path=/dev/ram0" > \
32 /sys/devices/virtual/rnbd-client/ctl/map_device
33
34 Where "sessname=" is a session name, a string to identify the session
35 on client and on server sides; "path=" is a destination IP address or
36 a pair of a source and a destination IPs, separated by comma. Multiple
37 "path=" options can be specified in order to use multipath (see RTRS
38 description for details); "device_path=" is the block device to be
39 mapped from the server side. After the session to the server machine is
40 established, the mapped device will appear on the client side under
41 /dev/rnbd<N>.
42
43
44RNBD-Server Module Parameters
45=============================
46
47dev_search_path
48---------------
49
50When a device is mapped from the client, the server generates the path
51to the block device on the server side by concatenating dev_search_path
52and the "device_path" that was specified in the map_device operation.
53
54The default dev_search_path is: "/".
55
56dev_search_path option can also contain %SESSNAME% in order to provide
57different device namespaces for different sessions. See "device_path"
58option for details.
59
60============================
61Protocol (rnbd/rnbd-proto.h)
62============================
63
641. Before mapping first device from a given server, client sends an
65RNBD_MSG_SESS_INFO to the server. Server responds with
66RNBD_MSG_SESS_INFO_RSP. Currently the messages only contain the protocol
67version for backward compatibility.
68
692. Client requests to open a device by sending RNBD_MSG_OPEN message. This
70contains the path to the device and access mode (read-only or writable).
71Server responds to the message with RNBD_MSG_OPEN_RSP. This contains
72a 32 bit device id to be used for IOs and device "geometry" related
73information: side, max_hw_sectors, etc.
74
753. Client attaches RNBD_MSG_IO to each IO message send to a device. This
76message contains device id, provided by server in his rnbd_msg_open_rsp,
77sector to be accessed, read-write flags and bi_size.
78
794. Client closes a device by sending RNBD_MSG_CLOSE which contains only the
80device id provided by the server.
81
82=========================================
83Contributors List(in alphabetical order)
84=========================================
85Danil Kipnis <danil.kipnis@profitbricks.com>
86Fabian Holler <mail@fholler.de>
87Guoqing Jiang <guoqing.jiang@cloud.ionos.com>
88Jack Wang <jinpu.wang@profitbricks.com>
89Kleber Souza <kleber.souza@profitbricks.com>
90Lutz Pogrell <lutz.pogrell@cloud.ionos.com>
91Milind Dumbare <Milind.dumbare@gmail.com>
92Roman Penyaev <roman.penyaev@profitbricks.com>
93Swapnil Ingle <ingleswapnil@gmail.com>
94