Linux-ext4 Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] Ext4 Documentation: Add missing quota section.
@ 2019-09-08 17:51 Ayush Ranjan
  0 siblings, 0 replies; only message in thread
From: Ayush Ranjan @ 2019-09-08 17:51 UTC (permalink / raw)
  To: Theodore Ts'o, Andreas Dilger, Jonathan Corbet
  Cc: linux-ext4, linux-doc, linux-kernel

There were a few broken links for quota. The page
https://ext4.wiki.kernel.org/index.php/Quota was not migrated into
the current documentation sources. This patch adds the contents of that
missing page as a new section in the overview page. Also fixes those
broken links by replacing them with cross document links to this new
quota section.

Signed-off-by: Ayush Ranjan <ayushr2@illinois.edu>
---
 Documentation/filesystems/ext4/overview.rst |  1 +
 Documentation/filesystems/ext4/quota.rst    | 53 +++++++++++++++++++++
 Documentation/filesystems/ext4/super.rst    |  6 +--
 3 files changed, 57 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/filesystems/ext4/quota.rst

diff --git a/Documentation/filesystems/ext4/overview.rst b/Documentation/filesystems/ext4/overview.rst
index cbab18bab..f97ea68ea 100644
--- a/Documentation/filesystems/ext4/overview.rst
+++ b/Documentation/filesystems/ext4/overview.rst
@@ -24,3 +24,4 @@ order.
 .. include:: bigalloc.rst
 .. include:: inlinedata.rst
 .. include:: eainode.rst
+.. include:: quota.rst
diff --git a/Documentation/filesystems/ext4/quota.rst b/Documentation/filesystems/ext4/quota.rst
new file mode 100644
index 000000000..8964c26cb
--- /dev/null
+++ b/Documentation/filesystems/ext4/quota.rst
@@ -0,0 +1,53 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _quota:
+
+Quota Feature
+-------------
+
+The quota feature (``EXT4_FEATURE_RO_COMPAT_QUOTA``) causes the quota
+files (i.e., user.quota and group.quota which existed in the older quota
+design) to be hidden inodes, so they can not be corrupted by user space
+programs. Instead, these inodes are managed directly via e2fsprogs, and
+journaled quota will be automatically enabled by the kernel as soon as
+the file system is mounted. This way, it strongly reduces the
+possibility that the usage tracking performed by the file system will
+get out of sync.
+
+Kernel Support
+~~~~~~~~~~~~~~
+
+Support for the quota feature first appeared in the 3.6 upstream kernel
+version. There is a bug which will not be fixed until v3.8 which will
+cause ext4 to fail to mount a file system with quotas if the quota code
+is built as a module. So users who wish to experiment with this feature
+are strongly encouraged to build with the following configuration
+options:
+
+- ``CONFIG_QUOTA=y``
+- ``CONFIG_QUOTATREE=y``
+- ``CONFIG_QUOTACTL=y``
+
+E2fsprogs Support
+~~~~~~~~~~~~~~~~~
+
+Support for the quota feature first appeared in e2fsprogs 1.42, although
+it is not enabled by default. It must enabled via a compile-time
+configuration option, --enable-quota. There are bug fixes which have
+been applied in various 1.42.x maintenance branch releases, so users who
+wish to experiment with the quota feature are strongly encouraged
+upgrade to the latest e2fsprogs 1.42.x maintenance release. As of this
+writing the following bugs are still in e2fsprogs 1.42.7, which means
+use of file systems with the quota feature in production can not be
+recommended:
+
+- The e2fsck check of the on-disk quota inodes won't notice if there is
+  a missing uid record. (i.e., if some uid, say daemon owns a bunch of
+  files, but that uid record is not in the quota inode, e2fsck won't say
+  boo.)
+- If e2fsck *does* notice a discrepancy between the usage information
+  recorded in the hidden quota inodes, and the actual number of blocks
+  used by a particular user id or group id, it will overwrite the user
+  or group quota inode with all of the information it has.
+  Unfortunately, in the process it will zero out all of the current
+  quota limits set. This is unfortunate....
diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst
index 04ff079a2..2a9e1438f 100644
--- a/Documentation/filesystems/ext4/super.rst
+++ b/Documentation/filesystems/ext4/super.rst
@@ -404,11 +404,11 @@ The ext4 superblock is laid out as follows in
    * - 0x240
      - \_\_le32
      - s\_usr\_quota\_inum
-     - Inode number of user `quota <quota>`__ file.
+     - Inode number of user :ref:`quota <quota>` file.
    * - 0x244
      - \_\_le32
      - s\_grp\_quota\_inum
-     - Inode number of group `quota <quota>`__ file.
+     - Inode number of group :ref:`quota <quota>` file.
    * - 0x248
      - \_\_le32
      - s\_overhead\_blocks
@@ -678,7 +678,7 @@ the following:
    * - 0x80
      - This filesystem has a snapshot (RO\_COMPAT\_HAS\_SNAPSHOT).
    * - 0x100
-     - `Quota <Quota>`__ (RO\_COMPAT\_QUOTA).
+     - :ref:`Quota <quota>` (RO\_COMPAT\_QUOTA).
    * - 0x200
      - This filesystem supports “bigalloc”, which means that file extents are
        tracked in units of clusters (of blocks) instead of blocks
-- 
2.23.0


^ permalink raw reply	[flat|nested] only message in thread

only message in thread, back to index

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-09-08 17:51 [PATCH] Ext4 Documentation: Add missing quota section Ayush Ranjan

Linux-ext4 Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-ext4/0 linux-ext4/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-ext4 linux-ext4/ https://lore.kernel.org/linux-ext4 \
		linux-ext4@vger.kernel.org linux-ext4@archiver.kernel.org
	public-inbox-index linux-ext4


Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-ext4


AGPL code for this site: git clone https://public-inbox.org/ public-inbox