0001 What: /sys/class/rnbd-client
0002 Date: Feb 2020
0003 KernelVersion: 5.7
0004 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
0005 Description: Provide information about RNBD-client.
0006 All sysfs files that are not read-only provide the usage information on read:
0007
0008 Example::
0009
0010 # cat /sys/class/rnbd-client/ctl/map_device
0011
0012 > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
0013 > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
0014 > [access_mode=<ro|rw|migration>] > map_device
0015 >
0016 > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
0017
0018 What: /sys/class/rnbd-client/ctl/map_device
0019 Date: Feb 2020
0020 KernelVersion: 5.7
0021 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
0022 Description: Expected format is the following::
0023
0024 sessname=<name of the rtrs session>
0025 path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
0026 device_path=<full path on remote side>
0027 [access_mode=<ro|rw|migration>]
0028
0029 Where:
0030
0031 sessname:
0032 accepts a string not bigger than 256 chars, which identifies
0033 a given session on the client and on the server.
0034 I.e. "clt_hostname-srv_hostname" could be a natural choice.
0035
0036 path:
0037 describes a connection between the client and the server by
0038 specifying destination and, when required, the source address.
0039 The addresses are to be provided in the following format::
0040
0041 ip:<IPv6>
0042 ip:<IPv4>
0043 gid:<GID>
0044
0045 for example::
0046
0047 path=ip:10.0.0.66
0048
0049 The single addr is treated as the destination.
0050 The connection will be established to this server from any client IP address.
0051
0052 ::
0053
0054 path=ip:10.0.0.66,ip:10.0.1.66
0055
0056 First addr is the source address and the second is the destination.
0057
0058 If multiple "path=" options are specified multiple connection
0059 will be established and data will be sent according to
0060 the selected multipath policy (see RTRS mp_policy sysfs entry description).
0061
0062 device_path:
0063 Path to the block device on the server side. Path is specified
0064 relative to the directory on server side configured in the
0065 'dev_search_path' module parameter of the rnbd_server.
0066 The rnbd_server prepends the <device_path> received from client
0067 with <dev_search_path> and tries to open the
0068 <dev_search_path>/<device_path> block device. On success,
0069 a /dev/rnbd<N> device file, a /sys/block/rnbd<N>/
0070 directory and an entry in /sys/class/rnbd-client/ctl/devices
0071 will be created.
0072
0073 If 'dev_search_path' contains '%SESSNAME%', then each session can
0074 have different devices namespace, e.g. server was configured with
0075 the following parameter "dev_search_path=/run/rnbd-devs/%SESSNAME%",
0076 client has this string "sessname=blya device_path=sda", then server
0077 will try to open: /run/rnbd-devs/blya/sda.
0078
0079 access_mode:
0080 the access_mode parameter specifies if the device is to be
0081 mapped as "ro" read-only or "rw" read-write. The server allows
0082 a device to be exported in rw mode only once. The "migration"
0083 access mode has to be specified if a second mapping in read-write
0084 mode is desired.
0085
0086 By default "rw" is used.
0087
0088 nr_poll_queues
0089 specifies the number of poll-mode queues. If the IO has HIPRI flag,
0090 the block-layer will send the IO via the poll-mode queue.
0091 For fast network and device the polling is faster than interrupt-base
0092 IO handling because it saves time for context switching, switching to
0093 another process, handling the interrupt and switching back to the
0094 issuing process.
0095
0096 Set -1 if you want to set it as the number of CPUs
0097 By default rnbd client creates only irq-mode queues.
0098
0099 NOTICE: MUST make a unique session for a device using the poll-mode queues.
0100
0101 Exit Codes:
0102
0103 If the device is already mapped it will fail with EEXIST. If the input
0104 has an invalid format it will return EINVAL. If the device path cannot
0105 be found on the server, it will fail with ENOENT.
0106
0107 Finding device file after mapping
0108 ---------------------------------
0109
0110 After mapping, the device file can be found by:
0111 o The symlink /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>
0112 points to /sys/block/<dev-name>. The last part of the symlink destination
0113 is the same as the device name. By extracting the last part of the
0114 path the path to the device /dev/<dev-name> can be build.
0115
0116 * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>/dev)
0117
0118 How to find the <device_id> of the device is described on the next
0119 section.
0120
0121 What: /sys/class/rnbd-client/ctl/devices/
0122 Date: Feb 2020
0123 KernelVersion: 5.7
0124 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
0125 Description: For each device mapped on the client a new symbolic link is created as
0126 /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>, which points
0127 to the block device created by rnbd (/sys/block/rnbd<N>/).
0128 The <device_id> of each device is created as follows:
0129
0130 - If the 'device_path' provided during mapping contains slashes ("/"),
0131 they are replaced by exclamation mark ("!") and used as as the
0132 <device_id>. Otherwise, the <device_id> will be the same as the
0133 "device_path" provided.
