1 What: /sys/class/rnbd-client 1 What: /sys/class/rnbd-client
2 Date: Feb 2020 2 Date: Feb 2020
3 KernelVersion: 5.7 3 KernelVersion: 5.7
4 Contact: Jack Wang <jinpu.wang@cloud.ion 4 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
5 Description: Provide information about RNBD 5 Description: Provide information about RNBD-client.
6 All sysfs files that are not r 6 All sysfs files that are not read-only provide the usage information on read:
7 7
8 Example:: 8 Example::
9 9
10 # cat /sys/class/rnbd-clie 10 # cat /sys/class/rnbd-client/ctl/map_device
11 11
12 > Usage: echo "sessname=<n 12 > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
13 > [path=<[srcaddr,]dstaddr 13 > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
14 > [access_mode=<ro|rw|migr 14 > [access_mode=<ro|rw|migration>] > map_device
15 > 15 >
16 > addr ::= [ ip:<ipv4> | i 16 > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
17 17
18 What: /sys/class/rnbd-client/ctl/map 18 What: /sys/class/rnbd-client/ctl/map_device
19 Date: Feb 2020 19 Date: Feb 2020
20 KernelVersion: 5.7 20 KernelVersion: 5.7
21 Contact: Jack Wang <jinpu.wang@cloud.ion 21 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
22 Description: Expected format is the followi 22 Description: Expected format is the following::
23 23
24 sessname=<name of the rtrs 24 sessname=<name of the rtrs session>
25 path=<[srcaddr,]dstaddr> [ 25 path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
26 device_path=<full path on 26 device_path=<full path on remote side>
27 [access_mode=<ro|rw|migrat 27 [access_mode=<ro|rw|migration>]
28 28
29 Where: 29 Where:
30 30
31 sessname: 31 sessname:
32 accepts a string not bigge 32 accepts a string not bigger than 256 chars, which identifies
33 a given session on the cli 33 a given session on the client and on the server.
34 I.e. "clt_hostname-srv_hos 34 I.e. "clt_hostname-srv_hostname" could be a natural choice.
35 35
36 path: 36 path:
37 describes a connection bet 37 describes a connection between the client and the server by
38 specifying destination and 38 specifying destination and, when required, the source address.
39 The addresses are to be pr 39 The addresses are to be provided in the following format::
40 40
41 ip:<IPv6> 41 ip:<IPv6>
42 ip:<IPv4> 42 ip:<IPv4>
43 gid:<GID> 43 gid:<GID>
44 44
45 for example:: 45 for example::
46 46
47 path=ip:10.0.0.66 47 path=ip:10.0.0.66
48 48
49 The single addr is treated as 49 The single addr is treated as the destination.
50 The connection will be establi 50 The connection will be established to this server from any client IP address.
51 51
52 :: 52 ::
53 53
54 path=ip:10.0.0.66,ip:10.0. 54 path=ip:10.0.0.66,ip:10.0.1.66
55 55
56 First addr is the source addre 56 First addr is the source address and the second is the destination.
57 57
58 If multiple "path=" options ar 58 If multiple "path=" options are specified multiple connection
59 will be established and data w 59 will be established and data will be sent according to
60 the selected multipath policy 60 the selected multipath policy (see RTRS mp_policy sysfs entry description).
61 61
62 device_path: 62 device_path:
63 Path to the block device o 63 Path to the block device on the server side. Path is specified
64 relative to the directory 64 relative to the directory on server side configured in the
65 'dev_search_path' module p 65 'dev_search_path' module parameter of the rnbd_server.
66 The rnbd_server prepends t 66 The rnbd_server prepends the <device_path> received from client
67 with <dev_search_path> and 67 with <dev_search_path> and tries to open the
68 <dev_search_path>/<device_ 68 <dev_search_path>/<device_path> block device. On success,
69 a /dev/rnbd<N> device file 69 a /dev/rnbd<N> device file, a /sys/block/rnbd<N>/
70 directory and an entry in 70 directory and an entry in /sys/class/rnbd-client/ctl/devices
71 will be created. 71 will be created.
72 72
73 If 'dev_search_path' contains 73 If 'dev_search_path' contains '%SESSNAME%', then each session can
74 have different devices namespa 74 have different devices namespace, e.g. server was configured with
75 the following parameter "dev_s 75 the following parameter "dev_search_path=/run/rnbd-devs/%SESSNAME%",
76 client has this string "sessna 76 client has this string "sessname=blya device_path=sda", then server
77 will try to open: /run/rnbd-de 77 will try to open: /run/rnbd-devs/blya/sda.
78 78
79 access_mode: 79 access_mode:
80 the access_mode parameter 80 the access_mode parameter specifies if the device is to be
81 mapped as "ro" read-only o 81 mapped as "ro" read-only or "rw" read-write. The server allows
82 a device to be exported in 82 a device to be exported in rw mode only once. The "migration"
83 access mode has to be spec 83 access mode has to be specified if a second mapping in read-write
84 mode is desired. 84 mode is desired.
85 85
86 By default "rw" is used. 86 By default "rw" is used.
87 87
88 nr_poll_queues 88 nr_poll_queues
89 specifies the number of poll 89 specifies the number of poll-mode queues. If the IO has HIPRI flag,
90 the block-layer will send th 90 the block-layer will send the IO via the poll-mode queue.
91 For fast network and device 91 For fast network and device the polling is faster than interrupt-base
92 IO handling because it saves 92 IO handling because it saves time for context switching, switching to
93 another process, handling th 93 another process, handling the interrupt and switching back to the
94 issuing process. 94 issuing process.
95 95
96 Set -1 if you want to set it 96 Set -1 if you want to set it as the number of CPUs
97 By default rnbd client creat 97 By default rnbd client creates only irq-mode queues.
98 98
99 NOTICE: MUST make a unique s 99 NOTICE: MUST make a unique session for a device using the poll-mode queues.
100 100
101 Exit Codes: 101 Exit Codes:
102 102
103 If the device is already mappe 103 If the device is already mapped it will fail with EEXIST. If the input
104 has an invalid format it will 104 has an invalid format it will return EINVAL. If the device path cannot
105 be found on the server, it wil 105 be found on the server, it will fail with ENOENT.
106 106
107 Finding device file after mapp 107 Finding device file after mapping
108 ------------------------------ 108 ---------------------------------
109 109
110 After mapping, the device file 110 After mapping, the device file can be found by:
111 o The symlink /sys/class/rnbd< 111 o The symlink /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>
112 points to /sys/block/<dev-name 112 points to /sys/block/<dev-name>. The last part of the symlink destination
113 is the same as the device name 113 is the same as the device name. By extracting the last part of the
114 path the path to the device /d 114 path the path to the device /dev/<dev-name> can be build.
115 115
116 * /dev/block/$(cat /sys/class/< 116 * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>/dev)
117 117
118 How to find the <device_id> of 118 How to find the <device_id> of the device is described on the next
119 section. 119 section.
120 120
121 What: /sys/class/rnbd-client/ctl/dev 121 What: /sys/class/rnbd-client/ctl/devices/
122 Date: Feb 2020 122 Date: Feb 2020
123 KernelVersion: 5.7 123 KernelVersion: 5.7
124 Contact: Jack Wang <jinpu.wang@cloud.ion 124 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
125 Description: For each device mapped on the 125 Description: For each device mapped on the client a new symbolic link is created as
126 /sys/class/rnbd-client/ctl/dev< 126 /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>, which points
127 to the block device created by 127 to the block device created by rnbd (/sys/block/rnbd<N>/).
128 The <device_id> of each device 128 The <device_id> of each device is created as follows:
129 129
130 - If the 'device_path' provide 130 - If the 'device_path' provided during mapping contains slashes ("/"),
131 they are replaced by exclama 131 they are replaced by exclamation mark ("!") and used as as the
132 <device_id>. Otherwise, the 132 <device_id>. Otherwise, the <device_id> will be the same as the
133 "device_path" provided. 133 "device_path" provided.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.