man: document interaction of --root= and the user/group databases (#7344)

[thirdparty/systemd.git] / man / systemd-tmpfiles.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd-tmpfiles"
    xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>systemd-tmpfiles</title>
    <productname>systemd</productname>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Lennart</firstname>
        <surname>Poettering</surname>
        <email>lennart@poettering.net</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-tmpfiles</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-tmpfiles</refname>
    <refname>systemd-tmpfiles-setup.service</refname>
    <refname>systemd-tmpfiles-setup-dev.service</refname>
    <refname>systemd-tmpfiles-clean.service</refname>
    <refname>systemd-tmpfiles-clean.timer</refname>
    <refpurpose>Creates, deletes and cleans up volatile
    and temporary files and directories</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>systemd-tmpfiles</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg>
    </cmdsynopsis>

    <para><filename>systemd-tmpfiles-setup.service</filename></para>
    <para><filename>systemd-tmpfiles-setup-dev.service</filename></para>
    <para><filename>systemd-tmpfiles-clean.service</filename></para>
    <para><filename>systemd-tmpfiles-clean.timer</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>systemd-tmpfiles</command> creates, deletes, and
    cleans up volatile and temporary files and directories, based on
    the configuration file format and location specified in
    <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
    </para>

    <para>If invoked with no arguments, it applies all directives from all configuration
    files. If one or more absolute filenames are passed on the command line, only the
    directives in these files are applied.  If <literal>-</literal> is specified instead
    of a filename, directives are read from standard input.  If only the basename of a
    configuration file is specified, all configuration directories as specified in
    <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    are searched for a matching file.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>--create</option></term>
        <listitem><para>If this option is passed, all files and
        directories marked with
        <varname>f</varname>,
        <varname>F</varname>,
        <varname>w</varname>,
        <varname>d</varname>,
        <varname>D</varname>,
        <varname>v</varname>,
        <varname>p</varname>,
        <varname>L</varname>,
        <varname>c</varname>,
        <varname>b</varname>,
        <varname>m</varname>
        in the configuration files are created or written to. Files
        and directories marked with
        <varname>z</varname>,
        <varname>Z</varname>,
        <varname>t</varname>,
        <varname>T</varname>,
        <varname>a</varname>, and
        <varname>A</varname> have their ownership, access mode and
        security labels set. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--clean</option></term>
        <listitem><para>If this option is passed, all files and
        directories with an age parameter configured will be cleaned
        up.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--remove</option></term>
        <listitem><para>If this option is passed, the contents of
        directories marked with <varname>D</varname> or
        <varname>R</varname>, and files or directories themselves
        marked with <varname>r</varname> or <varname>R</varname> are
        removed.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--boot</option></term>
        <listitem><para>Also execute lines with an exclamation mark.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--prefix=<replaceable>path</replaceable></option></term>
        <listitem><para>Only apply rules with paths that start with
        the specified prefix. This option can be specified multiple
        times.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term>
        <listitem><para>Ignore rules with paths that start with the
        specified prefix. This option can be specified multiple
        times.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--root=<replaceable>root</replaceable></option></term>
        <listitem><para>Takes a directory path as an argument. All paths will be prefixed with the given alternate
        <replaceable>root</replaceable> path, including config search paths.</para>

        <para>Note that this option does not alter how the users and groups specified in the configuration files are
        resolved. With or without this option, users and groups are always resolved according to the host's user and
        group databases, any such databases stored under the specified root directories are not
        consulted.</para></listitem>
      </varlistentry>

      <xi:include href="standard-options.xml" xpointer="help" />
      <xi:include href="standard-options.xml" xpointer="version" />
    </variablelist>

    <para>It is possible to combine <option>--create</option>,
    <option>--clean</option>, and <option>--remove</option> in one
    invocation. For example, during boot the following command line is
    executed to ensure that all temporary and volatile directories are
    removed and created according to the configuration file:</para>

    <programlisting>systemd-tmpfiles --remove --create</programlisting>

  </refsect1>

  <refsect1>
    <title>Unprivileged --cleanup operation</title>

    <para><command>systemd-tmpfiles</command> tries to avoid changing
    the access and modification times on the directories it accesses,
    which requires <constant>CAP_ADMIN</constant> privileges. When
    running as non-root, directories which are checked for files to
    clean up will have their access time bumped, which might prevent
    their cleanup.
    </para>
  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned, a non-zero failure code
    otherwise.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>