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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   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-early.service</refname>
  23     <refname>systemd-tmpfiles-setup-dev.service</refname>
  24     <refname>systemd-tmpfiles-clean.service</refname>
  25     <refname>systemd-tmpfiles-clean.timer</refname>
  26     <refpurpose>Create, delete, and clean up 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     <simplelist>
  38       <member><filename>systemd-tmpfiles-setup.service</filename></member>
  39       <member><filename>systemd-tmpfiles-setup-dev-early.service</filename></member>
  40       <member><filename>systemd-tmpfiles-setup-dev.service</filename></member>
  41       <member><filename>systemd-tmpfiles-clean.service</filename></member>
  42       <member><filename>systemd-tmpfiles-clean.timer</filename></member>
  43     </simplelist>
  44     </para>
  45
  46     <para>User units:
  47     <simplelist>
  48       <member><filename>systemd-tmpfiles-setup.service</filename></member>
  49       <member><filename>systemd-tmpfiles-clean.service</filename></member>
  50       <member><filename>systemd-tmpfiles-clean.timer</filename></member>
  51     </simplelist>
  52     </para>
  53   </refsynopsisdiv>
  54
  55   <refsect1>
  56     <title>Description</title>
  57
  58     <para><command>systemd-tmpfiles</command> creates, deletes, and cleans up volatile and temporary files
  59     and directories, using the configuration file format and location specified in
  60     <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It must
  61     be invoked with one or more commands <option>--create</option>, <option>--remove</option>, and
  62     <option>--clean</option>, to select the respective subset of operations.</para>
  63
  64     <para>If invoked with no arguments, directives from the configuration files found in the directories
  65     specified by
  66     <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When
  67     invoked with positional arguments, if option <option>--replace=<replaceable>PATH</replaceable></option>
  68     is specified, arguments specified on the command line are used instead of the configuration file
  69     <replaceable>PATH</replaceable>. Otherwise, just the configuration specified by the command line
  70     arguments is executed. If the string <literal>-</literal> is specified instead of a filename, the
  71     configuration is read from standard input. If the argument is a file name (without any slashes), all
  72     configuration directories are searched for a matching file and the file found that has the highest
  73     priority is executed. If the argument is a path, that file is used directly without searching the
  74     configuration directories for any other matching file.</para>
  75
  76     <para>System services (<filename>systemd-tmpfiles-setup.service</filename>,
  77     <filename>systemd-tmpfiles-setup-dev-early.service</filename>,
  78     <filename>systemd-tmpfiles-setup-dev.service</filename>,
  79     <filename>systemd-tmpfiles-clean.service</filename>) invoke <command>systemd-tmpfiles</command> to create
  80     system files and to perform system wide cleanup. Those services read administrator-controlled
  81     configuration files in <filename>tmpfiles.d/</filename> directories. User services
  82     (<filename>systemd-tmpfiles-setup.service</filename>,
  83     <filename>systemd-tmpfiles-clean.service</filename>) also invoke <command>systemd-tmpfiles</command>, but
  84     it reads a separate set of files, which includes user-controlled files under
  85     <filename>~/.config/user-tmpfiles.d/</filename> and <filename>~/.local/share/user-tmpfiles.d/</filename>,
  86     and administrator-controlled files under <filename>/usr/share/user-tmpfiles.d/</filename>. Users may use
  87     this to create and clean up files under their control, but the system instance performs global cleanup
  88     and is not influenced by user configuration. Note that this means a time-based cleanup configured in the
  89     system instance, such as the one typically configured for <filename>/tmp/</filename>, will thus also
  90     affect files created by the user instance if they are placed in <filename>/tmp/</filename>, even if the
  91     user instance's time-based cleanup is turned off.</para>
  92
  93     <para>To re-apply settings after configuration has been modified, simply restart
  94     <filename>systemd-tmpfiles-clean.service</filename>, which will apply any settings which can be safely
  95     executed at runtime. To debug <command>systemd-tmpfiles</command>, it may be useful to invoke it
  96     directly from the command line with increased log level (see <varname>$SYSTEMD_LOG_LEVEL</varname>
  97     below).</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Commands and options</title>
 102
 103     <para>The following commands are understood:</para>
 104
 105     <variablelist>
 106       <varlistentry>
 107         <term><option>--create</option></term>
 108         <listitem><para>If this command is passed, all files and
 109         directories marked with
 110         <varname>f</varname>,
 111         <varname>F</varname>,
 112         <varname>w</varname>,
 113         <varname>d</varname>,
 114         <varname>D</varname>,
 115         <varname>v</varname>,
 116         <varname>p</varname>,
 117         <varname>L</varname>,
 118         <varname>c</varname>,
 119         <varname>b</varname>,
 120         <varname>m</varname>
 121         in the configuration files are created or written to. Files
 122         and directories marked with
 123         <varname>z</varname>,
 124         <varname>Z</varname>,
 125         <varname>t</varname>,
 126         <varname>T</varname>,
 127         <varname>a</varname>, and
 128         <varname>A</varname> have their ownership, access mode and
 129         security labels set.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><option>--clean</option></term>
 134         <listitem><para>If this command is passed, all files and
 135         directories with an age parameter configured will be cleaned
 136         up.</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><option>--remove</option></term>
 141         <listitem><para>If this command is passed, the contents of
 142         directories marked with <varname>D</varname> or
 143         <varname>R</varname>, and files or directories themselves
 144         marked with <varname>r</varname> or <varname>R</varname> are
 145         removed unless an exclusive or shared BSD lock is taken on them (see <citerefentry
 146         project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>).
 147         </para></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>--purge</option></term>
 152         <listitem><para>If this option is passed, all files and directories created by a
 153         <filename>tmpfiles.d/</filename> entry will be deleted.</para>
 154
 155         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>--user</option></term>
 160         <listitem><para>Execute "user" configuration, i.e. <filename>tmpfiles.d</filename>
 161         files in user configuration directories.</para>
 162
 163         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><option>--boot</option></term>
 168         <listitem><para>Also execute lines with an exclamation mark. Lines that are not safe to be executed
 169         on a running system may be marked in this way. <command>systemd-tmpfiles</command> is executed in
 170         early boot with <option>--boot</option> specified and will execute those lines. When invoked again
 171         later, it should be called without <option>--boot</option>.</para>
 172
 173         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term><option>--graceful</option></term>
 178         <listitem><para>Ignore configuration lines pertaining to unknown users or groups. This option is
 179         intended to be used in early boot before all users or groups have been created.</para>
 180
 181         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 182       </varlistentry>
 183
 184       <varlistentry>
 185         <term><option>--dry-run</option></term>
 186         <listitem><para>Process the configuration and print what operations would be performed, but don't
 187         actually change anything in the file system.</para>
 188
 189         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 190       </varlistentry>
 191
 192       <varlistentry>
 193         <term><option>--prefix=<replaceable>path</replaceable></option></term>
 194         <listitem><para>Only apply rules with paths that start with
 195         the specified prefix. This option can be specified multiple
 196         times.</para>
 197
 198         <xi:include href="version-info.xml" xpointer="v212"/></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term>
 203         <listitem><para>Ignore rules with paths that start with the
 204         specified prefix. This option can be specified multiple
 205         times.</para>
 206
 207         <xi:include href="version-info.xml" xpointer="v207"/></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>-E</option></term>
 212         <listitem><para>A shortcut for <literal>--exclude-prefix=/dev --exclude-prefix=/proc
 213         --exclude-prefix=/run --exclude-prefix=/sys</literal>, i.e. exclude the hierarchies typically backed
 214         by virtual or memory file systems. This is useful in combination with <option>--root=</option>, if
 215         the specified directory tree contains an OS tree without these virtual/memory file systems mounted
 216         in, as it is typically not desirable to create any files and directories below these subdirectories
 217         if they are supposed to be overmounted during runtime.</para>
 218
 219         <xi:include href="version-info.xml" xpointer="v247"/></listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>--root=<replaceable>root</replaceable></option></term>
 224         <listitem><para>Takes a directory path as an argument. All paths will be prefixed with the given alternate
 225         <replaceable>root</replaceable> path, including config search paths.</para>
 226
 227         <para>When this option is used, the libc Name Service Switch (NSS) is bypassed for resolving users
 228         and groups. Instead the files <filename>/etc/passwd</filename> and <filename>/etc/group</filename>
 229         inside the alternate root are read directly. This means that users/groups not listed in these files
 230         will not be resolved, i.e. LDAP NIS and other complex databases are not considered.</para>
 231
 232         <para>Consider combining this with <option>-E</option> to ensure the invocation does not create files
 233         or directories below mount points in the OS image operated on that are typically overmounted during
 234         runtime.</para>
 235
 236         <xi:include href="version-info.xml" xpointer="v212"/></listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term><option>--image=<replaceable>image</replaceable></option></term>
 241
 242         <listitem><para>Takes a path to a disk image file or block device node. If specified all operations
 243         are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
 244         but operates on file systems stored in disk images or block devices. The disk image should either
 245         contain just a file system or a set of file systems within a GPT partition table, following the
 246         <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
 247         Specification</ulink>. For further information on supported disk images, see
 248         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 249         switch of the same name.</para>
 250
 251         <para>Implies <option>-E</option>.</para>
 252
 253         <xi:include href="version-info.xml" xpointer="v247"/></listitem>
 254       </varlistentry>
 255
 256       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
 257
 258       <varlistentry>
 259         <term><option>--replace=<replaceable>PATH</replaceable></option></term>
 260         <listitem><para>When this option is given, one or more positional arguments
 261         must be specified. All configuration files found in the directories listed in
 262         <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 263         will be read, and the configuration given on the command line will be
 264         handled instead of and with the same priority as the configuration file
 265         <replaceable>PATH</replaceable>.</para>
 266
 267         <para>This option is intended to be used when package installation scripts
 268         are running and files belonging to that package are not yet available on
 269         disk, so their contents must be given on the command line, but the admin
 270         configuration might already exist and should be given higher priority.
 271         </para>
 272
 273         <xi:include href="version-info.xml" xpointer="v238"/></listitem>
 274       </varlistentry>
 275
 276       <xi:include href="standard-options.xml" xpointer="cat-config" />
 277       <xi:include href="standard-options.xml" xpointer="tldr" />
 278       <xi:include href="standard-options.xml" xpointer="no-pager" />
 279       <xi:include href="standard-options.xml" xpointer="help" />
 280       <xi:include href="standard-options.xml" xpointer="version" />
 281     </variablelist>
 282
 283     <para>It is possible to combine <option>--create</option>, <option>--clean</option>, and <option>--remove</option>
 284     in one invocation (in which case removal and cleanup are executed before creation of new files). For example,
 285     during boot the following command line is executed to ensure that all temporary and volatile directories are
 286     removed and created according to the configuration file:</para>
 287
 288     <programlisting>systemd-tmpfiles --remove --create</programlisting>
 289   </refsect1>
 290
 291   <refsect1>
 292     <title>Credentials</title>
 293
 294     <para><command>systemd-tmpfiles</command> supports the service credentials logic as implemented by
 295     <varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>
 296     (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 297     details). The following credentials are used when passed in:</para>
 298
 299     <variablelist class='system-credentials'>
 300       <varlistentry>
 301         <term><varname>tmpfiles.extra</varname></term>
 302
 303         <listitem><para> The contents of this credential may contain additional lines to operate on. The
 304         credential contents should follow the same format as any other <filename>tmpfiles.d/</filename>
 305         drop-in configuration file. If this credential is passed it is processed after all of the drop-in
 306         files read from the file system. The lines in the credential can hence augment existing lines of the
 307         OS, but not override them.</para>
 308
 309         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 310       </varlistentry>
 311     </variablelist>
 312
 313     <para>Note that by default the <filename>systemd-tmpfiles-setup.service</filename> unit file (and related
 314     unit files) is set up to inherit the <literal>tmpfiles.extra</literal> credential from the service
 315     manager.</para>
 316   </refsect1>
 317
 318   <refsect1>
 319     <title>Environment</title>
 320
 321     <variablelist class='environment-variables'>
 322       <xi:include href="common-variables.xml" xpointer="log-level" />
 323       <xi:include href="common-variables.xml" xpointer="log-color" />
 324       <xi:include href="common-variables.xml" xpointer="log-time" />
 325       <xi:include href="common-variables.xml" xpointer="log-location" />
 326       <xi:include href="common-variables.xml" xpointer="log-target" />
 327       <xi:include href="common-variables.xml" xpointer="pager" />
 328       <xi:include href="common-variables.xml" xpointer="less" />
 329       <xi:include href="common-variables.xml" xpointer="lesscharset" />
 330       <xi:include href="common-variables.xml" xpointer="lesssecure" />
 331       <xi:include href="common-variables.xml" xpointer="colors" />
 332       <xi:include href="common-variables.xml" xpointer="urlify" />
 333     </variablelist>
 334   </refsect1>
 335
 336   <refsect1>
 337     <title>Unprivileged --cleanup operation</title>
 338
 339     <para><command>systemd-tmpfiles</command> tries to avoid changing
 340     the access and modification times on the directories it accesses,
 341     which requires <constant>CAP_FOWNER</constant> privileges. When
 342     running as non-root, directories which are checked for files to
 343     clean up will have their access time bumped, which might prevent
 344     their cleanup.
 345     </para>
 346   </refsect1>
 347
 348   <refsect1>
 349     <title>Exit status</title>
 350
 351     <para>On success, 0 is returned. If the configuration was syntactically invalid (syntax errors, missing
 352     arguments, …), so some lines had to be ignored, but no other errors occurred, <constant>65</constant> is
 353     returned (<constant>EX_DATAERR</constant> from <filename>/usr/include/sysexits.h</filename>). If the
 354     configuration was syntactically valid, but could not be executed (lack of permissions, creation of files
 355     in missing directories, invalid contents when writing to <filename>/sys/</filename> values, …),
 356     <constant>73</constant> is returned (<constant>EX_CANTCREAT</constant> from
 357     <filename>/usr/include/sysexits.h</filename>). Otherwise, <constant>1</constant> is returned
 358     (<constant>EXIT_FAILURE</constant> from <filename>/usr/include/stdlib.h</filename>).</para>
 359
 360     <para>Note: when creating items, if the target already exists, but is of the wrong type or otherwise does
 361     not match the requested state, and forced operation has not been requested with <literal>+</literal>,
 362     a message is emitted, but the failure is otherwise ignored.</para>
 363   </refsect1>
 364
 365   <refsect1>
 366     <title>See Also</title>
 367     <para><simplelist type="inline">
 368       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 369       <member><citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 370     </simplelist></para>
 371   </refsect1>
 372
 373 </refentry>