From: Zac Dover Date: Mon, 20 May 2024 06:29:44 +0000 (+1000) Subject: doc/cephfs: separate commands into sections X-Git-Tag: v18.2.5~657^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F57669%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 (cherry picked from commit a84ec3a1c0f026f54d079509b5d6cafde032154c) --- diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst index 903b6f20d522c..a6af0f2629b43 100644 --- a/doc/cephfs/fs-volumes.rst +++ b/doc/cephfs/fs-volumes.rst @@ -249,6 +249,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 # @@ -266,6 +269,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 # @@ -290,6 +296,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 # @@ -303,6 +312,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: @@ -312,6 +324,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: @@ -319,6 +334,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: @@ -326,6 +344,8 @@ 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: @@ -334,12 +354,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 # @@ -395,6 +421,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 # @@ -404,6 +433,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: @@ -416,6 +448,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: @@ -434,6 +469,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: @@ -441,6 +479,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: @@ -448,6 +489,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: @@ -458,12 +502,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 # @@ -475,12 +526,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 # @@ -530,6 +587,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: @@ -548,6 +608,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: @@ -555,6 +618,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: @@ -562,6 +628,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: