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