[mirror_ubuntu-jammy-kernel.git] / Documentation / filesystems / quota.rst

.. SPDX-License-Identifier: GPL-2.0

===============
Quota subsystem
===============

Quota subsystem allows system administrator to set limits on used space and
number of used inodes (inode is a filesystem structure which is associated with
each file or directory) for users and/or groups. For both used space and number
of used inodes there are actually two limits. The first one is called softlimit
and the second one hardlimit.  A user can never exceed a hardlimit for any
resource (unless he has CAP_SYS_RESOURCE capability). User is allowed to exceed
softlimit but only for limited period of time. This period is called "grace
period" or "grace time". When grace time is over, user is not able to allocate
more space/inodes until he frees enough of them to get below softlimit.

Quota limits (and amount of grace time) are set independently for each
filesystem.

For more details about quota design, see the documentation in quota-tools package
(https://sourceforge.net/projects/linuxquota).

Quota netlink interface
=======================
When user exceeds a softlimit, runs out of grace time or reaches hardlimit,
quota subsystem traditionally printed a message to the controlling terminal of
the process which caused the excess. This method has the disadvantage that
when user is using a graphical desktop he usually cannot see the message.
Thus quota netlink interface has been designed to pass information about
the above events to userspace. There they can be captured by an application
and processed accordingly.

The interface uses generic netlink framework (see
https://lwn.net/Articles/208755/ and http://www.infradead.org/~tgr/libnl/ for
more details about this layer). The name of the quota generic netlink interface
is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>.  Since
the quota netlink protocol is not namespace aware, quota netlink messages are
sent only in initial network namespace.

Currently, the interface supports only one message type QUOTA_NL_C_WARNING.
This command is used to send a notification about any of the above mentioned
events. Each message has six attributes. These are (type of the argument is
in parentheses):

        QUOTA_NL_A_QTYPE (u32)
	  - type of quota being exceeded (one of USRQUOTA, GRPQUOTA)
        QUOTA_NL_A_EXCESS_ID (u64)
	  - UID/GID (depends on quota type) of user / group whose limit
	    is being exceeded.
        QUOTA_NL_A_CAUSED_ID (u64)
	  - UID of a user who caused the event
        QUOTA_NL_A_WARNING (u32)
	  - what kind of limit is exceeded:

		QUOTA_NL_IHARDWARN
		    inode hardlimit
		QUOTA_NL_ISOFTLONGWARN
		    inode softlimit is exceeded longer
		    than given grace period
		QUOTA_NL_ISOFTWARN
		    inode softlimit
		QUOTA_NL_BHARDWARN
		    space (block) hardlimit
		QUOTA_NL_BSOFTLONGWARN
		    space (block) softlimit is exceeded
		    longer than given grace period.
		QUOTA_NL_BSOFTWARN
		    space (block) softlimit

	  - four warnings are also defined for the event when user stops
	    exceeding some limit:

		QUOTA_NL_IHARDBELOW
		    inode hardlimit
		QUOTA_NL_ISOFTBELOW
		    inode softlimit
		QUOTA_NL_BHARDBELOW
		    space (block) hardlimit
		QUOTA_NL_BSOFTBELOW
		    space (block) softlimit

        QUOTA_NL_A_DEV_MAJOR (u32)
	  - major number of a device with the affected filesystem
        QUOTA_NL_A_DEV_MINOR (u32)
	  - minor number of a device with the affected filesystem
Commit	Line	Data
9b6f151e	1	.. SPDX-License-Identifier: GPL-2.0
8e893469	2
9b6f151e	3	===============
8e893469 JK	4	Quota subsystem
	5	===============
	6
	7	Quota subsystem allows system administrator to set limits on used space and
866c3663 JK	8	number of used inodes (inode is a filesystem structure which is associated with
	9	each file or directory) for users and/or groups. For both used space and number
	10	of used inodes there are actually two limits. The first one is called softlimit
9332ef9d	11	and the second one hardlimit. A user can never exceed a hardlimit for any
866c3663 JK	12	resource (unless he has CAP_SYS_RESOURCE capability). User is allowed to exceed
	13	softlimit but only for limited period of time. This period is called "grace
	14	period" or "grace time". When grace time is over, user is not able to allocate
	15	more space/inodes until he frees enough of them to get below softlimit.
8e893469 JK	16
	17	Quota limits (and amount of grace time) are set independently for each
	18	filesystem.
	19
	20	For more details about quota design, see the documentation in quota-tools package
476fdf14	21	(https://sourceforge.net/projects/linuxquota).
8e893469 JK	22
	23	Quota netlink interface
	24	=======================
	25	When user exceeds a softlimit, runs out of grace time or reaches hardlimit,
	26	quota subsystem traditionally printed a message to the controlling terminal of
	27	the process which caused the excess. This method has the disadvantage that
	28	when user is using a graphical desktop he usually cannot see the message.
	29	Thus quota netlink interface has been designed to pass information about
	30	the above events to userspace. There they can be captured by an application
	31	and processed accordingly.
	32
	33	The interface uses generic netlink framework (see
476fdf14 JK	34	https://lwn.net/Articles/208755/ and http://www.infradead.org/~tgr/libnl/ for
	35	more details about this layer). The name of the quota generic netlink interface
	36	is "VFS_DQUOT". Definitions of constants below are in <linux/quota.h>. Since
	37	the quota netlink protocol is not namespace aware, quota netlink messages are
	38	sent only in initial network namespace.
18e25fa4 JK	39
18e25fa4 JK	40	Currently, the interface supports only one message type QUOTA_NL_C_WARNING.
8e893469 JK	41	This command is used to send a notification about any of the above mentioned
	42	events. Each message has six attributes. These are (type of the argument is
	43	in parentheses):
9b6f151e	44
8e893469 JK	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:
9b6f151e MCC	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
866c3663 JK	70	- four warnings are also defined for the event when user stops
866c3663 JK	71	exceeding some limit:
9b6f151e MCC	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
8e893469 JK	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