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