diff options
Diffstat (limited to 'man/tmpfiles.d.xml')
| -rw-r--r-- | man/tmpfiles.d.xml | 300 |
1 files changed, 150 insertions, 150 deletions
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index e2e2eac228..5d393f3984 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1+ @@ -40,25 +40,33 @@ <refsect1> <title>Description</title> - <para><command>systemd-tmpfiles</command> uses the configuration - files from the above directories to describe the creation, - cleaning and removal of volatile and temporary files and - directories which usually reside in directories such as - <filename>/run</filename> or <filename>/tmp</filename>.</para> - - <para>Volatile and temporary files and directories are those - located in <filename>/run</filename> (and its alias - <filename>/var/run</filename>), <filename>/tmp</filename>, - <filename>/var/tmp</filename>, the API file systems such as - <filename>/sys</filename> or <filename>/proc</filename>, as well - as some other directories below <filename>/var</filename>.</para> - - <para>System daemons frequently require private runtime - directories below <filename>/run</filename> to place communication - sockets and similar in. For these, consider declaring them in - their unit files using <varname>RuntimeDirectory=</varname> (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details), if this is feasible.</para> + <para><filename>tmpfiles.d</filename> configuration files provide a generic mechanism to define the + <emphasis>creation</emphasis> of regular files, directories, pipes, and device nodes, adjustments to + their <emphasis>access mode, ownership, attributes, quota assignments, and contents</emphasis>, and + finally their time-based <emphasis>removal</emphasis>. It is mostly commonly used for volatile and + temporary files and directories (such as those located under <filename>/run</filename>, + <filename>/tmp</filename>, <filename>/var/tmp</filename>, the API file systems such as + <filename>/sys</filename> or <filename>/proc</filename>, as well as some other directories below + <filename>/var</filename>).</para> + + <para><command>systemd-tmpfiles</command> uses this configuration to create volatile files and + directories during boot and to do periodic cleanup afterwards. See + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + the description of <filename>systemd-tmpfiles-setup.service</filename>, + <filename>systemd-tmpfiles-cleanup.service</filename>, and associated units.</para> + + <para>System daemons frequently require private runtime directories below <filename>/run</filename> to + store communication sockets and similar. For these, is is better to use + <varname>RuntimeDirectory=</varname> in their unit files (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details), if the flexibility provided by <filename>tmpfiles.d</filename> is not required. The advantages + are that the configuration required by the unit is centralized in one place, and that the lifetime of the + directory is tied to the lifetime of the service itself. Similarly, <varname>StateDirectory=</varname>, + <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and + <varname>ConfigurationDirectory=</varname> should be used to create directories under + <filename>/var/lib/</filename>, <filename>/var/cache/</filename>, <filename>/var/log/</filename>, and + <filename>/etc/</filename>. <filename>tmpfiles.d</filename> should be used for files whose lifetime is + independent of any service or requires more complicated configuration.</para> </refsect1> <refsect1> @@ -70,28 +78,20 @@ The second variant should be used when it is desirable to make it easy to override just this part of configuration.</para> - <para>Files in <filename>/etc/tmpfiles.d</filename> override files - with the same name in <filename>/usr/lib/tmpfiles.d</filename> and - <filename>/run/tmpfiles.d</filename>. Files in - <filename>/run/tmpfiles.d</filename> override files with the same - name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should - install their configuration files in - <filename>/usr/lib/tmpfiles.d</filename>. Files in - <filename>/etc/tmpfiles.d</filename> are reserved for the local - administrator, who may use this logic to override the - configuration files installed by vendor packages. All - configuration files are sorted by their filename in lexicographic - order, regardless of which of the directories they reside in. If - multiple files specify the same path, the entry in the file with - the lexicographically earliest name will be applied. All other - conflicting entries will be logged as errors. When two lines are - prefix and suffix of each other, then the prefix is always - processed first, the suffix later. Lines that take globs are - applied after those accepting no globs. If multiple operations - shall be applied on the same file, (such as ACL, xattr, file - attribute adjustments), these are always done in the same fixed - order. Otherwise, the files/directories are processed in the order - they are listed.</para> + <para>Files in <filename>/etc/tmpfiles.d</filename> override files with the same name in + <filename>/usr/lib/tmpfiles.d</filename> and <filename>/run/tmpfiles.d</filename>. Files in + <filename>/run/tmpfiles.d</filename> override files with the same name in + <filename>/usr/lib/tmpfiles.d</filename>. Packages should install their configuration files in + <filename>/usr/lib/tmpfiles.d</filename>. Files in <filename>/etc/tmpfiles.d</filename> are reserved for the local + administrator, who may use this logic to override the configuration files installed by vendor packages. All + configuration files are sorted by their filename in lexicographic order, regardless of which of the directories + they reside in. If multiple files specify the same path, the entry in the file with the lexicographically earliest + name will be applied. All other conflicting entries will be logged as errors. When two lines are prefix path and + suffix path of each other, then the prefix line is always created first, the suffix later (and if removal applies + to the line, the order is reversed: the suffix is removed first, the prefix later). Lines that take globs are + applied after those accepting no globs. If multiple operations shall be applied on the same file (such as ACL, + xattr, file attribute adjustments), these are always done in the same fixed order. Except for those cases, the + files/directories are processed in the order they are listed.</para> <para>If the administrator wants to disable a configuration file supplied by the vendor, the recommended way is to place a symlink @@ -106,9 +106,9 @@ <para>The configuration format is one line per path containing type, path, mode, ownership, age, and argument fields:</para> - <programlisting>#Type Path Mode UID GID Age Argument -d /run/user 0755 root root 10d - -L /tmp/foobar - - - - /dev/null</programlisting> + <programlisting>#Type Path Mode User Group Age Argument +d /run/user 0755 root root 10d - +L /tmp/foobar - - - - /dev/null</programlisting> <para>Fields may be enclosed within quotes and contain C-style escapes.</para> @@ -116,7 +116,7 @@ L /tmp/foobar - - - - /dev/null</programlisting> <title>Type</title> <para>The type consists of a single letter and optionally an - exclamation mark.</para> + exclamation mark and/or minus sign.</para> <para>The following line types are understood:</para> @@ -146,107 +146,88 @@ L /tmp/foobar - - - - /dev/null</programlisting> <varlistentry> <term><varname>d</varname></term> - <listitem><para>Create a directory. The mode and ownership will be adjusted if - specified and the directory already exists. Contents of this directory are subject - to time based cleanup if the age argument is specified.</para></listitem> + <listitem><para>Create a directory. The mode and ownership will be adjusted if specified. Contents + of this directory are subject to time based cleanup if the age argument is specified. + </para></listitem> </varlistentry> <varlistentry> <term><varname>D</varname></term> - <listitem><para>Similar to <varname>d</varname>, but in addition the contents - of the directory will be removed when <option>--remove</option> is used. - </para></listitem> + <listitem><para>Similar to <varname>d</varname>, but in addition the contents of the directory will + be removed when <option>--remove</option> is used.</para></listitem> </varlistentry> <varlistentry> <term><varname>e</varname></term> - <listitem><para>Similar to <varname>d</varname>, but the directory will not be created if - it does not exist. Lines of this type accept shell-style globs in place of normal path - names. For this entry to be useful, at least one of the mode, uid, gid, or age arguments - must be specified, since otherwise this entry has no effect. If the age argument is - <literal>0</literal>, contents of the directory will be unconditionally deleted every time - <command>systemd-tmpfiles --clean</command> is run. This can be useful when combined with - <varname>!</varname>, see the examples.</para></listitem> + <listitem><para>Adjust the mode and ownership of existing directories and remove their contents + based on age. + Lines of this type accept shell-style globs in place of normal path names. Contents of the + directories are subject to time based cleanup if the age argument is specified. If the age argument + is <literal>0</literal>, contents will be unconditionally deleted every time + <command>systemd-tmpfiles --clean</command> is run.</para> + + <para>For this entry to be useful, at least one of the mode, user, group, or age arguments must be + specified, since otherwise this entry has no effect. As an exception, an entry with no effect may + be useful when combined with <varname>!</varname>, see the examples.</para></listitem> </varlistentry> <varlistentry> <term><varname>v</varname></term> - <listitem><para>Create a subvolume if the path does not - exist yet, the file system supports subvolumes (btrfs), and - the system itself is installed into a subvolume - (specifically: the root directory <filename>/</filename> is - itself a subvolume). Otherwise, create a normal directory, in - the same 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> + <listitem><para>Create a subvolume if the path does not exist yet, the file system supports + subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root + directory <filename>/</filename> is itself a subvolume). Otherwise, create a normal directory, in + the same way as <varname>d</varname>.</para> + + <para>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> + <listitem><para>Create a subvolume or directory the same as <varname>v</varname>, but assign the + subvolume to the same higher-level quota groups as the parent. 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>.</para> + + <para>If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the + subvolume is already attached to a quota group or not. 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> + <listitem><para>Create the subvolume or directory the same as <varname>v</varname>, but assign the + new subvolume to a new leaf quota group. Instead of copying the higher-level quota group + assignments from the parent as is done with <varname>q</varname>, 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>. </para> + + <para>As with <varname>q</varname>, <varname>Q</varname> has no effect on the quota group hierarchy if the + subvolume already exists, regardless of whether the subvolume already belong to a quota group or not. + </para></listitem> </varlistentry> <varlistentry> @@ -352,20 +333,17 @@ L /tmp/foobar - - - - /dev/null</programlisting> <varlistentry> <term><varname>z</varname></term> - <listitem><para>Adjust the access mode, group and user, and - restore the SELinux security context of a file or directory, - if it exists. Lines of this type accept shell-style globs in - place of normal path names. Does not follow symlinks.</para></listitem> + <listitem><para>Adjust the access mode, user and group ownership, and restore the SELinux security + context of a file or directory, if it exists. Lines of this type accept shell-style globs in place + of normal path names. Does not follow symlinks.</para></listitem> </varlistentry> <varlistentry> <term><varname>Z</varname></term> - <listitem><para>Recursively set the access mode, group and - user, and restore the SELinux security context of a file or - directory if it exists, as well as of its subdirectories and - the files contained therein (if applicable). Lines of this - type accept shell-style globs in place of normal path - names. Does not follow symlinks. </para></listitem> + <listitem><para>Recursively set the access mode, user and group ownership, and restore the SELinux + security context of a file or directory if it exists, as well as of its subdirectories and the + files contained therein (if applicable). Lines of this type accept shell-style globs in place of + normal path names. Does not follow symlinks.</para></listitem> </varlistentry> <varlistentry> @@ -460,6 +438,15 @@ r! /tmp/.X[0-9]*-lock</programlisting> running system, and will only be executed with <option>--boot</option>.</para> + <para>If the minus sign is used, this line failing to run + successfully during create (and only create) will not cause + the execution of <command>systemd-tmpfiles</command> to return + an error.</para> + + <para>For example: + <programlisting># Modify sysfs but don't fail if we are in a container with a read-only /proc +w- /proc/sys/vm/swappiness - - - - 10</programlisting></para> + <para>Note that for all line types that result in creation of any kind of file node (i.e. <varname>f</varname>/<varname>F</varname>, <varname>d</varname>/<varname>D</varname>/<varname>v</varname>/<varname>q</varname>/<varname>Q</varname>, @@ -503,18 +490,14 @@ r! /tmp/.X[0-9]*-lock</programlisting> </refsect2> <refsect2> - <title>UID, GID</title> - - <para>The user and group to use for this file or directory. This - may either be a numeric user/group ID or a user or group - name. If omitted or when set to <literal>-</literal>, the - default 0 (root) is used. For <varname>z</varname> and - <varname>Z</varname> lines, when omitted or when set to - <literal>-</literal>, the file ownership will not be - modified. These parameters are ignored for <varname>x</varname>, - <varname>r</varname>, <varname>R</varname>, - <varname>L</varname>, <varname>t</varname>, and - <varname>a</varname> lines.</para> + <title>User, Group</title> + + <para>The user and group to use for this file or directory. This may either be a numeric ID or a + user/group name. If omitted or when set to <literal>-</literal>, the user and group of the user who + invokes <command>systemd-tmpfiles</command> is used. For <varname>z</varname> and <varname>Z</varname> + lines, when omitted or when set to <literal>-</literal>, the file ownership will not be modified. These + parameters are ignored for <varname>x</varname>, <varname>r</varname>, <varname>R</varname>, + <varname>L</varname>, <varname>t</varname>, and <varname>a</varname> lines.</para> </refsect2> <refsect2> @@ -638,7 +621,7 @@ r! /tmp/.X[0-9]*-lock</programlisting> <row> <entry><literal>%t</literal></entry> <entry>System or user runtime directory</entry> - <entry>In --user mode, this is the same <varname>$XDG_RUNTIME_DIR</varname>, and <filename>/run</filename> otherwise.</entry> + <entry>In <option>--user</option> mode, this is the same <varname>$XDG_RUNTIME_DIR</varname>, and <filename>/run</filename> otherwise.</entry> </row> <row> <entry><literal>%T</literal></entry> @@ -646,6 +629,16 @@ r! /tmp/.X[0-9]*-lock</programlisting> <entry>This is either <filename>/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry> </row> <row> + <entry><literal>%g</literal></entry> + <entry>User group</entry> + <entry>This is the name of the group running the command. In case of the system instance this resolves to <literal>root</literal>.</entry> + </row> + <row> + <entry><literal>%G</literal></entry> + <entry>User GID</entry> + <entry>This is the numeric GID of the group running the command. In case of the system instance this resolves to <constant>0</constant>.</entry> + </row> + <row> <entry><literal>%u</literal></entry> <entry>User name</entry> <entry>This is the name of the user running the command. In case of the system instance this resolves to <literal>root</literal>.</entry> @@ -749,6 +742,13 @@ e! /var/cache/krb5rcache - - - 0 </refsect1> <refsect1> + <title><filename>/run/</filename> and <filename>/var/run/</filename></title> + <para><filename>/var/run/</filename> is a deprecated symlink to <filename>/run/</filename>, and + applications should use the latter. <command>systemd-tmpfiles</command> will warn if + <filename>/var/run/</filename> is used.</para> + </refsect1> + + <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |