3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5 This file is part of systemd.
7 Copyright 2010 Brandon Philips
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.
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.
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/>.
22 <refentry id="tmpfiles.d">
25 <title>tmpfiles.d</title>
26 <productname>systemd</productname>
30 <contrib>Documentation</contrib>
31 <firstname>Brandon</firstname>
32 <surname>Philips</surname>
33 <email>brandon@ifup.org</email>
39 <refentrytitle>tmpfiles.d</refentrytitle>
40 <manvolnum>5</manvolnum>
44 <refname>tmpfiles.d</refname>
45 <refpurpose>Configuration for creation, deletion and cleaning of
46 volatile and temporary files</refpurpose>
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>
56 <title>Description</title>
58 <para><command>systemd-tmpfiles</command> uses the configuration
59 files from the above directories to describe the creation,
60 cleaning and removal of volatile and temporary files and
61 directories which usually reside in directories such as
62 <filename>/run</filename> or <filename>/tmp</filename>.</para>
64 <para>Volatile and temporary files and directories are those
65 located in <filename>/run</filename> (and its alias
66 <filename>/var/run</filename>), <filename>/tmp</filename>,
67 <filename>/var/tmp</filename>, the API file systems such as
68 <filename>/sys</filename> or <filename>/proc</filename>, as well
69 as some other directories below <filename>/var</filename>.</para>
71 <para>System daemons frequently require private runtime
72 directories below <filename>/run</filename> to place communication
73 sockets and similar in. For these, consider declaring them in
74 their unit files using <varname>RuntimeDirectory=</varname> (see
75 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
76 for details), if this is feasible.</para>
80 <title>Configuration Format</title>
82 <para>Each configuration file shall be named in the style of
83 <filename><replaceable>package</replaceable>.conf</filename> or
84 <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
85 The second variant should be used when it is desirable to make it
86 easy to override just this part of configuration.</para>
88 <para>Files in <filename>/etc/tmpfiles.d</filename> override files
89 with the same name in <filename>/usr/lib/tmpfiles.d</filename> and
90 <filename>/run/tmpfiles.d</filename>. Files in
91 <filename>/run/tmpfiles.d</filename> override files with the same
92 name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should
93 install their configuration files in
94 <filename>/usr/lib/tmpfiles.d</filename>. Files in
95 <filename>/etc/tmpfiles.d</filename> are reserved for the local
96 administrator, who may use this logic to override the
97 configuration files installed by vendor packages. All
98 configuration files are sorted by their filename in lexicographic
99 order, regardless of which of the directories they reside in. If
100 multiple files specify the same path, the entry in the file with
101 the lexicographically earliest name will be applied. All other
102 conflicting entries will be logged as errors. When two lines are
103 prefix and suffix of each other, then the prefix is always
104 processed first, the suffix later. Otherwise, the
105 files/directories are processed in the order they are
108 <para>If the administrator wants to disable a configuration file
109 supplied by the vendor, the recommended way is to place a symlink
110 to <filename>/dev/null</filename> in
111 <filename>/etc/tmpfiles.d/</filename> bearing the same filename.
114 <para>The configuration format is one line per path containing
115 type, path, mode, ownership, age, and argument fields:</para>
117 <programlisting>#Type Path Mode UID GID Age Argument
118 d /run/user 0755 root root 10d -
119 L /tmp/foobar - - - - /dev/null</programlisting>
121 <para>Fields may be enclosed within quotes and contain C-style escapes.</para>
126 <para>The type consists of a single letter and optionally an
127 exclamation mark.</para>
129 <para>The following line types are understood:</para>
133 <term><varname>f</varname></term>
134 <listitem><para>Create a file if it does not exist yet. If
135 the argument parameter is given, it will be written to the
136 file.</para></listitem>
140 <term><varname>F</varname></term>
141 <listitem><para>Create or truncate a file. If the argument
142 parameter is given, it will be written to the file.</para>
147 <term><varname>w</varname></term>
148 <listitem><para>Write the argument parameter to a file, if
149 the file exists. Lines of this type accept shell-style
150 globs in place of normal path names. The argument parameter
151 will be written without a trailing newline. C-style
152 backslash escapes are interpreted.</para></listitem>
156 <term><varname>d</varname></term>
157 <listitem><para>Create a directory if it does not exist yet.
162 <term><varname>D</varname></term>
163 <listitem><para>Create or empty a directory.</para></listitem>
167 <term><varname>v</varname></term>
168 <listitem><para>Create a subvolume if the path does not
169 exist yet and the file system supports this
170 (btrfs). Otherwise create a normal directory, in the same
171 way as <varname>d</varname>.</para></listitem>
175 <term><varname>p</varname></term>
176 <term><varname>p+</varname></term>
177 <listitem><para>Create a named pipe (FIFO) if it does not
178 exist yet. If suffixed with <varname>+</varname> and a file
179 already exists where the pipe is to be created, it will be
180 removed and be replaced by the pipe.</para></listitem>
184 <term><varname>L</varname></term>
185 <term><varname>L+</varname></term>
186 <listitem><para>Create a symlink if it does not exist
187 yet. If suffixed with <varname>+</varname> and a file
188 already exists where the symlink is to be created, it will
189 be removed and be replaced by the symlink. If the argument
190 is omitted, symlinks to files with the same name residing in
191 the directory <filename>/usr/share/factory/</filename> are
192 created.</para></listitem>
196 <term><varname>c</varname></term>
197 <term><varname>c+</varname></term>
198 <listitem><para>Create a character device node if it does
199 not exist yet. If suffixed with <varname>+</varname> and a
200 file already exists where the device node is to be created,
201 it will be removed and be replaced by the device node. It is
202 recommended to suffix this entry with an exclamation mark to
203 only create static device nodes at boot, as udev will not
204 manage static device nodes that are created at runtime.
209 <term><varname>b</varname></term>
210 <term><varname>b+</varname></term>
211 <listitem><para>Create a block device node if it does not
212 exist yet. If suffixed with <varname>+</varname> and a file
213 already exists where the device node is to be created, it
214 will be removed and be replaced by the device node. It is
215 recommended to suffix this entry with an exclamation mark to
216 only create static device nodes at boot, as udev will not
217 manage static device nodes that are created at runtime.
222 <term><varname>C</varname></term>
223 <listitem><para>Recursively copy a file or directory, if the
224 destination files or directories do not exist yet. Note that
225 this command will not descend into subdirectories if the
226 destination directory already exists. Instead, the entire
227 copy operation is skipped. If the argument is omitted, files
228 from the source directory
229 <filename>/usr/share/factory/</filename> with the same name
230 are copied.</para></listitem>
234 <term><varname>x</varname></term>
235 <listitem><para>Ignore a path during cleaning. Use this type
236 to exclude paths from clean-up as controlled with the Age
237 parameter. Note that lines of this type do not influence the
238 effect of <varname>r</varname> or <varname>R</varname>
239 lines. Lines of this type accept shell-style globs in place
240 of normal path names. </para></listitem>
244 <term><varname>X</varname></term>
245 <listitem><para>Ignore a path during cleaning. Use this type
246 to exclude paths from clean-up as controlled with the Age
247 parameter. Unlike <varname>x</varname>, this parameter will
248 not exclude the content if path is a directory, but only
249 directory itself. Note that lines of this type do not
250 influence the effect of <varname>r</varname> or
251 <varname>R</varname> lines. Lines of this type accept
252 shell-style globs in place of normal path names.
257 <term><varname>r</varname></term>
258 <listitem><para>Remove a file or directory if it exists.
259 This may not be used to remove non-empty directories, use
260 <varname>R</varname> for that. Lines of this type accept
261 shell-style globs in place of normal path
262 names.</para></listitem>
266 <term><varname>R</varname></term>
267 <listitem><para>Recursively remove a path and all its
268 subdirectories (if it is a directory). Lines of this type
269 accept shell-style globs in place of normal path
270 names.</para></listitem>
274 <term><varname>z</varname></term>
275 <listitem><para>Adjust the access mode, group and user, and
276 restore the SELinux security context of a file or directory,
277 if it exists. Lines of this type accept shell-style globs in
278 place of normal path names.</para></listitem>
282 <term><varname>Z</varname></term>
283 <listitem><para>Recursively set the access mode, group and
284 user, and restore the SELinux security context of a file or
285 directory if it exists, as well as of its subdirectories and
286 the files contained therein (if applicable). Lines of this
287 type accept shell-style globs in place of normal path names.
292 <term><varname>t</varname></term>
293 <listitem><para>Set extended attributes. Lines of this type
294 accept shell-style globs in place of normal path names.
295 This can be useful for setting SMACK labels.
300 <term><varname>T</varname></term>
301 <listitem><para>Recursively set extended attributes. Lines
302 of this type accept shell-style globs in place of normal
303 path names. This can be useful for setting SMACK labels.
308 <term><varname>a</varname></term>
309 <term><varname>a+</varname></term>
310 <listitem><para>Set POSIX ACLs (access control lists). If
311 suffixed with <varname>+</varname>, specified entries will
312 be added to the existing set.
313 <command>systemd-tmpfiles</command> will automatically add
314 the required base entries for user and group based on the
315 access mode of the file, unless base entries already exist
316 or are explictly specified. The mask will be added if not
317 specified explicitly or already present. Lines of this type
318 accept shell-style globs in place of normal path names. This
319 can be useful for allowing additional access to certain
320 files.</para></listitem>
324 <term><varname>A</varname></term>
325 <term><varname>A+</varname></term>
326 <listitem><para>Same as <varname>a</varname> and
327 <varname>a+</varname>, but recursive.</para></listitem>
331 <para>If the exclamation mark is used, this line is only safe of
332 execute during boot, and can break a running system. Lines
333 without the exclamation mark are presumed to be safe to execute
334 at any time, e.g. on package upgrades.
335 <command>systemd-tmpfiles</command> will execute line with an
336 exclamation mark only if option <option>--boot</option> is
340 <programlisting># Make sure these are created by default so that nobody else can
341 d /tmp/.X11-unix 1777 root root 10d
343 # Unlink the X11 lock files
344 r! /tmp/.X[0-9]*-lock</programlisting>
345 The second line in contrast to the first one would break a
346 running system, and will only be executed with
347 <option>--boot</option>.</para>
353 <para>The file system path specification supports simple
354 specifier expansion. The following expansions are
358 <title>Specifiers available</title>
359 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
360 <colspec colname="spec" />
361 <colspec colname="mean" />
362 <colspec colname="detail" />
365 <entry>Specifier</entry>
366 <entry>Meaning</entry>
367 <entry>Details</entry>
372 <entry><literal>%m</literal></entry>
373 <entry>Machine ID</entry>
374 <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>
377 <entry><literal>%b</literal></entry>
378 <entry>Boot ID</entry>
379 <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
382 <entry><literal>%H</literal></entry>
383 <entry>Host name</entry>
384 <entry>The hostname of the running system.</entry>
387 <entry><literal>%v</literal></entry>
388 <entry>Kernel release</entry>
389 <entry>Identical to <command>uname -r</command> output.</entry>
392 <entry><literal>%%</literal></entry>
393 <entry>Escaped %</entry>
394 <entry>Single percent sign.</entry>
404 <para>The file access mode to use when creating this file or
405 directory. If omitted or when set to <literal>-</literal>, the
406 default is used: 0755 for directories, 0644 for all other file
407 objects. For <varname>z</varname>, <varname>Z</varname> lines,
408 if omitted or when set to <literal>-</literal>, the file access
409 mode will not be modified. This parameter is ignored for
410 <varname>x</varname>, <varname>r</varname>,
411 <varname>R</varname>, <varname>L</varname>, <varname>t</varname>,
412 and <varname>a</varname> lines.</para>
414 <para>Optionally, if prefixed with <literal>~</literal>, the
415 access mode is masked based on the already set access bits for
416 existing file or directories: if the existing file has all
417 executable bits unset, all executable bits are removed from the
418 new access mode, too. Similarly, if all read bits are removed
419 from the old access mode, they will be removed from the new
420 access mode too, and if all write bits are removed, they will be
421 removed from the new access mode too. In addition, the
422 sticky/SUID/SGID bit is removed unless applied to a
423 directory. This functionality is particularly useful in
424 conjunction with <varname>Z</varname>.</para>
428 <title>UID, GID</title>
430 <para>The user and group to use for this file or directory. This
431 may either be a numeric user/group ID or a user or group
432 name. If omitted or when set to <literal>-</literal>, the
433 default 0 (root) is used. For <varname>z</varname>,
434 <varname>Z</varname> lines, when omitted or when set to
435 <literal>-</literal>, the file ownership will not be
436 modified. These parameters are ignored for <varname>x</varname>,
437 <varname>r</varname>, <varname>R</varname>,
438 <varname>L</varname>, <varname>t</varname>, and
439 <varname>a</varname> lines.</para>
444 <para>The date field, when set, is used to decide what files to
445 delete when cleaning. If a file or directory is older than the
446 current time minus the age field, it is deleted. The field
447 format is a series of integers each followed by one of the
448 following postfixes for the respective time units:
449 <constant>s</constant>,
450 <constant>m</constant> or <constant>min</constant>,
451 <constant>h</constant>,
452 <constant>d</constant>,
453 <constant>w</constant>,
454 <constant>ms</constant>,
455 <constant>us</constant>,
456 respectively meaning seconds, minutes, hours, days, weeks,
457 milliseconds, and microseconds. Full names of the time units can
461 <para>If multiple integers and units are specified, the time
462 values are summed. If an integer is given without a unit,
463 <constant>s</constant> is assumed.
466 <para>When the age is set to zero, the files are cleaned
467 unconditionally.</para>
469 <para>The age field only applies to lines
470 starting with <varname>d</varname>,
471 <varname>D</varname>, and
472 <varname>x</varname>. If omitted or set to
473 <literal>-</literal>, no automatic clean-up is
476 <para>If the age field starts with a tilde character
477 <literal>~</literal>, the clean-up is only applied to files and
478 directories one level inside the directory specified, but not
479 the files and directories immediately inside it.</para>
483 <title>Argument</title>
485 <para>For <varname>L</varname> lines determines the destination
486 path of the symlink. For <varname>c</varname>,
487 <varname>b</varname> determines the major/minor of the device
488 node, with major and minor formatted as integers, separated by
489 <literal>:</literal>, e.g. <literal>1:3</literal>. For
490 <varname>f</varname>, <varname>F</varname>, and
491 <varname>w</varname> may be used to specify a short string that
492 is written to the file, suffixed by a newline. For
493 <varname>C</varname>, specifies the source file or
494 directory. For <varname>t</varname> determines extended
495 attributes to be set. For <varname>a</varname> determines
496 ACL attributes to be set. Ignored for all other lines.</para>
502 <title>Example</title>
504 <title>/etc/tmpfiles.d/screen.conf example</title>
505 <para><command>screen</command> needs two directories created at
506 boot with specific modes and ownership.</para>
508 <programlisting>d /run/screens 1777 root root 10d
509 d /run/uscreens 0755 root root 10d12h
510 t /run/screen - - - - user.name="John Smith" security.SMACK64=screen</programlisting>
513 <title>/etc/tmpfiles.d/abrt.conf example</title>
514 <para><command>abrt</command> needs a directory created at boot with specific mode and ownership and its content should be preserved.</para>
516 <programlisting>d /var/tmp/abrt 0755 abrt abrt
517 x /var/tmp/abrt/*</programlisting>
522 <title>See Also</title>
524 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
525 <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
526 <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
527 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
528 <citerefentry project='man-pages'><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
529 <citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
530 <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
531 <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
532 <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>