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.
 210           Lines of this type accept shell-style globs in place of normal path names. Contents of the
 211           directories are subject to time-based cleanup if the age argument is specified. If the age argument
 212           is <literal>0</literal>, contents will be unconditionally deleted every time
 213           <command>systemd-tmpfiles --clean</command> 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></listitem>
 218         </varlistentry>
 219
 220         <varlistentry>
 221           <term><varname>v</varname></term>
 222           <listitem><para>Create a subvolume if the path does not exist yet, the file system supports
 223           subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root
 224           directory <filename>/</filename> is itself a subvolume). Otherwise, create a normal directory, in
 225           the same way as <varname>d</varname>.</para>
 226
 227           <para>A subvolume created with this line type is not assigned to any higher-level quota group. For
 228           that, use <varname>q</varname> or <varname>Q</varname>, which allow creating simple quota group
 229           hierarchies, see below.</para></listitem>
 230         </varlistentry>
 231
 232         <varlistentry>
 233           <term><varname>q</varname></term>
 234           <listitem><para>Create a subvolume or directory the same as <varname>v</varname>, but assign the
 235           subvolume to the same higher-level quota groups as the parent. This ensures that higher-level
 236           limits and accounting applied to the parent subvolume also include the specified subvolume. On
 237           non-btrfs file systems, this line type is identical to <varname>d</varname>.</para>
 238
 239           <para>If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the
 240           subvolume is already attached to a quota group or not. Also see <varname>Q</varname> below. See <citerefentry
 241           project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
 242           details about the btrfs quota group concept.</para></listitem>
 243         </varlistentry>
 244
 245         <varlistentry>
 246           <term><varname>Q</varname></term>
 247           <listitem><para>Create the subvolume or directory the same as <varname>v</varname>, but assign the
 248           new subvolume to a new leaf quota group. Instead of copying the higher-level quota group
 249           assignments from the parent as is done with <varname>q</varname>, the lowest quota group of the
 250           parent subvolume is determined that is not the leaf quota group. Then, an "intermediary" quota
 251           group is inserted that is one level below this level, and shares the same ID part as the specified
 252           subvolume. If no higher-level quota group exists for the parent subvolume, a new quota group at
 253           level 255 sharing the same ID as the specified subvolume is inserted instead. This new intermediary
 254           quota group is then assigned to the parent subvolume's higher-level quota groups, and the specified
 255           subvolume's leaf quota group is assigned to it.</para>
 256
 257           <para>Effectively, this has a similar effect as <varname>q</varname>, however introduces a new higher-level
 258           quota group for the specified subvolume that may be used to enforce limits and accounting to the specified
 259           subvolume and children subvolume created within it. Thus, by creating subvolumes only via
 260           <varname>q</varname> and <varname>Q</varname>, a concept of "subtree quotas" is implemented. Each subvolume
 261           for which <varname>Q</varname> is set will get a "subtree" quota group created, and all child subvolumes
 262           created within it will be assigned to it. Each subvolume for which <varname>q</varname> is set will not get
 263           such a "subtree" quota group, but it is ensured that they are added to the same "subtree" quota group as
 264           their immediate parents.</para>
 265
 266           <para>It is recommended to use <varname>Q</varname> for subvolumes that typically contain further subvolumes,
 267           and where it is desirable to have accounting and quota limits on all child subvolumes together. Examples for
 268           <varname>Q</varname> are typically <filename>/home/</filename> or <filename>/var/lib/machines/</filename>. In
 269           contrast, <varname>q</varname> should be used for subvolumes that either usually do not include further
 270           subvolumes or where no accounting and quota limits are needed that apply to all child subvolumes
 271           together. Examples for <varname>q</varname> are typically <filename>/var/</filename> or
 272           <filename>/var/tmp/</filename>. </para>
 273
 274           <para>As with <varname>q</varname>, <varname>Q</varname> has no effect on the quota group hierarchy if the
 275           subvolume already exists, regardless of whether the subvolume already belong to a quota group or not.
 276           </para></listitem>
 277         </varlistentry>
 278
 279         <varlistentry>
 280           <term><varname>p</varname></term>
 281           <term><varname>p+</varname></term>
 282           <listitem><para>Create a named pipe (FIFO) if it does not
 283           exist yet. If suffixed with <varname>+</varname> and a file
 284           already exists where the pipe is to be created, it will be
 285           removed and be replaced by the pipe.</para></listitem>
 286         </varlistentry>
 287
 288         <varlistentry>
 289           <term><varname>L</varname></term>
 290           <term><varname>L+</varname></term>
 291           <listitem><para>Create a symlink if it does not exist
 292           yet. If suffixed with <varname>+</varname> and a file or
 293           directory already exists where the symlink is to be created,
 294           it will be removed and be replaced by the symlink. If the
 295           argument is omitted, symlinks to files with the same name
 296           residing in the directory
 297           <filename>/usr/share/factory/</filename> are created. Note
 298           that permissions and ownership on symlinks are ignored.
 299           </para></listitem>
 300         </varlistentry>
 301
 302         <varlistentry>
 303           <term><varname>c</varname></term>
 304           <term><varname>c+</varname></term>
 305           <listitem><para>Create a character device node if it does
 306           not exist yet. If suffixed with <varname>+</varname> and a
 307           file already exists where the device node is to be created,
 308           it will be removed and be replaced by the device node. It is
 309           recommended to suffix this entry with an exclamation mark to
 310           only create static device nodes at boot, as udev will not
 311           manage static device nodes that are created at runtime.
 312           </para></listitem>
 313         </varlistentry>
 314
 315         <varlistentry>
 316           <term><varname>b</varname></term>
 317           <term><varname>b+</varname></term>
 318           <listitem><para>Create a block device node if it does not
 319           exist yet. If suffixed with <varname>+</varname> and a file
 320           already exists where the device node is to be created, it
 321           will be removed and be replaced by the device node. It is
 322           recommended to suffix this entry with an exclamation mark to
 323           only create static device nodes at boot, as udev will not
 324           manage static device nodes that are created at runtime.
 325           </para></listitem>
 326         </varlistentry>
 327
 328         <varlistentry>
 329           <term><varname>C</varname></term>
 330           <term><varname>C+</varname></term>
 331           <listitem><para>Recursively copy a file or directory, if the destination files or directories do
 332           not exist yet or the destination directory is empty. Note that this command will not descend into
 333           subdirectories if the destination directory already exists and is not empty, unless the action is
 334           suffixed with <varname>+</varname>. Instead, the entire copy operation is skipped. If the argument
 335           is omitted, files from the source directory <filename>/usr/share/factory/</filename> with the same
 336           name are copied. Does not follow symlinks. Contents of the directories are subject to time-based
 337           cleanup if the age argument is specified.
 338           </para></listitem>
 339         </varlistentry>
 340
 341         <varlistentry>
 342           <term><varname>x</varname></term>
 343           <listitem><para>Ignore a path during cleaning. Use this type
 344           to exclude paths from clean-up as controlled with the Age
 345           parameter. Note that lines of this type do not influence the
 346           effect of <varname>r</varname> or <varname>R</varname>
 347           lines. Lines of this type accept shell-style globs in place
 348           of normal path names.  </para></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. Unlike <varname>x</varname>, this parameter will
 356           not exclude the content if path is a directory, but only
 357           directory itself. Note that lines of this type do not
 358           influence the effect of <varname>r</varname> or
 359           <varname>R</varname> lines. Lines of this type accept
 360           shell-style globs in place of normal path names.
 361           </para></listitem>
 362         </varlistentry>
 363
 364         <varlistentry>
 365           <term><varname>r</varname></term>
 366           <listitem><para>Remove a file or directory if it exists.
 367           This may not be used to remove non-empty directories, use
 368           <varname>R</varname> for that.  Lines of this type accept
 369           shell-style globs in place of normal path
 370           names. Does not follow symlinks.</para></listitem>
 371         </varlistentry>
 372
 373         <varlistentry>
 374           <term><varname>R</varname></term>
 375           <listitem><para>Recursively remove a path and all its
 376           subdirectories (if it is a directory). Lines of this type
 377           accept shell-style globs in place of normal path
 378           names. Does not follow symlinks.</para></listitem>
 379         </varlistentry>
 380
 381         <varlistentry>
 382           <term><varname>z</varname></term>
 383           <listitem><para>Adjust the access mode, user and group ownership, and restore the SELinux security
 384           context of a file or directory, if it exists. Lines of this type accept shell-style globs in place
 385           of normal path names. Does not follow symlinks.</para></listitem>
 386         </varlistentry>
 387
 388         <varlistentry>
 389           <term><varname>Z</varname></term>
 390           <listitem><para>Recursively set the access mode, user and group ownership, and restore the SELinux
 391           security context of a file or directory if it exists, as well as of its subdirectories and the
 392           files contained therein (if applicable). Lines of this type accept shell-style globs in place of
 393           normal path names. Does not follow symlinks.</para></listitem>
 394         </varlistentry>
 395
 396         <varlistentry>
 397           <term><varname>t</varname></term>
 398           <listitem><para>Set extended attributes, see <citerefentry
 399           project='man-pages'><refentrytitle>attr</refentrytitle>
 400           <manvolnum>5</manvolnum></citerefentry> for details. The argument field should take one or more
 401           assignment expressions in the form
 402           <replaceable>namespace</replaceable>.<replaceable>attribute</replaceable>=<replaceable>value</replaceable>,
 403           for examples see below. Lines of this type accept shell-style globs in place of normal path
 404           names. This can be useful for setting SMACK labels. Does not follow symlinks.</para>
 405
 406           <para>Please note that extended attributes settable with this line type are a different concept
 407           from the Linux file attributes settable with <varname>h</varname>/<varname>H</varname>, see
 408           below.</para></listitem>
 409         </varlistentry>
 410
 411         <varlistentry>
 412           <term><varname>T</varname></term>
 413           <listitem><para>Same as <varname>t</varname>, but operates recursively.</para></listitem>
 414         </varlistentry>
 415
 416         <varlistentry>
 417           <term><varname>h</varname></term>
 418           <listitem><para>Set Linux file/directory attributes. Lines of this type accept shell-style globs in
 419           place of normal path names.</para>
 420
 421           <para>The format of the argument field is <varname>[+-=][aAcCdDeijPsStTu]</varname>. The prefix
 422           <varname>+</varname> (the default one) causes the attributes to be added; <varname>-</varname>
 423           causes the attributes to be removed; <varname>=</varname> causes the attributes to be set exactly
 424           as the following letters. The letters <literal>aAcCdDeijPsStTu</literal> select the new attributes
 425           for the files, see <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle>
 426           <manvolnum>1</manvolnum></citerefentry> for further information.
 427           </para>
 428
 429           <para>Passing only <varname>=</varname> as argument resets all the file attributes listed above. It
 430           has to be pointed out that the <varname>=</varname> prefix limits itself to the attributes
 431           corresponding to the letters listed here. All other attributes will be left untouched. Does not
 432           follow symlinks.</para>
 433
 434           <para>Please note that the Linux file attributes settable with this line type are a different
 435           concept from the extended attributes settable with <varname>t</varname>/<varname>T</varname>,
 436           see above.</para></listitem>
 437         </varlistentry>
 438
 439         <varlistentry>
 440           <term><varname>H</varname></term>
 441           <listitem><para>Sames as <varname>h</varname>, but operates recursively.</para></listitem>
 442         </varlistentry>
 443
 444         <varlistentry>
 445           <term><varname>a</varname></term>
 446           <term><varname>a+</varname></term>
 447           <listitem><para>Set POSIX ACLs (access control lists), see <citerefentry
 448           project='man-pages'><refentrytitle>acl</refentrytitle>
 449           <manvolnum>5</manvolnum></citerefentry>. Additionally, if 'X' is used, the execute bit is set only
 450           if the file is a directory or already has execute permission for some user, as mentioned in
 451           <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 452           If suffixed with <varname>+</varname>, the specified entries will be added to the existing set.
 453           <command>systemd-tmpfiles</command> will automatically add the required base entries for user
 454           and group based on the access mode of the file, unless base entries already exist or are explicitly
 455           specified. The mask will be added if not specified explicitly or already present. Lines of this type
 456           accept shell-style globs in place of normal path names. This can be useful for allowing additional
 457           access to certain files. Does not follow symlinks.</para></listitem>
 458         </varlistentry>
 459
 460         <varlistentry>
 461           <term><varname>A</varname></term>
 462           <term><varname>A+</varname></term>
 463           <listitem><para>Same as <varname>a</varname> and
 464           <varname>a+</varname>, but recursive. Does not follow
 465           symlinks.</para></listitem>
 466         </varlistentry>
 467       </variablelist>
 468     </refsect2>
 469
 470     <refsect2>
 471       <title>Type Modifiers</title>
 472
 473       <para>If the exclamation mark (<literal>!</literal>) is used, this line is only safe to execute during
 474       boot, and can break a running system. Lines without the exclamation mark are presumed to be safe to
 475       execute at any time, e.g. on package upgrades. <command>systemd-tmpfiles</command> will take lines with
 476       an exclamation mark only into consideration, if the <option>--boot</option> option is given.</para>
 477
 478       <para>For example:
 479       <programlisting># Make sure these are created by default so that nobody else can
 480 d /tmp/.X11-unix 1777 root root 10d
 481
 482 # Unlink the X11 lock files
 483 r! /tmp/.X[0-9]*-lock</programlisting>
 484       The second line in contrast to the first one would break a
 485       running system, and will only be executed with
 486       <option>--boot</option>.</para>
 487
 488       <para>If the minus sign (<literal>-</literal>) is used, this line failing to run successfully during
 489       create (and only create) will not cause the execution of <command>systemd-tmpfiles</command> to return
 490       an error.</para>
 491
 492       <para>For example:
 493       <programlisting># Modify sysfs but don't fail if we are in a container with a read-only /proc
 494 w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
 495
 496       <para>If the equals sign (<literal>=</literal>) is used, the file types of existing objects in the specified path
 497       are checked, and removed if they do not match. This includes any implicitly created parent directories (which can
 498       be either directories or directory symlinks). For example, if there is a FIFO in place of one of the parent path
 499       components it will be replaced with a directory.</para>
 500
 501       <para>If the tilde character (<literal>~</literal>) is used, the argument (i.e. 6th) column is <ulink
 502       url="https://www.rfc-editor.org/rfc/rfc4648.html">Base64 decoded</ulink> before use. This modifier is
 503       only supported on line types that can write file contents, i.e. <varname>f</varname>,
 504       <varname>f+</varname>, <varname>w</varname>, <varname>+</varname>. This is useful for writing arbitrary
 505       binary data (including newlines and NUL bytes) to files. Note that if this switch is used, the argument
 506       is not subject to specifier expansion, neither before nor after Base64 decoding.</para>
 507
 508       <para>If the caret character (<literal>^</literal>) is used, the argument (i.e. 6th) column takes a
 509       service credential name to read the argument data from. See <ulink
 510       url="https://systemd.io/CREDENTIALS">System and Service Credentials</ulink> for details about the
 511       credentials concept. This modifier is only supported on line types that can write file contents,
 512       i.e. <varname>f</varname>, <varname>f+</varname>, <varname>w</varname>, <varname>w+</varname>. This is
 513       useful for writing arbitrary files with contents sourced from elsewhere, including from VM or container
 514       managers further up. If the specified credential is not set for the <command>systemd-tmpfiles</command>
 515       service, the line is silently skipped. If <literal>^</literal> and <literal>~</literal> are combined
 516       Base64 decoding is applied to the credential contents.</para>
 517
 518       <para>Note that for all line types that result in creation of any kind of file node
 519       (i.e. <varname>f</varname>/<varname>F</varname>,
 520       <varname>d</varname>/<varname>D</varname>/<varname>v</varname>/<varname>q</varname>/<varname>Q</varname>,
 521       <varname>p</varname>, <varname>L</varname>, <varname>c</varname>/<varname>b</varname> and <varname>C</varname>)
 522       leading directories are implicitly created if needed, owned by root with an access mode of 0755. In order to
 523       create them with different modes or ownership make sure to add appropriate <varname>d</varname> lines.</para>
 524     </refsect2>
 525
 526     <refsect2>
 527       <title>Path</title>
 528
 529       <para>The file system path specification supports simple
 530       specifier expansion, see below. The path (after expansion) must be
 531       absolute.</para>
 532     </refsect2>
 533
 534     <refsect2>
 535       <title>Mode</title>
 536
 537       <para>The file access mode to use when creating this file or directory. If omitted or when set to
 538       <literal>-</literal>, the default is used: 0755 for directories, 0644 for all other file objects. For
 539       <varname>z</varname>, <varname>Z</varname> lines, if omitted or when set to <literal>-</literal>, the
 540       file access mode will not be modified. This parameter is ignored for <varname>x</varname>,
 541       <varname>r</varname>, <varname>R</varname>, <varname>L</varname>, <varname>t</varname>, and
 542       <varname>a</varname> lines.</para>
 543
 544       <para>Optionally, if prefixed with <literal>~</literal>, the access mode is masked based on the already
 545       set access bits for existing file or directories: if the existing file has all executable bits unset,
 546       all executable bits are removed from the new access mode, too. Similarly, if all read bits are removed
 547       from the old access mode, they will be removed from the new access mode too, and if all write bits are
 548       removed, they will be removed from the new access mode too. In addition, the sticky/SUID/SGID bit is
 549       removed unless applied to a directory. This functionality is particularly useful in conjunction with
 550       <varname>Z</varname>.</para>
 551
 552       <para>Optionally, if prefixed with <literal>:</literal>, the configured access mode is only used when
 553       creating new inodes. If the inode the line refers to already exists, its access mode is left in place
 554       unmodified.</para>
 555     </refsect2>
 556
 557     <refsect2>
 558       <title>User, Group</title>
 559
 560       <para>The user and group to use for this file or directory. This may either be a numeric ID or a
 561       user/group name. If omitted or when set to <literal>-</literal>, the user and group of the user who
 562       invokes <command>systemd-tmpfiles</command> is used. For <varname>z</varname> and <varname>Z</varname>
 563       lines, when omitted or when set to <literal>-</literal>, the file ownership will not be modified. These
 564       parameters are ignored for <varname>x</varname>, <varname>r</varname>, <varname>R</varname>,
 565       <varname>L</varname>, <varname>t</varname>, and <varname>a</varname> lines.</para>
 566
 567       <para>This field should generally only reference system users/groups, i.e. users/groups that are
 568       guaranteed to be resolvable during early boot. If this field references users/groups that only become
 569       resolveable during later boot (i.e. after NIS, LDAP or a similar networked directory service become
 570       available), execution of the operations declared by the line will likely fail. Also see <ulink
 571       url="https://systemd.io/UIDS-GIDS/#notes-on-resolvability-of-user-and-group-names">Notes on
 572       Resolvability of User and Group Names</ulink> for more information on requirements on system user/group
 573       definitions.</para>
 574
 575       <para>Optionally, if prefixed with <literal>:</literal>, the configured user/group information is only
 576       used when creating new inodes. If the inode the line refers to already exists, its user/group is left
 577       in place unmodified.</para>
 578     </refsect2>
 579
 580     <refsect2>
 581       <title>Age</title>
 582
 583       <para>The date field, when set, is used to decide what files to
 584       delete when cleaning. If a file or directory is older than the
 585       current time minus the age field, it is deleted. The field
 586       format is a series of integers each followed by one of the
 587       following suffixes for the respective time units:
 588       <constant>s</constant>,
 589       <constant>m</constant> or <constant>min</constant>,
 590       <constant>h</constant>,
 591       <constant>d</constant>,
 592       <constant>w</constant>,
 593       <constant>ms</constant>, and
 594       <constant>us</constant>,
 595       meaning seconds, minutes, hours, days, weeks,
 596       milliseconds, and microseconds, respectively. Full names of the time units can
 597       be used too.
 598       </para>
 599
 600       <para>If multiple integers and units are specified, the time
 601       values are summed. If an integer is given without a unit,
 602       <constant>s</constant> is assumed.
 603       </para>
 604
 605       <para>When the age is set to zero, the files are cleaned
 606       unconditionally.</para>
 607
 608       <para>The age field only applies to lines starting with
 609       <varname>d</varname>, <varname>D</varname>, <varname>e</varname>,
 610       <varname>v</varname>, <varname>q</varname>,
 611       <varname>Q</varname>, <varname>C</varname>, <varname>x</varname>
 612       and <varname>X</varname>. If omitted or set to
 613       <literal>-</literal>, no automatic clean-up is done.</para>
 614
 615       <para>If the age field starts with a tilde character <literal>~</literal>, clean-up is only applied to
 616       files and directories one level inside the directory specified, but not the files and directories
 617       immediately inside it.</para>
 618
 619       <para>The age of a file system entry is determined from its last
 620       modification timestamp (mtime), its last access timestamp (atime),
 621       and (except for directories) its last status change timestamp
 622       (ctime). By default, any of these three (or two) values will
 623       prevent cleanup if it is more recent than the current time minus
 624       the age field. To restrict the deletion based on particular type
 625       of file timestamps, the age-by argument can be used.</para>
 626
 627       <para>The age-by argument overrides the timestamp types to be used for the age check. It can be
 628       specified by prefixing the age argument with a sequence of characters to specify the timestamp types
 629       and a colon (<literal>:</literal>):
 630       <literal><replaceable>age-by</replaceable>...:<replaceable>cleanup-age</replaceable></literal>.  The
 631       argument can consist of <constant>a</constant> (<constant>A</constant> for directories),
 632       <constant>b</constant> (<constant>B</constant> for directories), <constant>c</constant>
 633       (<constant>C</constant> for directories), or <constant>m</constant> (<constant>M</constant> for
 634       directories). Those respectively indicate access, creation, last status change, and last modification
 635       time of a file system entry. The lower-case letter signifies that the given timestamp type should be
 636       considered for files, while the upper-case letter signifies that the given timestamp type should be
 637       considered for directories. See <citerefentry
 638       project='man-pages'><refentrytitle>statx</refentrytitle><manvolnum>2</manvolnum></citerefentry> file
 639       timestamp fields for more details about timestamp types.</para>
 640
 641       <para>If not specified, the age-by field defaults to <constant>abcmABM</constant>, i.e. by default all
 642       file timestamps are taken into consideration, with the exception of the last status change timestamp
 643       (ctime) for directories. This is because the aging logic itself will alter the ctime whenever it
 644       deletes a file inside it. To ensure that running the aging logic does not feed back into the next
 645       iteration of itself, ctime for directories is ignored by default.</para>
 646
 647       <para>For example:<programlisting>
 648 # Files created and modified, and directories accessed more than
 649 # an hour ago in "/tmp/foo/bar", are subject to time-based cleanup.
 650 d /tmp/foo/bar - - - bmA:1h -</programlisting></para>
 651
 652       <para>Note that while the aging algorithm is run an exclusive BSD file lock (see <citerefentry
 653       project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) is
 654       taken on each directory/file the algorithm decides to remove. If the aging algorithm finds a lock (
 655       shared or exclusive) is already taken on some directory/file, it (and everything below it) is skipped.
 656       Applications may use this to temporarily exclude certain directory subtrees from the aging algorithm:
 657       the applications can take a BSD file lock themselves, and as long as they keep it aging of the
 658       directory/file and everything below it is disabled.</para>
 659     </refsect2>
 660
 661     <refsect2>
 662       <title>Argument</title>
 663
 664       <para>For <varname>L</varname> lines determines the destination path of the symlink. For <varname>c</varname> and
 665       <varname>b</varname>, determines the major/minor of the device node, with major and minor formatted as integers,
 666       separated by <literal>:</literal>, e.g.  <literal>1:3</literal>. For <varname>f</varname>, <varname>F</varname>,
 667       and <varname>w</varname>, the argument may be used to specify a short string that is written to the file,
 668       suffixed by a newline. For <varname>C</varname>, specifies the source file or directory. For <varname>t</varname>
 669       and <varname>T</varname>, determines extended attributes to be set. For <varname>a</varname> and
 670       <varname>A</varname>, determines ACL attributes to be set. For <varname>h</varname> and <varname>H</varname>,
 671       determines the file attributes to set. Ignored for all other lines.</para>
 672
 673       <para>This field can contain specifiers, see below.</para>
 674     </refsect2>
 675   </refsect1>
 676
 677   <refsect1>
 678     <title>Specifiers</title>
 679
 680     <para>Specifiers can be used in the "path" and "argument" fields.
 681     An unknown or unresolvable specifier is treated as invalid configuration.
 682     The following expansions are understood:</para>
 683       <table class='specifiers'>
 684         <title>Specifiers available</title>
 685         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 686           <colspec colname="spec" />
 687           <colspec colname="mean" />
 688           <colspec colname="detail" />
 689           <thead>
 690             <row>
 691               <entry>Specifier</entry>
 692               <entry>Meaning</entry>
 693               <entry>Details</entry>
 694             </row>
 695           </thead>
 696           <tbody>
 697             <xi:include href="standard-specifiers.xml" xpointer="a"/>
 698             <xi:include href="standard-specifiers.xml" xpointer="A"/>
 699             <xi:include href="standard-specifiers.xml" xpointer="b"/>
 700             <xi:include href="standard-specifiers.xml" xpointer="B"/>
 701             <row>
 702               <entry><literal>%C</literal></entry>
 703               <entry>System or user cache directory</entry>
 704               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CACHE_HOME</varname>, and <filename>/var/cache</filename> otherwise.</entry>
 705             </row>
 706             <row>
 707               <entry><literal>%g</literal></entry>
 708               <entry>User group</entry>
 709               <entry>This is the name of the group running the command. In case of the system instance this resolves to <literal>root</literal>.</entry>
 710             </row>
 711             <row>
 712               <entry><literal>%G</literal></entry>
 713               <entry>User GID</entry>
 714               <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>
 715             </row>
 716             <row>
 717               <entry><literal>%h</literal></entry>
 718               <entry>User home directory</entry>
 719               <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>
 720             </row>
 721             <xi:include href="standard-specifiers.xml" xpointer="H"/>
 722             <xi:include href="standard-specifiers.xml" xpointer="l"/>
 723             <row>
 724               <entry><literal>%L</literal></entry>
 725               <entry>System or user log directory</entry>
 726               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname> with <filename index="false">/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
 727             </row>
 728             <xi:include href="standard-specifiers.xml" xpointer="m"/>
 729             <xi:include href="standard-specifiers.xml" xpointer="M"/>
 730             <xi:include href="standard-specifiers.xml" xpointer="o"/>
 731             <row>
 732               <entry><literal>%S</literal></entry>
 733               <entry>System or user state directory</entry>
 734               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname>, and <filename>/var/lib</filename> otherwise.</entry>
 735             </row>
 736             <row>
 737               <entry><literal>%t</literal></entry>
 738               <entry>System or user runtime directory</entry>
 739               <entry>In <option>--user</option> mode, this is the same <varname>$XDG_RUNTIME_DIR</varname>, and <filename>/run/</filename> otherwise.</entry>
 740             </row>
 741             <xi:include href="standard-specifiers.xml" xpointer="T"/>
 742             <row>
 743               <entry><literal>%u</literal></entry>
 744               <entry>User name</entry>
 745               <entry>This is the name of the user running the command. In case of the system instance this resolves to <literal>root</literal>.</entry>
 746             </row>
 747             <row>
 748               <entry><literal>%U</literal></entry>
 749               <entry>User UID</entry>
 750               <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>
 751             </row>
 752             <xi:include href="standard-specifiers.xml" xpointer="v"/>
 753             <xi:include href="standard-specifiers.xml" xpointer="V"/>
 754             <xi:include href="standard-specifiers.xml" xpointer="w"/>
 755             <xi:include href="standard-specifiers.xml" xpointer="W"/>
 756             <xi:include href="standard-specifiers.xml" xpointer="percent"/>
 757           </tbody>
 758         </tgroup>
 759       </table>
 760   </refsect1>
 761
 762   <refsect1>
 763     <title>Examples</title>
 764     <example>
 765       <title>Create directories with specific mode and ownership</title>
 766       <para>
 767       <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 768       needs two directories created at boot with specific modes and ownership:</para>
 769
 770       <programlisting># /usr/lib/tmpfiles.d/screen.conf
 771 d /run/screens  1777 root screen 10d
 772 d /run/uscreens 0755 root screen 10d12h
 773 </programlisting>
 774
 775       <para>Contents of <filename>/run/screens</filename> and /run/uscreens will
 776       be cleaned up after 10 and 10½ days, respectively.</para>
 777     </example>
 778
 779     <example>
 780       <title>Create a directory with a SMACK attribute</title>
 781       <programlisting>D /run/cups - - - -
 782 t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar"
 783       </programlisting>
 784
 785       <para>The directory will be owned by root and have default mode. Its contents are
 786       not subject to time-based cleanup, but will be obliterated when
 787       <command>systemd-tmpfiles --remove</command> runs.</para>
 788     </example>
 789
 790     <example>
 791       <title>Create a directory and prevent its contents from cleanup</title>
 792       <para>
 793       <citerefentry project='die-net'><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 794       needs a directory created at boot with specific mode and ownership and its content
 795       should be preserved from the automatic cleanup applied to the contents of
 796       <filename>/var/tmp</filename>:</para>
 797
 798       <programlisting># /usr/lib/tmpfiles.d/tmp.conf
 799 d /var/tmp 1777 root root 30d
 800 </programlisting>
 801
 802       <programlisting># /usr/lib/tmpfiles.d/abrt.conf
 803 d /var/tmp/abrt 0755 abrt abrt -
 804 </programlisting>
 805     </example>
 806
 807     <example>
 808       <title>Apply clean up during boot and based on time</title>
 809
 810       <programlisting># /usr/lib/tmpfiles.d/dnf.conf
 811 r! /var/cache/dnf/*/*/download_lock.pid
 812 r! /var/cache/dnf/*/*/metadata_lock.pid
 813 r! /var/lib/dnf/rpmdb_lock.pid
 814 e  /var/cache/dnf/ - - - 30d
 815 </programlisting>
 816
 817      <para>The lock files will be removed during boot. Any files and directories in
 818      <filename>/var/cache/dnf/</filename> will be removed after they have not been
 819      accessed in 30 days.</para>
 820     </example>
 821
 822     <example>
 823       <title>Empty the contents of a cache directory on boot</title>
 824
 825       <programlisting># /usr/lib/tmpfiles.d/krb5rcache.conf
 826 e! /var/cache/krb5rcache - - - 0
 827 </programlisting>
 828
 829       <para>Any files and subdirectories in <filename>/var/cache/krb5rcache/</filename>
 830       will be removed on boot. The directory will not be created.
 831       </para>
 832     </example>
 833
 834     <example>
 835       <title>Provision SSH public key access for root user via Credentials in QEMU</title>
 836
 837       <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)
 838 </programlisting>
 839
 840       <para>By passing this line to QEMU, the public key of the current user will be encoded in
 841       base64, added to a tmpfiles.d line that tells systemd-tmpfiles to decode it into
 842       <filename>/root/.ssh/authorized_keys</filename>, encode that line itself in base64 and
 843       pass it as a Credential that will be picked up by systemd from SMBIOS on boot.
 844       </para>
 845     </example>
 846   </refsect1>
 847
 848   <refsect1>
 849     <title><filename>/run/</filename> and <filename>/var/run/</filename></title>
 850     <para><filename>/var/run/</filename> is a deprecated symlink to <filename>/run/</filename>, and
 851     applications should use the latter. <command>systemd-tmpfiles</command> will warn if
 852     <filename>/var/run/</filename> is used.</para>
 853   </refsect1>
 854
 855   <refsect1>
 856     <title>See Also</title>
 857     <para>
 858       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 859       <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 860       <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 861       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 862       <citerefentry project='man-pages'><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 863       <citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 864       <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 865       <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 866       <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 867       <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 868       <citerefentry project='die-net'><refentrytitle>btrfs-subvolume</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 869       <citerefentry project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 870     </para>
 871   </refsect1>
 872
 873 </refentry>