From dbcfe7c93cf84b6dde2041e1311600b354f63b7a Mon Sep 17 00:00:00 2001
From: Zac Dover <zac.dover@proton.me>
Date: Thu, 24 Oct 2024 14:52:58 +1000
Subject: [PATCH] doc/cephfs: edit "Disabling Volumes Plugin"

Improve the English language in the section 'Disabling Volumes Plugin"
(which here becomes "Disabling the Volumes Plugin") in the
doc/cephfs/troubleshooting.rst file.

The change here is similar to a change introduced in
https://github.com/ceph/ceph/pull/60448/. That PR seems to be unable to
pass the "make check", and this PR is part of a test to see if breaking
the changes in that PR into several smaller changes results in mergeable
PRs.

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 3e043a903ca26ce153093cbd7c498e2577c41d8a)
---
 doc/cephfs/fs-volumes.rst      | 56 +++++++++++++++++++++++++++++-----
 doc/cephfs/troubleshooting.rst |  9 +++---
 2 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst
index 9f2b12965ceeb..3e7dd7815ad94 100644
--- a/doc/cephfs/fs-volumes.rst
+++ b/doc/cephfs/fs-volumes.rst
@@ -299,6 +299,24 @@ The earmarking mechanism ensures that subvolumes are correctly tagged and manage
 helping to avoid conflicts and ensuring that each subvolume is associated
 with the intended service or use case.
 
+Valid Earmarks
+~~~~~~~~~~~~~~~~~~~~
+
+- **For NFS:**
+   - The valid earmark format is the top-level scope: ``'nfs'``.
+
+- **For SMB:**
+   - The valid earmark formats are:
+      - The top-level scope: ``'smb'``.
+      - The top-level scope with an intra-module level scope: ``'smb.cluster.{cluster_id}'``, where ``cluster_id`` is a short string uniquely identifying the cluster.
+      - Example without intra-module scope: ``smb``
+      - Example with intra-module scope: ``smb.cluster.cluster_1``
+
+.. note:: If you are changing an earmark from one scope to another (e.g., from nfs to smb or vice versa),
+   be aware that user permissions and ACLs associated with the previous scope might still apply. Ensure that
+   any necessary permissions are updated as needed to maintain proper access control.
+
+
 Removing a subvolume
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -795,16 +813,40 @@ Here is an example of an ``in-progress`` clone:
 ::
 
     {
-        "status": {
-            "state": "in-progress",
-            "source": {
-                "volume": "cephfs",
-                "subvolume": "subvol1",
-                "snapshot": "snap1"
-            }
+      "status": {
+        "state": "in-progress",
+        "source": {
+          "volume": "cephfs",
+          "subvolume": "subvol1",
+          "snapshot": "snap1"
+        },
+        "progress_report": {
+          "percentage cloned": "12.24%",
+          "amount cloned": "376M/3.0G",
+          "files cloned": "4/6"
         }
+      }
     }
 
+A progress report is also printed in the output when clone is ``in-progress``.
+Here the progress is reported only for the specific clone. For collective
+progress made by all ongoing clones, a progress bar is printed at the bottom
+in ouput of ``ceph status`` command::
+
+  progress:
+    3 ongoing clones - average progress is 47.569% (10s)
+      [=============...............] (remaining: 11s)
+
+If the number of clone jobs are more than cloner threads, two progress bars
+are printed, one for ongoing clones (same as above) and other for all
+(ongoing+pending) clones::
+
+  progress:
+    4 ongoing clones - average progress is 27.669% (15s)
+      [=======.....................] (remaining: 41s)
+    Total 5 clones - average progress is 41.667% (3s)
+      [===========.................] (remaining: 4s)
+
 .. note:: The ``failure`` section will be shown only if the clone's state is ``failed`` or ``cancelled``
 
 Here is an example of a ``failed`` clone:
diff --git a/doc/cephfs/troubleshooting.rst b/doc/cephfs/troubleshooting.rst
index 46befcad58298..c5c956cf66766 100644
--- a/doc/cephfs/troubleshooting.rst
+++ b/doc/cephfs/troubleshooting.rst
@@ -407,10 +407,11 @@ its associated key. A less drastic but half-fix is to change the osd cap for
 your user to just ``caps osd = "allow rw"``  and delete ``tag cephfs
 data=....``
 
-Disabling Volumes Plugin
-========================
-In certain scenarios, volumes plugin might be needed to disabled to prevent compromise
-for rest of the Ceph cluster. For details see: :ref:`disabling-volumes-plugin`
+Disabling the Volumes Plugin
+============================
+In certain scenarios, the Volumes plugin may need to be disabled to prevent
+compromise for rest of the Ceph cluster. For details see:
+:ref:`disabling-volumes-plugin`
 
 Reporting Issues
 ================
-- 
2.47.3