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. Otherwise, the
 105     files/directories are processed in the order they are
 106     listed.</para>
 107
 108     <para>If the administrator wants to disable a configuration file
 109     supplied by the vendor, the recommended way is to place a symlink
 110     to <filename>/dev/null</filename> in
 111     <filename>/etc/tmpfiles.d/</filename> bearing the same filename.
 112     </para>
 113
 114     <para>The configuration format is one line per path containing
 115     type, path, mode, ownership, age, and argument fields:</para>
 116
 117     <programlisting>#Type Path        Mode UID  GID  Age Argument
 118     d    /run/user   0755 root root 10d -
 119     L    /tmp/foobar -    -    -    -   /dev/null</programlisting>
 120
 121     <refsect2>
 122       <title>Type</title>
 123
 124       <para>The type consists of a single letter and optionally an
 125       exclamation mark.</para>
 126
 127       <para>The following line types are understood:</para>
 128
 129       <variablelist>
 130         <varlistentry>
 131           <term><varname>f</varname></term>
 132           <listitem><para>Create a file if it does not exist yet. If
 133           the argument parameter is given, it will be written to the
 134           file.</para></listitem>
 135         </varlistentry>
 136
 137         <varlistentry>
 138           <term><varname>F</varname></term>
 139           <listitem><para>Create or truncate a file. If the argument
 140           parameter is given, it will be written to the file.</para>
 141           </listitem>
 142         </varlistentry>
 143
 144         <varlistentry>
 145           <term><varname>w</varname></term>
 146           <listitem><para>Write the argument parameter to a file, if
 147           the file exists.  Lines of this type accept shell-style
 148           globs in place of normal path names. The argument parameter
 149           will be written without a trailing newline. C-style
 150           backslash escapes are interpreted.</para></listitem>
 151         </varlistentry>
 152
 153         <varlistentry>
 154           <term><varname>d</varname></term>
 155           <listitem><para>Create a directory if it does not exist yet.
 156           </para></listitem>
 157         </varlistentry>
 158
 159         <varlistentry>
 160           <term><varname>D</varname></term>
 161           <listitem><para>Create or empty a directory.</para></listitem>
 162         </varlistentry>
 163
 164         <varlistentry>
 165           <term><varname>v</varname></term>
 166           <listitem><para>Create a subvolume if the path does not
 167           exist yet and the file system supports this
 168           (btrfs). Otherwise create a normal directory, in the same
 169           way as <varname>d</varname>.</para></listitem>
 170         </varlistentry>
 171
 172         <varlistentry>
 173           <term><varname>p</varname></term>
 174           <term><varname>p+</varname></term>
 175           <listitem><para>Create a named pipe (FIFO) if it does not
 176           exist yet. If suffixed with <varname>+</varname> and a file
 177           already exists where the pipe is to be created, it will be
 178           removed and be replaced by the pipe.</para></listitem>
 179         </varlistentry>
 180
 181         <varlistentry>
 182           <term><varname>L</varname></term>
 183           <term><varname>L+</varname></term>
 184           <listitem><para>Create a symlink if it does not exist
 185           yet. If suffixed with <varname>+</varname> and a file
 186           already exists where the symlink is to be created, it will
 187           be removed and be replaced by the symlink. If the argument
 188           is omitted, symlinks to files with the same name residing in
 189           the directory <filename>/usr/share/factory/</filename> are
 190           created.</para></listitem>
 191         </varlistentry>
 192
 193         <varlistentry>
 194           <term><varname>c</varname></term>
 195           <term><varname>c+</varname></term>
 196           <listitem><para>Create a character device node if it does
 197           not exist yet. If suffixed with <varname>+</varname> and a
 198           file already exists where the device node is to be created,
 199           it will be removed and be replaced by the device node. It is
 200           recommended to suffix this entry with an exclamation mark to
 201           only create static device nodes at boot, as udev will not
 202           manage static device nodes that are created at runtime.
 203           </para></listitem>
 204         </varlistentry>
 205
 206         <varlistentry>
 207           <term><varname>b</varname></term>
 208           <term><varname>b+</varname></term>
 209           <listitem><para>Create a block device node if it does not
 210           exist yet. If suffixed with <varname>+</varname> and a file
 211           already exists where the device node is to be created, it
 212           will be removed and be replaced by the device node. It is
 213           recommended to suffix this entry with an exclamation mark to
 214           only create static device nodes at boot, as udev will not
 215           manage static device nodes that are created at runtime.
 216           </para></listitem>
 217         </varlistentry>
 218
 219         <varlistentry>
 220           <term><varname>C</varname></term>
 221           <listitem><para>Recursively copy a file or directory, if the
 222           destination files or directories do not exist yet. Note that
 223           this command will not descend into subdirectories if the
 224           destination directory already exists. Instead, the entire
 225           copy operation is skipped. If the argument is omitted, files
 226           from the source directory
 227           <filename>/usr/share/factory/</filename> with the same name
 228           are copied.</para></listitem>
 229         </varlistentry>
 230
 231         <varlistentry>
 232           <term><varname>x</varname></term>
 233           <listitem><para>Ignore a path during cleaning. Use this type
 234           to exclude paths from clean-up as controlled with the Age
 235           parameter. Note that lines of this type do not influence the
 236           effect of <varname>r</varname> or <varname>R</varname>
 237           lines.  Lines of this type accept shell-style globs in place
 238           of normal path names.  </para></listitem>
 239         </varlistentry>
 240
 241         <varlistentry>
 242           <term><varname>X</varname></term>
 243           <listitem><para>Ignore a path during cleaning. Use this type
 244           to exclude paths from clean-up as controlled with the Age
 245           parameter. Unlike <varname>x</varname>, this parameter will
 246           not exclude the content if path is a directory, but only
 247           directory itself. Note that lines of this type do not
 248           influence the effect of <varname>r</varname> or
 249           <varname>R</varname> lines.  Lines of this type accept
 250           shell-style globs in place of normal path names.
 251           </para></listitem>
 252         </varlistentry>
 253
 254         <varlistentry>
 255           <term><varname>r</varname></term>
 256           <listitem><para>Remove a file or directory if it exists.
 257           This may not be used to remove non-empty directories, use
 258           <varname>R</varname> for that.  Lines of this type accept
 259           shell-style globs in place of normal path
 260           names.</para></listitem>
 261         </varlistentry>
 262
 263         <varlistentry>
 264           <term><varname>R</varname></term>
 265           <listitem><para>Recursively remove a path and all its
 266           subdirectories (if it is a directory). Lines of this type
 267           accept shell-style globs in place of normal path
 268           names.</para></listitem>
 269         </varlistentry>
 270
 271         <varlistentry>
 272           <term><varname>z</varname></term>
 273           <listitem><para>Adjust the access mode, group and user, and
 274           restore the SELinux security context of a file or directory,
 275           if it exists. Lines of this type accept shell-style globs in
 276           place of normal path names.  </para></listitem>
 277         </varlistentry>
 278
 279         <varlistentry>
 280           <term><varname>Z</varname></term>
 281           <listitem><para>Recursively set the access mode, group and
 282           user, and restore the SELinux security context of a file or
 283           directory if it exists, as well as of its subdirectories and
 284           the files contained therein (if applicable). Lines of this
 285           type accept shell-style globs in place of normal path names.
 286           </para></listitem>
 287         </varlistentry>
 288
 289         <varlistentry>
 290           <term><varname>t</varname></term>
 291           <listitem><para>Set extended attributes on item. It may be
 292           used in conjunction with other types (only
 293           <varname>d</varname>, <varname>D</varname>,
 294           <varname>f</varname>, <varname>F</varname>,
 295           <varname>L</varname>, <varname>p</varname>,
 296           <varname>c</varname>, <varname>b</varname>, makes sense).
 297           If used as a standalone line, then
 298           <command>systemd-tmpfiles</command> will try to set extended
 299           attributes on specified path.  This can be especially used
 300           to set SMACK labels.  </para></listitem>
 301         </varlistentry>
 302       </variablelist>
 303
 304       <para>If the exclamation mark is used, this line is only safe of
 305       execute during boot, and can break a running system. Lines
 306       without the exclamation mark are presumed to be safe to execute
 307       at any time, e.g. on package upgrades.
 308       <command>systemd-tmpfiles</command> will execute line with an
 309       exclamation mark only if option <option>--boot</option> is
 310       given.</para>
 311
 312       <para>For example:
 313       <programlisting># Make sure these are created by default so that nobody else can
 314       d /tmp/.X11-unix 1777 root root 10d
 315
 316       # Unlink the X11 lock files
 317       r! /tmp/.X[0-9]*-lock</programlisting>
 318       The second line in contrast to the first one would break a
 319       running system, and will only be executed with
 320       <option>--boot</option>.</para>
 321     </refsect2>
 322
 323     <refsect2>
 324       <title>Path</title>
 325
 326       <para>The file system path specification supports simple
 327       specifier expansion. The following expansions are
 328       understood:</para>
 329
 330       <table>
 331         <title>Specifiers available</title>
 332         <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 333           <colspec colname="spec" />
 334           <colspec colname="mean" />
 335           <colspec colname="detail" />
 336           <thead>
 337             <row>
 338               <entry>Specifier</entry>
 339               <entry>Meaning</entry>
 340               <entry>Details</entry>
 341             </row>
 342           </thead>
 343           <tbody>
 344             <row>
 345               <entry><literal>%m</literal></entry>
 346               <entry>Machine ID</entry>
 347               <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>
 348             </row>
 349             <row>
 350               <entry><literal>%b</literal></entry>
 351               <entry>Boot ID</entry>
 352               <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
 353             </row>
 354             <row>
 355               <entry><literal>%H</literal></entry>
 356               <entry>Host name</entry>
 357               <entry>The hostname of the running system.</entry>
 358             </row>
 359             <row>
 360               <entry><literal>%v</literal></entry>
 361               <entry>Kernel release</entry>
 362               <entry>Identical to <command>uname -r</command> output.</entry>
 363             </row>
 364             <row>
 365               <entry><literal>%%</literal></entry>
 366               <entry>Escaped %</entry>
 367               <entry>Single percent sign.</entry>
 368             </row>
 369           </tbody>
 370         </tgroup>
 371       </table>
 372     </refsect2>
 373
 374     <refsect2>
 375       <title>Mode</title>
 376
 377       <para>The file access mode to use when creating this file or
 378       directory. If omitted or when set to <literal>-</literal>, the
 379       default is used: 0755 for directories, 0644 for all other file
 380       objects.  For <varname>z</varname>, <varname>Z</varname> lines,
 381       if omitted or when set to <literal>-</literal>, the file access
 382       mode will not be modified. This parameter is ignored for
 383       <varname>x</varname>, <varname>r</varname>,
 384       <varname>R</varname>, <varname>L</varname>, <varname>t</varname>
 385       lines.</para>
 386
 387       <para>Optionally, if prefixed with <literal>~</literal>, the
 388       access mode is masked based on the already set access bits for
 389       existing file or directories: if the existing file has all
 390       executable bits unset, all executable bits are removed from the
 391       new access mode, too. Similarly, if all read bits are removed
 392       from the old access mode, they will be removed from the new
 393       access mode too, and if all write bits are removed, they will be
 394       removed from the new access mode too. In addition, the
 395       sticky/SUID/SGID bit is removed unless applied to a
 396       directory. This functionality is particularly useful in
 397       conjunction with <varname>Z</varname>.</para>
 398     </refsect2>
 399
 400     <refsect2>
 401       <title>UID, GID</title>
 402
 403       <para>The user and group to use for this file or directory. This
 404       may either be a numeric user/group ID or a user or group
 405       name. If omitted or when set to <literal>-</literal>, the
 406       default 0 (root) is used. For <varname>z</varname>,
 407       <varname>Z</varname> lines, when omitted or when set to -, the
 408       file ownership will not be modified. These parameters are
 409       ignored for <varname>x</varname>, <varname>r</varname>,
 410       <varname>R</varname>, <varname>L</varname>, <varname>t</varname>
 411       lines.</para>
 412     </refsect2>
 413
 414     <refsect2>
 415       <title>Age</title>
 416       <para>The date field, when set, is used to decide what files to
 417       delete when cleaning. If a file or directory is older than the
 418       current time minus the age field, it is deleted. The field
 419       format is a series of integers each followed by one of the
 420       following postfixes for the respective time units:</para>
 421
 422       <variablelist>
 423         <varlistentry>
 424           <term><varname>s</varname></term>
 425           <term><varname>min</varname></term>
 426           <term><varname>h</varname></term>
 427           <term><varname>d</varname></term>
 428           <term><varname>w</varname></term>
 429           <term><varname>ms</varname></term>
 430           <term><varname>m</varname></term>
 431         <term><varname>us</varname></term></varlistentry>
 432       </variablelist>
 433
 434       <para>If multiple integers and units are specified, the time
 435       values are summed up. If an integer is given without a unit,
 436       <varname>s</varname> is assumed.
 437       </para>
 438
 439       <para>When the age is set to zero, the files are cleaned
 440       unconditionally.</para>
 441
 442       <para>The age field only applies to lines
 443       starting with <varname>d</varname>,
 444       <varname>D</varname>, and
 445       <varname>x</varname>. If omitted or set to
 446       <literal>-</literal>, no automatic clean-up is
 447       done.</para>
 448
 449       <para>If the age field starts with a tilde character
 450       <literal>~</literal>, the clean-up is only applied to files and
 451       directories one level inside the directory specified, but not
 452       the files and directories immediately inside it.</para>
 453     </refsect2>
 454
 455     <refsect2>
 456       <title>Argument</title>
 457
 458       <para>For <varname>L</varname> lines determines the destination
 459       path of the symlink. For <varname>c</varname>,
 460       <varname>b</varname> determines the major/minor of the device
 461       node, with major and minor formatted as integers, separated by
 462       <literal>:</literal>, e.g.  <literal>1:3</literal>. For
 463       <varname>f</varname>, <varname>F</varname>, and
 464       <varname>w</varname> may be used to specify a short string that
 465       is written to the file, suffixed by a newline. For
 466       <varname>C</varname>, specifies the source file or
 467       directory. For <varname>t</varname> determines extended
 468       attributes to be set. Ignored for all other lines.</para>
 469     </refsect2>
 470
 471   </refsect1>
 472
 473   <refsect1>
 474     <title>Example</title>
 475     <example>
 476       <title>/etc/tmpfiles.d/screen.conf example</title>
 477       <para><command>screen</command> needs two directories created at
 478       boot with specific modes and ownership.</para>
 479
 480       <programlisting>d /run/screens  1777 root root 10d
 481       d /run/uscreens 0755 root root 10d12h
 482       t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting>
 483     </example>
 484     <example>
 485       <title>/etc/tmpfiles.d/abrt.conf example</title>
 486       <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para>
 487
 488       <programlisting>d /var/tmp/abrt 0755 abrt abrt
 489       x /var/tmp/abrt/*</programlisting>
 490     </example>
 491   </refsect1>
 492
 493   <refsect1>
 494     <title>See Also</title>
 495     <para>
 496       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 497       <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 498       <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 499       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 500     </para>
 501   </refsect1>
 502
 503 </refentry>