]> git.ipfire.org Git - thirdparty/systemd.git/blobdiff - man/tmpfiles.d.xml
doc: document the `architecture` setting
[thirdparty/systemd.git] / man / tmpfiles.d.xml
index 957475d2bd44fa4dbc740e66b0752429ec4c9cf8..e2e2eac228d01fd2927025de575c1b77ff9f9d29 100644 (file)
@@ -1,37 +1,15 @@
 <?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">
 <!--
-  This file is part of systemd.
+  SPDX-License-Identifier: LGPL-2.1+
 
-  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>
@@ -76,7 +62,7 @@
   </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>
+    /run/user   0755 root root 10d -
+    /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, 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>
           <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 time argument is specified.</para></listitem>
+          to time based cleanup if the age argument is specified.</para></listitem>
         </varlistentry>
 
         <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.</para></listitem>
+          <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>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. Note that permissions and ownership on symlinks
-          are ignored.</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>
 
       <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>
+
+      <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>
       <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 --user 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>%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>
     <example>
       <title>Create directories with specific mode and ownership</title>
       <para>
-      <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <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
@@ -635,7 +689,7 @@ 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>
+      be cleaned up after 10 and 10½ days, respectively.</para>
     </example>
 
     <example>
@@ -644,7 +698,7 @@ d /run/uscreens 0755 root screen 10d12h
 t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar"
       </programlisting>
 
-      <para>The direcory will be owned by root and have default mode. It's contents are
+      <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>
@@ -652,7 +706,7 @@ t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar"
     <example>
       <title>Create a directory and prevent its contents from cleanup</title>
       <para>
-      <citerefentry><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <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>
@@ -673,13 +727,25 @@ d /var/tmp/abrt 0755 abrt abrt -
 r! /var/cache/dnf/*/*/download_lock.pid
 r! /var/cache/dnf/*/*/metadata_lock.pid
 r! /var/lib/dnf/rpmdb_lock.pid
-e  /var/chache/dnf/ - - - 30d
+e  /var/cache/dnf/ - - - 30d
 </programlisting>
 
      <para>The lock files will be removed during boot. Any files and directories in
-     <filename>/var/chache/dnf/</filename> will be removed after they have not been
+     <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>
 
   <refsect1>