From: Rishabh Dave <ridave@redhat.com>
Date: Mon, 20 Feb 2023 07:51:25 +0000 (+0530)
Subject: doc/cephfs: describe conf opt "client quota df" in quota doc
X-Git-Tag: v17.2.6~81^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=f918058a1bf37b4d08ffde76c257819d817706bb;p=ceph.git

doc/cephfs: describe conf opt "client quota df" in quota doc

The ceph config file option (from the client section) "client quota df"
is mentioned in "CephFS Client Capabilities" document but not in the
"CephFS Quota" document. Adding information about this option to this
document too would make it easier for CephFS users to discover,
understand and use this option.

Signed-off-by: Rishabh Dave <ridave@redhat.com>
(cherry picked from commit cd3f9575afb33bdb0a311a3f27801879a3254824)
---

diff --git a/doc/cephfs/quota.rst b/doc/cephfs/quota.rst
index a13795159e9d..e5a846118ab8 100644
--- a/doc/cephfs/quota.rst
+++ b/doc/cephfs/quota.rst
@@ -5,6 +5,60 @@ CephFS allows quotas to be set on any directory in the 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
+
+Space Usage Reporting and CephFS Quotas
+---------------------------------------
+When the root directory of the CephFS mount has quota set on it, the available
+space on the CephFS reported by space usage report tools (like ``df``) is
+based on quota limit. That is, ``available space = quota limit - used space``
+instead of ``available space = total space - used space``.
+
+This behaviour can be disabled by setting following option in client section
+of ``ceph.conf``::
+
+    client quota df = false
+
 Limitations
 -----------