summaryrefslogtreecommitdiffstats
path: root/doc/cephfs/quota.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/cephfs/quota.rst')
-rw-r--r--doc/cephfs/quota.rst111
1 files changed, 111 insertions, 0 deletions
diff --git a/doc/cephfs/quota.rst b/doc/cephfs/quota.rst
new file mode 100644
index 000000000..0bc56be12
--- /dev/null
+++ b/doc/cephfs/quota.rst
@@ -0,0 +1,111 @@
+CephFS Quotas
+=============
+
+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
+
+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
+-----------
+
+#. *Quotas are cooperative and non-adversarial.* CephFS quotas rely on
+ the cooperation of the client who is mounting the file system to
+ stop writers when a limit is reached. A modified or adversarial
+ client cannot be prevented from writing as much data as it needs.
+ Quotas should not be relied on to prevent filling the system in
+ environments where the clients are fully untrusted.
+
+#. *Quotas are imprecise.* Processes that are writing to the file
+ system will be stopped a short time after the quota limit is
+ reached. They will inevitably be allowed to write some amount of
+ data over the configured limit. How far over the quota they are
+ able to go depends primarily on the amount of time, not the amount
+ of data. Generally speaking writers will be stopped within 10s of
+ seconds of crossing the configured limit.
+
+#. *Quotas are implemented in the kernel client 4.17 and higher.*
+ Quotas are supported by the userspace client (libcephfs, ceph-fuse).
+ Linux kernel clients >= 4.17 support CephFS quotas but only on
+ mimic+ clusters. Kernel clients (even recent versions) will fail
+ to handle quotas on older clusters, even if they may be able to set
+ the quotas extended attributes.
+
+#. *Quotas must be configured carefully when used with path-based
+ mount restrictions.* The client needs to have access to the
+ directory inode on which quotas are configured in order to enforce
+ them. If the client has restricted access to a specific path
+ (e.g., ``/home/user``) based on the MDS capability, and a quota is
+ configured on an ancestor directory they do not have access to
+ (e.g., ``/home``), the client will not enforce it. When using
+ path-based access restrictions be sure to configure the quota on
+ the directory the client is restricted too (e.g., ``/home/user``)
+ or something nested beneath it.
+
+ In case of a kernel client, it needs to have access to the parent
+ of the directory inode on which quotas are configured in order to
+ enforce them. If quota is configured on a directory path
+ (e.g., ``/home/volumes/group``), the kclient needs to have access
+ to the parent (e.g., ``/home/volumes``).
+
+ An example command to create such an user is as below::
+
+ $ ceph auth get-or-create client.guest mds 'allow r path=/home/volumes, allow rw path=/home/volumes/group' mgr 'allow rw' osd 'allow rw tag cephfs metadata=*' mon 'allow r'
+
+ See also: https://tracker.ceph.com/issues/55090
+
+#. *Snapshot file data which has since been deleted or changed does not count
+ towards the quota.* See also: http://tracker.ceph.com/issues/24284