<?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>
<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>
<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.
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>