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

diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index 7d7f977979d..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,30 +33,78 @@
     <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>
     <title>Description</title>
 
-    <para><command>systemd-tmpfiles</command> uses the configuration
-    files from the above directories to describe the creation,
-    cleaning and removal of volatile and temporary files and
-    directories which usually reside in directories such as
-    <filename>/run</filename> or <filename>/tmp</filename>.</para>
-
-    <para>Volatile and temporary files and directories are those located in <filename>/run</filename>,
-    <filename>/tmp</filename>, <filename>/var/tmp</filename>, the API file systems such as <filename>/sys</filename> or
-    <filename>/proc</filename>, as well as some other directories below <filename>/var</filename>.</para>
-
-    <para>System daemons frequently require private runtime
-    directories below <filename>/run</filename> to place communication
-    sockets and similar in. For these, consider declaring them in
-    their unit files using <varname>RuntimeDirectory=</varname> (see
-    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for details), if this is feasible.</para>
+    <para><filename>tmpfiles.d</filename> configuration files provide a generic mechanism to define the
+    <emphasis>creation</emphasis> of regular files, directories, pipes, and device nodes, adjustments to
+    their <emphasis>access mode, ownership, attributes, quota assignments, and contents</emphasis>, and
+    finally their time-based <emphasis>removal</emphasis>. It is mostly commonly used for volatile and
+    temporary files and directories (such as those located under <filename>/run</filename>,
+    <filename>/tmp</filename>, <filename>/var/tmp</filename>, the API file systems such as
+    <filename>/sys</filename> or <filename>/proc</filename>, as well as some other directories below
+    <filename>/var</filename>).</para>
+
+    <para><command>systemd-tmpfiles</command> uses this configuration to create volatile files and
+    directories during boot and to do periodic cleanup afterwards. See
+    <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    the description of <filename>systemd-tmpfiles-setup.service</filename>,
+    <filename>systemd-tmpfiles-cleanup.service</filename>, and associated units.</para>
+
+    <para>System daemons frequently require private runtime directories below <filename>/run</filename> to
+    store communication sockets and similar. For these, is is better to use
+    <varname>RuntimeDirectory=</varname> in their unit files (see
+    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    details), if the flexibility provided by <filename>tmpfiles.d</filename> is not required. The advantages
+    are that the configuration required by the unit is centralized in one place, and that the lifetime of the
+    directory is tied to the lifetime of the service itself. Similarly, <varname>StateDirectory=</varname>,
+    <varname>CacheDirectory=</varname>, <varname>LogsDirectory=</varname>, and
+    <varname>ConfigurationDirectory=</varname> should be used to create directories under
+    <filename>/var/lib/</filename>, <filename>/var/cache/</filename>, <filename>/var/log/</filename>, and
+    <filename>/etc/</filename>. <filename>tmpfiles.d</filename> should be used for files whose lifetime is
+    independent of any service or requires more complicated configuration.</para>
   </refsect1>
 
   <refsect1>
@@ -67,28 +116,20 @@
     The second variant should be used when it is desirable to make it
     easy to override just this part of configuration.</para>
 
-    <para>Files in <filename>/etc/tmpfiles.d</filename> override files
-    with the same name in <filename>/usr/lib/tmpfiles.d</filename> and
-    <filename>/run/tmpfiles.d</filename>. Files in
-    <filename>/run/tmpfiles.d</filename> override files with the same
-    name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should
-    install their configuration files in
-    <filename>/usr/lib/tmpfiles.d</filename>. Files in
-    <filename>/etc/tmpfiles.d</filename> are reserved for the local
-    administrator, who may use this logic to override the
-    configuration files installed by vendor packages. All
-    configuration files are sorted by their filename in lexicographic
-    order, regardless of which of the directories they reside in. If
-    multiple files specify the same path, the entry in the file with
-    the lexicographically earliest name will be applied.  All other
-    conflicting entries will be logged as errors. When two lines are
-    prefix and suffix of each other, then the prefix is always
-    processed first, the suffix later. Lines that take globs are
-    applied after those accepting no globs. If multiple operations
-    shall be applied on the same file, (such as ACL, xattr, file
-    attribute adjustments), these are always done in the same fixed
-    order. Otherwise, the files/directories are processed in the order
-    they are listed.</para>
+    <para>Files in <filename>/etc/tmpfiles.d</filename> override files with the same name in
+    <filename>/usr/lib/tmpfiles.d</filename> and <filename>/run/tmpfiles.d</filename>. Files in
+    <filename>/run/tmpfiles.d</filename> override files with the same name in
+    <filename>/usr/lib/tmpfiles.d</filename>. Packages should install their configuration files in
+    <filename>/usr/lib/tmpfiles.d</filename>. Files in <filename>/etc/tmpfiles.d</filename> are reserved for the local
+    administrator, who may use this logic to override the configuration files installed by vendor packages. All
+    configuration files are sorted by their filename in lexicographic order, regardless of which of the directories
+    they reside in. If multiple files specify the same path, the entry in the file with the lexicographically earliest
+    name will be applied.  All other conflicting entries will be logged as errors. When two lines are prefix path and
+    suffix path of each other, then the prefix line is always created first, the suffix later (and if removal applies
+    to the line, the order is reversed: the suffix is removed first, the prefix later). Lines that take globs are
+    applied after those accepting no globs. If multiple operations shall be applied on the same file (such as ACL,
+    xattr, file attribute adjustments), these are always done in the same fixed order. Except for those cases, the
+    files/directories are processed in the order they are listed.</para>
 
     <para>If the administrator wants to disable a configuration file
     supplied by the vendor, the recommended way is to place a symlink
@@ -103,9 +144,9 @@
     <para>The configuration format is one line per path containing
     type, path, mode, ownership, age, and argument fields:</para>
 
-    <programlisting>#Type Path        Mode UID  GID  Age Argument
-d     /run/user   0755 root root 10d -
-L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
+    <programlisting>#Type Path        Mode User Group Age Argument
+d     /run/user   0755 root root  10d -
+L     /tmp/foobar -    -    -     -   /dev/null</programlisting>
 
     <para>Fields may be enclosed within quotes and contain C-style escapes.</para>
 
@@ -120,72 +161,69 @@ 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>
           <term><varname>d</varname></term>
-          <listitem><para>Create a directory. The mode and ownership will be adjusted if
-          specified and the directory already exists. Contents of this directory are subject
-          to time based cleanup if the age argument is specified.</para></listitem>
+          <listitem><para>Create a directory. The mode and ownership will be adjusted if specified. Contents
+          of this directory are subject to time based cleanup if the age argument is specified.
+          </para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>D</varname></term>
-          <listitem><para>Similar to <varname>d</varname>, but in addition the contents
-          of the directory will be removed when <option>--remove</option> is used.
-          </para></listitem>
+          <listitem><para>Similar to <varname>d</varname>, but in addition the contents of the directory will
+          be removed when <option>--remove</option> is used.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>e</varname></term>
-          <listitem><para>Similar to <varname>d</varname>, but the directory will not be created if
-          it does not exist. Lines of this type accept shell-style globs in place of normal path
-          names. For this entry to be useful, at least one of the mode, uid, gid, or age arguments
-          must be specified, since otherwise this entry has no effect. If the age argument is
-          <literal>0</literal>, contents of the directory will be unconditionally deleted every time
-          <command>systemd-tmpfiles --clean</command> is run. This can be useful when combined with
-          <varname>!</varname>, see the examples.</para></listitem>
+          <listitem><para>Adjust the mode and ownership of existing directories and remove their contents
+          based on age.
+          Lines of this type accept shell-style globs in place of normal path names. Contents of the
+          directories are subject to time based cleanup if the age argument is specified. If the age argument
+          is <literal>0</literal>, contents will be unconditionally deleted every time
+          <command>systemd-tmpfiles --clean</command> is run.</para>
+
+          <para>For this entry to be useful, at least one of the mode, user, group, or age arguments must be
+          specified, since otherwise this entry has no effect. As an exception, an entry with no effect may
+          be useful when combined with <varname>!</varname>, see the examples.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>v</varname></term>
-          <listitem><para>Create a subvolume if the path does not
-          exist yet, the file system supports subvolumes (btrfs), and
-          the system itself is installed into a subvolume
-          (specifically: the root directory <filename>/</filename> is
-          itself a subvolume). Otherwise, create a normal directory, in
-          the same way as <varname>d</varname>. A subvolume created
-          with this line type is not assigned to any higher-level
-          quota group. For that, use <varname>q</varname> or
-          <varname>Q</varname>, which allow creating simple quota
-          group hierarchies, see below.</para></listitem>
+          <listitem><para>Create a subvolume if the path does not exist yet, the file system supports
+          subvolumes (btrfs), and the system itself is installed into a subvolume (specifically: the root
+          directory <filename>/</filename> is itself a subvolume). Otherwise, create a normal directory, in
+          the same way as <varname>d</varname>.</para>
+
+          <para>A subvolume created with this line type is not assigned to any higher-level quota group. For
+          that, use <varname>q</varname> or <varname>Q</varname>, which allow creating simple quota group
+          hierarchies, see below.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>q</varname></term>
-          <listitem><para>Similar to <varname>v</varname>. However, makes sure that the subvolume will be assigned to
-          the same higher-level quota groups as the subvolume it has been created in. This ensures that higher-level
-          limits and accounting applied to the parent subvolume also include the specified subvolume. On non-btrfs file
-          systems, this line type is identical to <varname>d</varname>.</para>
+          <listitem><para>Create a subvolume or directory the same as <varname>v</varname>, but assign the
+          subvolume to the same higher-level quota groups as the parent. This ensures that higher-level
+          limits and accounting applied to the parent subvolume also include the specified subvolume. On
+          non-btrfs file systems, this line type is identical to <varname>d</varname>.</para>
 
           <para>If the subvolume already exists, no change to the quota hierarchy is made, regardless of whether the
           subvolume is already attached to a quota group or not. Also see <varname>Q</varname> below. See <citerefentry
@@ -195,13 +233,15 @@ L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
 
         <varlistentry>
           <term><varname>Q</varname></term>
-          <listitem><para>Similar to <varname>q</varname>. However, instead of copying the higher-level quota group
-          assignments from the parent as-is, the lowest quota group of the parent subvolume is determined that is not
-          the leaf quota group. Then, an "intermediary" quota group is inserted that is one level below this level, and
-          shares the same ID part as the specified subvolume. If no higher-level quota group exists for the parent
-          subvolume, a new quota group at level 255 sharing the same ID as the specified subvolume is inserted
-          instead. This new intermediary quota group is then assigned to the parent subvolume's higher-level quota
-          groups, and the specified subvolume's leaf quota group is assigned to it.</para>
+          <listitem><para>Create the subvolume or directory the same as <varname>v</varname>, but assign the
+          new subvolume to a new leaf quota group. Instead of copying the higher-level quota group
+          assignments from the parent as is done with <varname>q</varname>, the lowest quota group of the
+          parent subvolume is determined that is not the leaf quota group. Then, an "intermediary" quota
+          group is inserted that is one level below this level, and shares the same ID part as the specified
+          subvolume. If no higher-level quota group exists for the parent subvolume, a new quota group at
+          level 255 sharing the same ID as the specified subvolume is inserted instead. This new intermediary
+          quota group is then assigned to the parent subvolume's higher-level quota groups, and the specified
+          subvolume's leaf quota group is assigned to it.</para>
 
           <para>Effectively, this has a similar effect as <varname>q</varname>, however introduces a new higher-level
           quota group for the specified subvolume that may be used to enforce limits and accounting to the specified
