Add support for unix:runtime=yes as an address mode

This is not used by default, but can be configured by OS builders (or
regression-test environments) if desired.

If used, this listens on $XDG_RUNTIME_DIR/bus, or fails if $XDG_RUNTIME_DIR
is not set. Fallback behaviour is unnecessary, because it is already
possible to use a string of semicolon-separated addresses like
<listen>unix:runtime=yes;unix:tmpdir=/tmp</listen>, resulting in
listening on either $XDG_RUNTIME_DIR/bus or /tmp/something.

We use a non-abstract socket here, because that is desirable for
use with Linux containers: abstract sockets are attached to the
network namespace, whereas non-abstract sockets are part of the
filesystem and can be bind-mounted between domains if necessary.
The major advantage of abstract sockets is that they do not need
cleanup, but the specification of XDG_RUNTIME_DIR guarantees to
provide cleanup anyway.

Based on prior work by Simon McVittie, Colin Walters and Alexander
Larsson.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=61303
Reviewed-by: Philip Withnall <philip.withnall@collabora.co.uk>

1 files changed, 14 insertions, 3 deletions

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index ce3929e2..1e0fe207 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3102,9 +3102,12 @@
       For instance, listening on <literal>tcp:host=127.0.0.1</literal>
       might result in the connectable address
       <literal>tcp:host=127.0.0.1,port=30958</literal>,
-      or listening on <literal>unix:tmpdir=/tmp</literal>
+      listening on <literal>unix:tmpdir=/tmp</literal>
       might result in the connectable address
-      <literal>unix:abstract=/tmp/dbus-U8OSdmf7</literal>.
+      <literal>unix:abstract=/tmp/dbus-U8OSdmf7</literal>, or
+      listening on <literal>unix:runtime=yes</literal>
+      might result in the connectable address
+      <literal>unix:path=/run/user/1234/bus</literal>.
     </para>
   </sect1>
   
@@ -3144,6 +3147,9 @@
         Unix addresses that specify <literal>tmpdir</literal> are only
         listenable: the corresponding connectable address will specify
         either <literal>path</literal> or <literal>abstract</literal>.
+        Similarly, Unix addresses that specify <literal>runtime</literal>
+        are only listenable, and the corresponding connectable address
+        will specify <literal>path</literal>.
       </para>
       <sect3 id="transports-unix-domain-sockets-addresses">
         <title>Server Address Format</title>
@@ -3176,12 +3182,17 @@
             <entry>(string)</entry>
             <entry>unique string (path) in the abstract namespace. If set, the "path" or "tmpdir" key must not be set. This key is only supported on platforms with "abstract Unix sockets", of which Linux is the only known example.</entry>
           </row>
+          <row>
+            <entry>runtime</entry>
+            <entry><literal>yes</literal></entry>
+            <entry>If given, This key can only be used in server addresses, not in client addresses. If set, its value must be <literal>yes</literal>. This is typically used in an address string like <literal>unix:runtime=yes;unix:tmpdir=/tmp</literal> so that there can be a fallback if <literal>XDG_RUNTIME_DIR</literal> is not set.</entry>
+          </row>
         </tbody>
         </tgroup>
        </informaltable>
        <para>
          Exactly one of the keys <literal>path</literal>,
-         <literal>abstract</literal> or
+         <literal>abstract</literal>, <literal>runtime</literal> or
          <literal>tmpdir</literal> must be provided.
        </para>
       </sect3>