[systemd-commits] 2 commits - man/file-hierarchy.xml

[Lennart Poettering]

 man/file-hierarchy.xml |   63 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 57 insertions(+), 6 deletions(-)

New commits:
commit 82a30aae48de73c39b59fbcb810636f7376b7bbc
Author: Lennart Poettering <lennart at poettering.net>
Date:   Tue Jul 1 01:14:11 2014 +0200

    man: extend a bit what to expect from the various places apps can store data

diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml
index c85df72..a1b232d 100644
--- a/man/file-hierarchy.xml
+++ b/man/file-hierarchy.xml
@@ -709,15 +709,15 @@
                       </row>
                       <row>
                         <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
-                        <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry>
+                        <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry>
                       </row>
                       <row>
                         <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
-                        <entry>Runtime log data for the package.</entry>
+                        <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry>
                       </row>
                       <row>
                         <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
-                        <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed done due to the need to rebuild any local cache files.</entry>
+                        <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed done due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry>
                       </row>
                       <row>
                         <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
@@ -725,11 +725,11 @@
                       </row>
                       <row>
                         <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
-                        <entry>Persistent log data of the package.</entry>
+                        <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
                       </row>
                       <row>
                         <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
-                        <entry>Persistent spool/queue data of the package.</entry>
+                        <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
                       </row>
                     </tbody>
                   </tgroup>
@@ -743,7 +743,9 @@
                         <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
         </refsect1>
 

commit c65b503d01dd61aba6ca0689b1ab151b3279cda6
Author: Lennart Poettering <lennart at poettering.net>
Date:   Tue Jul 1 01:13:50 2014 +0200

    man: add sections about file node types and write access to file-hierarchy(7)

diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml
index fb72693..c85df72 100644
--- a/man/file-hierarchy.xml
+++ b/man/file-hierarchy.xml
@@ -615,6 +615,55 @@
         </refsect1>
 
         <refsect1>
+                <title>Unpriviliged Write Access</title>
+
+                <para>Unpriviliged processes generally lack
+                write access to most of the hierarchy.</para>
+
+                <para>The exceptions for normal users are
+                <filename>/tmp</filename>,
+                <filename>/var/tmp</filename>,
+                <filename>/dev/shm</filename>, as well as the home
+                directory <varname>$HOME</varname> (usually found
+                below <filename>/home</filename>) and the runtime
+                directory <varname>$XDG_RUNTIME_DIR</varname> (found
+                below <filename>/run/user</filename>) of the
+                user, which are all writable.</para>
+
+                <para>For unpriviliged system processes only
+                <filename>/tmp</filename>,
+                <filename>/var/tmp</filename> and
+                <filename>/dev/shm</filename> are writable. If an
+                unpriviliged system process needs a private, writable
+                directory in <filename>/var</filename> or
+                <filename>/run</filename>, it is recommended to either
+                create it before dropping priviliges in the daemon
+                code, to create it via
+                <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                fragments during boot, or via the
+                <varname>RuntimeDirectory=</varname> directive of
+                service units (see
+                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                for details).</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Node Types</title>
+
+                <para>Unix file systems support different types of file
+                nodes, including regular files, directories, symlinks,
+                character and block device nodes, sockets and FIFOs.</para>
+
+                <para>It is strongly recommended that
+                <filename>/dev</filename> is the only location below
+                which device nodes shall be placed. Similar,
+                <filename>/run</filename> shall be the only location
+                to place sockets and FIFOs. Regular files,
+                directories and symlinks may be used in all
+                directories.</para>
+        </refsect1>
+
+        <refsect1>
                 <title>System Packages</title>
 
                 <para>Developers of system packages should follow