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