-<?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+
- This file is part of systemd.
-
- Copyright 2010 Brandon Philips
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
+ Copyright © 2010 Brandon Philips
-->
<refentry id="tmpfiles.d">
<refentryinfo>
<title>tmpfiles.d</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Documentation</contrib>
- <firstname>Brandon</firstname>
- <surname>Philips</surname>
- <email>brandon@ifup.org</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
</refnamediv>
<refsynopsisdiv>
- <para><filename>/etc/tmpfiles.d/*.conf</filename></para>
- <para><filename>/run/tmpfiles.d/*.conf</filename></para>
- <para><filename>/usr/lib/tmpfiles.d/*.conf</filename></para>
+ <para><literallayout><filename>/etc/tmpfiles.d/*.conf</filename>
+<filename>/run/tmpfiles.d/*.conf</filename>
+<filename>/usr/lib/tmpfiles.d/*.conf</filename>
+ </literallayout></para>
+
+ <para><literallayout><filename>~/.config/user-tmpfiles.d/*.conf</filename>
+<filename>$XDG_RUNTIME_DIR/user-tmpfiles.d/*.conf</filename>
+<filename>~/.local/share/user-tmpfiles.d/*.conf</filename>
+<filename>…</filename>
+<filename>/usr/share/user-tmpfiles.d/*.conf</filename>
+ </literallayout></para>
</refsynopsisdiv>
<refsect1>
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>Volatile and temporary files and directories are those located in <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>System daemons frequently require private runtime
directories below <filename>/run</filename> to place communication
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
<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>
<variablelist>
<varlistentry>
<term><varname>f</varname></term>
- <listitem><para>Create a file if it does not exist yet. If
- the argument parameter is given, it will be written to the
- file. Does not follow symlinks.</para></listitem>
+ <listitem><para>Create a file if it does not exist yet. If the argument parameter is given and the file did
+ not exist yet, it will be written to the file. Does not follow symlinks.</para></listitem>
</varlistentry>
<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>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>.</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>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>. </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>
The second line in contrast to the first one would break a
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>,
+ <varname>p</varname>, <varname>L</varname>, <varname>c</varname>/<varname>b</varname> and <varname>C</varname>)
+ leading directories are implicitly created if needed, owned by root with an access mode of 0755. In order to
+ create them with different modes or ownership make sure to add appropriate <varname>d</varname> lines.</para>
</refsect2>
<refsect2>
<title>Path</title>
<para>The file system path specification supports simple
- specifier expansion. The following expansions are
- understood:</para>
-
- <table>
- <title>Specifiers available</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname="spec" />
- <colspec colname="mean" />
- <colspec colname="detail" />
- <thead>
- <row>
- <entry>Specifier</entry>
- <entry>Meaning</entry>
- <entry>Details</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>%m</literal></entry>
- <entry>Machine ID</entry>
- <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
- </row>
- <row>
- <entry><literal>%b</literal></entry>
- <entry>Boot ID</entry>
- <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
- </row>
- <row>
- <entry><literal>%H</literal></entry>
- <entry>Host name</entry>
- <entry>The hostname of the running system.</entry>
- </row>
- <row>
- <entry><literal>%v</literal></entry>
- <entry>Kernel release</entry>
- <entry>Identical to <command>uname -r</command> output.</entry>
- </row>
- <row>
- <entry><literal>%%</literal></entry>
- <entry>Escaped %</entry>
- <entry>Single percent sign.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ specifier expansion, see below. The path (after expansion) must be
+ absolute.</para>
</refsect2>
<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>
+ <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 user/group ID 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>
<literal>~</literal>, the clean-up is only applied to files and
directories one level inside the directory specified, but not
the files and directories immediately inside it.</para>
+
+ <para>The age of a file system entry is determined from its last
+ modification timestamp (mtime), its last access timestamp (atime),
+ and (except for directories) its last status change timestamp
+ (ctime). Any of these three (or two) values will prevent cleanup
+ if it is more recent than the current time minus the age
+ field.</para>
</refsect2>
<refsect2>
<title>Argument</title>
- <para>For <varname>L</varname> lines determines the destination
- path of the symlink. For <varname>c</varname> and
- <varname>b</varname>, determines the major/minor of the device
- node, with major and minor formatted as integers, separated by
- <literal>:</literal>, e.g. <literal>1:3</literal>. For
- <varname>f</varname>, <varname>F</varname>, and
- <varname>w</varname>, the argument may be used to specify a short string that
- is written to the file, suffixed by a newline. For
- <varname>C</varname>, specifies the source file or
- directory. For <varname>t</varname> and <varname>T</varname>,
- determines extended attributes to be set. For
- <varname>a</varname> and <varname>A</varname>, determines ACL
- attributes to be set. For <varname>h</varname> and
- <varname>H</varname>, determines the file attributes to
- set. Ignored for all other lines.</para>
+ <para>For <varname>L</varname> lines determines the destination path of the symlink. For <varname>c</varname> and
+ <varname>b</varname>, determines the major/minor of the device node, with major and minor formatted as integers,
+ separated by <literal>:</literal>, e.g. <literal>1:3</literal>. For <varname>f</varname>, <varname>F</varname>,
+ and <varname>w</varname>, the argument may be used to specify a short string that is written to the file,
+ suffixed by a newline. For <varname>C</varname>, specifies the source file or directory. For <varname>t</varname>
+ and <varname>T</varname>, determines extended attributes to be set. For <varname>a</varname> and
+ <varname>A</varname>, determines ACL attributes to be set. For <varname>h</varname> and <varname>H</varname>,
+ determines the file attributes to set. Ignored for all other lines.</para>
+
+ <para>This field can contain specifiers, see below.</para>
</refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Specifiers</title>
+ <para>Specifiers can be used in the "path" and "argument" fields.
+ An unknown or unresolvable specifier is treated as invalid configuration.
+ The following expansions are understood:</para>
+ <table>
+ <title>Specifiers available</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <colspec colname="spec" />
+ <colspec colname="mean" />
+ <colspec colname="detail" />
+ <thead>
+ <row>
+ <entry>Specifier</entry>
+ <entry>Meaning</entry>
+ <entry>Details</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>%b</literal></entry>
+ <entry>Boot ID</entry>
+ <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
+ </row>
+ <row>
+ <entry><literal>%C</literal></entry>
+ <entry>System or user cache directory</entry>
+ <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CACHE_HOME</varname>, and <filename>/var/cache</filename> otherwise.</entry>
+ </row>
+ <row>
+ <entry><literal>%h</literal></entry>
+ <entry>User home directory</entry>
+ <entry>This is the home directory of the user running the command. In case of the system instance this resolves to <literal>/root</literal>.</entry>
+ </row>
+ <row>
+ <entry><literal>%H</literal></entry>
+ <entry>Host name</entry>
+ <entry>The hostname of the running system.</entry>
+ </row>
+ <row>
+ <entry><literal>%L</literal></entry>
+ <entry>System or user log directory</entry>
+ <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname> with <filename noindex='true'>/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
+ </row>
+ <row>
+ <entry><literal>%m</literal></entry>
+ <entry>Machine ID</entry>
+ <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+ </row>
+ <row>
+ <entry><literal>%S</literal></entry>
+ <entry>System or user state directory</entry>
+ <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname>, and <filename>/var/lib</filename> otherwise.</entry>
+ </row>
+ <row>
+ <entry><literal>%t</literal></entry>
+ <entry>System or user runtime directory</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>
+ <entry>Directory for temporary files</entry>
+ <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>
+ </row>
+ <row>
+ <entry><literal>%U</literal></entry>
+ <entry>User UID</entry>
+ <entry>This is the numeric UID of the user running the command. In case of the system instance this resolves to <constant>0</constant>.</entry>
+ </row>
+ <row>
+ <entry><literal>%v</literal></entry>
+ <entry>Kernel release</entry>
+ <entry>Identical to <command>uname -r</command> output.</entry>
+ </row>
+ <row>
+ <entry><literal>%V</literal></entry>
+ <entry>Directory for larger and persistent temporary files</entry>
+ <entry>This is either <filename>/var/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
+ </row>
+ <row>
+ <entry><literal>%%</literal></entry>
+ <entry>Escaped <literal>%</literal></entry>
+ <entry>Single percent sign.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</refsect1>
<refsect1>
</programlisting>
<para>Contents of <filename>/run/screens</filename> and /run/uscreens will
- cleaned up after 10 and 10½ days, respectively.</para>
+ be cleaned up after 10 and 10½ days, respectively.</para>
</example>
<example>
projects / thirdparty / systemd.git / blobdiff