* [PATCH] block: rbd: update sysfs interface
@ 2018-02-20 9:08 Aishwarya Pant
2018-02-21 16:07 ` Ilya Dryomov
0 siblings, 1 reply; 2+ messages in thread
From: Aishwarya Pant @ 2018-02-20 9:08 UTC (permalink / raw)
To: Ilya Dryomov, Sage Weil, Alex Elder, ceph-devel, linux-kernel,
Jonathan Corbet, Greg KH
Cc: Julia Lawall
The existing sysfs interface has been updated to be in the same format
as described in Documentation/ABI/README. This will be useful for
scripting and tracking changes in the ABI. Attributes have been grouped
by functionality and/or the date on which they were added.
There are a couple of more changes:
- The attributes have been annotated with file permissions RO/RW/WO.
- Added description of the bus attribute supported_features
Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
---
Documentation/ABI/testing/sysfs-bus-rbd | 202 +++++++++++++++++++-------------
1 file changed, 122 insertions(+), 80 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd
index f208ac58d613..9549e9b0fcf8 100644
--- a/Documentation/ABI/testing/sysfs-bus-rbd
+++ b/Documentation/ABI/testing/sysfs-bus-rbd
@@ -1,121 +1,163 @@
-What: /sys/bus/rbd/
-Date: November 2010
+What: /sys/bus/rbd/add
+What: /sys/bus/rbd/remove
+Date: Jan, 2012
+KernelVersion: v3.10
Contact: Yehuda Sadeh <yehuda@newdream.net>,
Sage Weil <sage@newdream.net>
Description:
+ add : (WO) Add rbd block device.
-Being used for adding and removing rbd block devices.
+ Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
-Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
+ $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
- $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
+ The snapshot name can be "-" or omitted to map the image
+ read/write. A <dev-id> will be assigned for any registered block
+ device. If snapshot is used, it will be mapped read-only.
-The snapshot name can be "-" or omitted to map the image read/write. A <dev-id>
-will be assigned for any registered block device. If snapshot is used, it will
-be mapped read-only.
+ remove: (WO) Remove rbd block device.
-Usage: <dev-id> [force]
+ Usage: <dev-id> [force]
- $ echo 2 > /sys/bus/rbd/remove
+ $ echo 2 > /sys/bus/rbd/remove
+
+ Optional "force" argument which when passed will wait for
+ running requests and then unmap the image. Requests sent to the
+ driver after initiating the removal will be failed. (August
+ 2016, since 4.9.)
-Optional "force" argument which when passed will wait for running requests and
-then unmap the image. Requests sent to the driver after initiating the removal
-will be failed. (August 2016, since 4.9.)
What: /sys/bus/rbd/add_single_major
-Date: December 2013
-KernelVersion: 3.14
-Contact: Sage Weil <sage@inktank.com>
-Description: Available only if rbd module is inserted with single_major
+Date: Dec, 2013
+KernelVersion: v3.14
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ (WO) Available only if rbd module is inserted with single_major
parameter set to true.
- Usage is the same as for /sys/bus/rbd/add. If present,
+
+ Usage is the same as for /sys/bus/rbd/add. If present, this
should be used instead of the latter: any attempts to use
- /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is
- available will fail for backwards compatibility reasons.
+ /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available
+ will fail for backwards compatibility reasons.
+
What: /sys/bus/rbd/remove_single_major
-Date: December 2013
-KernelVersion: 3.14
-Contact: Sage Weil <sage@inktank.com>
-Description: Available only if rbd module is inserted with single_major
+Date: Dec, 2013
+KernelVersion: v3.14
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ (WO) Available only if rbd module is inserted with single_major
parameter set to true.
- Usage is the same as for /sys/bus/rbd/remove. If present,
+
+ Usage is the same as for /sys/bus/rbd/remove. If present, this
should be used instead of the latter: any attempts to use
/sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is
available will fail for backwards compatibility reasons.
-Entries under /sys/bus/rbd/devices/<dev-id>/
---------------------------------------------
-
-client_addr
-
- The ceph unique client entity_addr_t (address + nonce).
- The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
- '[1:2:3:4:5:6:7:8]:1234/5678'. (August 2016, since 4.9.)
-
-client_id
-
- The ceph unique client id that was assigned for this specific session.
-
-cluster_fsid
-
- The ceph cluster UUID. (August 2016, since 4.9.)
-
-config_info
-
- The string written into /sys/bus/rbd/add{,_single_major}. (August
- 2016, since 4.9.)
-
-features
-
- A hexadecimal encoding of the feature bits for this image.
-major
-
- The block device major number.
-
-minor
+What: /sys/bus/rbd/supported_features
+Date: Mar, 2017
+KernelVersion: v4.11
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ (RO) Displays the features supported by the client software
+ implementation so that userspace can generate meaningful error
+ messages and spell out unsupported features that need to be
+ disabled.
+
+
+What: /sys/bus/rbd/devices/<dev-id>/size
+What: /sys/bus/rbd/devices/<dev-id>/refresh
+What: /sys/bus/rbd/devices/<dev-id>/current_snap
+What: /sys/bus/rbd/devices/<dev-id>/name
+What: /sys/bus/rbd/devices/<dev-id>/major
+What: /sys/bus/rbd/devices/<dev-id>/client_id
+Date: Aug, 2010
+KernelVersion: v2.6.37
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ size: (RO) The size (in bytes) of the mapped block
+ device.
- The block device minor number. (December 2013, since 3.14.)
+ refresh: (WO) Writing to this file will reread the image
+ header data and set all relevant data structures
+ accordingly.
-name
+ current_snap: (RO) The current snapshot for which the device
+ is mapped.
- The name of the rbd image.
+ name: (RO) The name of the rbd image.
-image_id
+ major: (RO) The block device major number.
- The unique id for the rbd image. (For rbd image format 1
- this is empty.)
+ client_id: (RO) The ceph unique client id that was assigned
+ for this specific session.
-pool
- The name of the storage pool where this rbd image resides.
- An rbd image name is unique within its pool.
+What: /sys/bus/rbd/devices/<dev-id>/pool
+What: /sys/bus/rbd/devices/<dev-id>/image_id
+What: /sys/bus/rbd/devices/<dev-id>/features
+What: /sys/bus/rbd/devices/<dev-id>/pool_id
+Date: Jul, 2012
+KernelVersion: v3.10
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ pool: (RO) The name of the storage pool where this rbd
+ image resides. An rbd image name is unique
+ within its pool.
-pool_id
+ image_id: (WO) The unique id for the rbd image. (For rbd
+ image format 1 this is empty.)
- The unique identifier for the rbd image's pool. This is
- a permanent attribute of the pool. A pool's id will never
- change.
+ features: (RO) A hexadecimal encoding of the feature bits
+ for this image.
-size
+ pool_idr: (RO) The unique identifier for the rbd image's
+ pool. This is a permanent attribute of the pool.
+ A pool's id will never change.
- The size (in bytes) of the mapped block device.
-refresh
+What: /sys/bus/rbd/devices/<dev-id>/parent
+Date: Oct, 2012
+KernelVersion: v3.10
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ (RO) Information identifying the chain of parent images in a
+ layered rbd image. Entries are separated by empty lines.
- Writing to this file will reread the image header data and set
- all relevant datastructures accordingly.
-current_snap
+What: /sys/bus/rbd/devices/<dev-id>/minor
+Date: Dec, 2013
+KernelVersion: v3.14
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ (RO) The block device minor number.
- The current snapshot for which the device is mapped.
-snap_id
+What: /sys/bus/rbd/devices/<dev-id>/snap_id
+What: /sys/bus/rbd/devices/<dev-id>/config_info
+What: /sys/bus/rbd/devices/<dev-id>/cluster_fsid
+What: /sys/bus/rbd/devices/<dev-id>/client_addr
+Date: Aug, 2016
+KernelVersion: v4.9
+Contact: Yehuda Sadeh <yehuda@newdream.net>,
+ Sage Weil <sage@newdream.net>
+Description:
+ snap_id: (RO) The current snapshot's id.
- The current snapshot's id. (August 2016, since 4.9.)
+ config_info: (RO) The string written into
+ /sys/bus/rbd/add{,_single_major}.
-parent
+ cluster_fsid: (RO) The ceph cluster UUID.
- Information identifying the chain of parent images in a layered rbd
- image. Entries are separated by empty lines.
+ client_addr: (RO) The ceph unique client
+ entity_addr_t (address + nonce). The format is
+ <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
+ '[1:2:3:4:5:6:7:8]:1234/5678'.
--
2.16.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] block: rbd: update sysfs interface
2018-02-20 9:08 [PATCH] block: rbd: update sysfs interface Aishwarya Pant
@ 2018-02-21 16:07 ` Ilya Dryomov
0 siblings, 0 replies; 2+ messages in thread
From: Ilya Dryomov @ 2018-02-21 16:07 UTC (permalink / raw)
To: Aishwarya Pant
Cc: Sage Weil, Alex Elder, Ceph Development, linux-kernel,
Jonathan Corbet, Greg KH, Julia Lawall
On Tue, Feb 20, 2018 at 10:08 AM, Aishwarya Pant <aishpant@gmail.com> wrote:
> The existing sysfs interface has been updated to be in the same format
> as described in Documentation/ABI/README. This will be useful for
> scripting and tracking changes in the ABI. Attributes have been grouped
> by functionality and/or the date on which they were added.
>
> There are a couple of more changes:
> - The attributes have been annotated with file permissions RO/RW/WO.
> - Added description of the bus attribute supported_features
>
> Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
> ---
> Documentation/ABI/testing/sysfs-bus-rbd | 202 +++++++++++++++++++-------------
> 1 file changed, 122 insertions(+), 80 deletions(-)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd
> index f208ac58d613..9549e9b0fcf8 100644
> --- a/Documentation/ABI/testing/sysfs-bus-rbd
> +++ b/Documentation/ABI/testing/sysfs-bus-rbd
> @@ -1,121 +1,163 @@
> -What: /sys/bus/rbd/
> -Date: November 2010
> +What: /sys/bus/rbd/add
> +What: /sys/bus/rbd/remove
Hi Aishwarya,
No need to group "add" and "remove" together. Do them separate, like
"add_single_major" and "remove_single_major".
> +Date: Jan, 2012
> +KernelVersion: v3.10
I think "add" and "remove" go back to v2.6.37.
> Contact: Yehuda Sadeh <yehuda@newdream.net>,
> Sage Weil <sage@newdream.net>
Remove Yehuda from the contact list here and everywhere else.
> Description:
> + add : (WO) Add rbd block device.
>
> -Being used for adding and removing rbd block devices.
> + Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
>
> -Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
> + $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
>
> - $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
> + The snapshot name can be "-" or omitted to map the image
> + read/write. A <dev-id> will be assigned for any registered block
> + device. If snapshot is used, it will be mapped read-only.
>
> -The snapshot name can be "-" or omitted to map the image read/write. A <dev-id>
> -will be assigned for any registered block device. If snapshot is used, it will
> -be mapped read-only.
> + remove: (WO) Remove rbd block device.
>
> -Usage: <dev-id> [force]
> + Usage: <dev-id> [force]
>
> - $ echo 2 > /sys/bus/rbd/remove
> + $ echo 2 > /sys/bus/rbd/remove
> +
> + Optional "force" argument which when passed will wait for
> + running requests and then unmap the image. Requests sent to the
> + driver after initiating the removal will be failed. (August
> + 2016, since 4.9.)
>
> -Optional "force" argument which when passed will wait for running requests and
> -then unmap the image. Requests sent to the driver after initiating the removal
> -will be failed. (August 2016, since 4.9.)
>
> What: /sys/bus/rbd/add_single_major
> -Date: December 2013
> -KernelVersion: 3.14
> -Contact: Sage Weil <sage@inktank.com>
> -Description: Available only if rbd module is inserted with single_major
> +Date: Dec, 2013
> +KernelVersion: v3.14
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + (WO) Available only if rbd module is inserted with single_major
> parameter set to true.
> - Usage is the same as for /sys/bus/rbd/add. If present,
> +
> + Usage is the same as for /sys/bus/rbd/add. If present, this
> should be used instead of the latter: any attempts to use
> - /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is
> - available will fail for backwards compatibility reasons.
> + /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is available
> + will fail for backwards compatibility reasons.
> +
>
> What: /sys/bus/rbd/remove_single_major
> -Date: December 2013
> -KernelVersion: 3.14
> -Contact: Sage Weil <sage@inktank.com>
> -Description: Available only if rbd module is inserted with single_major
> +Date: Dec, 2013
> +KernelVersion: v3.14
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + (WO) Available only if rbd module is inserted with single_major
> parameter set to true.
> - Usage is the same as for /sys/bus/rbd/remove. If present,
> +
> + Usage is the same as for /sys/bus/rbd/remove. If present, this
> should be used instead of the latter: any attempts to use
> /sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is
> available will fail for backwards compatibility reasons.
>
> -Entries under /sys/bus/rbd/devices/<dev-id>/
> ---------------------------------------------
> -
> -client_addr
> -
> - The ceph unique client entity_addr_t (address + nonce).
> - The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
> - '[1:2:3:4:5:6:7:8]:1234/5678'. (August 2016, since 4.9.)
> -
> -client_id
> -
> - The ceph unique client id that was assigned for this specific session.
> -
> -cluster_fsid
> -
> - The ceph cluster UUID. (August 2016, since 4.9.)
> -
> -config_info
> -
> - The string written into /sys/bus/rbd/add{,_single_major}. (August
> - 2016, since 4.9.)
> -
> -features
> -
> - A hexadecimal encoding of the feature bits for this image.
>
> -major
> -
> - The block device major number.
> -
> -minor
> +What: /sys/bus/rbd/supported_features
> +Date: Mar, 2017
> +KernelVersion: v4.11
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + (RO) Displays the features supported by the client software
the client software implementation -> rbd module
> + implementation so that userspace can generate meaningful error
> + messages and spell out unsupported features that need to be
> + disabled.
> +
> +
> +What: /sys/bus/rbd/devices/<dev-id>/size
> +What: /sys/bus/rbd/devices/<dev-id>/refresh
> +What: /sys/bus/rbd/devices/<dev-id>/current_snap
> +What: /sys/bus/rbd/devices/<dev-id>/name
> +What: /sys/bus/rbd/devices/<dev-id>/major
> +What: /sys/bus/rbd/devices/<dev-id>/client_id
> +Date: Aug, 2010
> +KernelVersion: v2.6.37
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + size: (RO) The size (in bytes) of the mapped block
> + device.
>
> - The block device minor number. (December 2013, since 3.14.)
> + refresh: (WO) Writing to this file will reread the image
> + header data and set all relevant data structures
> + accordingly.
>
> -name
> + current_snap: (RO) The current snapshot for which the device
> + is mapped.
>
> - The name of the rbd image.
> + name: (RO) The name of the rbd image.
>
> -image_id
> + major: (RO) The block device major number.
>
> - The unique id for the rbd image. (For rbd image format 1
> - this is empty.)
> + client_id: (RO) The ceph unique client id that was assigned
> + for this specific session.
>
> -pool
>
> - The name of the storage pool where this rbd image resides.
> - An rbd image name is unique within its pool.
> +What: /sys/bus/rbd/devices/<dev-id>/pool
"pool" also goes back to v2.6.37.
> +What: /sys/bus/rbd/devices/<dev-id>/image_id
"image_id" was added in v3.7.
Having these documented is nice, but wrong versions and dates are worse
than none at all. Please cross check the rest with git log/blame.
> +What: /sys/bus/rbd/devices/<dev-id>/features
> +What: /sys/bus/rbd/devices/<dev-id>/pool_id
> +Date: Jul, 2012
> +KernelVersion: v3.10
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + pool: (RO) The name of the storage pool where this rbd
> + image resides. An rbd image name is unique
> + within its pool.
>
> -pool_id
> + image_id: (WO) The unique id for the rbd image. (For rbd
> + image format 1 this is empty.)
image_id should be RO.
>
> - The unique identifier for the rbd image's pool. This is
> - a permanent attribute of the pool. A pool's id will never
> - change.
> + features: (RO) A hexadecimal encoding of the feature bits
> + for this image.
>
> -size
> + pool_idr: (RO) The unique identifier for the rbd image's
> + pool. This is a permanent attribute of the pool.
> + A pool's id will never change.
pool_idr -> pool_id
>
> - The size (in bytes) of the mapped block device.
>
> -refresh
> +What: /sys/bus/rbd/devices/<dev-id>/parent
> +Date: Oct, 2012
> +KernelVersion: v3.10
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + (RO) Information identifying the chain of parent images in a
> + layered rbd image. Entries are separated by empty lines.
>
> - Writing to this file will reread the image header data and set
> - all relevant datastructures accordingly.
>
> -current_snap
> +What: /sys/bus/rbd/devices/<dev-id>/minor
> +Date: Dec, 2013
> +KernelVersion: v3.14
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + (RO) The block device minor number.
>
> - The current snapshot for which the device is mapped.
>
> -snap_id
> +What: /sys/bus/rbd/devices/<dev-id>/snap_id
> +What: /sys/bus/rbd/devices/<dev-id>/config_info
> +What: /sys/bus/rbd/devices/<dev-id>/cluster_fsid
> +What: /sys/bus/rbd/devices/<dev-id>/client_addr
> +Date: Aug, 2016
> +KernelVersion: v4.9
> +Contact: Yehuda Sadeh <yehuda@newdream.net>,
> + Sage Weil <sage@newdream.net>
> +Description:
> + snap_id: (RO) The current snapshot's id.
>
> - The current snapshot's id. (August 2016, since 4.9.)
> + config_info: (RO) The string written into
> + /sys/bus/rbd/add{,_single_major}.
>
> -parent
> + cluster_fsid: (RO) The ceph cluster UUID.
>
> - Information identifying the chain of parent images in a layered rbd
> - image. Entries are separated by empty lines.
> + client_addr: (RO) The ceph unique client
> + entity_addr_t (address + nonce). The format is
> + <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
> + '[1:2:3:4:5:6:7:8]:1234/5678'.
Thanks,
Ilya
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2018-02-21 16:07 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-02-20 9:08 [PATCH] block: rbd: update sysfs interface Aishwarya Pant
2018-02-21 16:07 ` Ilya Dryomov
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).