1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="systemd-tmpfiles"
7    xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>systemd-tmpfiles</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>systemd-tmpfiles</refentrytitle>
16    <manvolnum>8</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>systemd-tmpfiles</refname>
21    <refname>systemd-tmpfiles-setup.service</refname>
22    <refname>systemd-tmpfiles-setup-dev.service</refname>
23    <refname>systemd-tmpfiles-clean.service</refname>
24    <refname>systemd-tmpfiles-clean.timer</refname>
25    <refpurpose>Creates, deletes and cleans up volatile
26    and temporary files and directories</refpurpose>
27  </refnamediv>
28
29  <refsynopsisdiv>
30    <cmdsynopsis>
31      <command>systemd-tmpfiles</command>
32      <arg choice="opt" rep="repeat">OPTIONS</arg>
33      <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg>
34    </cmdsynopsis>
35
36    <para>System units:
37<literallayout><filename>systemd-tmpfiles-setup.service</filename>
38<filename>systemd-tmpfiles-setup-dev.service</filename>
39<filename>systemd-tmpfiles-clean.service</filename>
40<filename>systemd-tmpfiles-clean.timer</filename></literallayout></para>
41
42    <para>User units:
43<literallayout><filename>systemd-tmpfiles-setup.service</filename>
44<filename>systemd-tmpfiles-clean.service</filename>
45<filename>systemd-tmpfiles-clean.timer</filename></literallayout></para>
46  </refsynopsisdiv>
47
48  <refsect1>
49    <title>Description</title>
50
51    <para><command>systemd-tmpfiles</command> creates, deletes, and cleans up volatile and temporary files
52    and directories, using the configuration file format and location specified in
53    <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It must
54    be invoked with one or more options <option>--create</option>, <option>--remove</option>, and
55    <option>--clean</option>, to select the respective subset of operations.</para>
56
57    <para>By default, directives from all configuration files are applied. When invoked with
58    <option>--replace=<replaceable>PATH</replaceable></option>, arguments specified on the command line are
59    used instead of the configuration file <replaceable>PATH</replaceable>. Otherwise, if one or more
60    absolute filenames are passed on the command line, only the directives in these files are applied. If
61    <literal>-</literal> is specified instead of a filename, directives are read from standard input. If only
62    the basename of a configuration file is specified, all configuration directories as specified in
63    <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
64    searched for a matching file and the file found that has the highest priority is executed.</para>
65
66    <para>System services (<filename>systemd-tmpfiles-setup.service</filename>,
67    <filename>systemd-tmpfiles-setup-dev.service</filename>,
68    <filename>systemd-tmpfiles-clean.service</filename>) invoke <command>systemd-tmpfiles</command> to create
69    system files and to perform system wide cleanup. Those services read administrator-controlled
70    configuration files in <filename>tmpfiles.d/</filename> directories. User services
71    (<filename>systemd-tmpfiles-setup.service</filename>,
72    <filename>systemd-tmpfiles-clean.service</filename>) also invoke <command>systemd-tmpfiles</command>, but
73    it reads a separate set of files, which includes user-controlled files under
74    <filename>~/.config/user-tmpfiles.d/</filename> and <filename>~/.local/share/user-tmpfiles.d/</filename>,
75    and administrator-controlled files under <filename>/usr/share/user-tmpfiles.d/</filename>. Users may use
76    this to create and clean up files under their control, but the system instance performs global cleanup
77    and is not influenced by user configuration. Note that this means a time-based cleanup configured in the
78    system instance, such as the one typically configured for <filename>/tmp/</filename>, will thus also
79    affect files created by the user instance if they are placed in <filename>/tmp/</filename>, even if the
80    user instance's time-based cleanup is turned off.</para>
81
82    <para>To re-apply settings after configuration has been modified, simply restart
83    <filename>systemd-tmpfiles-clean.service</filename>, which will apply any settings which can be safely
84    executed at runtime. To debug <command>systemd-tmpfiles</command>, it may be useful to invoke it
85    directly from the command line with increased log level (see <varname>$SYSTEMD_LOG_LEVEL</varname>
86    below).</para>
87  </refsect1>
88
89  <refsect1>
90    <title>Options</title>
91
92    <para>The following options are understood:</para>
93
94    <variablelist>
95      <varlistentry>
96        <term><option>--create</option></term>
97        <listitem><para>If this option is passed, all files and
98        directories marked with
99        <varname>f</varname>,
100        <varname>F</varname>,
101        <varname>w</varname>,
102        <varname>d</varname>,
103        <varname>D</varname>,
104        <varname>v</varname>,
105        <varname>p</varname>,
106        <varname>L</varname>,
107        <varname>c</varname>,
108        <varname>b</varname>,
109        <varname>m</varname>
110        in the configuration files are created or written to. Files
111        and directories marked with
112        <varname>z</varname>,
113        <varname>Z</varname>,
114        <varname>t</varname>,
115        <varname>T</varname>,
116        <varname>a</varname>, and
117        <varname>A</varname> have their ownership, access mode and
118        security labels set.</para></listitem>
119      </varlistentry>
120
121      <varlistentry>
122        <term><option>--clean</option></term>
123        <listitem><para>If this option is passed, all files and
124        directories with an age parameter configured will be cleaned
125        up.</para></listitem>
126      </varlistentry>
127
128      <varlistentry>
129        <term><option>--remove</option></term>
130        <listitem><para>If this option is passed, the contents of
131        directories marked with <varname>D</varname> or
132        <varname>R</varname>, and files or directories themselves
133        marked with <varname>r</varname> or <varname>R</varname> are
134        removed.</para></listitem>
135      </varlistentry>
136
137      <varlistentry>
138        <term><option>--user</option></term>
139        <listitem><para>Execute "user" configuration, i.e. <filename>tmpfiles.d</filename>
140        files in user configuration directories.</para></listitem>
141      </varlistentry>
142
143      <varlistentry>
144        <term><option>--boot</option></term>
145        <listitem><para>Also execute lines with an exclamation mark.
146        </para></listitem>
147      </varlistentry>
148
149      <varlistentry>
150        <term><option>--prefix=<replaceable>path</replaceable></option></term>
151        <listitem><para>Only apply rules with paths that start with
152        the specified prefix. This option can be specified multiple
153        times.</para></listitem>
154      </varlistentry>
155
156      <varlistentry>
157        <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term>
158        <listitem><para>Ignore rules with paths that start with the
159        specified prefix. This option can be specified multiple
160        times.</para></listitem>
161      </varlistentry>
162
163      <varlistentry>
164        <term><option>-E</option></term>
165        <listitem><para>A shortcut for <literal>--exclude-prefix=/dev --exclude-prefix=/proc
166        --exclude-prefix=/run --exclude-prefix=/sys</literal>, i.e. exclude the hierarchies typically backed
167        by virtual or memory file systems. This is useful in combination with <option>--root=</option>, if
168        the specified directory tree contains an OS tree without these virtual/memory file systems mounted
169        in, as it is typically not desirable to create any files and directories below these subdirectories
170        if they are supposed to be overmounted during runtime.</para></listitem>
171      </varlistentry>
172
173      <varlistentry>
174        <term><option>--root=<replaceable>root</replaceable></option></term>
175        <listitem><para>Takes a directory path as an argument. All paths will be prefixed with the given alternate
176        <replaceable>root</replaceable> path, including config search paths.</para>
177
178        <para>When this option is used, the libc Name Service Switch (NSS) is bypassed for resolving users
179        and groups. Instead the files <filename>/etc/passwd</filename> and <filename>/etc/group</filename>
180        inside the alternate root are read directly. This means that users/groups not listed in these files
181        will not be resolved, i.e. LDAP NIS and other complex databases are not considered.</para>
182
183        <para>Consider combining this with <option>-E</option> to ensure the invocation does not create files
184        or directories below mount points in the OS image operated on that are typically overmounted during
185        runtime.</para></listitem>
186      </varlistentry>
187
188      <varlistentry>
189        <term><option>--image=<replaceable>image</replaceable></option></term>
190
191        <listitem><para>Takes a path to a disk image file or block device node. If specified all operations
192        are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
193        but operates on file systems stored in disk images or block devices. The disk image should either
194        contain just a file system or a set of file systems within a GPT partition table, following the
195        <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
196        Specification</ulink>. For further information on supported disk images, see
197        <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
198        switch of the same name.</para>
199
200        <para>Implies <option>-E</option>.</para></listitem>
201      </varlistentry>
202
203      <varlistentry>
204        <term><option>--replace=<replaceable>PATH</replaceable></option></term>
205        <listitem><para>When this option is given, one or more positional arguments
206        must be specified. All configuration files found in the directories listed in
207        <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
208        will be read, and the configuration given on the command line will be
209        handled instead of and with the same priority as the configuration file
210        <replaceable>PATH</replaceable>.</para>
211
212        <para>This option is intended to be used when package installation scripts
213        are running and files belonging to that package are not yet available on
214        disk, so their contents must be given on the command line, but the admin
215        configuration might already exist and should be given higher priority.
216        </para></listitem>
217      </varlistentry>
218
219      <xi:include href="standard-options.xml" xpointer="cat-config" />
220      <xi:include href="standard-options.xml" xpointer="no-pager" />
221      <xi:include href="standard-options.xml" xpointer="help" />
222      <xi:include href="standard-options.xml" xpointer="version" />
223    </variablelist>
224
225    <para>It is possible to combine <option>--create</option>, <option>--clean</option>, and <option>--remove</option>
226    in one invocation (in which case removal and cleanup are executed before creation of new files). For example,
227    during boot the following command line is executed to ensure that all temporary and volatile directories are
228    removed and created according to the configuration file:</para>
229
230    <programlisting>systemd-tmpfiles --remove --create</programlisting>
231  </refsect1>
232
233  <refsect1>
234    <title>Environment</title>
235
236    <variablelist class='environment-variables'>
237      <xi:include href="common-variables.xml" xpointer="log-level" />
238      <xi:include href="common-variables.xml" xpointer="log-color" />
239      <xi:include href="common-variables.xml" xpointer="log-time" />
240      <xi:include href="common-variables.xml" xpointer="log-location" />
241      <xi:include href="common-variables.xml" xpointer="log-target" />
242      <xi:include href="common-variables.xml" xpointer="pager" />
243      <xi:include href="common-variables.xml" xpointer="less" />
244      <xi:include href="common-variables.xml" xpointer="lesscharset" />
245      <xi:include href="common-variables.xml" xpointer="lesssecure" />
246      <xi:include href="common-variables.xml" xpointer="colors" />
247      <xi:include href="common-variables.xml" xpointer="urlify" />
248    </variablelist>
249  </refsect1>
250
251  <refsect1>
252    <title>Unprivileged --cleanup operation</title>
253
254    <para><command>systemd-tmpfiles</command> tries to avoid changing
255    the access and modification times on the directories it accesses,
256    which requires <constant>CAP_FOWNER</constant> privileges. When
257    running as non-root, directories which are checked for files to
258    clean up will have their access time bumped, which might prevent
259    their cleanup.
260    </para>
261  </refsect1>
262
263  <refsect1>
264    <title>Exit status</title>
265
266    <para>On success, 0 is returned. If the configuration was syntactically invalid (syntax errors, missing
267    arguments, …), so some lines had to be ignored, but no other errors occurred, <constant>65</constant> is
268    returned (<constant>EX_DATAERR</constant> from <filename>/usr/include/sysexits.h</filename>). If the
269    configuration was syntactically valid, but could not be executed (lack of permissions, creation of files
270    in missing directories, invalid contents when writing to <filename>/sys/</filename> values, …),
271    <constant>73</constant> is returned (<constant>EX_CANTCREAT</constant> from
272    <filename>/usr/include/sysexits.h</filename>). Otherwise, <constant>1</constant> is returned
273    (<constant>EXIT_FAILURE</constant> from <filename>/usr/include/stdlib.h</filename>).</para>
274
275    <para>Note: when creating items, if the target already exists, but is of the wrong type or otherwise does
276    not match the requested state, and forced operation has not been requested with <literal>+</literal>,
277    a message is emitted, but the failure is otherwise ignored.</para>
278  </refsect1>
279
280  <refsect1>
281    <title>See Also</title>
282    <para>
283      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
284      <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
285    </para>
286  </refsect1>
287
288</refentry>
289