summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2015-10-21 19:46:23 +0200
committerLennart Poettering <lennart@poettering.net>2015-10-22 01:59:25 +0200
commit5fb13eb51bf641a3434828947e137e1a5f2d7eb2 (patch)
tree891b21eb9e2bd536843d0f9cb8bcfe023188e70f /man
parent8c9cfc28448bf671807e7d96b580221edebd71da (diff)
tmpfiles: introduce "q" and "Q" for creating quota-enabled btrfs subvolumes
This allows us to set up the quota group hierarchy in a reasonable way on btrfs file systems.
Diffstat (limited to 'man')
-rw-r--r--man/tmpfiles.d.xml92
1 files changed, 81 insertions, 11 deletions
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index 3cee0fff59..662ec4518b 100644
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -1,5 +1,4 @@
-<?xml version="1.0"?>
-<!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
@@ -172,7 +171,77 @@
<listitem><para>Create a subvolume if the path does not
exist yet and the file system supports this
(btrfs). Otherwise create a normal directory, in the same
- way as <varname>d</varname>.</para></listitem>
+ way as <varname>d</varname>. A subvolume created with this
+ line type is not assigned to any higher-level quota
+ group. For that use <varname>q</varname> or
+ <varname>Q</varname> which allow creating simple quota group
+ hierarchies, see below.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>q</varname></term>
+ <listitem><para>Similar to <varname>v</varname>, however
+ makes sure that the subvolume will be assigned to the same
+ higher-level quota groups as the subvolume it has been
+ created in. This ensures that higher-level limits and
+ accounting applied to the parent subvolume also include the
+ specified subvolume. On non-btrfs file systems, this line
+ type is identical to <varname>d</varname>. If the subvolume
+ already exists and is already assigned to one or more higher
+ level quota groups no change to the quota hierarchy is
+ made. Also see <varname>Q</varname> below. See <citerefentry
+ project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ for details about the btrfs quota group
+ concept.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Q</varname></term>
+ <listitem><para>Similar to <varname>q</varname>, however
+ instead of copying the higher-level quota group assignments
+ from the parent as-is, the lowest quota group of the parent
+ subvolume is determined that is not the leaf quota
+ group. Then, an "intermediary" quota group is inserted that
+ is one level below this level, and shares the same ID part
+ as the specified subvolume. If no higher-level quota group
+ exists for the parent subvolume, a new quota group at level
+ 255 sharing the same ID as the specified subvolume is
+ inserted instead. This new intermediary quota group is then
+ assigned to the parent subvolume's higher-level quota
+ groups, and the specified subvolume's leaf quota group is
+ assigned to it.</para>
+
+ <para>Effectively, this has a similar effect as
+ <varname>q</varname>, however introduces a new higher-level
+ quota group for the specified subvolume that may be used to
+ enforce limits and accounting to the specified subvolume and
+ children subvolume created within it. Thus, by creating
+ subvolumes only via <varname>q</varname> and
+ <varname>Q</varname> a concept of "subtree quotas" is
+ implemented. Each subvolume for which <varname>Q</varname>
+ is set will get a "subtree" quota group created, and all
+ child subvolumes created within it will be assigned to
+ it. Each subvolume for which <varname>q</varname> is set
+ will not get such a "subtree" quota group, but it is ensured
+ that they are added to the same "subtree" quota group as their
+ immediate parents.</para>
+
+ <para>It is recommended to use
+ <varname>Q</varname> for subvolumes that typically contain
+ further subvolumes, and where it is desirable to have
+ accounting and quota limits on all child subvolumes
+ together. Examples for <varname>Q</varname> are typically
+ <filename>/home</filename> or
+ <filename>/var/lib/machines</filename>. In contrast,
+ <varname>q</varname> should be used for subvolumes that
+ either usually do not include further subvolumes or where no
+ accounting and quota limits are needed that apply to all
+ child subvolumes together. Examples for <varname>q</varname>
+ are typically <filename>/var</filename> or
+ <filename>/var/tmp</filename>. As with <varname>Q</varname>,
+ <varname>q</varname> has no effect on the quota group
+ hierarchy if the subvolume exists and already has at least
+ one higher-level quota group assigned.</para></listitem>
</varlistentry>
<varlistentry>
@@ -504,13 +573,12 @@
<para>When the age is set to zero, the files are cleaned
unconditionally.</para>
- <para>The age field only applies to lines
- starting with <varname>d</varname>,
- <varname>D</varname>, <varname>v</varname>,
- <varname>C</varname>, <varname>x</varname> and
- <varname>X</varname>. If omitted or set to
- <literal>-</literal>, no automatic clean-up is
- done.</para>
+ <para>The age field only applies to lines starting with
+ <varname>d</varname>, <varname>D</varname>,
+ <varname>v</varname>, <varname>q</varname>,
+ <varname>Q</varname>, <varname>C</varname>, <varname>x</varname>
+ and <varname>X</varname>. If omitted or set to
+ <literal>-</literal>, no automatic clean-up is done.</para>
<para>If the age field starts with a tilde character
<literal>~</literal>, the clean-up is only applied to files and
@@ -572,7 +640,9 @@ x /var/tmp/abrt/*</programlisting>
<citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>btrfs-subvolume</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>