X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Ftmpfiles.d.xml;h=a497b9b4894770b8b5a3dd3203e475a87ee6a35f;hb=f8b68539d0ddda5964d533c2eb9c0d8bff95616b;hp=3f2ef7ee97a950911bf92d2cb44f2eef0bec74f5;hpb=e5d21c24a0902a6f692dce556dbaee26500b934b;p=thirdparty%2Fsystemd.git

diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index 3f2ef7ee97a..a497b9b4894 100644
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -1,5 +1,6 @@
 <?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!--
   SPDX-License-Identifier: LGPL-2.1+
 
@@ -32,9 +33,46 @@
     <para><literallayout><filename>~/.config/user-tmpfiles.d/*.conf</filename>
 <filename>$XDG_RUNTIME_DIR/user-tmpfiles.d/*.conf</filename>
 <filename>~/.local/share/user-tmpfiles.d/*.conf</filename>
-<filename>…</filename>
+<filename index='false'>…</filename>
 <filename>/usr/share/user-tmpfiles.d/*.conf</filename>
     </literallayout></para>
+
+    <programlisting>#Type Path                                     Mode User Group Age         Argument
+f     /file/to/create                          mode user group -           content
+f+    /file/to/create-or-truncate              mode user group -           content
+w     /file/to/write-to                        -    -    -     -           content
+w+    /file/to/append-to                       -    -    -     -           content
+d     /directory/to/create-and-cleanup         mode user group cleanup-age -
+D     /directory/to/create-and-remove          mode user group cleanup-age -
+e     /directory/to/cleanup                    mode user group cleanup-age -
+v     /subvolume/to/create                     mode user group -           -
+v     /subvolume-or-directory/to/create        mode user group -           -
+Q     /subvolume/to/create                     mode user group -           -
+p     /fifo/to/create                          mode user group -           -
+p+    /fifo/to/[re]create                      mode user group -           -
+L     /symlink/to/create                       -    -    -     -           symlink/target/path
+L+    /symlink/to/[re]create                   -    -    -     -           symlink/target/path
+c     /dev/char-device-to-create               mode user group -           -
+c+    /dev/char-device-to-[re]create           mode user group -           -
+b     /dev/block-device-to-create              mode user group -           -
+b+    /dev/block-device-to-[re]create          mode user group -           -
+C     /target/to/create                        -    -    -     -           /source/to/copy
+x     /path-or-glob/to/ignore                  -    -    -     -           -
+X     /path-or-glob/to/ignore/recursively      -    -    -     -           -
+r     /empty/dir/to/remove                     -    -    -     -           -
+R     /dir/to/remove/recursively               -    -    -     -           -
+z     /path-or-glob/to/adjust/mode             mode user group -           MAC context
+Z     /path-or-glob/to/adjust/mode/recursively mode user group -           MAC context
+t     /path-or-glob/to/set/xattrs              -    -    -     -           xattrs
+T     /path-or-glob/to/set/xattrs/recursively  -    -    -     -           xattrs
+h     /path-or-glob/to/set/attrs               -    -    -     -           file attrs
+H     /path-or-glob/to/set/attrs/recursively   -    -    -     -           file attrs
+a     /path-or-glob/to/set/acls                -    -    -     -           POSIX ACLs
+a+    /path-or-glob/to/append/acls             -    -    -     -           POSIX ACLs
+A     /path-or-glob/to/set/acls/recursively    -    -    -     -           POSIX ACLs
+A+    /path-or-glob/to/append/acls/recursively -    -    -     -           POSIX ACLs
+
+</programlisting>
   </refsynopsisdiv>
 
   <refsect1>
@@ -123,25 +161,22 @@ L     /tmp/foobar -    -    -     -   /dev/null</programlisting>
       <variablelist>
         <varlistentry>
           <term><varname>f</varname></term>
-          <listitem><para>Create a file if it does not exist yet. If the argument parameter is given and the file did
-          not exist yet, it will be written to the file. Does not follow symlinks.</para></listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><varname>F</varname></term>
-          <listitem><para>Create or truncate a file. If the argument
-          parameter is given, it will be written to the file. Does not follow symlinks.</para>
-          </listitem>
+          <term><varname>f+</varname></term>
+          <listitem><para><varname>f</varname> will create a file if it does not exist yet. If the argument
+          parameter is given and the file did not exist yet, it will be written to the file.
+          <varname>f+</varname> will create or truncate the file. If the argument parameter is given, it will
+          be written to the file. Does not follow symlinks.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>w</varname></term>
-          <listitem><para>Write the argument parameter to a file, if
-          the file exists.  Lines of this type accept shell-style
-          globs in place of normal path names. The argument parameter
-          will be written without a trailing newline. C-style
-          backslash escapes are interpreted. Follows
-          symlinks.</para></listitem>
+          <term><varname>w+</varname></term>
+          <listitem><para>Write the argument parameter to a file, if the file exists.
+          If suffixed with <varname>+</varname>, the line will be appended to the file.
+          If your configuration writes multiple lines to the same file, use <varname>w+</varname>.
+          Lines of this type accept shell-style globs in place of normal path names.
+          The argument parameter will be written without a trailing newline.
+          C-style backslash escapes are interpreted. Follows symlinks.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -348,67 +383,64 @@ L     /tmp/foobar -    -    -     -   /dev/null</programlisting>
 
         <varlistentry>
           <term><varname>t</varname></term>
-          <listitem><para>Set extended attributes. Lines of this type
-          accept shell-style globs in place of normal path names.
-          This can be useful for setting SMACK labels. Does not follow
-          symlinks.</para></listitem>
+          <listitem><para>Set extended attributes, see <citerefentry
+          project='man-pages'><refentrytitle>attr</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry> for details. The argument field should take one or more
+          assignment expressions in the form
+          <replaceable>namespace</replaceable>.<replaceable>attribute</replaceable>=<replaceable>value</replaceable>,
+          for examples see below. Lines of this type accept shell-style globs in place of normal path
+          names. This can be useful for setting SMACK labels. Does not follow symlinks.</para>
+
+          <para>Please note that extended attributes settable with this line type are a different concept
+          from the Linux file attributes settable with <varname>h</varname>/<varname>H</varname>, see
+          below.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>T</varname></term>
-          <listitem><para>Recursively set extended attributes. Lines
-          of this type accept shell-style globs in place of normal
-          path names.  This can be useful for setting SMACK
-          labels. Does not follow symlinks.  </para></listitem>
+          <listitem><para>Same as <varname>t</varname>, but operates recursively.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>h</varname></term>
-          <listitem><para>Set file/directory attributes. Lines of this type
-          accept shell-style globs in place of normal path names.</para>
-
-          <para>The format of the argument field is
-          <varname>[+-=][aAcCdDeijsStTu] </varname>. The prefix
-          <varname>+</varname> (the default one) causes the
-          attribute(s) to be added; <varname>-</varname> causes the
-          attribute(s) to be removed; <varname>=</varname> causes the
-          attributes to be set exactly as the following letters. The
-          letters <literal>aAcCdDeijsStTu</literal> select the new
-          attributes for the files, see
-          <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle>
+          <listitem><para>Set Linux file/directory attributes. Lines of this type accept shell-style globs in
+          place of normal path names.</para>
+
+          <para>The format of the argument field is <varname>[+-=][aAcCdDeijPsStTu]</varname>. The prefix
+          <varname>+</varname> (the default one) causes the attribute(s) to be added; <varname>-</varname>
+          causes the attribute(s) to be removed; <varname>=</varname> causes the attributes to be set exactly
+          as the following letters. The letters <literal>aAcCdDeijPsStTu</literal> select the new attributes
+          for the files, see <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle>
           <manvolnum>1</manvolnum></citerefentry> for further information.
           </para>
-          <para>Passing only <varname>=</varname> as argument resets
-          all the file attributes listed above. It has to be pointed
-          out that the <varname>=</varname> prefix limits itself to
-          the attributes corresponding to the letters listed here. All
-          other attributes will be left untouched. Does not follow
-          symlinks.</para>
-          </listitem>
+
+          <para>Passing only <varname>=</varname> as argument resets all the file attributes listed above. It
+          has to be pointed out that the <varname>=</varname> prefix limits itself to the attributes
+          corresponding to the letters listed here. All other attributes will be left untouched. Does not
+          follow symlinks.</para>
+
+          <para>Please note that the Linux file attributes settable with this line type are a different
+          concept from the extended attributes settable with <varname>t</varname>/<varname>T</varname>,
+          see above.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>H</varname></term>
-          <listitem><para>Recursively set file/directory attributes. Lines
-          of this type accept shell-style globs in place of normal
-          path names. Does not follow symlinks.
-          </para></listitem>
+          <listitem><para>Sames as <varname>h</varname>, but operates recursively.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>a</varname></term>
           <term><varname>a+</varname></term>
-          <listitem><para>Set POSIX ACLs (access control lists). If
-          suffixed with <varname>+</varname>, the specified entries will
-          be added to the existing set.
-          <command>systemd-tmpfiles</command> will automatically add
-          the required base entries for user and group based on the
-          access mode of the file, unless base entries already exist
-          or are explicitly specified. The mask will be added if not
-          specified explicitly or already present. Lines of this type
-          accept shell-style globs in place of normal path names. This
-          can be useful for allowing additional access to certain
-          files. Does not follow symlinks.</para></listitem>
+          <listitem><para>Set POSIX ACLs (access control lists), see <citerefentry
+          project='man-pages'><refentrytitle>acl</refentrytitle>
+          <manvolnum>5</manvolnum></citerefentry>. If suffixed with <varname>+</varname>, the specified
+          entries will be added to the existing set. <command>systemd-tmpfiles</command> will automatically
+          add the required base entries for user and group based on the access mode of the file, unless base
+          entries already exist or are explicitly specified. The mask will be added if not specified
+          explicitly or already present. Lines of this type accept shell-style globs in place of normal path
+          names. This can be useful for allowing additional access to certain files. Does not follow
+          symlinks.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -498,6 +530,14 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
       lines, when omitted or when set to <literal>-</literal>, the file ownership will not be modified. These
       parameters are ignored for <varname>x</varname>, <varname>r</varname>, <varname>R</varname>,
       <varname>L</varname>, <varname>t</varname>, and <varname>a</varname> lines.</para>
+
+      <para>This field should generally only reference system users/groups, i.e. users/groups that are
+      guaranteed to be resolvable during early boot. If this field references users/groups that only become
+      resolveable during later boot (i.e. after NIS, LDAP or a similar networked directory service become
+      available), execution of the operations declared by the line will likely fail. Also see <ulink
+      url="https://systemd.io/UIDS-GIDS.html#notes-on-resolvability-of-user-and-group-names">Notes on
+      Resolvability of User and Group Names</ulink> for more information on requirements on system user/group
+      definitions.</para>
     </refsect2>
 
     <refsect2>
@@ -545,6 +585,14 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
       (ctime). Any of these three (or two) values will prevent cleanup
       if it is more recent than the current time minus the age
       field.</para>
+
+      <para>Note that while the aging algorithm is run a 'shared' BSD file lock (see <citerefentry
+      project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) is
+      taken on each directory the algorithm descends into (and each directory below that, and so on). If the
+      aging algorithm finds a lock is already taken on some directory, it (and everything below it) is
+      skipped. Applications may use this to temporarily exclude certain directory subtrees from the aging
+      algorithm: the applications can take a BSD file lock themselves, and as long as they keep it aging of
+      the directory and everything below it is disabled.</para>
     </refsect2>
 
     <refsect2>
@@ -606,7 +654,7 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
             <row>
               <entry><literal>%L</literal></entry>
               <entry>System or user log directory</entry>
-              <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname> with <filename noindex='true'>/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
+              <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname> with <filename index="false">/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
             </row>
             <row>
               <entry><literal>%m</literal></entry>