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