From: Zac Dover Date: Mon, 20 May 2024 06:29:44 +0000 (+1000) Subject: doc/cephfs: separate commands into sections X-Git-Tag: v20.0.0~1875^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F57554%2Fhead;p=ceph.git doc/cephfs: separate commands into sections Separate commands so that each command has its own subsection in the section "FS Subvolumes" in the file doc/cephfs/fs-volumes.rst. Previously, the list of commands for manipulating subvolumes was one long, unbroken list and the beginning of one section could easily be mistaken for the end of the previous section. Signed-off-by: Zac Dover --- diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst index 8ad5258814ae6..2b709f3bcce3f 100644 --- a/doc/cephfs/fs-volumes.rst +++ b/doc/cephfs/fs-volumes.rst @@ -268,6 +268,9 @@ List snapshots of a subvolume group by running a command of the following form: FS Subvolumes ------------- +Creating a subvolume +~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to create a subvolume: .. prompt:: bash # @@ -286,6 +289,9 @@ default subvolume group with an octal file mode of ``755``, a uid of its subvolume group, a gid of its subvolume group, a data pool layout of its parent directory, and no size limit. +Removing a subvolume +~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to remove a subvolume: .. prompt:: bash # @@ -310,6 +316,9 @@ involve the retained snapshots. .. note:: Retained snapshots can be used as clone sources for recreating the subvolume or for cloning to a newer subvolume. +Resizing a subvolume +~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to resize a subvolume: .. prompt:: bash # @@ -323,6 +332,9 @@ below the current "used size" of the subvolume. The subvolume can be resized to an unlimited (but sparse) logical size by passing ``inf`` or ``infinite`` as ````. +Authorizing CephX auth IDs +~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to authorize CephX auth IDs. This provides the read/read-write access to file system subvolumes: @@ -332,6 +344,9 @@ the read/read-write access to file system subvolumes: The ```` option takes either ``r`` or ``rw`` as a value. +De-authorizing CephX auth IDs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to deauthorize CephX auth IDs. This removes the read/read-write access to file system subvolumes: @@ -339,6 +354,9 @@ the read/read-write access to file system subvolumes: ceph fs subvolume deauthorize [--group_name=] +Listing CephX auth IDs +~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to list CephX auth IDs authorized to access the file system subvolume: @@ -346,6 +364,9 @@ the file system subvolume: ceph fs subvolume authorized_list [--group_name=] +Evicting File System Clients (Auth ID) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to evict file system clients based on the auth ID and the subvolume mounted: @@ -353,12 +374,18 @@ auth ID and the subvolume mounted: ceph fs subvolume evict [--group_name=] +Fetching the Absolute Path of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to fetch the absolute path of a subvolume: .. prompt:: bash # ceph fs subvolume getpath [--group_name ] +Fetching a Subvolume's Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to fetch a subvolume's information: .. prompt:: bash # @@ -414,6 +441,9 @@ contains one of the following values. * ``complete``: subvolume is ready for all operations * ``snapshot-retained``: subvolume is removed but its snapshots are retained +Listing Subvolumes +~~~~~~~~~~~~~~~~~~ + Use a command of the following form to list subvolumes: .. prompt:: bash # @@ -423,6 +453,9 @@ Use a command of the following form to list subvolumes: .. note:: Subvolumes that have been removed but have snapshots retained, are also listed. +Checking for the Presence of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to check for the presence of a given subvolume: @@ -435,6 +468,9 @@ These are the possible results of the ``exist`` command: * ``subvolume exists``: if any subvolume of given ``group_name`` is present * ``no subvolume exists``: if no subvolume of given ``group_name`` is present +Setting Custom Metadata On a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to set custom metadata on the subvolume as a key-value pair: @@ -452,6 +488,9 @@ a key-value pair: subvolume, and is therefore also not preserved when cloning the subvolume snapshot. +Getting The Custom Metadata Set of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to get the custom metadata set on the subvolume using the metadata key: @@ -459,6 +498,9 @@ subvolume using the metadata key: ceph fs subvolume metadata get [--group_name ] +Listing The Custom Metadata Set of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to list custom metadata (key-value pairs) set on the subvolume: @@ -466,6 +508,9 @@ set on the subvolume: ceph fs subvolume metadata ls [--group_name ] +Removing a Custom Metadata Set from a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to remove custom metadata set on the subvolume using the metadata key: @@ -476,12 +521,19 @@ subvolume using the metadata key: Using the ``--force`` flag allows the command to succeed when it would otherwise fail (if the metadata key did not exist). +Creating a Snapshot of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to create a snapshot of a subvolume: .. prompt:: bash # ceph fs subvolume snapshot create [--group_name ] + +Removing a Snapshot of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to remove a snapshot of a subvolume: .. prompt:: bash # @@ -493,12 +545,18 @@ otherwise fail (if the snapshot did not exist). .. note:: if the last snapshot within a snapshot retained subvolume is removed, the subvolume is also removed +Listing the Snapshots of a Subvolume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following from to list the snapshots of a subvolume: .. prompt:: bash # ceph fs subvolume snapshot ls [--group_name ] +Fetching a Snapshot's Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to fetch a snapshot's information: .. prompt:: bash # @@ -558,6 +616,9 @@ Sample output when no snapshot clone is in progress or pending: "has_pending_clones": "no" } +Setting Custom Key-Value Pair Metadata on a Snapshot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to set custom key-value metadata on the snapshot: @@ -576,6 +637,9 @@ snapshot: subvolume, and is therefore not preserved when cloning the subvolume snapshot. +Getting Custom Metadata That Has Been Set on a Snapshot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to get custom metadata that has been set on the snapshot using the metadata key: @@ -583,6 +647,9 @@ the snapshot using the metadata key: ceph fs subvolume snapshot metadata get [--group_name ] +Listing Custom Metadata that has been Set on a Snapshot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following from to list custom metadata (key-value pairs) set on the snapshot: @@ -590,6 +657,9 @@ set on the snapshot: ceph fs subvolume snapshot metadata ls [--group_name ] +Removing Custom Metadata from a Snapshot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Use a command of the following form to remove custom metadata set on the snapshot using the metadata key: