man/systemd-tmpfiles.xml

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