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