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