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