man/tmpfiles.d.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!--
   5   This file is part of systemd.
   6
   7   Copyright 2010 Brandon Philips
   8
   9   systemd is free software; you can redistribute it and/or modify it
  10   under the terms of the GNU Lesser General Public License as published by
  11   the Free Software Foundation; either version 2.1 of the License, or
  12   (at your option) any later version.
  13
  14   systemd is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  21 -->
  22 <refentry id="tmpfiles.d">
  23
  24   <refentryinfo>
  25     <title>tmpfiles.d</title>
  26     <productname>systemd</productname>
  27
  28     <authorgroup>
  29       <author>
  30         <contrib>Documentation</contrib>
  31         <firstname>Brandon</firstname>
  32         <surname>Philips</surname>
  33         <email>brandon@ifup.org</email>
  34       </author>
  35     </authorgroup>
  36   </refentryinfo>
  37
  38   <refmeta>
  39     <refentrytitle>tmpfiles.d</refentrytitle>
  40     <manvolnum>5</manvolnum>
  41   </refmeta>
  42
  43   <refnamediv>
  44     <refname>tmpfiles.d</refname>
  45     <refpurpose>Configuration for creation, deletion and cleaning of
  46     volatile and temporary files</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <para><filename>/etc/tmpfiles.d/*.conf</filename></para>
  51     <para><filename>/run/tmpfiles.d/*.conf</filename></para>
  52     <para><filename>/usr/lib/tmpfiles.d/*.conf</filename></para>
  53   </refsynopsisdiv>
  54
  55   <refsect1>
  56     <title>Description</title>
  57
  58     <para><command>systemd-tmpfiles</command> uses the configuration
  59     files from the above directories to describe the creation,
  60     cleaning and removal of volatile and temporary files and
  61     directories which usually reside in directories such as
  62     <filename>/run</filename> or <filename>/tmp</filename>.</para>
  63
  64     <para>Volatile and temporary files and directories are those
  65     located in <filename>/run</filename> (and its alias
  66     <filename>/var/run</filename>), <filename>/tmp</filename>,
  67     <filename>/var/tmp</filename>, the API file systems such as
  68     <filename>/sys</filename> or <filename>/proc</filename>, as well
  69     as some other directories below <filename>/var</filename>.</para>
  70
  71     <para>System daemons frequently require private runtime
  72     directories below <filename>/run</filename> to place communication
  73     sockets and similar in. For these, consider declaring them in
  74     their unit files using <varname>RuntimeDirectory=</varname> (see
  75     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  76     for details), if this is feasible.</para>
  77   </refsect1>
  78
  79   <refsect1>
  80     <title>Configuration Format</title>
  81
  82     <para>Each configuration file shall be named in the style of
  83     <filename><replaceable>package</replaceable>.conf</filename> or
  84     <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
  85     The second variant should be used when it is desirable to make it
  86     easy to override just this part of configuration.</para>
  87
  88     <para>Files in <filename>/etc/tmpfiles.d</filename> override files
  89     with the same name in <filename>/usr/lib/tmpfiles.d</filename> and
  90     <filename>/run/tmpfiles.d</filename>. Files in
  91     <filename>/run/tmpfiles.d</filename> override files with the same
  92     name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should
  93     install their configuration files in
  94     <filename>/usr/lib/tmpfiles.d</filename>. Files in
  95     <filename>/etc/tmpfiles.d</filename> are reserved for the local
  96     administrator, who may use this logic to override the
  97     configuration files installed by vendor packages. All
  98     configuration files are sorted by their filename in lexicographic
  99     order, regardless of which of the directories they reside in. If
 100     multiple files specify the same path, the entry in the file with
 101     the lexicographically earliest name will be applied.  All other
 102     conflicting entries will be logged as errors. When two lines are
 103     prefix and suffix of each other, then the prefix is always
 104     processed first, the suffix later. Lines that take globs are
 105     applied after those accepting no globs. If multiple operations
 106     shall be applied on the same file (such as ACL, xattr, file
 107     attribute adjustments) these are always done in the same fixed
 108     order. Otherwise, the files/directories are processed in the order
 109     they are listed.</para>
 110
 111     <para>If the administrator wants to disable a configuration file
 112     supplied by the vendor, the recommended way is to place a symlink
 113     to <filename>/dev/null</filename> in
 114     <filename>/etc/tmpfiles.d/</filename> bearing the same filename.
 115     </para>
 116
 117     <para>The configuration format is one line per path containing
 118     type, path, mode, ownership, age, and argument fields:</para>
 119
 120     <programlisting>#Type Path        Mode UID  GID  Age Argument
 121     d    /run/user   0755 root root 10d -
 122     L    /tmp/foobar -    -    -    -   /dev/null</programlisting>
 123
 124     <para>Fields may be enclosed within quotes and contain C-style escapes.</para>
 125
 126     <refsect2>
 127       <title>Type</title>
 128
 129       <para>The type consists of a single letter and optionally an
 130       exclamation mark.</para>
 131
 132       <para>The following line types are understood:</para>
 133
 134       <variablelist>
 135         <varlistentry>
 136           <term><varname>f</varname></term>
 137           <listitem><para>Create a file if it does not exist yet. If
 138           the argument parameter is given, it will be written to the
 139           file. Does not follow symlinks.</para></listitem>
 140         </varlistentry>
 141
 142         <varlistentry>
 143           <term><varname>F</varname></term>
 144           <listitem><para>Create or truncate a file. If the argument
 145           parameter is given, it will be written to the file. Does not follow symlinks.</para>
 146           </listitem>
 147         </varlistentry>
 148
 149         <varlistentry>
 150           <term><varname>w</varname></term>
 151           <listitem><para>Write the argument parameter to a file, if
 152           the file exists.  Lines of this type accept shell-style
 153           globs in place of normal path names. The argument parameter
 154           will be written without a trailing newline. C-style
 155           backslash escapes are interpreted. Follows
 156           symlinks.</para></listitem>
 157         </varlistentry>
 158
 159         <varlistentry>
 160           <term><varname>d</varname></term>
 161           <listitem><para>Create a directory if it does not exist yet.
 162           </para></listitem>
 163         </varlistentry>
 164
 165         <varlistentry>
 166           <term><varname>D</varname></term>
 167           <listitem><para>Create or empty a directory.</para></listitem>
 168         </varlistentry>
 169
 170         <varlistentry>
 171           <term><varname>v</varname></term>
 172           <listitem><para>Create a subvolume if the path does not
 173           exist yet and the file system supports this
 174           (btrfs). Otherwise create a normal directory, in the same
 175           way as <varname>d</varname>.</para></listitem>
 176         </varlistentry>
 177
 178         <varlistentry>
 179           <term><varname>p</varname></term>
 180           <term><varname>p+</varname></term>
 181           <listitem><para>Create a named pipe (FIFO) if it does not
 182           exist yet. If suffixed with <varname>+</varname> and a file
 183           already exists where the pipe is to be created, it will be
 184           removed and be replaced by the pipe.</para></listitem>
 185         </varlistentry>
 186
 187         <varlistentry>
 188           <term><varname>L</varname></term>
 189           <term><varname>L+</varname></term>
 190           <listitem><para>Create a symlink if it does not exist
 191           yet. If suffixed with <varname>+</varname> and a file
 192           already exists where the symlink is to be created, it will
 193           be removed and be replaced by the symlink. If the argument
 194           is omitted, symlinks to files with the same name residing in
 195           the directory <filename>/usr/share/factory/</filename> are
 196           created.</para></listitem>
 197         </varlistentry>
 198
 199         <varlistentry>
 200           <term><varname>c</varname></term>
 201           <term><varname>c+</varname></term>
 202           <listitem><para>Create a character device node if it does
 203           not exist yet. If suffixed with <varname>+</varname> and a
 204           file already exists where the device node is to be created,
 205           it will be removed and be replaced by the device node. It is
 206           recommended to suffix this entry with an exclamation mark to
 207           only create static device nodes at boot, as udev will not
 208           manage static device nodes that are created at runtime.
 209           </para></listitem>
 210         </varlistentry>
 211
 212         <varlistentry>
 213           <term><varname>b</varname></term>
 214           <term><varname>b+</varname></term>
 215           <listitem><para>Create a block device node if it does not
 216           exist yet. If suffixed with <varname>+</varname> and a file
 217           already exists where the device node is to be created, it
 218           will be removed and be replaced by the device node. It is
 219           recommended to suffix this entry with an exclamation mark to
 220           only create static device nodes at boot, as udev will not
 221           manage static device nodes that are created at runtime.
 222           </para></listitem>
 223         </varlistentry>
 224
 225         <varlistentry>
 226           <term><varname>C</varname></term>
 227           <listitem><para>Recursively copy a file or directory, if the
 228           destination files or directories do not exist yet. Note that
 229           this command will not descend into subdirectories if the
 230           destination directory already exists. Instead, the entire
 231           copy operation is skipped. If the argument is omitted, files
 232           from the source directory
 233           <filename>/usr/share/factory/</filename> with the same name
 234           are copied. Does not follow symlinks.</para></listitem>
 235         </varlistentry>
 236
 237         <varlistentry>
 238           <term><varname>x</varname></term>
 239           <listitem><para>Ignore a path during cleaning. Use this type
 240           to exclude paths from clean-up as controlled with the Age
 241           parameter. Note that lines of this type do not influence the
 242           effect of <varname>r</varname> or <varname>R</varname>
 243           lines. Lines of this type accept shell-style globs in place
 244           of normal path names.  </para></listitem>
 245         </varlistentry>
 246
 247         <varlistentry>
 248           <term><varname>X</varname></term>
 249           <listitem><para>Ignore a path during cleaning. Use this type
 250           to exclude paths from clean-up as controlled with the Age
 251           parameter. Unlike <varname>x</varname>, this parameter will
 252           not exclude the content if path is a directory, but only
 253           directory itself. Note that lines of this type do not
 254           influence the effect of <varname>r</varname> or
 255           <varname>R</varname> lines. Lines of this type accept
 256           shell-style globs in place of normal path names.
 257           </para></listitem>
 258         </varlistentry>
 259
 260         <varlistentry>
 261           <term><varname>r</varname></term>
 262           <listitem><para>Remove a file or directory if it exists.
 263           This may not be used to remove non-empty directories, use
 264           <varname>R</varname> for that.  Lines of this type accept
 265           shell-style globs in place of normal path
 266           names. Does not follow symlinks.</para></listitem>
 267         </varlistentry>
 268
 269         <varlistentry>
 270           <term><varname>R</varname></term>
 271           <listitem><para>Recursively remove a path and all its
 272           subdirectories (if it is a directory). Lines of this type
 273           accept shell-style globs in place of normal path
 274           names. Does not follow symlinks.</para></listitem>
 275         </varlistentry>
 276
 277         <varlistentry>
 278           <term><varname>z</varname></term>
 279           <listitem><para>Adjust the access mode, group and user, and
 280           restore the SELinux security context of a file or directory,
 281           if it exists. Lines of this type accept shell-style globs in
 282           place of normal path names. Does not follow symlinks.</para></listitem>
 283         </varlistentry>
 284
 285         <varlistentry>
 286           <term><varname>Z</varname></term>
 287           <listitem><para>Recursively set the access mode, group and
 288           user, and restore the SELinux security context of a file or
 289           directory if it exists, as well as of its subdirectories and
 290           the files contained therein (if applicable). Lines of this
 291           type accept shell-style globs in place of normal path
 292           names. Does not follow symlinks.  </para></listitem>
 293         </varlistentry>
 294
 295         <varlistentry>
 296           <term><varname>t</varname></term>
 297           <listitem><para>Set extended attributes. Lines of this type
 298           accept shell-style globs in place of normal path names.
 299           This can be useful for setting SMACK labels. Does not follow
 300           symlinks.</para></listitem>
 301         </varlistentry>
 302
 303         <varlistentry>
 304           <term><varname>T</varname></term>
 305           <listitem><para>Recursively set extended attributes. Lines
 306           of this type accept shell-style globs in place of normal
 307           path names.  This can be useful for setting SMACK
 308           labels. Does not follow symlinks.  </para></listitem>
 309         </varlistentry>
 310
 311         <varlistentry>
 312           <term><varname>h</varname></term>
 313           <listitem><para>Set file/directory attributes. Lines of this type
 314           accept shell-style globs in place of normal path names.</para>
 315
 316           <para>The format of the argument field is
 317           <varname>[+-=][aAcCdDeijsStTu] </varname>. The prefix
 318           <varname>+</varname> (the default one) causes the
 319           attribute(s) to be added; <varname>-</varname> causes the
 320           attribute(s) to be removed; <varname>=</varname> causes the
 321           attributes to set exactly as the following letters. The
 322           letters <literal>aAcCdDeijsStTu</literal> select the new
 323           attributes for the files, see
 324           <citerefentry><refentrytitle>chattr</refentrytitle>
 325           <manvolnum>1</manvolnum></citerefentry> for further information.
 326           </para>
 327           <para>Passing only <varname>=</varname> as argument resets
 328           all the file attributes listed above. It has to be pointed
 329           out that the <varname>=</varname> prefix, limits itself to
 330           the attributes corresponding to the letters listed here. All
 331           other attributes will be left untouched. Does not follow
 332           symlinks.</para>
 333           </listitem>
 334         </varlistentry>
 335
 336         <varlistentry>
 337           <term><varname>H</varname></term>
 338           <listitem><para>Recursively set file/directory attributes. Lines
 339           of this type accept shell-style globs in place of normal
 340           path names. Does not follow symlinks.
 341           </para></listitem>
 342         </varlistentry>
 343
 344         <varlistentry>
 345           <term><varname>a</varname></term>
 346           <term><varname>a+</varname></term>
 347           <listitem><para>Set POSIX ACLs (access control lists). If
 348           suffixed with <varname>+</varname>, specified entries will
 349           be added to the existing set.
 350           <command>systemd-tmpfiles</command> will automatically add
 351           the required base entries for user and group based on the
 352           access mode of the file, unless base entries already exist
 353           or are explictly specified. The mask will be added if not
 354           specified explicitly or already present. Lines of this type
 355           accept shell-style globs in place of normal path names. This
 356           can be useful for allowing additional access to certain
 357           files. Does not follow symlinks.</para></listitem>
 358         </varlistentry>
 359
 360         <varlistentry>
 361           <term><varname>A</varname></term>
 362           <term><varname>A+</varname></term>
 363           <listitem><para>Same as <varname>a</varname> and
 364           <varname>a+</varname>, but recursive. Does not follow
 365           symlinks.</para></listitem>
 366         </varlistentry>
 367       </variablelist>
 368
 369       <para>If the exclamation mark is used, this line is only safe of
 370       execute during boot, and can break a running system. Lines
 371       without the exclamation mark are presumed to be safe to execute
 372       at any time, e.g. on package upgrades.
 373       <command>systemd-tmpfiles</command> will execute line with an
 374       exclamation mark only if option <option>--boot</option> is
 375       given.</para>
 376
 377       <para>For example:
 378       <programlisting># Make sure these are created by default so that nobody else can
 379       d /tmp/.X11-unix 1777 root root 10d
 380
 381       # Unlink the X11 lock files
 382       r! /tmp/.X[0-9]*-lock</programlisting>
 383       The second line in contrast to the first one would break a
 384       running system, and will only be executed with
 385       <option>--boot</option>.</para>
 386     </refsect2>
 387
 388     <refsect2>
 389       <title>Path</title>
 390
 391       <para>The file system path specification supports simple
 392       specifier expansion. The following expansions are
 393       understood:</para>
 394
 395       <table>
 396         <title>Specifiers available</title>
 397         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 398           <colspec colname="spec" />
 399           <colspec colname="mean" />
 400           <colspec colname="detail" />
 401           <thead>
 402             <row>
 403               <entry>Specifier</entry>
 404               <entry>Meaning</entry>
 405               <entry>Details</entry>
 406             </row>
 407           </thead>
 408           <tbody>
 409             <row>
 410               <entry><literal>%m</literal></entry>
 411               <entry>Machine ID</entry>
 412               <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
 413             </row>
 414             <row>
 415               <entry><literal>%b</literal></entry>
 416               <entry>Boot ID</entry>
 417               <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
 418             </row>
 419             <row>
 420               <entry><literal>%H</literal></entry>
 421               <entry>Host name</entry>
 422               <entry>The hostname of the running system.</entry>
 423             </row>
 424             <row>
 425               <entry><literal>%v</literal></entry>
 426               <entry>Kernel release</entry>
 427               <entry>Identical to <command>uname -r</command> output.</entry>
 428             </row>
 429             <row>
 430               <entry><literal>%%</literal></entry>
 431               <entry>Escaped %</entry>
 432               <entry>Single percent sign.</entry>
 433             </row>
 434           </tbody>
 435         </tgroup>
 436       </table>
 437     </refsect2>
 438
 439     <refsect2>
 440       <title>Mode</title>
 441
 442       <para>The file access mode to use when creating this file or
 443       directory. If omitted or when set to <literal>-</literal>, the
 444       default is used: 0755 for directories, 0644 for all other file
 445       objects.  For <varname>z</varname>, <varname>Z</varname> lines,
 446       if omitted or when set to <literal>-</literal>, the file access
 447       mode will not be modified. This parameter is ignored for
 448       <varname>x</varname>, <varname>r</varname>,
 449       <varname>R</varname>, <varname>L</varname>, <varname>t</varname>,
 450       and <varname>a</varname> lines.</para>
 451
 452       <para>Optionally, if prefixed with <literal>~</literal>, the
 453       access mode is masked based on the already set access bits for
 454       existing file or directories: if the existing file has all
 455       executable bits unset, all executable bits are removed from the
 456       new access mode, too. Similarly, if all read bits are removed
 457       from the old access mode, they will be removed from the new
 458       access mode too, and if all write bits are removed, they will be
 459       removed from the new access mode too. In addition, the
 460       sticky/SUID/SGID bit is removed unless applied to a
 461       directory. This functionality is particularly useful in
 462       conjunction with <varname>Z</varname>.</para>
 463     </refsect2>
 464
 465     <refsect2>
 466       <title>UID, GID</title>
 467
 468       <para>The user and group to use for this file or directory. This
 469       may either be a numeric user/group ID or a user or group
 470       name. If omitted or when set to <literal>-</literal>, the
 471       default 0 (root) is used. For <varname>z</varname>,
 472       <varname>Z</varname> lines, when omitted or when set to
 473       <literal>-</literal>, the file ownership will not be
 474       modified. These parameters are ignored for <varname>x</varname>,
 475       <varname>r</varname>, <varname>R</varname>,
 476       <varname>L</varname>, <varname>t</varname>, and
 477       <varname>a</varname> lines.</para>
 478     </refsect2>
 479
 480     <refsect2>
 481       <title>Age</title>
 482       <para>The date field, when set, is used to decide what files to
 483       delete when cleaning. If a file or directory is older than the
 484       current time minus the age field, it is deleted. The field
 485       format is a series of integers each followed by one of the
 486       following postfixes for the respective time units:
 487       <constant>s</constant>,
 488       <constant>m</constant> or <constant>min</constant>,
 489       <constant>h</constant>,
 490       <constant>d</constant>,
 491       <constant>w</constant>,
 492       <constant>ms</constant>,
 493       <constant>us</constant>,
 494       respectively meaning seconds, minutes, hours, days, weeks,
 495       milliseconds, and microseconds. Full names of the time units can
 496       be used too.
 497       </para>
 498
 499       <para>If multiple integers and units are specified, the time
 500       values are summed. If an integer is given without a unit,
 501       <constant>s</constant> is assumed.
 502       </para>
 503
 504       <para>When the age is set to zero, the files are cleaned
 505       unconditionally.</para>
 506
 507       <para>The age field only applies to lines
 508       starting with <varname>d</varname>,
 509       <varname>D</varname>, and
 510       <varname>x</varname>. If omitted or set to
 511       <literal>-</literal>, no automatic clean-up is
 512       done.</para>
 513
 514       <para>If the age field starts with a tilde character
 515       <literal>~</literal>, the clean-up is only applied to files and
 516       directories one level inside the directory specified, but not
 517       the files and directories immediately inside it.</para>
 518     </refsect2>
 519
 520     <refsect2>
 521       <title>Argument</title>
 522
 523       <para>For <varname>L</varname> lines determines the destination
 524       path of the symlink. For <varname>c</varname>,
 525       <varname>b</varname> determines the major/minor of the device
 526       node, with major and minor formatted as integers, separated by
 527       <literal>:</literal>, e.g.  <literal>1:3</literal>. For
 528       <varname>f</varname>, <varname>F</varname>, and
 529       <varname>w</varname> may be used to specify a short string that
 530       is written to the file, suffixed by a newline. For
 531       <varname>C</varname>, specifies the source file or
 532       directory. For <varname>t</varname>, <varname>T</varname>
 533       determines extended attributes to be set. For
 534       <varname>a</varname>, <varname>A</varname> determines ACL
 535       attributes to be set. For <varname>h</varname>,
 536       <varname>H</varname> determines the file attributes to
 537       set. Ignored for all other lines.</para>
 538     </refsect2>
 539
 540   </refsect1>
 541
 542   <refsect1>
 543     <title>Example</title>
 544     <example>
 545       <title>/etc/tmpfiles.d/screen.conf example</title>
 546       <para><command>screen</command> needs two directories created at
 547       boot with specific modes and ownership.</para>
 548
 549       <programlisting>d /run/screens  1777 root root 10d
 550 d /run/uscreens 0755 root root 10d12h
 551 t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting>
 552     </example>
 553     <example>
 554       <title>/etc/tmpfiles.d/abrt.conf example</title>
 555       <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para>
 556
 557       <programlisting>d /var/tmp/abrt 0755 abrt abrt
 558 x /var/tmp/abrt/*</programlisting>
 559     </example>
 560   </refsect1>
 561
 562   <refsect1>
 563     <title>See Also</title>
 564     <para>
 565       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 566       <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 567       <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 568       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 569       <citerefentry project='man-pages'><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 570       <citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 571       <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 572       <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 573       <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 574       <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 575     </para>
 576   </refsect1>
 577
 578 </refentry>