man/tmpfiles.d.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!--
   5   SPDX-License-Identifier: LGPL-2.1-or-later
   6
   7   Copyright © 2010 Brandon Philips
   8 -->
   9 <refentry id="tmpfiles.d"
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>tmpfiles.d</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>tmpfiles.d</refentrytitle>
  19     <manvolnum>5</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>tmpfiles.d</refname>
  24     <refpurpose>Configuration for creation, deletion and cleaning of
  25     volatile and temporary files</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <para><literallayout><filename>/etc/tmpfiles.d/*.conf</filename>
  30 <filename>/run/tmpfiles.d/*.conf</filename>
  31 <filename>/usr/lib/tmpfiles.d/*.conf</filename>
  32     </literallayout></para>
  33
  34     <para><literallayout><filename>~/.config/user-tmpfiles.d/*.conf</filename>
  35 <filename>$XDG_RUNTIME_DIR/user-tmpfiles.d/*.conf</filename>
  36 <filename>~/.local/share/user-tmpfiles.d/*.conf</filename>
  37 <filename index='false'>…</filename>
  38 <filename>/usr/share/user-tmpfiles.d/*.conf</filename>
  39     </literallayout></para>
  40
  41     <programlisting>#Type Path                                     Mode User Group Age         Argument
  42 f     /file/to/create                          mode user group -           content
  43 f+    /file/to/create-or-truncate              mode user group -           content
  44 w     /file/to/write-to                        -    -    -     -           content
  45 w+    /file/to/append-to                       -    -    -     -           content
  46 d     /directory/to/create-and-clean-up        mode user group cleanup-age -
  47 D     /directory/to/create-and-remove          mode user group cleanup-age -
  48 e     /directory/to/clean-up                   mode user group cleanup-age -
  49 v     /subvolume-or-directory/to/create        mode user group cleanup-age -
  50 q     /subvolume-or-directory/to/create        mode user group cleanup-age -
  51 Q     /subvolume-or-directory/to/create        mode user group cleanup-age -
  52 p     /fifo/to/create                          mode user group -           -
  53 p+    /fifo/to/[re]create                      mode user group -           -
  54 L     /symlink/to/create                       -    -    -     -           symlink/target/path
  55 L+    /symlink/to/[re]create                   -    -    -     -           symlink/target/path
  56 c     /dev/char-device-to-create               mode user group -           major:minor
  57 c+    /dev/char-device-to-[re]create           mode user group -           major:minor
  58 b     /dev/block-device-to-create              mode user group -           major:minor
  59 b+    /dev/block-device-to-[re]create          mode user group -           major:minor
  60 C     /target/to/create                        -    -    -     cleanup-age /source/to/copy
  61 C+    /target/to/create                        -    -    -     cleanup-age /source/to/copy
  62 x     /path-or-glob/to/ignore/recursively      -    -    -     cleanup-age -
  63 X     /path-or-glob/to/ignore                  -    -    -     cleanup-age -
  64 r     /path-or-glob/to/remove                  -    -    -     -           -
  65 R     /path-or-glob/to/remove/recursively      -    -    -     -           -
  66 z     /path-or-glob/to/adjust/mode             mode user group -           -
  67 Z     /path-or-glob/to/adjust/mode/recursively mode user group -           -
  68 t     /path-or-glob/to/set/xattrs              -    -    -     -           xattrs
  69 T     /path-or-glob/to/set/xattrs/recursively  -    -    -     -           xattrs
  70 h     /path-or-glob/to/set/attrs               -    -    -     -           file attrs
  71 H     /path-or-glob/to/set/attrs/recursively   -    -    -     -           file attrs
  72 a     /path-or-glob/to/set/acls                -    -    -     -           POSIX ACLs
  73 a+    /path-or-glob/to/append/acls             -    -    -     -           POSIX ACLs
  74 A     /path-or-glob/to/set/acls/recursively    -    -    -     -           POSIX ACLs
  75 A+    /path-or-glob/to/append/acls/recursively -    -    -     -           POSIX ACLs
  76
  77 </programlisting>
  78   </refsynopsisdiv>
  79
  80   <refsect1>
  81     <title>Description</title>
  82
  83     <para><filename>tmpfiles.d</filename> configuration files provide a generic mechanism to define the
  84     <emphasis>creation</emphasis> of regular files, directories, pipes, and device nodes, adjustments to
  85     their <emphasis>access mode, ownership, attributes, quota assignments, and contents</emphasis>, and
  86     finally their time-based <emphasis>removal</emphasis>. It is mostly commonly used for volatile and
  87     temporary files and directories (such as those located under <filename>/run/</filename>,
  88     <filename>/tmp/</filename>, <filename>/var/tmp/</filename>, the API file systems such as
  89     <filename>/sys/</filename> or <filename>/proc/</filename>, as well as some other directories below
  90     <filename>/var/</filename>).</para>
  91
  92     <para><citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  93     uses this configuration to create volatile files and directories during boot and to do periodic cleanup
  94     afterwards. See
  95     <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
  96     the description of <filename>systemd-tmpfiles-setup.service</filename>,
  97     <filename>systemd-tmpfiles-clean.service</filename>, and associated units.</para>
  98
  99     <para>System daemons frequently require private runtime directories below <filename>/run/</filename> to
 100     store communication sockets and similar. For these, it is better to use
 101     <varname>RuntimeDirectory=</varname> in their unit files (see
 102     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 103     details), if the flexibility provided by <filename>tmpfiles.d</filename> is not required. The advantages
 104     are that the configuration required by the unit is centralized in one place, and that the lifetime of the
 105     directory is tied to the lifetime of the service itself. Similarly, <varname>StateDirectory=</varname>,
 106     <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and
 107     <varname>ConfigurationDirectory=</varname> should be used to create directories under
 108     <filename>/var/lib/</filename>, <filename>/var/cache/</filename>, <filename>/var/log/</filename>, and
 109     <filename>/etc/</filename>. <filename>tmpfiles.d</filename> should be used for files whose lifetime is
 110     independent of any service or requires more complicated configuration.</para>
 111   </refsect1>
 112
 113   <refsect1>
 114     <title>Configuration Directories and Precedence</title>
 115
 116     <para>Each configuration file shall be named in the style of
 117     <filename><replaceable>package</replaceable>.conf</filename> or
 118     <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
 119     The second variant should be used when it is desirable to make it
 120     easy to override just this part of configuration.</para>
 121
 122     <para>Files in <filename>/etc/tmpfiles.d</filename> override files with the same name in
 123     <filename>/usr/lib/tmpfiles.d</filename> and <filename>/run/tmpfiles.d</filename>. Files in
 124     <filename>/run/tmpfiles.d</filename> override files with the same name in
 125     <filename>/usr/lib/tmpfiles.d</filename>. Packages should install their configuration files in
 126     <filename>/usr/lib/tmpfiles.d</filename>. Files in <filename>/etc/tmpfiles.d</filename> are reserved for
 127     the local administrator, who may use this logic to override the configuration files installed by vendor
 128     packages. All configuration files are sorted by their filename in lexicographic order, regardless of
 129     which of the directories they reside in. If multiple files specify the same path, the entry in the file
 130     with the lexicographically earliest name will be applied (note that lines suppressed due to the
 131     <literal>!</literal> are filtered before application, meaning that if an early line carries the
 132     exclamation mark and is suppressed because of that, a later line matching in path will be applied).  All
 133     other conflicting entries will be logged as errors. When two lines are prefix path and suffix path of
 134     each other, then the prefix line is always created first, the suffix later (and if removal applies to the
 135     line, the order is reversed: the suffix is removed first, the prefix later). Lines that take globs are
 136     applied after those accepting no globs. If multiple operations shall be applied on the same file (such as
 137     ACL, xattr, file attribute adjustments), these are always done in the same fixed order. Except for those
 138     cases, the files/directories are processed in the order they are listed.</para>
 139
 140     <para>If the administrator wants to disable a configuration file
 141     supplied by the vendor, the recommended way is to place a symlink
 142     to <filename>/dev/null</filename> in
 143     <filename>/etc/tmpfiles.d/</filename> bearing the same filename.
 144     </para>
 145   </refsect1>
 146
 147   <refsect1>
 148     <title>Configuration File Format</title>
 149
 150     <para>The configuration format is one line per path, containing type, path, mode, ownership, age, and
 151     argument fields. The lines are separated by newlines, the fields by whitespace:</para>
 152
 153     <programlisting>#Type Path        Mode User Group Age Argument…
 154 d     /run/user   0755 root root  10d -
 155 L     /tmp/foobar -    -    -     -   /dev/null</programlisting>
 156
 157     <para>Fields may contain C-style escapes. With the exception of the seventh field (the "argument") all
 158     fields may be enclosed in quotes. Note that any whitespace found in the line after the beginning of the
 159     argument field will be considered part of the argument field. To begin the argument field with a
 160     whitespace character, use C-style escapes (e.g. <literal>\x20</literal>).</para>
 161
 162     <refsect2>
 163       <title>Type</title>
 164
 165       <para>The type consists of a single letter and optionally one or more modifier characters: a plus sign
 166       (<literal>+</literal>), exclamation mark (<literal>!</literal>), minus sign (<literal>-</literal>),
 167       equals sign (<literal>=</literal>), tilde character (<literal>~</literal>) and/or caret
 168       (<literal>^</literal>).</para>
 169
 170       <para>The following line types are understood:</para>
 171
 172       <variablelist>
 173         <varlistentry>
 174           <term><varname>f</varname></term>
 175           <term><varname>f+</varname></term>
 176           <listitem><para><varname>f</varname> will create a file if it does not exist yet. If the argument
 177           parameter is given and the file did not exist yet, it will be written to the file.
 178           <varname>f+</varname> will create or truncate the file. If the argument parameter is given, it will
 179           be written to the file. Does not follow symlinks.</para></listitem>
 180         </varlistentry>
 181
 182         <varlistentry>
 183           <term><varname>w</varname></term>
 184           <term><varname>w+</varname></term>
 185           <listitem><para>Write the argument parameter to a file, if the file exists.
 186           If suffixed with <varname>+</varname>, the line will be appended to the file.
 187           If your configuration writes multiple lines to the same file, use <varname>w+</varname>.
 188           Lines of this type accept shell-style globs in place of normal path names.
 189           The argument parameter will be written without a trailing newline.
 190           C-style backslash escapes are interpreted. Follows symlinks.</para></listitem>
 191         </varlistentry>
 192
 193         <varlistentry>
 194           <term><varname>d</varname></term>
 195           <listitem><para>Create a directory. The mode and ownership will be adjusted if specified. Contents
 196           of this directory are subject to time-based cleanup if the age argument is specified.
 197           </para></listitem>
 198         </varlistentry>
 199
 200         <varlistentry>
 201           <term><varname>D</varname></term>
 202           <listitem><para>Similar to <varname>d</varname>, but in addition the contents of the directory will
 203           be removed when <option>--remove</option> is used.</para></listitem>
 204         </varlistentry>
 205
 206         <varlistentry>
 207           <term><varname>e</varname></term>
 208           <listitem><para>Adjust the mode and ownership of existing directories and remove their contents
 209           based on age. Lines of this type accept shell-style globs in place of normal path names. Contents
 210           of the directories are subject to time-based cleanup if the age argument is specified. If the age
 211           argument is <literal>0</literal>, contents will be unconditionally deleted every time
 212           <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 213           <option>--clean</option> is run.</para>
 214
 215           <para>For this entry to be useful, at least one of the mode, user, group, or age arguments must be
 216           specified, since otherwise this entry has no effect. As an exception, an entry with no effect may
 217           be useful when combined with <varname>!</varname>, see the examples.</para>
 218
 219           <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 220         </varlistentry>
 221
 222         <varlistentry>
 223           <term><varname>v</varname></term>
 224           <listitem><para>Create a subvolume if the path does not exist yet, the file system supports
 225           subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root
 226           directory <filename>/</filename> is itself a subvolume). Otherwise, create a normal directory, in
 227           the same way as <varname>d</varname>.</para>
 228
 229           <para>A subvolume created with this line type is not assigned to any higher-level quota group. For
 230           that, use <varname>q</varname> or <varname>Q</varname>, which allow creating simple quota group
 231           hierarchies, see below.</para>
 232
 233           <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 234         </varlistentry>
 235
 236         <varlistentry>
 237           <term><varname>q</varname></term>
 238           <listitem><para>Create a subvolume or directory the same as <varname>v</varname>, but assign the
 239           subvolume to the same higher-level quota groups as the parent. This ensures that higher-level
 240           limits and accounting applied to the parent subvolume also include the specified subvolume. On
 241           non-btrfs file systems, this line type is identical to <varname>d</varname>.</para>
 242
 243           <para>If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the
 244           subvolume is already attached to a quota group or not. Also see <varname>Q</varname> below. See <citerefentry
 245           project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
 246           details about the btrfs quota group concept.</para>
 247
 248           <xi:include href="version-info.xml" xpointer="v228"/></listitem>
 249         </varlistentry>
 250
 251         <varlistentry>
 252           <term><varname>Q</varname></term>
 253           <listitem><para>Create the subvolume or directory the same as <varname>v</varname>, but assign the
 254           new subvolume to a new leaf quota group. Instead of copying the higher-level quota group
 255           assignments from the parent as is done with <varname>q</varname>, the lowest quota group of the
 256           parent subvolume is determined that is not the leaf quota group. Then, an "intermediary" quota
 257           group is inserted that is one level below this level, and shares the same ID part as the specified
 258           subvolume. If no higher-level quota group exists for the parent subvolume, a new quota group at
 259           level 255 sharing the same ID as the specified subvolume is inserted instead. This new intermediary
 260           quota group is then assigned to the parent subvolume's higher-level quota groups, and the specified
 261           subvolume's leaf quota group is assigned to it.</para>
 262
 263           <para>Effectively, this has a similar effect as <varname>q</varname>, however introduces a new higher-level
 264           quota group for the specified subvolume that may be used to enforce limits and accounting to the specified
 265           subvolume and children subvolume created within it. Thus, by creating subvolumes only via
 266           <varname>q</varname> and <varname>Q</varname>, a concept of "subtree quotas" is implemented. Each subvolume
 267           for which <varname>Q</varname> is set will get a "subtree" quota group created, and all child subvolumes
 268           created within it will be assigned to it. Each subvolume for which <varname>q</varname> is set will not get
 269           such a "subtree" quota group, but it is ensured that they are added to the same "subtree" quota group as
 270           their immediate parents.</para>
 271
 272           <para>It is recommended to use <varname>Q</varname> for subvolumes that typically contain further subvolumes,
 273           and where it is desirable to have accounting and quota limits on all child subvolumes together. Examples for
 274           <varname>Q</varname> are typically <filename>/home/</filename> or <filename>/var/lib/machines/</filename>. In
 275           contrast, <varname>q</varname> should be used for subvolumes that either usually do not include further
 276           subvolumes or where no accounting and quota limits are needed that apply to all child subvolumes
 277           together. Examples for <varname>q</varname> are typically <filename>/var/</filename> or
 278           <filename>/var/tmp/</filename>. </para>
 279
 280           <para>As with <varname>q</varname>, <varname>Q</varname> has no effect on the quota group hierarchy if the
 281           subvolume already exists, regardless of whether the subvolume already belong to a quota group or not.
 282           </para>
 283
 284           <xi:include href="version-info.xml" xpointer="v228"/></listitem>
 285         </varlistentry>
 286
 287         <varlistentry>
 288           <term><varname>p</varname></term>
 289           <term><varname>p+</varname></term>
 290           <listitem><para>Create a named pipe (FIFO) if it does not
 291           exist yet. If suffixed with <varname>+</varname> and a file
 292           already exists where the pipe is to be created, it will be
 293           removed and be replaced by the pipe.</para></listitem>
 294         </varlistentry>
 295
 296         <varlistentry>
 297           <term><varname>L</varname></term>
 298           <term><varname>L+</varname></term>
 299           <listitem><para>Create a symlink if it does not exist
 300           yet. If suffixed with <varname>+</varname> and a file or
 301           directory already exists where the symlink is to be created,
 302           it will be removed and be replaced by the symlink. If the
 303           argument is omitted, symlinks to files with the same name
 304           residing in the directory
 305           <filename>/usr/share/factory/</filename> are created. Note
 306           that permissions and ownership on symlinks are ignored.
 307           </para></listitem>
 308         </varlistentry>
 309
 310         <varlistentry>
 311           <term><varname>c</varname></term>
 312           <term><varname>c+</varname></term>
 313           <listitem><para>Create a character device node if it does
 314           not exist yet. If suffixed with <varname>+</varname> and a
 315           file already exists where the device node is to be created,
 316           it will be removed and be replaced by the device node. It is
 317           recommended to suffix this entry with an exclamation mark to
 318           only create static device nodes at boot, as udev will not
 319           manage static device nodes that are created at runtime.
 320           </para></listitem>
 321         </varlistentry>
 322
 323         <varlistentry>
 324           <term><varname>b</varname></term>
 325           <term><varname>b+</varname></term>
 326           <listitem><para>Create a block device node if it does not
 327           exist yet. If suffixed with <varname>+</varname> and a file
 328           already exists where the device node is to be created, it
 329           will be removed and be replaced by the device node. It is
 330           recommended to suffix this entry with an exclamation mark to
 331           only create static device nodes at boot, as udev will not
 332           manage static device nodes that are created at runtime.
 333           </para></listitem>
 334         </varlistentry>
 335
 336         <varlistentry>
 337           <term><varname>C</varname></term>
 338           <term><varname>C+</varname></term>
 339           <listitem><para>Recursively copy a file or directory, if the destination files or directories do
 340           not exist yet or the destination directory is empty. Note that this command will not descend into
 341           subdirectories if the destination directory already exists and is not empty, unless the action is
 342           suffixed with <varname>+</varname>. Instead, the entire copy operation is skipped. If the argument
 343           is omitted, files from the source directory <filename>/usr/share/factory/</filename> with the same
 344           name are copied. Does not follow symlinks. Contents of the directories are subject to time-based
 345           cleanup if the age argument is specified.
 346           </para>
 347
 348           <xi:include href="version-info.xml" xpointer="v214"/></listitem>
 349         </varlistentry>
 350
 351         <varlistentry>
 352           <term><varname>x</varname></term>
 353           <listitem><para>Ignore a path during cleaning. Use this type
 354           to exclude paths from clean-up as controlled with the Age
 355           parameter. Note that lines of this type do not influence the
 356           effect of <varname>r</varname> or <varname>R</varname>
 357           lines. Lines of this type accept shell-style globs in place
 358           of normal path names.  </para></listitem>
 359         </varlistentry>
 360
 361         <varlistentry>
 362           <term><varname>X</varname></term>
 363           <listitem><para>Ignore a path during cleaning. Use this type
 364           to exclude paths from clean-up as controlled with the Age
 365           parameter. Unlike <varname>x</varname>, this parameter will
 366           not exclude the content if path is a directory, but only
 367           directory itself. Note that lines of this type do not
 368           influence the effect of <varname>r</varname> or
 369           <varname>R</varname> lines. Lines of this type accept
 370           shell-style globs in place of normal path names.
 371           </para>
 372
 373           <xi:include href="version-info.xml" xpointer="v198"/></listitem>
 374         </varlistentry>
 375
 376         <varlistentry>
 377           <term><varname>r</varname></term>
 378           <listitem><para>Remove a file or directory if it exists.
 379           This may not be used to remove non-empty directories, use
 380           <varname>R</varname> for that.  Lines of this type accept
 381           shell-style globs in place of normal path
 382           names. Does not follow symlinks.</para></listitem>
 383         </varlistentry>
 384
 385         <varlistentry>
 386           <term><varname>R</varname></term>
 387           <listitem><para>Recursively remove a path and all its
 388           subdirectories (if it is a directory). Lines of this type
 389           accept shell-style globs in place of normal path
 390           names. Does not follow symlinks.</para></listitem>
 391         </varlistentry>
 392
 393         <varlistentry>
 394           <term><varname>z</varname></term>
 395           <listitem><para>Adjust the access mode, user and group ownership, and restore the SELinux security
 396           context of a file or directory, if it exists. Lines of this type accept shell-style globs in place
 397           of normal path names. Does not follow symlinks.</para></listitem>
 398         </varlistentry>
 399
 400         <varlistentry>
 401           <term><varname>Z</varname></term>
 402           <listitem><para>Recursively set the access mode, user and group ownership, and restore the SELinux
 403           security context of a file or directory if it exists, as well as of its subdirectories and the
 404           files contained therein (if applicable). Lines of this type accept shell-style globs in place of
 405           normal path names. Does not follow symlinks.</para></listitem>
 406         </varlistentry>
 407
 408         <varlistentry>
 409           <term><varname>t</varname></term>
 410           <listitem><para>Set extended attributes, see <citerefentry
 411           project='man-pages'><refentrytitle>attr</refentrytitle>
 412           <manvolnum>5</manvolnum></citerefentry> for details. The argument field should take one or more
 413           assignment expressions in the form
 414           <replaceable>namespace</replaceable>.<replaceable>attribute</replaceable>=<replaceable>value</replaceable>,
 415           for examples see below. Lines of this type accept shell-style globs in place of normal path
 416           names. This can be useful for setting SMACK labels. Does not follow symlinks.</para>
 417
 418           <para>Please note that extended attributes settable with this line type are a different concept
 419           from the Linux file attributes settable with <varname>h</varname>/<varname>H</varname>, see
 420           below.</para>
 421
 422           <xi:include href="version-info.xml" xpointer="v218"/></listitem>
 423         </varlistentry>
 424
 425         <varlistentry>
 426           <term><varname>T</varname></term>
 427           <listitem><para>Same as <varname>t</varname>, but operates recursively.</para>
 428
 429           <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 430         </varlistentry>
 431
 432         <varlistentry>
 433           <term><varname>h</varname></term>
 434           <listitem><para>Set Linux file/directory attributes. Lines of this type accept shell-style globs in
 435           place of normal path names.</para>
 436
 437           <para>The format of the argument field is <varname>[+-=][aAcCdDeijPsStTu]</varname>. The prefix
 438           <varname>+</varname> (the default one) causes the attributes to be added; <varname>-</varname>
 439           causes the attributes to be removed; <varname>=</varname> causes the attributes to be set exactly
 440           as the following letters. The letters <literal>aAcCdDeijPsStTu</literal> select the new attributes
 441           for the files, see <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle>
 442           <manvolnum>1</manvolnum></citerefentry> for further information.
 443           </para>
 444
 445           <para>Passing only <varname>=</varname> as argument resets all the file attributes listed above. It
 446           has to be pointed out that the <varname>=</varname> prefix limits itself to the attributes
 447           corresponding to the letters listed here. All other attributes will be left untouched. Does not
 448           follow symlinks.</para>
 449
 450           <para>Please note that the Linux file attributes settable with this line type are a different
 451           concept from the extended attributes settable with <varname>t</varname>/<varname>T</varname>,
 452           see above.</para></listitem>
 453         </varlistentry>
 454
 455         <varlistentry>
 456           <term><varname>H</varname></term>
 457           <listitem><para>Sames as <varname>h</varname>, but operates recursively.</para>
 458
 459           <xi:include href="version-info.xml" xpointer="v220"/></listitem>
 460         </varlistentry>
 461
 462         <varlistentry>
 463           <term><varname>a</varname></term>
 464           <term><varname>a+</varname></term>
 465           <listitem><para>Set POSIX ACLs (access control lists), see
 466           <citerefentry project='man-pages'><refentrytitle>acl</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 467           Additionally, if 'X' is used, the execute bit is set only if the file is a directory or already has
 468           execute permission for some user, as mentioned in
 469           <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 470           If suffixed with <varname>+</varname>, the specified entries will be added to the existing set.
 471           <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 472           will automatically add the required base entries for user and group based on the access mode of the
 473           file, unless base entries already exist or are explicitly specified. The mask will be added if not
 474           specified explicitly or already present. Lines of this type accept shell-style globs in place of
 475           normal path names. This can be useful for allowing additional access to certain files. Does not
 476           follow symlinks.</para>
 477
 478           <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 479         </varlistentry>
 480
 481         <varlistentry>
 482           <term><varname>A</varname></term>
 483           <term><varname>A+</varname></term>
 484           <listitem><para>Same as <varname>a</varname> and
 485           <varname>a+</varname>, but recursive. Does not follow
 486           symlinks.</para>
 487
 488           <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 489         </varlistentry>
 490       </variablelist>
 491     </refsect2>
 492
 493     <refsect2>
 494       <title>Type Modifiers</title>
 495
 496       <para>If the exclamation mark (<literal>!</literal>) is used, this line is only safe to execute during
 497       boot, and can break a running system. Lines without the exclamation mark are presumed to be safe to
 498       execute at any time, e.g. on package upgrades.
 499       <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 500       will take lines with an exclamation mark only into consideration, if the <option>--boot</option> option
 501       is given.</para>
 502
 503       <para>For example:
 504       <programlisting># Make sure these are created by default so that nobody else can
 505 d /tmp/.X11-unix 1777 root root 10d
 506
 507 # Unlink the X11 lock files
 508 r! /tmp/.X[0-9]*-lock</programlisting>
 509       The second line in contrast to the first one would break a
 510       running system, and will only be executed with
 511       <option>--boot</option>.</para>
 512
 513       <para>If the minus sign (<literal>-</literal>) is used, this line failing to run successfully during
 514       create (and only create) will not cause the execution of <command>systemd-tmpfiles</command> to return
 515       an error.</para>
 516
 517       <para>For example:
 518       <programlisting># Modify sysfs but don't fail if we are in a container with a read-only /proc
 519 w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
 520
 521       <para>If the equals sign (<literal>=</literal>) is used, the file types of existing objects in the specified path
 522       are checked, and removed if they do not match. This includes any implicitly created parent directories (which can
 523       be either directories or directory symlinks). For example, if there is a FIFO in place of one of the parent path
 524       components it will be replaced with a directory.</para>
 525
 526       <para>If the tilde character (<literal>~</literal>) is used, the argument (i.e. 6th) column is <ulink
 527       url="https://www.rfc-editor.org/rfc/rfc4648.html">Base64 decoded</ulink> before use. This modifier is
 528       only supported on line types that can write file contents, i.e. <varname>f</varname>,
 529       <varname>f+</varname>, <varname>w</varname>, <varname>+</varname>. This is useful for writing arbitrary
 530       binary data (including newlines and NUL bytes) to files. Note that if this switch is used, the argument
 531       is not subject to specifier expansion, neither before nor after Base64 decoding.</para>
 532
 533       <para>If the caret character (<literal>^</literal>) is used, the argument (i.e. 6th) column takes a
 534       service credential name to read the argument data from. See <ulink
 535       url="https://systemd.io/CREDENTIALS">System and Service Credentials</ulink> for details about the
 536       credentials concept. This modifier is only supported on line types that can write file contents,
 537       i.e. <varname>f</varname>, <varname>f+</varname>, <varname>w</varname>, <varname>w+</varname>. This is
 538       useful for writing arbitrary files with contents sourced from elsewhere, including from VM or container
 539       managers further up. If the specified credential is not set for the <command>systemd-tmpfiles</command>
 540       service, the line is silently skipped. If <literal>^</literal> and <literal>~</literal> are combined
 541       Base64 decoding is applied to the credential contents.</para>
 542
 543       <para>Note that for all line types that result in creation of any kind of file node
 544       (i.e. <varname>f</varname>/<varname>F</varname>,
 545       <varname>d</varname>/<varname>D</varname>/<varname>v</varname>/<varname>q</varname>/<varname>Q</varname>,
 546       <varname>p</varname>, <varname>L</varname>, <varname>c</varname>/<varname>b</varname> and <varname>C</varname>)
 547       leading directories are implicitly created if needed, owned by root with an access mode of 0755. In order to
 548       create them with different modes or ownership make sure to add appropriate <varname>d</varname> lines.</para>
 549     </refsect2>
 550
 551     <refsect2>
 552       <title>Path</title>
 553
 554       <para>The file system path specification supports simple
 555       specifier expansion, see below. The path (after expansion) must be
 556       absolute.</para>
 557     </refsect2>
 558
 559     <refsect2>
 560       <title>Mode</title>
 561
 562       <para>The file access mode to use when creating this file or directory. If omitted or when set to
 563       <literal>-</literal>, the default is used: 0755 for directories, 0644 for all other file objects. For
 564       <varname>z</varname>, <varname>Z</varname> lines, if omitted or when set to <literal>-</literal>, the
 565       file access mode will not be modified. This parameter is ignored for <varname>x</varname>,
 566       <varname>r</varname>, <varname>R</varname>, <varname>L</varname>, <varname>t</varname>, and
 567       <varname>a</varname> lines.</para>
 568
 569       <para>Optionally, if prefixed with <literal>~</literal>, the access mode is masked based on the already
 570       set access bits for existing file or directories: if the existing file has all executable bits unset,
 571       all executable bits are removed from the new access mode, too. Similarly, if all read bits are removed
 572       from the old access mode, they will be removed from the new access mode too, and if all write bits are
 573       removed, they will be removed from the new access mode too. In addition, the sticky/SUID/SGID bit is
 574       removed unless applied to a directory. This functionality is particularly useful in conjunction with
 575       <varname>Z</varname>.</para>
 576
 577       <para>Optionally, if prefixed with <literal>:</literal>, the configured access mode is only used when
 578       creating new inodes. If the inode the line refers to already exists, its access mode is left in place
 579       unmodified.</para>
 580     </refsect2>
 581
 582     <refsect2>
 583       <title>User, Group</title>
 584
 585       <para>The user and group to use for this file or directory. This may either be a numeric ID or a
 586       user/group name. If omitted or when set to <literal>-</literal>, the user and group of the user who
 587       invokes
 588       <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> is
 589       used. For <varname>z</varname> and <varname>Z</varname> lines, when omitted or when set to
 590       <literal>-</literal>, the file ownership will not be modified. These parameters are ignored for
 591       <varname>x</varname>, <varname>r</varname>, <varname>R</varname>, <varname>L</varname>,
 592       <varname>t</varname>, and <varname>a</varname> lines.</para>
 593
 594       <para>This field should generally only reference system users/groups, i.e. users/groups that are
 595       guaranteed to be resolvable during early boot. If this field references users/groups that only become
 596       resolveable during later boot (i.e. after NIS, LDAP or a similar networked directory service become
 597       available), execution of the operations declared by the line will likely fail. Also see <ulink
 598       url="https://systemd.io/UIDS-GIDS/#notes-on-resolvability-of-user-and-group-names">Notes on
 599       Resolvability of User and Group Names</ulink> for more information on requirements on system user/group
 600       definitions.</para>
 601
 602       <para>Optionally, if prefixed with <literal>:</literal>, the configured user/group information is only
 603       used when creating new inodes. If the inode the line refers to already exists, its user/group is left
 604       in place unmodified.</para>
 605     </refsect2>
 606
 607     <refsect2>
 608       <title>Age</title>
 609
 610       <para>The date field, when set, is used to decide what files to
 611       delete when cleaning. If a file or directory is older than the
 612       current time minus the age field, it is deleted. The field
 613       format is a series of integers each followed by one of the
 614       following suffixes for the respective time units:
 615       <constant>s</constant>,
 616       <constant>m</constant> or <constant>min</constant>,
 617       <constant>h</constant>,
 618       <constant>d</constant>,
 619       <constant>w</constant>,
 620       <constant>ms</constant>, and
 621       <constant>us</constant>,
 622       meaning seconds, minutes, hours, days, weeks,
 623       milliseconds, and microseconds, respectively. Full names of the time units can
 624       be used too.
 625       </para>
 626
 627       <para>If multiple integers and units are specified, the time
 628       values are summed. If an integer is given without a unit,
 629       <constant>s</constant> is assumed.
 630       </para>
 631
 632       <para>When the age is set to zero, the files are cleaned
 633       unconditionally.</para>
 634
 635       <para>The age field only applies to lines starting with
 636       <varname>d</varname>, <varname>D</varname>, <varname>e</varname>,
 637       <varname>v</varname>, <varname>q</varname>,
 638       <varname>Q</varname>, <varname>C</varname>, <varname>x</varname>
 639       and <varname>X</varname>. If omitted or set to
 640       <literal>-</literal>, no automatic clean-up is done.</para>
 641
 642       <para>If the age field starts with a tilde character <literal>~</literal>, clean-up is only applied to
 643       files and directories one level inside the directory specified, but not the files and directories
 644       immediately inside it.</para>
 645
 646       <para>The age of a file system entry is determined from its last
 647       modification timestamp (mtime), its last access timestamp (atime),
 648       and (except for directories) its last status change timestamp
 649       (ctime). By default, any of these three (or two) values will
 650       prevent cleanup if it is more recent than the current time minus
 651       the age field. To restrict the deletion based on particular type
 652       of file timestamps, the age-by argument can be used.</para>
 653
 654       <para>The age-by argument overrides the timestamp types to be used for the age check. It can be
 655       specified by prefixing the age argument with a sequence of characters to specify the timestamp types
 656       and a colon (<literal>:</literal>):
 657       <literal><replaceable>age-by</replaceable>...:<replaceable>cleanup-age</replaceable></literal>.  The
 658       argument can consist of <constant>a</constant> (<constant>A</constant> for directories),
 659       <constant>b</constant> (<constant>B</constant> for directories), <constant>c</constant>
 660       (<constant>C</constant> for directories), or <constant>m</constant> (<constant>M</constant> for
 661       directories). Those respectively indicate access, creation, last status change, and last modification
 662       time of a file system entry. The lower-case letter signifies that the given timestamp type should be
 663       considered for files, while the upper-case letter signifies that the given timestamp type should be
 664       considered for directories. See <citerefentry
 665       project='man-pages'><refentrytitle>statx</refentrytitle><manvolnum>2</manvolnum></citerefentry> file
 666       timestamp fields for more details about timestamp types.</para>
 667
 668       <para>If not specified, the age-by field defaults to <constant>abcmABM</constant>, i.e. by default all
 669       file timestamps are taken into consideration, with the exception of the last status change timestamp
 670       (ctime) for directories. This is because the aging logic itself will alter the ctime whenever it
 671       deletes a file inside it. To ensure that running the aging logic does not feed back into the next
 672       iteration of itself, ctime for directories is ignored by default.</para>
 673
 674       <para>For example:<programlisting>
 675 # Files created and modified, and directories accessed more than
 676 # an hour ago in "/tmp/foo/bar", are subject to time-based cleanup.
 677 d /tmp/foo/bar - - - bmA:1h -</programlisting></para>
 678
 679       <para>Note that while the aging algorithm is run an exclusive BSD file lock (see <citerefentry
 680       project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) is
 681       taken on each directory/file the algorithm decides to remove. If the aging algorithm finds a lock
 682       (shared or exclusive) is already taken on some directory/file, it (and everything below it) is skipped.
 683       Applications may use this to temporarily exclude certain directory subtrees from the aging algorithm:
 684       the applications can take a BSD file lock themselves, and as long as they keep it aging of the
 685       directory/file and everything below it is disabled.</para>
 686
 687       <para>This behavior can be used to ensure guaranteed cleanup of files or directories whose lifetime
 688       should be aligned with the process that created them by having that process create them in a location
 689       monitored by <command>systemd-tmpfiles</command> with an age of <literal>0</literal>, and having the
 690       process immediately lock the directory or file before using it. Because the BSD lock is process
 691       specific, the file is guaranteed to be unlocked as soon as the process exits, meaning that even if the
 692       process crashes, those files and directories will be unlocked and cleaned up by
 693       <command>systemd-tmpfiles</command>.</para>
 694     </refsect2>
 695
 696     <refsect2>
 697       <title>Argument</title>
 698
 699       <para>For <varname>L</varname> lines determines the destination path of the symlink. For <varname>c</varname> and
 700       <varname>b</varname>, determines the major/minor of the device node, with major and minor formatted as integers,
 701       separated by <literal>:</literal>, e.g.  <literal>1:3</literal>. For <varname>f</varname>, <varname>F</varname>,
 702       and <varname>w</varname>, the argument may be used to specify a short string that is written to the file,
 703       suffixed by a newline. For <varname>C</varname>, specifies the source file or directory. For <varname>t</varname>
 704       and <varname>T</varname>, determines extended attributes to be set. For <varname>a</varname> and
 705       <varname>A</varname>, determines ACL attributes to be set. For <varname>h</varname> and <varname>H</varname>,
 706       determines the file attributes to set. Ignored for all other lines.</para>
 707
 708       <para>This field can contain specifiers, see below.</para>
 709     </refsect2>
 710   </refsect1>
 711
 712   <refsect1>
 713     <title>Specifiers</title>
 714
 715     <para>Specifiers can be used in the "path" and "argument" fields.
 716     An unknown or unresolvable specifier is treated as invalid configuration.
 717     The following expansions are understood:</para>
 718       <table class='specifiers'>
 719         <title>Specifiers available</title>
 720         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 721           <colspec colname="spec" />
 722           <colspec colname="mean" />
 723           <colspec colname="detail" />
 724           <thead>
 725             <row>
 726               <entry>Specifier</entry>
 727               <entry>Meaning</entry>
 728               <entry>Details</entry>
 729             </row>
 730           </thead>
 731           <tbody>
 732             <xi:include href="standard-specifiers.xml" xpointer="a"/>
 733             <xi:include href="standard-specifiers.xml" xpointer="A"/>
 734             <xi:include href="standard-specifiers.xml" xpointer="b"/>
 735             <xi:include href="standard-specifiers.xml" xpointer="B"/>
 736             <row>
 737               <entry><literal>%C</literal></entry>
 738               <entry>System or user cache directory</entry>
 739               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CACHE_HOME</varname>, and <filename>/var/cache</filename> otherwise.</entry>
 740             </row>
 741             <row>
 742               <entry><literal>%g</literal></entry>
 743               <entry>User group</entry>
 744               <entry>This is the name of the group running the command. In case of the system instance this resolves to <literal>root</literal>.</entry>
 745             </row>
 746             <row>
 747               <entry><literal>%G</literal></entry>
 748               <entry>User GID</entry>
 749               <entry>This is the numeric GID of the group running the command. In case of the system instance this resolves to <constant>0</constant>.</entry>
 750             </row>
 751             <row>
 752               <entry><literal>%h</literal></entry>
 753               <entry>User home directory</entry>
 754               <entry>This is the home directory of the user running the command. In case of the system instance this resolves to <literal>/root</literal>.</entry>
 755             </row>
 756             <xi:include href="standard-specifiers.xml" xpointer="H"/>
 757             <xi:include href="standard-specifiers.xml" xpointer="l"/>
 758             <row>
 759               <entry><literal>%L</literal></entry>
 760               <entry>System or user log directory</entry>
 761               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_STATE_HOME</varname> with <filename index="false">/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
 762             </row>
 763             <xi:include href="standard-specifiers.xml" xpointer="m"/>
 764             <xi:include href="standard-specifiers.xml" xpointer="M"/>
 765             <xi:include href="standard-specifiers.xml" xpointer="o"/>
 766             <row>
 767               <entry><literal>%S</literal></entry>
 768               <entry>System or user state directory</entry>
 769               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_STATE_HOME</varname>, and <filename>/var/lib</filename> otherwise.</entry>
 770             </row>
 771             <row>
 772               <entry><literal>%t</literal></entry>
 773               <entry>System or user runtime directory</entry>
 774               <entry>In <option>--user</option> mode, this is the same <varname>$XDG_RUNTIME_DIR</varname>, and <filename>/run/</filename> otherwise.</entry>
 775             </row>
 776             <xi:include href="standard-specifiers.xml" xpointer="T"/>
 777             <row>
 778               <entry><literal>%u</literal></entry>
 779               <entry>User name</entry>
 780               <entry>This is the name of the user running the command. In case of the system instance this resolves to <literal>root</literal>.</entry>
 781             </row>
 782             <row>
 783               <entry><literal>%U</literal></entry>
 784               <entry>User UID</entry>
 785               <entry>This is the numeric UID of the user running the command. In case of the system instance this resolves to <constant>0</constant>.</entry>
 786             </row>
 787             <xi:include href="standard-specifiers.xml" xpointer="v"/>
 788             <xi:include href="standard-specifiers.xml" xpointer="V"/>
 789             <xi:include href="standard-specifiers.xml" xpointer="w"/>
 790             <xi:include href="standard-specifiers.xml" xpointer="W"/>
 791             <xi:include href="standard-specifiers.xml" xpointer="percent"/>
 792           </tbody>
 793         </tgroup>
 794       </table>
 795   </refsect1>
 796
 797   <refsect1>
 798     <title>Examples</title>
 799     <example>
 800       <title>Create directories with specific mode and ownership</title>
 801       <para>
 802       <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 803       needs two directories created at boot with specific modes and ownership:</para>
 804
 805       <programlisting># /usr/lib/tmpfiles.d/screen.conf
 806 d /run/screens  1777 root screen 10d
 807 d /run/uscreens 0755 root screen 10d12h
 808 </programlisting>
 809
 810       <para>Contents of <filename>/run/screens</filename> and /run/uscreens will
 811       be cleaned up after 10 and 10½ days, respectively.</para>
 812     </example>
 813
 814     <example>
 815       <title>Create a directory with a SMACK attribute</title>
 816       <programlisting>D /run/cups - - - -
 817 t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar"
 818       </programlisting>
 819
 820       <para>The directory will be owned by root and have default mode. Its contents are
 821       not subject to time-based cleanup, but will be obliterated when
 822       <command>systemd-tmpfiles --remove</command> runs.</para>
 823     </example>
 824
 825     <example>
 826       <title>Create a directory and prevent its contents from cleanup</title>
 827       <para>
 828       <citerefentry project='die-net'><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 829       needs a directory created at boot with specific mode and ownership and its content
 830       should be preserved from the automatic cleanup applied to the contents of
 831       <filename>/var/tmp</filename>:</para>
 832
 833       <programlisting># /usr/lib/tmpfiles.d/tmp.conf
 834 d /var/tmp 1777 root root 30d
 835 </programlisting>
 836
 837       <programlisting># /usr/lib/tmpfiles.d/abrt.conf
 838 d /var/tmp/abrt 0755 abrt abrt -
 839 </programlisting>
 840     </example>
 841
 842     <example>
 843       <title>Apply clean up during boot and based on time</title>
 844
 845       <programlisting># /usr/lib/tmpfiles.d/dnf.conf
 846 r! /var/cache/dnf/*/*/download_lock.pid
 847 r! /var/cache/dnf/*/*/metadata_lock.pid
 848 r! /var/lib/dnf/rpmdb_lock.pid
 849 e  /var/cache/dnf/ - - - 30d
 850 </programlisting>
 851
 852      <para>The lock files will be removed during boot. Any files and directories in
 853      <filename>/var/cache/dnf/</filename> will be removed after they have not been
 854      accessed in 30 days.</para>
 855     </example>
 856
 857     <example>
 858       <title>Empty the contents of a cache directory on boot</title>
 859
 860       <programlisting># /usr/lib/tmpfiles.d/krb5rcache.conf
 861 e! /var/cache/krb5rcache - - - 0
 862 </programlisting>
 863
 864       <para>Any files and subdirectories in <filename>/var/cache/krb5rcache/</filename>
 865       will be removed on boot. The directory will not be created.
 866       </para>
 867     </example>
 868
 869     <example>
 870       <title>Provision SSH public key access for root user via Credentials in QEMU</title>
 871
 872       <programlisting>-smbios type=11,value=io.systemd.credential.binary:tmpfiles.extra=$(echo "f~ /root/.ssh/authorized_keys 700 root root - $(ssh-add -L | base64 -w 0)" | base64 -w 0)
 873 </programlisting>
 874
 875       <para>By passing this line to QEMU, the public key of the current user will be encoded in
 876       base64, added to a tmpfiles.d line that tells systemd-tmpfiles to decode it into
 877       <filename>/root/.ssh/authorized_keys</filename>, encode that line itself in base64 and
 878       pass it as a Credential that will be picked up by systemd from SMBIOS on boot.
 879       </para>
 880     </example>
 881   </refsect1>
 882
 883   <refsect1>
 884     <title><filename>/run/</filename> and <filename>/var/run/</filename></title>
 885     <para><filename>/var/run/</filename> is a deprecated symlink to <filename>/run/</filename>, and
 886     applications should use the latter. <command>systemd-tmpfiles</command> will warn if
 887     <filename>/var/run/</filename> is used.</para>
 888   </refsect1>
 889
 890   <refsect1>
 891     <title>See Also</title>
 892     <para>
 893       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 894       <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 895       <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 896       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 897       <citerefentry project='man-pages'><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 898       <citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 899       <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 900       <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 901       <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 902       <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 903       <citerefentry project='die-net'><refentrytitle>btrfs-subvolume</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 904       <citerefentry project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 905     </para>
 906   </refsect1>
 907
 908 </refentry>