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