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