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
  46                 cleaning of 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
  59                 configuration files from the above directories to describe the
  60                 creation, cleaning and removal of volatile and
  61                 temporary files and directories which usually reside
  62                 in directories such as <filename>/run</filename>
  63                 or <filename>/tmp</filename>.</para>
  64
  65                 <para>Volatile and temporary files and directories are
  66                 those located in <filename>/run</filename> (and its
  67                 alias <filename>/var/run</filename>),
  68                 <filename>/tmp</filename>,
  69                 <filename>/var/tmp</filename>, the API file systems
  70                 such as <filename>/sys</filename> or
  71                 <filename>/proc</filename>, as well as some other
  72                 directories below <filename>/var</filename>.</para>
  73
  74                 <para>System daemons frequently require private
  75                 runtime directories below <filename>/run</filename> to
  76                 place communication sockets and similar in. For these,
  77                 consider declaring them in their unit files using
  78                 <varname>RuntimeDirectory=</varname>
  79                 (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details),
  80                 if this is feasible.</para>
  81         </refsect1>
  82
  83         <refsect1>
  84                 <title>Configuration Format</title>
  85
  86                 <para>Each configuration file shall be named in the
  87                 style of
  88                 <filename><replaceable>package</replaceable>.conf</filename>
  89                 or
  90                 <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
  91                 The second variant should be used when it is desirable
  92                 to make it easy to override just this part of
  93                 configuration.</para>
  94
  95                 <para>Files in <filename>/etc/tmpfiles.d</filename>
  96                 override files with the same name in
  97                 <filename>/usr/lib/tmpfiles.d</filename> and
  98                 <filename>/run/tmpfiles.d</filename>. Files in
  99                 <filename>/run/tmpfiles.d</filename> override files
 100                 with the same name in
 101                 <filename>/usr/lib/tmpfiles.d</filename>. Packages
 102                 should install their configuration files in
 103                 <filename>/usr/lib/tmpfiles.d</filename>. Files in
 104                 <filename>/etc/tmpfiles.d</filename> are reserved for
 105                 the local administrator, who may use this logic to
 106                 override the configuration files installed by vendor
 107                 packages. All configuration files are sorted by their
 108                 filename in lexicographic order, regardless of which
 109                 of the directories they reside in. If multiple files
 110                 specify the same path, the entry in the file with the
 111                 lexicographically earliest name will be applied.
 112                 All other conflicting entries will be logged as
 113                 errors. When two lines are prefix and suffix of each
 114                 other, then the prefix is always processed first, the
 115                 suffix later. Otherwise, the files/directories are
 116                 processed in the order they are listed.</para>
 117
 118                 <para>If the administrator wants to disable a
 119                 configuration file supplied by the vendor, the
 120                 recommended way is to place a symlink to
 121                 <filename>/dev/null</filename> in
 122                 <filename>/etc/tmpfiles.d/</filename> bearing the
 123                 same filename.</para>
 124
 125                 <para>The configuration format is one line per path
 126                 containing type, path, mode, ownership, age, and argument
 127                 fields:</para>
 128
 129                 <programlisting>#Type Path        Mode UID  GID  Age Argument
 130 d    /run/user   0755 root root 10d -
 131 L    /tmp/foobar -    -    -    -   /dev/null</programlisting>
 132
 133                 <refsect2>
 134                         <title>Type</title>
 135
 136                         <para>The type consists of a single letter and
 137                         optionally an exclamation mark.</para>
 138
 139                         <para>The following line types are understood:</para>
 140
 141                         <variablelist>
 142                                 <varlistentry>
 143                                         <term><varname>f</varname></term>
 144                                         <listitem><para>Create a file if it does not exist yet. If the argument parameter is given, it will be written to the file.</para></listitem>
 145                                 </varlistentry>
 146
 147                                 <varlistentry>
 148                                         <term><varname>F</varname></term>
 149                                         <listitem><para>Create or truncate a file. If the argument parameter is given, it will be written to the file.</para></listitem>
 150                                 </varlistentry>
 151
 152                                 <varlistentry>
 153                                         <term><varname>w</varname></term>
 154                                         <listitem><para>Write the argument parameter to a file, if the file exists.
 155                                             Lines of this type accept shell-style globs in place of normal path
 156                                             names. The argument parameter will be written without a trailing
 157                                             newline. C-style backslash escapes are interpreted.</para></listitem>
 158                                 </varlistentry>
 159
 160                                 <varlistentry>
 161                                         <term><varname>d</varname></term>
 162                                         <listitem><para>Create a directory if it does not exist yet.</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>p</varname></term>
 172                                         <term><varname>p+</varname></term>
 173                                         <listitem><para>Create a named
 174                                         pipe (FIFO) if it does not
 175                                         exist yet. If suffixed with
 176                                         <varname>+</varname> and a
 177                                         file already exists where the
 178                                         pipe is to be created, it will
 179                                         be removed and be replaced by
 180                                         the pipe.</para></listitem>
 181                                 </varlistentry>
 182
 183                                 <varlistentry>
 184                                         <term><varname>L</varname></term>
 185                                         <term><varname>L+</varname></term>
 186                                         <listitem><para>Create a
 187                                         symlink if it does not exist
 188                                         yet. If suffixed with
 189                                         <varname>+</varname> and a
 190                                         file already exists where the
 191                                         symlink is to be created, it
 192                                         will be removed and be
 193                                         replaced by the
 194                                         symlink. If the argument is omitted,
 195                                         symlinks to files with the same name
 196                                         residing in the directory
 197                                         <filename>/usr/share/factory/</filename>
 198                                         are created.</para></listitem>
 199                                 </varlistentry>
 200
 201                                 <varlistentry>
 202                                         <term><varname>c</varname></term>
 203                                         <term><varname>c+</varname></term>
 204                                         <listitem><para>Create a
 205                                         character device node if it
 206                                         does not exist yet. If
 207                                         suffixed with
 208                                         <varname>+</varname> and a
 209                                         file already exists where the
 210                                         device node is to be created,
 211                                         it will be removed and be
 212                                         replaced by the device
 213                                         node. It is recommended to suffix this
 214                                         entry with an exclamation mark to only
 215                                         create static device nodes at boot,
 216                                         as udev will not manage static device
 217                                         nodes that are created at runtime.
 218                                         </para></listitem>
 219                                 </varlistentry>
 220
 221                                 <varlistentry>
 222                                         <term><varname>b</varname></term>
 223                                         <term><varname>b+</varname></term>
 224                                         <listitem><para>Create a block
 225                                         device node if it does not
 226                                         exist yet. If suffixed with
 227                                         <varname>+</varname> and a
 228                                         file already exists where the
 229                                         device node is to be created,
 230                                         it will be removed and be
 231                                         replaced by the device
 232                                         node. It is recommended to suffix this
 233                                         entry with an exclamation mark to only
 234                                         create static device nodes at boot,
 235                                         as udev will not manage static device
 236                                         nodes that are created at runtime.
 237                                         </para></listitem>
 238                                 </varlistentry>
 239
 240                                 <varlistentry>
 241                                         <term><varname>C</varname></term>
 242                                         <listitem><para>Recursively
 243                                         copy a file or directory, if
 244                                         the destination files or
 245                                         directories do not exist
 246                                         yet. Note that this command
 247                                         will not descend into
 248                                         subdirectories if the
 249                                         destination directory already
 250                                         exists. Instead, the entire
 251                                         copy operation is
 252                                         skipped. If the argument is omitted,
 253                                         files from the source directory
 254                                         <filename>/usr/share/factory/</filename>
 255                                         with the same name are copied.</para></listitem>
 256                                 </varlistentry>
 257
 258                                 <varlistentry>
 259                                         <term><varname>x</varname></term>
 260                                         <listitem><para>Ignore a path
 261                                         during cleaning. Use this type
 262                                         to exclude paths from clean-up
 263                                         as controlled with the Age
 264                                         parameter. Note that lines of
 265                                         this type do not influence the
 266                                         effect of <varname>r</varname>
 267                                         or <varname>R</varname> lines.
 268                                         Lines of this type accept
 269                                         shell-style globs in place of
 270                                         normal path names.
 271                                         </para></listitem>
 272                                 </varlistentry>
 273
 274                                 <varlistentry>
 275                                         <term><varname>X</varname></term>
 276                                         <listitem><para>Ignore a path
 277                                         during cleaning. Use this type
 278                                         to exclude paths from clean-up
 279                                         as controlled with the Age
 280                                         parameter. Unlike
 281                                         <varname>x</varname>, this
 282                                         parameter will not exclude the
 283                                         content if path is a
 284                                         directory, but only directory
 285                                         itself. Note that lines of
 286                                         this type do not influence the
 287                                         effect of <varname>r</varname>
 288                                         or <varname>R</varname> lines.
 289                                         Lines of this type accept
 290                                         shell-style globs in place of
 291                                         normal path names.
 292                                         </para></listitem>
 293                                 </varlistentry>
 294
 295                                 <varlistentry>
 296                                         <term><varname>r</varname></term>
 297                                         <listitem><para>Remove a file
 298                                         or directory if it exists.
 299                                         This may not be used to remove
 300                                         non-empty directories, use
 301                                         <varname>R</varname> for that.
 302                                         Lines of this type accept
 303                                         shell-style globs in place of
 304                                         normal path
 305                                         names.</para></listitem>
 306                                 </varlistentry>
 307
 308                                 <varlistentry>
 309                                         <term><varname>R</varname></term>
 310                                         <listitem><para>Recursively
 311                                         remove a path and all its
 312                                         subdirectories (if it is a
 313                                         directory). Lines of this type
 314                                         accept shell-style globs in
 315                                         place of normal path
 316                                         names.</para></listitem>
 317                                 </varlistentry>
 318
 319                                 <varlistentry>
 320                                         <term><varname>z</varname></term>
 321                                         <listitem><para>Adjust the
 322                                         access mode, group and user,
 323                                         and restore the SELinux security
 324                                         context of a file or directory,
 325                                         if it exists. Lines of this
 326                                         type accept shell-style globs
 327                                         in place of normal path names.
 328                                         </para></listitem>
 329                                 </varlistentry>
 330
 331                                 <varlistentry>
 332                                         <term><varname>Z</varname></term>
 333                                         <listitem><para>Recursively
 334                                         set the access mode, group and
 335                                         user, and restore the SELinux
 336                                         security context of a file or
 337                                         directory if it exists, as
 338                                         well as of its subdirectories
 339                                         and the files contained
 340                                         therein (if applicable). Lines
 341                                         of this type accept
 342                                         shell-style globs in place of
 343                                         normal path
 344                                         names.</para></listitem>
 345                                 </varlistentry>
 346
 347                                 <varlistentry>
 348                                         <term><varname>t</varname></term>
 349                                         <listitem><para>Set extended
 350                                         attributes on item. It may be
 351                                         used in conjunction with other
 352                                         types (only <varname>d</varname>,
 353                                         <varname>D</varname>, <varname>f</varname>,
 354                                         <varname>F</varname>, <varname>L</varname>,
 355                                         <varname>p</varname>, <varname>c</varname>,
 356                                         <varname>b</varname>, makes sense).
 357                                         If used as a standalone line, then
 358                                         <command>systemd-tmpfiles</command>
 359                                         will try to set extended
 360                                         attributes on specified path.
 361                                         This can be especially used to set
 362                                         SMACK labels.
 363                                         </para></listitem>
 364                                 </varlistentry>
 365                         </variablelist>
 366
 367                         <para>If the exclamation mark is used, this
 368                         line is only safe of execute during boot, and
 369                         can break a running system. Lines without the
 370                         exclamation mark are presumed to be safe to
 371                         execute at any time, e.g. on package upgrades.
 372                         <command>systemd-tmpfiles</command> will
 373                         execute line with an exclamation mark only if
 374                         option <option>--boot</option> is given.
 375                         </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
 384                         would break a running system, and will only be
 385                         executed with <option>--boot</option>.</para>
 386                 </refsect2>
 387
 388                 <refsect2>
 389                         <title>Path</title>
 390
 391                         <para>The file system path specification supports simple specifier
 392                         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
 443                         creating this file or directory. If omitted or
 444                         when set to -, the default is used: 0755 for
 445                         directories, 0644 for all other file objects.
 446                         For <varname>z</varname>, <varname>Z</varname>
 447                         lines, if omitted or when set to
 448                         <literal>-</literal>, the file access mode
 449                         will not be modified. This parameter is
 450                         ignored for <varname>x</varname>,
 451                         <varname>r</varname>, <varname>R</varname>,
 452                         <varname>L</varname>, <varname>t</varname> lines.</para>
 453
 454                         <para>Optionally, if prefixed with
 455                         <literal>~</literal>, the access mode is masked
 456                         based on the already set access bits for
 457                         existing file or directories: if the existing
 458                         file has all executable bits unset, all
 459                         executable bits are removed from the new
 460                         access mode, too. Similarly, if all read bits
 461                         are removed from the old access mode, they will
 462                         be removed from the new access mode too, and
 463                         if all write bits are removed, they will be
 464                         removed from the new access mode too. In
 465                         addition, the sticky/SUID/SGID bit is removed unless
 466                         applied to a directory. This
 467                         functionality is particularly useful in
 468                         conjunction with <varname>Z</varname>.</para>
 469                 </refsect2>
 470
 471                 <refsect2>
 472                         <title>UID, GID</title>
 473
 474                         <para>The user and group to use for this file
 475                         or directory. This may either be a numeric
 476                         user/group ID or a user or group name. If
 477                         omitted or when set to <literal>-</literal>,
 478                         the default 0 (root) is used. For
 479                         <varname>z</varname>, <varname>Z</varname>
 480                         lines, when omitted or when set to -, the file
 481                         ownership will not be modified. These
 482                         parameters are ignored for
 483                         <varname>x</varname>, <varname>r</varname>,
 484                         <varname>R</varname>, <varname>L</varname>,
 485                         <varname>t</varname> lines.</para>
 486                 </refsect2>
 487
 488                 <refsect2>
 489                         <title>Age</title>
 490                         <para>The date field, when set, is used to
 491                         decide what files to delete when cleaning. If
 492                         a file or directory is older than the current
 493                         time minus the age field, it is deleted. The
 494                         field format is a series of integers each
 495                         followed by one of the following
 496                         postfixes for the respective time units:</para>
 497
 498                         <variablelist>
 499                                 <varlistentry>
 500                                 <term><varname>s</varname></term>
 501                                 <term><varname>min</varname></term>
 502                                 <term><varname>h</varname></term>
 503                                 <term><varname>d</varname></term>
 504                                 <term><varname>w</varname></term>
 505                                 <term><varname>ms</varname></term>
 506                                 <term><varname>m</varname></term>
 507                                 <term><varname>us</varname></term></varlistentry>
 508                         </variablelist>
 509
 510                         <para>If multiple integers and units are specified, the time
 511                         values are summed up. If an integer is given without a unit,
 512                         s is assumed.
 513                         </para>
 514
 515                         <para>When the age is set to zero, the files are cleaned
 516                         unconditionally.</para>
 517
 518                         <para>The age field only applies to lines
 519                         starting with <varname>d</varname>,
 520                         <varname>D</varname>, and
 521                         <varname>x</varname>. If omitted or set to
 522                         <literal>-</literal>, no automatic clean-up is
 523                         done.</para>
 524
 525                         <para>If the age field starts with a tilde
 526                         character <literal>~</literal>, the clean-up
 527                         is only applied to files and directories one
 528                         level inside the directory specified, but not
 529                         the files and directories immediately inside
 530                         it.</para>
 531                 </refsect2>
 532
 533                 <refsect2>
 534                         <title>Argument</title>
 535
 536                         <para>For <varname>L</varname> lines
 537                         determines the destination path of the
 538                         symlink. For <varname>c</varname>,
 539                         <varname>b</varname> determines the
 540                         major/minor of the device node, with major and
 541                         minor formatted as integers, separated by
 542                         <literal>:</literal>, e.g.
 543                         <literal>1:3</literal>. For
 544                         <varname>f</varname>, <varname>F</varname>,
 545                         and <varname>w</varname> may be used to
 546                         specify a short string that is written to the
 547                         file, suffixed by a newline. For
 548                         <varname>C</varname>, specifies the source file
 549                         or directory. For <varname>t</varname> determines
 550                         extended attributes to be set. Ignored for all other lines.</para>
 551                 </refsect2>
 552
 553         </refsect1>
 554
 555         <refsect1>
 556                 <title>Example</title>
 557                 <example>
 558                         <title>/etc/tmpfiles.d/screen.conf example</title>
 559                         <para><command>screen</command> needs two directories created at boot with specific modes and ownership.</para>
 560
 561                         <programlisting>d /run/screens  1777 root root 10d
 562 d /run/uscreens 0755 root root 10d12h
 563 t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting>
 564                 </example>
 565                 <example>
 566                         <title>/etc/tmpfiles.d/abrt.conf example</title>
 567                         <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para>
 568
 569                         <programlisting>d /var/tmp/abrt 0755 abrt abrt
 570 x /var/tmp/abrt/*</programlisting>
 571                 </example>
 572         </refsect1>
 573
 574         <refsect1>
 575                 <title>See Also</title>
 576                 <para>
 577                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 578                         <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 579                         <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 580                         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 581                 </para>
 582         </refsect1>
 583
 584 </refentry>