src/ceph/doc/cephfs/quota.rst

   1 Quotas
   2 ======
   3
   4 CephFS allows quotas to be set on any directory in the system.  The
   5 quota can restrict the number of *bytes* or the number of *files*
   6 stored beneath that point in the directory hierarchy.
   7
   8 Limitations
   9 -----------
  10
  11 #. *Quotas are cooperative and non-adversarial.* CephFS quotas rely on
  12    the cooperation of the client who is mounting the file system to
  13    stop writers when a limit is reached.  A modified or adversarial
  14    client cannot be prevented from writing as much data as it needs.
  15    Quotas should not be relied on to prevent filling the system in
  16    environments where the clients are fully untrusted.
  17
  18 #. *Quotas are imprecise.* Processes that are writing to the file
  19    system will be stopped a short time after the quota limit is
  20    reached.  They will inevitably be allowed to write some amount of
  21    data over the configured limit.  How far over the quota they are
  22    able to go depends primarily on the amount of time, not the amount
  23    of data.  Generally speaking writers will be stopped within 10s of
  24    seconds of crossing the configured limit.
  25
  26 #. *Quotas are not yet implemented in the kernel client.* Quotas are
  27    supported by the userspace client (libcephfs, ceph-fuse) but are
  28    not yet implemented in the Linux kernel client.
  29
  30 #. *Quotas must be configured carefully when used with path-based
  31    mount restrictions.* The client needs to have access to the
  32    directory inode on which quotas are configured in order to enforce
  33    them.  If the client has restricted access to a specific path
  34    (e.g., ``/home/user``) based on the MDS capability, and a quota is
  35    configured on an ancestor directory they do not have access to
  36    (e.g., ``/home``), the client will not enforce it.  When using
  37    path-based access restrictions be sure to configure the quota on
  38    the directory the client is restricted too (e.g., ``/home/user``)
  39    or something nested beneath it.
  40
  41 Configuration
  42 -------------
  43
  44 Like most other things in CephFS, quotas are configured using virtual
  45 extended attributes:
  46
  47  * ``ceph.quota.max_files`` -- file limit
  48  * ``ceph.quota.max_bytes`` -- byte limit
  49
  50 If the attributes appear on a directory inode that means a quota is
  51 configured there.  If they are not present then no quota is set on
  52 that directory (although one may still be configured on a parent directory).
  53
  54 To set a quota::
  55
  56   setfattr -n ceph.quota.max_bytes -v 100000000 /some/dir     # 100 MB
  57   setfattr -n ceph.quota.max_files -v 10000 /some/dir         # 10,000 files
  58
  59 To view quota settings::
  60
  61   getfattr -n ceph.quota.max_bytes /some/dir
  62   getfattr -n ceph.quota.max_files /some/dir
  63
  64 Note that if the value of the extended attribute is ``0`` that means
  65 the quota is not set.
  66
  67 To remove a quota::
  68
  69   setfattr -n ceph.quota.max_bytes -v 0 /some/dir
  70   setfattr -n ceph.quota.max_files -v 0 /some/dir