From: Zac Dover Date: Mon, 20 May 2024 06:29:44 +0000 (+1000) Subject: doc/cephfs: separate commands into sections X-Git-Tag: v17.2.8~347^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=88ec50ee3ee6703ce26e5a5350334b0fbd9171ad;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 29bc258d200c..85adab997ae7 100644 --- a/doc/cephfs/fs-volumes.rst +++ b/doc/cephfs/fs-volumes.rst @@ -237,6 +237,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 # @@ -254,6 +257,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 # @@ -278,6 +284,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 # @@ -291,6 +300,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: @@ -300,6 +312,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: @@ -307,6 +322,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: @@ -314,6 +332,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: @@ -322,12 +342,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 # @@ -383,6 +409,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 # @@ -392,6 +421,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: @@ -404,6 +436,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: @@ -422,6 +457,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: @@ -429,6 +467,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: @@ -436,6 +477,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: @@ -446,12 +490,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 # @@ -463,12 +514,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 # @@ -518,6 +575,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: @@ -536,6 +596,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: @@ -543,6 +606,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: @@ -550,6 +616,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: