doc/cephfs: rearrange CephFS Quota document

CephFS users, especially new users, would find it easier to discover,
understand and use CephFS Quota when basic information (like setting,
viewing and removing CephFS quota from a CephFS directory) is mentioned
in the documentation before advanced information (like limitations &
implementation details of CephFS Quota).

Signed-off-by: Rishabh Dave <ridave@redhat.com>

diff --git a/doc/cephfs/quota.rst b/doc/cephfs/quota.rst
index a13795159e9dcd5c1b17b313462de780d0a1d91e..6bc26a750d83818fa15335c7e6b6cbd01bd64580 100644 (file)
--- a/doc/cephfs/quota.rst
+++ b/doc/cephfs/quota.rst
@@ -1,10 +1,52 @@
-Quotas
-======
+CephFS Quotas
+=============
 
-CephFS allows quotas to be set on any directory in the system.  The
+CephFS allows quotas to be set on any directory in the file system.  The
 quota can restrict the number of *bytes* or the number of *files*
 stored beneath that point in the directory hierarchy.
 
+Like most other things in CephFS, quotas are configured using virtual
+extended attributes:
+
+ * ``ceph.quota.max_files`` -- file limit
+ * ``ceph.quota.max_bytes`` -- byte limit
+
+If the extended attributes appear on a directory that means a quota is
+configured there. If they are not present then no quota is set on that
+directory (although one may still be configured on a parent directory).
+
+To set a quota, set the extended attribute on a CephFS directory with a
+value::
+
+  setfattr -n ceph.quota.max_bytes -v 100000000 /some/dir     # 100 MB
+  setfattr -n ceph.quota.max_files -v 10000 /some/dir         # 10,000 files
+
+To view quota limit::
+
+  $ getfattr -n ceph.quota.max_bytes /some/dir
+  # file: dir1/
+  ceph.quota.max_bytes="100000000"
+  $
+  $ getfattr -n ceph.quota.max_files /some/dir
+  # file: dir1/
+  ceph.quota.max_files="10000"
+
+.. note:: Running ``getfattr /some/dir -d -m -`` for a CephFS directory will
+   print none of the CephFS extended attributes. This is because the CephFS
+   kernel and FUSE clients hide this information from the ``listxattr(2)``
+   system call. Instead, a specific CephFS extended attribute can be viewed by
+   running ``getfattr /some/dir -n ceph.<some-xattr>``.
+
+To remove a quota, set the value of extended attribute to ``0``::
+
+  $ setfattr -n ceph.quota.max_bytes -v 0 /some/dir
+  $ getfattr /some/dir -n ceph.quota.max_bytes
+  dir1/: ceph.quota.max_bytes: No such attribute
+  $
+  $ setfattr -n ceph.quota.max_files -v 0 /some/dir
+  $ getfattr dir1/ -n ceph.quota.max_files
+  dir1/: ceph.quota.max_files: No such attribute
+
 Limitations
 -----------
 
@@ -55,42 +97,3 @@ Limitations
 
 #. *Snapshot file data which has since been deleted or changed does not count
    towards the quota.* See also: http://tracker.ceph.com/issues/24284
-
-Configuration
--------------
-
-Like most other things in CephFS, quotas are configured using virtual
-extended attributes:
-
- * ``ceph.quota.max_files`` -- file limit
- * ``ceph.quota.max_bytes`` -- byte limit
-
-If the attributes appear on a directory inode that means a quota is
-configured there.  If they are not present then no quota is set on
-that directory (although one may still be configured on a parent directory).
-
-To set a quota::
-
-  setfattr -n ceph.quota.max_bytes -v 100000000 /some/dir     # 100 MB
-  setfattr -n ceph.quota.max_files -v 10000 /some/dir         # 10,000 files
-
-To view quota settings::
-
-  getfattr -n ceph.quota.max_bytes /some/dir
-  getfattr -n ceph.quota.max_files /some/dir
-
-Note that if the value of the extended attribute is ``0`` that means
-the quota is not set.
-
-To remove a quota::
-
-  setfattr -n ceph.quota.max_bytes -v 0 /some/dir
-  setfattr -n ceph.quota.max_files -v 0 /some/dir
-
-
-.. note:: In cases where CephFS extended attributes are set on a CephFS
-   directory (for example, ``/some/dir``), running ``getfattr /some/dir -d -m
-   -`` will not print those CephFS extended attributes. This is because CephFS
-   kernel and FUSE clients hide this information from the ``listxattr(2)``
-   system call. You can access a specific CephFS extended attribute by running
-   ``getfattr /some/dir -n ceph.<some-xattr>`` instead.