<?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+
<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>
<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>
<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>
+ <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
</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.
(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>
</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