RNBD client class sysfs ABI | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Client class and usage output

sysfs-class-rnbd-client:1-17

RNBD client의 writable sysfs file은 읽을 때 지원하는 mapping command usage와 address grammar를 반환합니다.

Remote block-device mapping

sysfs-class-rnbd-client:18-119

Session name, one or more RTRS paths, server-side device path, access mode와 poll queue를 지정해 remote block device를 mapping합니다.

Mapped device discovery

sysfs-class-rnbd-client:121-133

Mapped device마다 device_id@session_name symlink를 만들고 device_path의 slash는 exclamation mark로 변환합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

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:

8 Example::

10 # cat /sys/class/rnbd-client/ctl/map_device

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> ]

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::

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>]

29 Where:

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.

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::

41 ip:<IPv6>

42 ip:<IPv4>

43 gid:<GID>

45 for example::

47 path=ip:10.0.0.66

49 The single addr is treated as the destination.

50 The connection will be established to this server from any client IP address.

52 ::

54 path=ip:10.0.0.66,ip:10.0.1.66

56 First addr is the source address and the second is the destination.

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).

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.

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.

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.

86 By default "rw" is used.

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.

96 Set -1 if you want to set it as the number of CPUs

97 By default rnbd client creates only irq-mode queues.

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

121 What: /sys/class/rnbd-client/ctl/devices/

122 Date: Feb 2020

123 KernelVersion: 5.7

124 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>

125 Description: 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

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

RNBD client class and usage information

1-17

항목	한국어 전문 번역
What	/sys/class/rnbd-client
Date	2020년 2월
KernelVersion	5.7
Contact	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
Description	RNBD client에 관한 정보를 제공합니다. Read-only가 아닌 모든 sysfs file은 읽을 때 사용법 정보를 제공합니다.

# cat /sys/class/rnbd-client/ctl/map_device

> Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
> [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
> [access_mode=<ro|rw|migration>] > map_device
>
> addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]

Map a remote block device

18-119

항목	한국어 전문 번역
What	/sys/class/rnbd-client/ctl/map_device
Date	2020년 2월
KernelVersion	5.7
Contact	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
Description	Mapping input은 sessname, 하나 이상의 path, device_path, optional access_mode로 구성합니다. sessname은 최대 256자인 문자열로 client와 server 양쪽에서 session을 식별하며 clt_hostname-srv_hostname 같은 이름을 사용할 수 있습니다. path는 destination과 필요할 때 source address를 지정해 client-server connection을 설명합니다. Address 형식은 ip:<IPv6>, ip:<IPv4>, gid:<GID>입니다. Address 하나만 주면 destination으로 취급해 client의 임의 IP에서 server로 연결합니다. 두 address를 comma로 구분하면 첫 번째가 source, 두 번째가 destination입니다. path option을 여러 번 주면 여러 connection을 만들고 선택한 RTRS mp_policy에 따라 data를 전송합니다. device_path는 rnbd_server의 dev_search_path module parameter가 지정한 directory에 상대적인 server-side block-device path입니다. Server는 받은 device_path 앞에 dev_search_path를 붙여 block device를 엽니다. 성공하면 /dev/rnbd<N>, /sys/block/rnbd<N>/와 client ctl/devices entry를 만듭니다. dev_search_path에 %SESSNAME%이 있으면 session별 device namespace로 치환합니다. access_mode는 ro, rw, migration 중 하나이며 server는 rw export를 한 번만 허용하므로 두 번째 read-write mapping에는 migration을 사용해야 합니다. Default는 rw입니다. nr_poll_queues는 poll-mode queue 수를 정합니다. HIPRI IO는 poll-mode queue로 보내며 빠른 network/device에서는 context switch와 interrupt overhead를 줄일 수 있습니다. -1은 CPU 수만큼 설정하고 default client는 irq-mode queue만 만듭니다. Poll-mode queue를 쓰는 device에는 unique session이 반드시 필요합니다. 이미 mapped된 device는 EEXIST, invalid input format은 EINVAL, server에서 device path를 찾지 못하면 ENOENT로 실패합니다. Mapping 뒤 devices/<device_id>@<session_name> symlink의 destination 마지막 component로 device name을 얻거나 해당 entry의 dev 값을 /dev/block/ 아래에서 사용할 수 있습니다.

sessname=<name of the rtrs session>
path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
device_path=<full path on remote side>
[access_mode=<ro|rw|migration>]

ip:<IPv6>
ip:<IPv4>
gid:<GID>

path=ip:10.0.0.66
path=ip:10.0.0.66,ip:10.0.1.66

dev_search_path=/run/rnbd-devs/%SESSNAME%
sessname=blya device_path=sda
/run/rnbd-devs/blya/sda

/dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name>/dev)

RNBD map_device parameters

Parameter필수의미

sessname예Client와 server의 RTRS session 식별, 최대 256자

path예, 복수 가능[source,]destination connection

device_path예dev_search_path에 상대적인 server block-device path

access_mode아니오ro, rw, migration; default rw

nr_poll_queues아니오Poll-mode queue 수, -1은 CPU 수

Required mapping fields와 주요 constraint입니다.

RNBD mapping path

sessname + RTRS pathdevice_pathserver dev_search_path와 결합Server block device open/dev/rnbd<N> 생성ctl/devices symlink 생성

Client input이 server path resolution과 local block-device 생성으로 이어집니다.

RNBD access modes

Mode의미

roRead-only mapping

rwRead-write mapping, server에서 한 번만 허용

migration두 번째 read-write mapping이 필요할 때 사용

Server-side export 동시성에 따른 access mode입니다.

Successful mapping artifacts

Artifact역할

/dev/rnbd<N>Local block-device node

/sys/block/rnbd<N>/Block-device sysfs directory

ctl/devices/<device_id>@<session_name>Mapped device symlink

Mapping 성공 뒤 생성되는 local device와 discovery entry입니다.

Mapped device symbolic links

121-133

항목	한국어 전문 번역
What	/sys/class/rnbd-client/ctl/devices/
Date	2020년 2월
KernelVersion	5.7
Contact	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
Description	Client에 mapped된 각 device마다 /sys/class/rnbd-client/ctl/devices/<device_id>@<session_name> symbolic link를 만들며 RNBD가 생성한 /sys/block/rnbd<N>/ block device를 가리킵니다. Mapping 때 제공한 device_path에 slash가 있으면 slash를 exclamation mark로 바꾼 값을 device_id로 사용하고, slash가 없으면 device_path 자체를 device_id로 사용합니다.

RNBD device_id construction

device_pathdevice_id rule예

Slash 없음그대로 사용sda → sda

Slash 있음/를 !로 치환pool/volume → pool!volume

device_path의 slash 유무에 따른 device_id 변환입니다.