@@ -221,8 +261,8 @@ L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
           <filename>/var/tmp</filename>. </para>
 
           <para>As with <varname>q</varname>, <varname>Q</varname> has no effect on the quota group hierarchy if the
-          subvolume already exists, regardless of whether the subvolume already belong to a quota group or
-          not.</para></listitem>
+          subvolume already exists, regardless of whether the subvolume already belong to a quota group or not.
+          </para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -277,11 +317,11 @@ L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
         <varlistentry>
           <term><varname>C</varname></term>
           <listitem><para>Recursively copy a file or directory, if the
-          destination files or directories do not exist yet. Note that
-          this command will not descend into subdirectories if the
-          destination directory already exists. Instead, the entire
-          copy operation is skipped. If the argument is omitted, files
-          from the source directory
+          destination files or directories do not exist yet or the
+          destination directory is empty. Note that this command will not
+          descend into subdirectories if the destination directory already
+          exists and is not empty. Instead, the entire copy operation is
+          skipped. If the argument is omitted, files from the source directory
           <filename>/usr/share/factory/</filename> with the same name
           are copied. Does not follow symlinks.</para></listitem>
         </varlistentry>
@@ -328,85 +368,79 @@ L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
 
         <varlistentry>
           <term><varname>z</varname></term>
-          <listitem><para>Adjust the access mode, group and user, and
-          restore the SELinux security context of a file or directory,
-          if it exists. Lines of this type accept shell-style globs in
-          place of normal path names. Does not follow symlinks.</para></listitem>
+          <listitem><para>Adjust the access mode, user and group ownership, and restore the SELinux security
+          context of a file or directory, if it exists. Lines of this type accept shell-style globs in place
+          of normal path names. Does not follow symlinks.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>Z</varname></term>
-          <listitem><para>Recursively set the access mode, group and
-          user, and restore the SELinux security context of a file or
-          directory if it exists, as well as of its subdirectories and
-          the files contained therein (if applicable). Lines of this
-          type accept shell-style globs in place of normal path
-          names. Does not follow symlinks.  </para></listitem>
+          <listitem><para>Recursively set the access mode, user and group ownership, and restore the SELinux
+          security context of a file or directory if it exists, as well as of its subdirectories and the
+          files contained therein (if applicable). Lines of this type accept shell-style globs in place of
+          normal path names. Does not follow symlinks.</para></listitem>
         </varlistentry>
 
         <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>
@@ -418,7 +452,7 @@ L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
         </varlistentry>
       </variablelist>
 
-      <para>If the exclamation mark is used, this line is only safe of
+      <para>If the exclamation mark is used, this line is only safe to
       execute during boot, and can break a running system. Lines
       without the exclamation mark are presumed to be safe to execute
       at any time, e.g. on package upgrades.
@@ -488,13 +522,22 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
     </refsect2>
 
     <refsect2>
-      <title>UID, GID</title>
-
-      <para>The user and group to use for this file or directory. This may either be a numeric user/group ID or a user or group
-      name. If omitted or when set to <literal>-</literal>, the user/group ID of the user who invokes <command>systemd-tmpfiles</command> is used.
-      For <varname>z</varname> and <varname>Z</varname> 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>
+      <title>User, Group</title>
+
+      <para>The user and group to use for this file or directory. This may either be a numeric ID or a
+      user/group name. If omitted or when set to <literal>-</literal>, the user and group of the user who
+      invokes <command>systemd-tmpfiles</command> is used. For <varname>z</varname> and <varname>Z</varname>
+      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>
@@ -542,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>
@@ -603,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>
@@ -738,6 +789,13 @@ e! /var/cache/krb5rcache - - - 0
     </example>
   </refsect1>
 
+  <refsect1>
+    <title><filename>/run/</filename> and <filename>/var/run/</filename></title>
+    <para><filename>/var/run/</filename> is a deprecated symlink to <filename>/run/</filename>, and
+    applications should use the latter. <command>systemd-tmpfiles</command> will warn if
+    <filename>/var/run/</filename> is used.</para>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>