<?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">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
<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 index='false'>…</filename>
<filename>/usr/share/user-tmpfiles.d/*.conf</filename>
</literallayout></para>
+
+ <programlisting>#Type Path Mode User Group Age Argument
+f /file/to/create mode user group - content
+f+ /file/to/create-or-truncate mode user group - content
+w /file/to/write-to - - - - content
+w+ /file/to/append-to - - - - content
+d /directory/to/create-and-cleanup mode user group cleanup-age -
+D /directory/to/create-and-remove mode user group cleanup-age -
+e /directory/to/cleanup mode user group cleanup-age -
+v /subvolume/to/create mode user group - -
+v /subvolume-or-directory/to/create mode user group - -
+Q /subvolume/to/create mode user group - -
+p /fifo/to/create mode user group - -
+p+ /fifo/to/[re]create mode user group - -
+L /symlink/to/create - - - - symlink/target/path
+L+ /symlink/to/[re]create - - - - symlink/target/path
+c /dev/char-device-to-create mode user group - -
+c+ /dev/char-device-to-[re]create mode user group - -
+b /dev/block-device-to-create mode user group - -
+b+ /dev/block-device-to-[re]create mode user group - -
+C /target/to/create - - - - /source/to/copy
+x /path-or-glob/to/ignore - - - - -
+X /path-or-glob/to/ignore/recursively - - - - -
+r /empty/dir/to/remove - - - - -
+R /dir/to/remove/recursively - - - - -
+z /path-or-glob/to/adjust/mode mode user group - MAC context
+Z /path-or-glob/to/adjust/mode/recursively mode user group - MAC context
+t /path-or-glob/to/set/xattrs - - - - xattrs
+T /path-or-glob/to/set/xattrs/recursively - - - - xattrs
+h /path-or-glob/to/set/attrs - - - - file attrs
+H /path-or-glob/to/set/attrs/recursively - - - - file attrs
+a /path-or-glob/to/set/acls - - - - POSIX ACLs
+a+ /path-or-glob/to/append/acls - - - - POSIX ACLs
+A /path-or-glob/to/set/acls/recursively - - - - POSIX ACLs
+A+ /path-or-glob/to/append/acls/recursively - - - - POSIX ACLs
+
+</programlisting>
</refsynopsisdiv>
<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>,
- <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>
<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>
<variablelist>
<varlistentry>
<term><varname>f</varname></term>
- <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>
- <term><varname>F</varname></term>
- <listitem><para>Create or truncate a file. If the argument
- parameter is given, it will be written to the file. Does not follow symlinks.</para>
- </listitem>
+ <term><varname>f+</varname></term>
+ <listitem><para><varname>f</varname> will 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.
+ <varname>f+</varname> will create or truncate the file. If the argument parameter is given, it will
+ be written to the file. Does not follow symlinks.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>w</varname></term>
- <listitem><para>Write the argument parameter to a file, if
- the file exists. Lines of this type accept shell-style
- globs in place of normal path names. The argument parameter
- will be written without a trailing newline. C-style
- backslash escapes are interpreted. Follows
- symlinks.</para></listitem>
+ <term><varname>w+</varname></term>
+ <listitem><para>Write the argument parameter to a file, if the file exists.
+ If suffixed with <varname>+</varname>, the line will be appended to the file.
+ If your configuration writes multiple lines to the same file, use <varname>w+</varname>.
+ Lines of this type accept shell-style globs in place of normal path names.
+ The argument parameter will be written without a trailing newline.
+ C-style backslash escapes are interpreted. Follows symlinks.</para></listitem>
</varlistentry>
<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>.</para>
+ <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
<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>
+ <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
<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>
+ subvolume already exists, regardless of whether the subvolume already belong to a quota group or not.
+ </para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>C</varname></term>
<listitem><para>Recursively copy a file or directory, if the
- destination files or directories do not exist yet. Note that
- this command will not descend into subdirectories if the
- destination directory already exists. Instead, the entire
- copy operation is skipped. If the argument is omitted, files
- from the source directory
+ destination files or directories do not exist yet or the
+ destination directory is empty. Note that this command will not
+ descend into subdirectories if the destination directory already
+ exists and is not empty. Instead, the entire copy operation is
+ skipped. If the argument is omitted, files from the source directory
<filename>/usr/share/factory/</filename> with the same name
are copied. Does not follow symlinks.</para></listitem>
</varlistentry>
<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>
<term><varname>t</varname></term>
- <listitem><para>Set extended attributes. Lines of this type
- accept shell-style globs in place of normal path names.
- This can be useful for setting SMACK labels. Does not follow
- symlinks.</para></listitem>
+ <listitem><para>Set extended attributes, see <citerefentry
+ project='man-pages'><refentrytitle>attr</refentrytitle>
+ <manvolnum>5</manvolnum></citerefentry> for details. The argument field should take one or more
+ assignment expressions in the form
+ <replaceable>namespace</replaceable>.<replaceable>attribute</replaceable>=<replaceable>value</replaceable>,
+ for examples see below. Lines of this type accept shell-style globs in place of normal path
+ names. This can be useful for setting SMACK labels. Does not follow symlinks.</para>
+
+ <para>Please note that extended attributes settable with this line type are a different concept
+ from the Linux file attributes settable with <varname>h</varname>/<varname>H</varname>, see
+ below.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>T</varname></term>
- <listitem><para>Recursively set extended attributes. Lines
- of this type accept shell-style globs in place of normal
- path names. This can be useful for setting SMACK
- labels. Does not follow symlinks. </para></listitem>
+ <listitem><para>Same as <varname>t</varname>, but operates recursively.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>h</varname></term>
- <listitem><para>Set file/directory attributes. Lines of this type
- accept shell-style globs in place of normal path names.</para>
-
- <para>The format of the argument field is
- <varname>[+-=][aAcCdDeijsStTu] </varname>. The prefix
- <varname>+</varname> (the default one) causes the
- attribute(s) to be added; <varname>-</varname> causes the
- attribute(s) to be removed; <varname>=</varname> causes the
- attributes to be set exactly as the following letters. The
- letters <literal>aAcCdDeijsStTu</literal> select the new
- attributes for the files, see
- <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle>
+ <listitem><para>Set Linux file/directory attributes. Lines of this type accept shell-style globs in
+ place of normal path names.</para>
+
+ <para>The format of the argument field is <varname>[+-=][aAcCdDeijPsStTu]</varname>. The prefix
+ <varname>+</varname> (the default one) causes the attribute(s) to be added; <varname>-</varname>
+ causes the attribute(s) to be removed; <varname>=</varname> causes the attributes to be set exactly
+ as the following letters. The letters <literal>aAcCdDeijPsStTu</literal> select the new attributes
+ for the files, see <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> for further information.
</para>
- <para>Passing only <varname>=</varname> as argument resets
- all the file attributes listed above. It has to be pointed
- out that the <varname>=</varname> prefix limits itself to
- the attributes corresponding to the letters listed here. All
- other attributes will be left untouched. Does not follow
- symlinks.</para>
- </listitem>
+
+ <para>Passing only <varname>=</varname> as argument resets all the file attributes listed above. It
+ has to be pointed out that the <varname>=</varname> prefix limits itself to the attributes
+ corresponding to the letters listed here. All other attributes will be left untouched. Does not
+ follow symlinks.</para>
+
+ <para>Please note that the Linux file attributes settable with this line type are a different
+ concept from the extended attributes settable with <varname>t</varname>/<varname>T</varname>,
+ see above.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>H</varname></term>
- <listitem><para>Recursively set file/directory attributes. Lines
- of this type accept shell-style globs in place of normal
- path names. Does not follow symlinks.
- </para></listitem>
+ <listitem><para>Sames as <varname>h</varname>, but operates recursively.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>a</varname></term>
<term><varname>a+</varname></term>
- <listitem><para>Set POSIX ACLs (access control lists). If
- suffixed with <varname>+</varname>, the specified entries will
- be added to the existing set.
- <command>systemd-tmpfiles</command> will automatically add
- the required base entries for user and group based on the
- access mode of the file, unless base entries already exist
- or are explicitly specified. The mask will be added if not
- specified explicitly or already present. Lines of this type
- accept shell-style globs in place of normal path names. This
- can be useful for allowing additional access to certain
- files. Does not follow symlinks.</para></listitem>
+ <listitem><para>Set POSIX ACLs (access control lists), see <citerefentry
+ project='man-pages'><refentrytitle>acl</refentrytitle>
+ <manvolnum>5</manvolnum></citerefentry>. If suffixed with <varname>+</varname>, the specified
+ entries will be added to the existing set. <command>systemd-tmpfiles</command> will automatically
+ add the required base entries for user and group based on the access mode of the file, unless base
+ entries already exist or are explicitly specified. The mask will be added if not specified
+ explicitly or already present. Lines of this type accept shell-style globs in place of normal path
+ names. This can be useful for allowing additional access to certain files. Does not follow
+ symlinks.</para></listitem>
</varlistentry>
<varlistentry>
</varlistentry>
</variablelist>
- <para>If the exclamation mark is used, this line is only safe of
+ <para>If the exclamation mark is used, this line is only safe to
execute during boot, and can break a running system. Lines
without the exclamation mark are presumed to be safe to execute
at any time, e.g. on package upgrades.
</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 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>
+ <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>
+
+ <para>This field should generally only reference system users/groups, i.e. users/groups that are
+ guaranteed to be resolvable during early boot. If this field references users/groups that only become
+ resolveable during later boot (i.e. after NIS, LDAP or a similar networked directory service become
+ available), execution of the operations declared by the line will likely fail. Also see <ulink
+ url="https://systemd.io/UIDS-GIDS.html#notes-on-resolvability-of-user-and-group-names">Notes on
+ Resolvability of User and Group Names</ulink> for more information on requirements on system user/group
+ definitions.</para>
</refsect2>
<refsect2>
(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>
+
+ <para>Note that while the aging algorithm is run a 'shared' BSD file lock (see <citerefentry
+ project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) is
+ taken on each directory the algorithm descends into (and each directory below that, and so on). If the
+ aging algorithm finds a lock is already taken on some directory, it (and everything below it) is
+ skipped. Applications may use this to temporarily exclude certain directory subtrees from the aging
+ algorithm: the applications can take a BSD file lock themselves, and as long as they keep it aging of
+ the directory and everything below it is disabled.</para>
</refsect2>
<refsect2>
<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>
+ <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname> with <filename index="false">/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
</row>
<row>
<entry><literal>%m</literal></entry>
</example>
</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>
projects / thirdparty / systemd.git / blobdiff