Merge pull request #56784 from zdover23/wip-doc-2024-04-09-cephfs-client-auth-2-of-3

doc/cephfs: refine client-auth (2 of 3)

Reviewed-by: Cole Mitchell <cole.mitchell.ceph@gmail.com>

1 files changed, 49 insertions, 29 deletions

diff --git a/doc/cephfs/client-auth.rst b/doc/cephfs/client-auth.rst
index 3f6826b070b..64423ad0b1f 100644
--- a/doc/cephfs/client-auth.rst
+++ b/doc/cephfs/client-auth.rst
@@ -110,13 +110,13 @@ value of this setting.
 Layout and Quota restriction (the 'p' flag)
 ===========================================
 
-To set layouts or quotas, clients require the 'p' flag in addition to 'rw'.
-This restricts all the attributes that are set by special extended attributes
-with a "ceph." prefix, as well as restricting other means of setting
-these fields (such as openc operations with layouts).
+To set layouts or quotas, clients require the ``p`` flag in addition to ``rw``.
+Using the ``p`` flag with ``rw`` restricts all the attributes that are set by
+special extended attributes by using a ``ceph.`` prefix, and restricts
+other means of setting these fields (such as ``openc`` operations with layouts).
 
-For example, in the following snippet client.0 can modify layouts and quotas
-on the file system cephfs_a, but client.1 cannot::
+For example, in the following snippet ``client.0`` can modify layouts and
+quotas on the file system ``cephfs_a``, but ``client.1`` cannot::
 
     client.0
         key: AQAz7EVWygILFRAAdIcuJ12opU/JKyfFmxhuaw==
@@ -134,12 +134,12 @@ on the file system cephfs_a, but client.1 cannot::
 Snapshot restriction (the 's' flag)
 ===========================================
 
-To create or delete snapshots, clients require the 's' flag in addition to
-'rw'. Note that when capability string also contains the 'p' flag, the 's'
-flag must appear after it (all flags except 'rw' must be specified in
+To create or delete snapshots, clients require the ``s`` flag in addition to
+``rw``. Note that when capability string also contains the ``p`` flag, the
+``s`` flag must appear after it (all flags except ``rw`` must be specified in
 alphabetical order).
 
-For example, in the following snippet client.0 can create or delete snapshots
+For example, in the following snippet ``client.0`` can create or delete snapshots
 in the ``bar`` directory of file system ``cephfs_a``::
 
     client.0
@@ -162,9 +162,9 @@ Network restriction
    caps: [mon] allow r network 10.0.0.0/8
    caps: [osd] allow rw tag cephfs data=cephfs_a network 10.0.0.0/8
 
-The optional ``{network/prefix}`` is a standard network name and
-prefix length in CIDR notation (e.g., ``10.3.0.0/16``).  If present,
-the use of this capability is restricted to clients connecting from
+The optional ``{network/prefix}`` is a standard network-name-and-prefix length
+in CIDR notation (for example, ``10.3.0.0/16``). If ``{network/prefix}}`` is
+present, the use of this capability is restricted to clients connecting from
 this network.
 
 .. _fs-authorize-multifs:
@@ -172,38 +172,58 @@ this network.
 File system Information Restriction
 ===================================
 
-If desired, the monitor cluster can present a limited view of the file systems
-available. In this case, the monitor cluster will only inform clients about
-file systems specified by the administrator. Other file systems will not be
-reported and commands affecting them will fail as if the file systems do
-not exist.
+The monitor cluster can present a limited view of the available file systems.
+In this case, the monitor cluster informs clients only about file systems
+specified by the administrator. Other file systems are not reported and
+commands affecting them fail as though the file systems do not exist.
 
-Consider following example. The Ceph cluster has 2 FSs::
+Consider following example. The Ceph cluster has 2 file systems:
+
+.. prompt:: bash #
+
+   ceph fs ls
+
+::
 
-    $ ceph fs ls
     name: cephfs, metadata pool: cephfs_metadata, data pools: [cephfs_data ]
     name: cephfs2, metadata pool: cephfs2_metadata, data pools: [cephfs2_data ]
 
-But we authorize client ``someuser`` for only one FS::
+We authorize client ``someuser`` for only one file system:
+
+.. prompt:: bash #
+
+   ceph fs authorize cephfs client.someuser / rw
+
+::
 
-    $ ceph fs authorize cephfs client.someuser / rw
     [client.someuser]
         key = AQAmthpf89M+JhAAiHDYQkMiCq3x+J0n9e8REQ==
-    $ cat ceph.client.someuser.keyring
+
+.. prompt:: bash #
+
+   cat ceph.client.someuser.keyring
+
+::
+
     [client.someuser]
         key = AQAmthpf89M+JhAAiHDYQkMiCq3x+J0n9e8REQ==
         caps mds = "allow rw fsname=cephfs"
         caps mon = "allow r fsname=cephfs"
         caps osd = "allow rw tag cephfs data=cephfs"
 
-And the client can only see the FS that it has authorization for::
+The client can see only the file system that it is authorized to see: 
 
-    $ ceph fs ls -n client.someuser -k ceph.client.someuser.keyring
-    name: cephfs, metadata pool: cephfs_metadata, data pools: [cephfs_data ]
+.. prompt:: bash #
+
+   ceph fs ls -n client.someuser -k ceph.client.someuser.keyring
+
+::
+
+   name: cephfs, metadata pool: cephfs_metadata, data pools: [cephfs_data ]
 
-Standby MDS daemons will always be displayed. Note that the information about
-restricted MDS daemons and file systems may become available by other means,
-such as ``ceph health detail``.
+Standby MDS daemons are always displayed. Information about restricted MDS
+daemons and file systems may become available by other means, such as by
+running ``ceph health detail``.
 
 MDS communication restriction
 =============================