core: introduce new RuntimeDirectory= and RuntimeDirectoryMode= unit settings

As discussed on the ML these are useful to manage runtime directories
below /run for services.

2 files changed, 60 insertions, 1 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 9224f1ef3d..f1bcf9b7bd 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -1195,6 +1195,46 @@
                                 kernel.</para></listitem>
                         </varlistentry>
 
+                        <varlistentry>
+                                <term><varname>RuntimeDirectory=</varname></term>
+                                <term><varname>RuntimeDirectoryMode=</varname></term>
+
+                                <listitem><para>Takes a list of
+                                directory names. If set one or more
+                                directories by the specified names
+                                will be created below
+                                <filename>/run</filename> (for system
+                                services) or below
+                                <varname>$XDG_RUNTIME_DIR</varname>
+                                (for user services) when the unit is
+                                started and removed when the unit is
+                                stopped. The directories will have the
+                                access mode specified in
+                                <varname>RuntimeDirectoryMode=</varname>,
+                                and will be owned by the user and
+                                group specified in
+                                <varname>User=</varname> and
+                                <varname>Group=</varname>. Use this to
+                                manage one or more runtime directories
+                                of the unit and bind their lifetime to
+                                the daemon runtime. The specified
+                                directory names must be relative, and
+                                may not include a
+                                <literal>/</literal>, i.e. must refer
+                                to simple directories to create or
+                                remove. This is particularly useful
+                                for unpriviliges daemons that cannot
+                                create runtime directories in
+                                <filename>/run</filename> due to lack
+                                of privileges, and to make sure the
+                                runtime directory is cleaned up
+                                automatically after use. For runtime
+                                directories that require more complex
+                                or different configuration or lifetime
+                                guarantees, please consider using
+                                <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+                        </varlistentry>
+
                 </variablelist>
         </refsect1>
 
@@ -1352,6 +1392,7 @@
                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                   </para>
         </refsect1>
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index 0a006d17ab..343fad163c 100644
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -61,6 +61,23 @@
                 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> (and its
+                alias <filename>/var/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>
         </refsect1>
 
         <refsect1>
@@ -458,7 +475,8 @@ x /var/tmp/abrt/*</programlisting>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
         </refsect1>