spec: Mention that the system bus address might actually be in /run

The interoperable address is unix:path=/var/run/dbus/system_bus_socket.
However, in most (perhaps all) current Linux distributions, /var/run
is guaranteed to be a symbolic link to /run, and using the path in /run
has some advantages (particularly if automounters are used).

Implementations that intend to be interoperable are not required to
listen on exactly /var/run/dbus/system_bus_socket, as long as clients
that connect to that socket will work correctly. Similarly, clients
are not required to connect to exactly /var/run/dbus/system_bus_socket,
as long as the overall system (consisting of the client and the OSs
that it supports) ensures that it ends up connecting to the same
well-known system bus that is available at
/var/run/dbus/system_bus_socket.

Because of the Unix conventions for how software installs into a prefix,
building a D-Bus implementation with its default build-time
configuration options will not necessarily result in an interoperable
system bus. The system bus is normally shipped by OS distributors,
who should ensure that they have configured it in a way that is
interoperable.

Resolves: https://gitlab.freedesktop.org/dbus/dbus/-/issues/180
Signed-off-by: Simon McVittie <smcv@collabora.com>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 9b02f5cd9c40b654fa1de9bb4f091dc504a08e6f..3b0f4cab3e70e1fc3b9c5746a66134d03da13a9d 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -5783,13 +5783,27 @@
           variable. If that variable is not set, applications should try
           to connect to the well-known address
           <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
-          <footnote>
-            <para>
-              The D-Bus reference implementation actually honors the
-              <literal>$(localstatedir)</literal> configure option
-              for this address, on both client and server side.
-            </para>
-          </footnote>
+          Implementations of the well-known system bus should listen on
+          an address that will result in that connection being successful.
+        </para>
+        <para>
+          On systems where <filename>/var/run/</filename> is known to be
+          synonymous with <filename>/run/</filename> (such as most Linux
+          operating system distributions), implementations might prefer
+          to make use of that knowledge to connect to or listen on
+          <literal>unix:path=/run/dbus/system_bus_socket</literal> instead,
+          which has some minor technical advantages, particularly during
+          early startup and late shutdown.
+        </para>
+        <para>
+          In practice, implementations of D-Bus often have build-time
+          configuration options for the system bus address, whose defaults
+          often depend on other build-time options such as the installation
+          prefix (in particular, this is the case for dbus, the reference
+          implementation of D-Bus).
+          Distributors intending to provide access to the well-known
+          system bus should verify that they are using an interoperable
+          address.
         </para>
         <para>
           On Unix systems, the system bus should default to searching