Documentation/ABI/testing/sysfs-class-rnbd-client

   1 What:           /sys/class/rnbd-client
   2 Date:           Feb 2020
   3 KernelVersion:  5.7
   4 Contact:        Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
   5 Description:    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
  18 What:           /sys/class/rnbd-client/ctl/map_device
  19 Date:           Feb 2020
  20 KernelVersion:  5.7
  21 Contact:        Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
  22 Description:    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                 Exit Codes:
  89
  90                 If the device is already mapped it will fail with EEXIST. If the input
  91                 has an invalid format it will return EINVAL. If the device path cannot
  92                 be found on the server, it will fail with ENOENT.
  93
  94                 Finding device file after mapping
  95                 ---------------------------------
  96
  97                 After mapping, the device file can be found by:
  98                 o  The symlink /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>
  99                 points to /sys/block/<dev-name>. The last part of the symlink destination
 100                 is the same as the device name.  By extracting the last part of the
 101                 path the path to the device /dev/<dev-name> can be build.
 102
 103                 * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>/dev)
 104
 105                 How to find the <device_id> of the device is described on the next
 106                 section.
 107
 108 What:           /sys/class/rnbd-client/ctl/devices/
 109 Date:           Feb 2020
 110 KernelVersion:  5.7
 111 Contact:        Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
 112 Description:    For each device mapped on the client a new symbolic link is created as
 113                 /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>, which points
 114                 to the block device created by rnbd (/sys/block/rnbd<N>/).
 115                 The <device_id> of each device is created as follows:
 116
 117                 - If the 'device_path' provided during mapping contains slashes ("/"),
 118                   they are replaced by exclamation mark ("!") and used as as the
 119                   <device_id>. Otherwise, the <device_id> will be the same as the
 120                   "device_path" provided.