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