0001 ********************************
0002 RDMA Network Block Device (RNBD)
0003 ********************************
0004
0005 Introduction
0006 ------------
0007
0008 RNBD (RDMA Network Block Device) is a pair of kernel modules
0009 (client and server) that allow for remote access of a block device on
0010 the server over RTRS protocol using the RDMA (InfiniBand, RoCE, iWARP)
0011 transport. After being mapped, the remote block devices can be accessed
0012 on the client side as local block devices.
0013
0014 I/O is transferred between client and server by the RTRS transport
0015 modules. The administration of RNBD and RTRS modules is done via
0016 sysfs entries.
0017
0018 Requirements
0019 ------------
0020
0021 RTRS kernel modules
0022
0023 Quick Start
0024 -----------
0025
0026 Server side:
0027 # modprobe rnbd_server
0028
0029 Client side:
0030 # modprobe rnbd_client
0031 # echo "sessname=blya path=ip:10.50.100.66 device_path=/dev/ram0" > \
0032 /sys/devices/virtual/rnbd-client/ctl/map_device
0033
0034 Where "sessname=" is a session name, a string to identify the session
0035 on client and on server sides; "path=" is a destination IP address or
0036 a pair of a source and a destination IPs, separated by comma. Multiple
0037 "path=" options can be specified in order to use multipath (see RTRS
0038 description for details); "device_path=" is the block device to be
0039 mapped from the server side. After the session to the server machine is
0040 established, the mapped device will appear on the client side under
0041 /dev/rnbd<N>.
0042
0043
0044 RNBD-Server Module Parameters
0045 =============================
0046
0047 dev_search_path
0048 ---------------
0049
0050 When a device is mapped from the client, the server generates the path
0051 to the block device on the server side by concatenating dev_search_path
0052 and the "device_path" that was specified in the map_device operation.
0053
0054 The default dev_search_path is: "/".
0055
0056 dev_search_path option can also contain %SESSNAME% in order to provide
0057 different device namespaces for different sessions. See "device_path"
0058 option for details.
0059
0060 ============================
0061 Protocol (rnbd/rnbd-proto.h)
0062 ============================
0063
0064 1. Before mapping first device from a given server, client sends an
0065 RNBD_MSG_SESS_INFO to the server. Server responds with
0066 RNBD_MSG_SESS_INFO_RSP. Currently the messages only contain the protocol
0067 version for backward compatibility.
0068
0069 2. Client requests to open a device by sending RNBD_MSG_OPEN message. This
0070 contains the path to the device and access mode (read-only or writable).
0071 Server responds to the message with RNBD_MSG_OPEN_RSP. This contains
0072 a 32 bit device id to be used for IOs and device "geometry" related
0073 information: side, max_hw_sectors, etc.
0074
0075 3. Client attaches RNBD_MSG_IO to each IO message send to a device. This
0076 message contains device id, provided by server in his rnbd_msg_open_rsp,
0077 sector to be accessed, read-write flags and bi_size.
0078
0079 4. Client closes a device by sending RNBD_MSG_CLOSE which contains only the
0080 device id provided by the server.
0081
0082 =========================================
0083 Contributors List(in alphabetical order)
0084 =========================================
0085 Danil Kipnis <danil.kipnis@profitbricks.com>
0086 Fabian Holler <mail@fholler.de>
0087 Guoqing Jiang <guoqing.jiang@cloud.ionos.com>
0088 Jack Wang <jinpu.wang@profitbricks.com>
0089 Kleber Souza <kleber.souza@profitbricks.com>
0090 Lutz Pogrell <lutz.pogrell@cloud.ionos.com>
0091 Milind Dumbare <Milind.dumbare@gmail.com>
0092 Roman Penyaev <roman.penyaev@profitbricks.com>
0093 Swapnil Ingle <ingleswapnil@gmail.com>
