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, all
 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                                         <listitem><para>Create a named pipe (FIFO) if it does not exist yet.</para></listitem>
 173                                 </varlistentry>
 174
 175                                 <varlistentry>
 176                                         <term><varname>L</varname></term>
 177                                         <listitem><para>Create a symlink if it does not exist yet.</para></listitem>
 178                                 </varlistentry>
 179
 180                                 <varlistentry>
 181                                         <term><varname>c</varname></term>
 182                                         <listitem><para>Create a character device node if it does not exist yet.</para></listitem>
 183                                 </varlistentry>
 184
 185                                 <varlistentry>
 186                                         <term><varname>b</varname></term>
 187                                         <listitem><para>Create a block device node if it does not exist yet.</para></listitem>
 188                                 </varlistentry>
 189
 190                                 <varlistentry>
 191                                         <term><varname>C</varname></term>
 192                                         <listitem><para>Recursively copy a file or directory, if the destination files or directories don't exist yet.</para></listitem>
 193                                 </varlistentry>
 194
 195                                 <varlistentry>
 196                                         <term><varname>x</varname></term>
 197                                         <listitem><para>Ignore a path
 198                                         during cleaning. Use this type
 199                                         to exclude paths from clean-up
 200                                         as controlled with the Age
 201                                         parameter. Note that lines of
 202                                         this type do not influence the
 203                                         effect of <varname>r</varname>
 204                                         or <varname>R</varname> lines.
 205                                         Lines of this type accept
 206                                         shell-style globs in place of
 207                                         normal path names.
 208                                         </para></listitem>
 209                                 </varlistentry>
 210
 211                                 <varlistentry>
 212                                         <term><varname>X</varname></term>
 213                                         <listitem><para>Ignore a path
 214                                         during cleaning. Use this type
 215                                         to exclude paths from clean-up
 216                                         as controlled with the Age
 217                                         parameter. Unlike
 218                                         <varname>x</varname>, this
 219                                         parameter will not exclude the
 220                                         content if path is a
 221                                         directory, but only directory
 222                                         itself. Note that lines of
 223                                         this type do not influence the
 224                                         effect of <varname>r</varname>
 225                                         or <varname>R</varname> lines.
 226                                         Lines of this type accept
 227                                         shell-style globs in place of
 228                                         normal path names.
 229                                         </para></listitem>
 230                                 </varlistentry>
 231
 232                                 <varlistentry>
 233                                         <term><varname>r</varname></term>
 234                                         <listitem><para>Remove a file
 235                                         or directory if it exists.
 236                                         This may not be used to remove
 237                                         non-empty directories, use
 238                                         <varname>R</varname> for that.
 239                                         Lines of this type accept
 240                                         shell-style globs in place of
 241                                         normal path
 242                                         names.</para></listitem>
 243                                 </varlistentry>
 244
 245                                 <varlistentry>
 246                                         <term><varname>R</varname></term>
 247                                         <listitem><para>Recursively
 248                                         remove a path and all its
 249                                         subdirectories (if it is a
 250                                         directory). Lines of this type
 251                                         accept shell-style globs in
 252                                         place of normal path
 253                                         names.</para></listitem>
 254                                 </varlistentry>
 255
 256                                 <varlistentry>
 257                                         <term><varname>z</varname></term>
 258                                         <listitem><para>Adjust the
 259                                         access mode, group and user,
 260                                         and restore the SELinux security
 261                                         context of a file or directory,
 262                                         if it exists. Lines of this
 263                                         type accept shell-style globs
 264                                         in place of normal path names.
 265                                         </para></listitem>
 266                                 </varlistentry>
 267
 268                                 <varlistentry>
 269                                         <term><varname>Z</varname></term>
 270                                         <listitem><para>Recursively
 271                                         set the access mode, group and
 272                                         user, and restore the SELinux
 273                                         security context of a file or
 274                                         directory if it exists, as
 275                                         well as of its subdirectories
 276                                         and the files contained
 277                                         therein (if applicable). Lines
 278                                         of this type accept
 279                                         shell-style globs in place of
 280                                         normal path
 281                                         names.</para></listitem>
 282                                 </varlistentry>
 283                         </variablelist>
 284
 285                         <para>If the exclamation mark is used, this
 286                         line is only safe of execute during boot, and
 287                         can break a running system. Lines without the
 288                         exclamation mark are presumed to be safe to
 289                         execute at any time, e.g. on package upgrades.
 290                         <command>systemd-tmpfiles</command> will
 291                         execute line with an exclamation mark only if
 292                         option <option>--boot</option> is given.
 293                         </para>
 294
 295                         <para>For example:
 296                         <programlisting># Make sure these are created by default so that nobody else can
 297 d /tmp/.X11-unix 1777 root root 10d
 298
 299 # Unlink the X11 lock files
 300 r! /tmp/.X[0-9]*-lock</programlisting>
 301                         The second line in contrast to the first one
 302                         would break a running system, and will only be
 303                         executed with <option>--boot</option>.</para>
 304                 </refsect2>
 305
 306                 <refsect2>
 307                         <title>Path</title>
 308
 309                         <para>The file system path specification supports simple specifier
 310                         expansion. The following expansions are
 311                         understood:</para>
 312
 313                         <table>
 314                                 <title>Specifiers available</title>
 315                                 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 316                                         <colspec colname="spec" />
 317                                         <colspec colname="mean" />
 318                                         <colspec colname="detail" />
 319                                         <thead>
 320                                                 <row>
 321                                                         <entry>Specifier</entry>
 322                                                         <entry>Meaning</entry>
 323                                                         <entry>Details</entry>
 324                                                 </row>
 325                                         </thead>
 326                                         <tbody>
 327                                                 <row>
 328                                                         <entry><literal>%m</literal></entry>
 329                                                         <entry>Machine ID</entry>
 330                                                         <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>
 331                                                 </row>
 332                                                 <row>
 333                                                         <entry><literal>%b</literal></entry>
 334                                                         <entry>Boot ID</entry>
 335                                                         <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
 336                                                 </row>
 337                                                 <row>
 338                                                         <entry><literal>%H</literal></entry>
 339                                                         <entry>Host name</entry>
 340                                                         <entry>The hostname of the running system.</entry>
 341                                                 </row>
 342                                                 <row>
 343                                                         <entry><literal>%v</literal></entry>
 344                                                         <entry>Kernel release</entry>
 345                                                         <entry>Identical to <command>uname -r</command> output.</entry>
 346                                                 </row>
 347                                                 <row>
 348                                                         <entry><literal>%%</literal></entry>
 349                                                         <entry>Escaped %</entry>
 350                                                         <entry>Single percent sign.</entry>
 351                                                 </row>
 352                                         </tbody>
 353                                 </tgroup>
 354                         </table>
 355                 </refsect2>
 356
 357                 <refsect2>
 358                         <title>Mode</title>
 359
 360                         <para>The file access mode to use when
 361                         creating this file or directory. If omitted or
 362                         when set to -, the default is used: 0755 for
 363                         directories, 0644 for all other file objects.
 364                         For <varname>z</varname>, <varname>Z</varname>
 365                         lines, if omitted or when set to
 366                         <literal>-</literal>, the file access mode
 367                         will not be modified. This parameter is
 368                         ignored for <varname>x</varname>,
 369                         <varname>r</varname>, <varname>R</varname>,
 370                         <varname>L</varname> lines.</para>
 371                 </refsect2>
 372
 373                 <refsect2>
 374                         <title>UID, GID</title>
 375
 376                         <para>The user and group to use for this file
 377                         or directory. This may either be a numeric
 378                         user/group ID or a user or group name. If
 379                         omitted or when set to <literal>-</literal>,
 380                         the default 0 (root) is used. For
 381                         <varname>z</varname>, <varname>Z</varname>
 382                         lines, when omitted or when set to -, the file
 383                         ownership will not be modified. These
 384                         parameters are ignored for
 385                         <varname>x</varname>, <varname>r</varname>,
 386                         <varname>R</varname>, <varname>L</varname>
 387                         lines.</para>
 388                 </refsect2>
 389
 390                 <refsect2>
 391                         <title>Age</title>
 392                         <para>The date field, when set, is used to
 393                         decide what files to delete when cleaning. If
 394                         a file or directory is older than the current
 395                         time minus the age field, it is deleted. The
 396                         field format is a series of integers each
 397                         followed by one of the following
 398                         postfixes for the respective time units:</para>
 399
 400                         <variablelist>
 401                                 <varlistentry>
 402                                 <term><varname>s</varname></term>
 403                                 <term><varname>min</varname></term>
 404                                 <term><varname>h</varname></term>
 405                                 <term><varname>d</varname></term>
 406                                 <term><varname>w</varname></term>
 407                                 <term><varname>ms</varname></term>
 408                                 <term><varname>m</varname></term>
 409                                 <term><varname>us</varname></term></varlistentry>
 410                         </variablelist>
 411
 412                         <para>If multiple integers and units are specified, the time
 413                         values are summed up. If an integer is given without a unit,
 414                         s is assumed.
 415                         </para>
 416
 417                         <para>When the age is set to zero, the files are cleaned
 418                         unconditionally.</para>
 419
 420                         <para>The age field only applies to lines
 421                         starting with <varname>d</varname>,
 422                         <varname>D</varname>, and
 423                         <varname>x</varname>. If omitted or set to
 424                         <literal>-</literal>, no automatic clean-up is
 425                         done.</para>
 426
 427                         <para>If the age field starts with a tilde
 428                         character <literal>~</literal>, the clean-up
 429                         is only applied to files and directories one
 430                         level inside the directory specified, but not
 431                         the files and directories immediately inside
 432                         it.</para>
 433                 </refsect2>
 434
 435                 <refsect2>
 436                         <title>Argument</title>
 437
 438                         <para>For <varname>L</varname> lines
 439                         determines the destination path of the
 440                         symlink. For <varname>c</varname>,
 441                         <varname>b</varname> determines the
 442                         major/minor of the device node, with major and
 443                         minor formatted as integers, separated by
 444                         <literal>:</literal>, e.g.
 445                         <literal>1:3</literal>. For
 446                         <varname>f</varname>, <varname>F</varname>,
 447                         and <varname>w</varname> may be used to
 448                         specify a short string that is written to the
 449                         file, suffixed by a newline. For
 450                         <varname>C</varname> specifies the source file
 451                         or directory. Ignored for all other
 452                         lines.</para>
 453                 </refsect2>
 454
 455         </refsect1>
 456
 457         <refsect1>
 458                 <title>Example</title>
 459                 <example>
 460                         <title>/etc/tmpfiles.d/screen.conf example</title>
 461                         <para><command>screen</command> needs two directories created at boot with specific modes and ownership.</para>
 462
 463                         <programlisting>d /run/screens  1777 root root 10d
 464 d /run/uscreens 0755 root root 10d12h</programlisting>
 465                 </example>
 466                 <example>
 467                         <title>/etc/tmpfiles.d/abrt.conf example</title>
 468                         <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para>
 469
 470                         <programlisting>d /var/tmp/abrt 0755 abrt abrt
 471 x /var/tmp/abrt/*</programlisting>
 472                 </example>
 473         </refsect1>
 474
 475         <refsect1>
 476                 <title>See Also</title>
 477                 <para>
 478                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 479                         <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 480                         <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 481                         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 482                 </para>
 483         </refsect1>
 484
 485 </refentry>