1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4Quota subsystem
5===============
6
7Quota subsystem allows system administrator to set limits on used space and
8number of used inodes (inode is a filesystem structure which is associated with
9each file or directory) for users and/or groups. For both used space and number
10of used inodes there are actually two limits. The first one is called softlimit
11and the second one hardlimit.  A user can never exceed a hardlimit for any
12resource (unless he has CAP_SYS_RESOURCE capability). User is allowed to exceed
13softlimit but only for limited period of time. This period is called "grace
14period" or "grace time". When grace time is over, user is not able to allocate
15more space/inodes until he frees enough of them to get below softlimit.
16
17Quota limits (and amount of grace time) are set independently for each
18filesystem.
19
20For more details about quota design, see the documentation in quota-tools package
21(https://sourceforge.net/projects/linuxquota).
22
23Quota netlink interface
24=======================
25When user exceeds a softlimit, runs out of grace time or reaches hardlimit,
26quota subsystem traditionally printed a message to the controlling terminal of
27the process which caused the excess. This method has the disadvantage that
28when user is using a graphical desktop he usually cannot see the message.
29Thus quota netlink interface has been designed to pass information about
30the above events to userspace. There they can be captured by an application
31and processed accordingly.
32
33The interface uses generic netlink framework (see
34https://lwn.net/Articles/208755/ and http://www.infradead.org/~tgr/libnl/ for
35more details about this layer). The name of the quota generic netlink interface
36is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>.  Since
37the quota netlink protocol is not namespace aware, quota netlink messages are
38sent only in initial network namespace.
39
40Currently, the interface supports only one message type QUOTA_NL_C_WARNING.
41This command is used to send a notification about any of the above mentioned
42events. Each message has six attributes. These are (type of the argument is
43in parentheses):
44
45        QUOTA_NL_A_QTYPE (u32)
46	  - type of quota being exceeded (one of USRQUOTA, GRPQUOTA)
47        QUOTA_NL_A_EXCESS_ID (u64)
48	  - UID/GID (depends on quota type) of user / group whose limit
49	    is being exceeded.
50        QUOTA_NL_A_CAUSED_ID (u64)
51	  - UID of a user who caused the event
52        QUOTA_NL_A_WARNING (u32)
53	  - what kind of limit is exceeded:
54
55		QUOTA_NL_IHARDWARN
56		    inode hardlimit
57		QUOTA_NL_ISOFTLONGWARN
58		    inode softlimit is exceeded longer
59		    than given grace period
60		QUOTA_NL_ISOFTWARN
61		    inode softlimit
62		QUOTA_NL_BHARDWARN
63		    space (block) hardlimit
64		QUOTA_NL_BSOFTLONGWARN
65		    space (block) softlimit is exceeded
66		    longer than given grace period.
67		QUOTA_NL_BSOFTWARN
68		    space (block) softlimit
69
70	  - four warnings are also defined for the event when user stops
71	    exceeding some limit:
72
73		QUOTA_NL_IHARDBELOW
74		    inode hardlimit
75		QUOTA_NL_ISOFTBELOW
76		    inode softlimit
77		QUOTA_NL_BHARDBELOW
78		    space (block) hardlimit
79		QUOTA_NL_BSOFTBELOW
80		    space (block) softlimit
81
82        QUOTA_NL_A_DEV_MAJOR (u32)
83	  - major number of a device with the affected filesystem
84        QUOTA_NL_A_DEV_MINOR (u32)
85	  - minor number of a device with the affected filesystem
86