man/systemd-tmpfiles.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2010 Lennart Poettering
   9 -->
  10
  11 <refentry id="systemd-tmpfiles"
  12     xmlns:xi="http://www.w3.org/2001/XInclude">
  13
  14   <refentryinfo>
  15     <title>systemd-tmpfiles</title>
  16     <productname>systemd</productname>
  17
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>Lennart</firstname>
  22         <surname>Poettering</surname>
  23         <email>lennart@poettering.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>systemd-tmpfiles</refentrytitle>
  30     <manvolnum>8</manvolnum>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname>systemd-tmpfiles</refname>
  35     <refname>systemd-tmpfiles-setup.service</refname>
  36     <refname>systemd-tmpfiles-setup-dev.service</refname>
  37     <refname>systemd-tmpfiles-clean.service</refname>
  38     <refname>systemd-tmpfiles-clean.timer</refname>
  39     <refpurpose>Creates, deletes and cleans up volatile
  40     and temporary files and directories</refpurpose>
  41   </refnamediv>
  42
  43   <refsynopsisdiv>
  44     <cmdsynopsis>
  45       <command>systemd-tmpfiles</command>
  46       <arg choice="opt" rep="repeat">OPTIONS</arg>
  47       <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg>
  48     </cmdsynopsis>
  49
  50     <para>System units:
  51 <literallayout><filename>systemd-tmpfiles-setup.service</filename>
  52 <filename>systemd-tmpfiles-setup-dev.service</filename>
  53 <filename>systemd-tmpfiles-clean.service</filename>
  54 <filename>systemd-tmpfiles-clean.timer</filename></literallayout></para>
  55
  56     <para>User units:
  57 <literallayout><filename>systemd-tmpfiles-setup.service</filename>
  58 <filename>systemd-tmpfiles-clean.service</filename>
  59 <filename>systemd-tmpfiles-clean.timer</filename></literallayout></para>
  60   </refsynopsisdiv>
  61
  62   <refsect1>
  63     <title>Description</title>
  64
  65     <para><command>systemd-tmpfiles</command> creates, deletes, and
  66     cleans up volatile and temporary files and directories, based on
  67     the configuration file format and location specified in
  68     <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  69     </para>
  70
  71     <para>If invoked with no arguments, it applies all directives from all configuration
  72     files. When invoked with <option>--replace=<replaceable>PATH</replaceable></option>,
  73     arguments specified on the command line are used instead of the configuration file
  74     <replaceable>PATH</replaceable>. Otherwise, if one or more absolute filenames are
  75     passed on the command line, only the directives in these files are applied. If
  76     <literal>-</literal> is specified instead of a filename, directives are read from
  77     standard input. If only the basename of a configuration file is specified, all
  78     configuration directories as specified in
  79     <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  80     are searched for a matching file and the file found that has the highest priority is
  81     executed.</para>
  82   </refsect1>
  83
  84   <refsect1>
  85     <title>Options</title>
  86
  87     <para>The following options are understood:</para>
  88
  89     <variablelist>
  90       <varlistentry>
  91         <term><option>--create</option></term>
  92         <listitem><para>If this option is passed, all files and
  93         directories marked with
  94         <varname>f</varname>,
  95         <varname>F</varname>,
  96         <varname>w</varname>,
  97         <varname>d</varname>,
  98         <varname>D</varname>,
  99         <varname>v</varname>,
 100         <varname>p</varname>,
 101         <varname>L</varname>,
 102         <varname>c</varname>,
 103         <varname>b</varname>,
 104         <varname>m</varname>
 105         in the configuration files are created or written to. Files
 106         and directories marked with
 107         <varname>z</varname>,
 108         <varname>Z</varname>,
 109         <varname>t</varname>,
 110         <varname>T</varname>,
 111         <varname>a</varname>, and
 112         <varname>A</varname> have their ownership, access mode and
 113         security labels set.</para></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><option>--clean</option></term>
 118         <listitem><para>If this option is passed, all files and
 119         directories with an age parameter configured will be cleaned
 120         up.</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><option>--remove</option></term>
 125         <listitem><para>If this option is passed, the contents of
 126         directories marked with <varname>D</varname> or
 127         <varname>R</varname>, and files or directories themselves
 128         marked with <varname>r</varname> or <varname>R</varname> are
 129         removed.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><option>--user</option></term>
 134         <listitem><para>Execute "user" configuration, i.e. <filename>tmpfiles.d</filename>
 135         files in user configuration directories.</para></listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term><option>--boot</option></term>
 140         <listitem><para>Also execute lines with an exclamation mark.
 141         </para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><option>--prefix=<replaceable>path</replaceable></option></term>
 146         <listitem><para>Only apply rules with paths that start with
 147         the specified prefix. This option can be specified multiple
 148         times.</para></listitem>
 149       </varlistentry>
 150       <varlistentry>
 151         <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term>
 152         <listitem><para>Ignore rules with paths that start with the
 153         specified prefix. This option can be specified multiple
 154         times.</para></listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><option>--root=<replaceable>root</replaceable></option></term>
 159         <listitem><para>Takes a directory path as an argument. All paths will be prefixed with the given alternate
 160         <replaceable>root</replaceable> path, including config search paths.</para>
 161
 162         <para>Note that this option does not alter how the users and groups specified in the configuration files are
 163         resolved. With or without this option, users and groups are always resolved according to the host's user and
 164         group databases, any such databases stored under the specified root directories are not
 165         consulted.</para></listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><option>--replace=<replaceable>PATH</replaceable></option></term>
 170         <listitem><para>When this option is given, one ore more positional arguments
 171         must be specified. All configuration files found in the directories listed in
 172         <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 173         will be read, and the configuration given on the command line will be
 174         handled instead of and with the same priority as the configuration file
 175         <replaceable>PATH</replaceable>.</para>
 176
 177         <para>This option is intended to be used when package installation scripts
 178         are running and files belonging to that package are not yet available on
 179         disk, so their contents must be given on the command line, but the admin
 180         configuration might already exist and should be given higher priority.
 181         </para></listitem>
 182       </varlistentry>
 183
 184       <xi:include href="standard-options.xml" xpointer="cat-config" />
 185       <xi:include href="standard-options.xml" xpointer="no-pager" />
 186       <xi:include href="standard-options.xml" xpointer="help" />
 187       <xi:include href="standard-options.xml" xpointer="version" />
 188     </variablelist>
 189
 190     <para>It is possible to combine <option>--create</option>,
 191     <option>--clean</option>, and <option>--remove</option> in one
 192     invocation. For example, during boot the following command line is
 193     executed to ensure that all temporary and volatile directories are
 194     removed and created according to the configuration file:</para>
 195
 196     <programlisting>systemd-tmpfiles --remove --create</programlisting>
 197
 198   </refsect1>
 199
 200   <refsect1>
 201     <title>Unprivileged --cleanup operation</title>
 202
 203     <para><command>systemd-tmpfiles</command> tries to avoid changing
 204     the access and modification times on the directories it accesses,
 205     which requires <constant>CAP_FOWNER</constant> privileges. When
 206     running as non-root, directories which are checked for files to
 207     clean up will have their access time bumped, which might prevent
 208     their cleanup.
 209     </para>
 210   </refsect1>
 211
 212   <refsect1>
 213     <title>Exit status</title>
 214
 215     <para>On success, 0 is returned. If the configuration was syntactically invalid (syntax errors,
 216     missing arguments, …), so some lines had to be ignored, but no other errors occurred,
 217     <constant>65</constant> is returned (<constant>EX_DATAERR</constant> from
 218     <filename>/usr/include/sysexits.h</filename>). If the configuration was syntactically valid, but
 219     could not be executed (lack of permissions, creation of files in missing directories, invalid
 220     contents when writing to <filename>/sys/</filename> values, …), <constant>73</constant> is
 221     returned (<constant>EX_CANTCREAT</constant> from <filename>/usr/include/sysexits.h</filename>).
 222     Otherwise, <constant>1</constant> is returned (<constant>EXIT_FAILURE</constant> from
 223     <filename>/usr/include/stdlib.h</filename>).
 224     </para>
 225   </refsect1>
 226
 227   <refsect1>
 228     <title>See Also</title>
 229     <para>
 230       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 231       <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 232     </para>
 233   </refsect1>
 234
 235 </refentry>