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