<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!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
</refsect1>
<refsect1>
- <title>Configuration Format</title>
+ <title>Configuration Directories and Precedence</title>
<para>Each configuration file shall be named in the style of
<filename><replaceable>package</replaceable>.conf</filename> or
to <filename>/dev/null</filename> in
<filename>/etc/tmpfiles.d/</filename> bearing the same filename.
</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Configuration File Format</title>
<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>
+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>
<varlistentry>
<term><varname>d</varname></term>
- <listitem><para>Create a directory if it does not exist yet.
- </para></listitem>
+ <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>
</varlistentry>
<varlistentry>
<term><varname>D</varname></term>
- <listitem><para>Create or empty a directory.</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>
</varlistentry>
<varlistentry>
<term><varname>v</varname></term>
<listitem><para>Create a subvolume if the path does not
- exist yet and the file system supports this
- (btrfs). 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>
+ 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>
</varlistentry>
<varlistentry>
<term><varname>L</varname></term>
<term><varname>L+</varname></term>
<listitem><para>Create a symlink if it does not exist
- yet. If suffixed with <varname>+</varname> and a file
- already exists where the symlink is to be created, it will
- be removed and be replaced by the symlink. If the argument
- is omitted, symlinks to files with the same name residing in
- the directory <filename>/usr/share/factory/</filename> are
- created.</para></listitem>
+ yet. If suffixed with <varname>+</varname> and a file or
+ directory already exists where the symlink is to be created,
+ it will be removed and be replaced by the symlink. If the
+ argument is omitted, symlinks to files with the same name
+ residing in the directory
+ <filename>/usr/share/factory/</filename> are created. Note
+ that permissions and ownership on symlinks are ignored.
+ </para></listitem>
</varlistentry>
<varlistentry>
<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 explictly specified. The mask will be added if not
+ 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
<para>For example:
<programlisting># Make sure these are created by default so that nobody else can
- d /tmp/.X11-unix 1777 root root 10d
+d /tmp/.X11-unix 1777 root root 10d
- # Unlink the X11 lock files
- r! /tmp/.X[0-9]*-lock</programlisting>
+# Unlink the X11 lock files
+r! /tmp/.X[0-9]*-lock</programlisting>
The second line in contrast to the first one would break a
running system, and will only be executed with
<option>--boot</option>.</para>
<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>
unconditionally.</para>
<para>The age field only applies to lines starting with
- <varname>d</varname>, <varname>D</varname>,
+ <varname>d</varname>, <varname>D</varname>, <varname>e</varname>,
<varname>v</varname>, <varname>q</varname>,
<varname>Q</varname>, <varname>C</varname>, <varname>x</varname>
and <varname>X</varname>. If omitted or set to
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>%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>
</refsect1>
<refsect1>
- <title>Example</title>
+ <title>Examples</title>
<example>
- <title>/etc/tmpfiles.d/screen.conf example</title>
- <para><command>screen</command> needs two directories created at
- boot with specific modes and ownership.</para>
+ <title>Create directories with specific mode and ownership</title>
+ <para>
+ <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ needs two directories created at boot with specific modes and ownership:</para>
+
+ <programlisting># /usr/lib/tmpfiles.d/screen.conf
+d /run/screens 1777 root screen 10d
+d /run/uscreens 0755 root screen 10d12h
+</programlisting>
+
+ <para>Contents of <filename>/run/screens</filename> and /run/uscreens will
+ cleaned up after 10 and 10½ days, respectively.</para>
+ </example>
- <programlisting>d /run/screens 1777 root root 10d
-d /run/uscreens 0755 root root 10d12h
-t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting>
+ <example>
+ <title>Create a directory with a SMACK attribute</title>
+ <programlisting>D /run/cups - - - -
+t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar"
+ </programlisting>
+
+ <para>The directory will be owned by root and have default mode. Its contents are
+ not subject to time based cleanup, but will be obliterated when
+ <command>systemd-tmpfiles --remove</command> runs.</para>
</example>
+
<example>
- <title>/etc/tmpfiles.d/abrt.conf example</title>
- <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para>
+ <title>Create a directory and prevent its contents from cleanup</title>
+ <para>
+ <citerefentry project='die-net'><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ needs a directory created at boot with specific mode and ownership and its content
+ should be preserved from the automatic cleanup applied to the contents of
+ <filename>/var/tmp</filename>:</para>
+
+ <programlisting># /usr/lib/tmpfiles.d/tmp.conf
+d /var/tmp 1777 root root 30d
+</programlisting>
+
+ <programlisting># /usr/lib/tmpfiles.d/abrt.conf
+d /var/tmp/abrt 0755 abrt abrt -
+</programlisting>
+ </example>
- <programlisting>d /var/tmp/abrt 0755 abrt abrt
-x /var/tmp/abrt/*</programlisting>
+ <example>
+ <title>Apply clean up during boot and based on time</title>
+
+ <programlisting># /usr/lib/tmpfiles.d/dnf.conf
+r! /var/cache/dnf/*/*/download_lock.pid
+r! /var/cache/dnf/*/*/metadata_lock.pid
+r! /var/lib/dnf/rpmdb_lock.pid
+e /var/cache/dnf/ - - - 30d
+</programlisting>
+
+ <para>The lock files will be removed during boot. Any files and directories in
+ <filename>/var/cache/dnf/</filename> will be removed after they have not been
+ accessed in 30 days.</para>
+ </example>
+
+ <example>
+ <title>Empty the contents of a cache directory on boot</title>
+
+ <programlisting># /usr/lib/tmpfiles.d/krb5rcache.conf
+e! /var/cache/krb5rcache - - - 0
+</programlisting>
+
+ <para>Any files and subdirectories in <filename>/var/cache/krb5rcache/</filename>
+ will be removed on boot. The directory will not be created.
+ </para>
</example>
</refsect1>
projects / thirdparty / systemd.git / blobdiff