Attachment 75347 Details for Bug 61303 – specification: discuss "listenable" and "connectable" addresses

[patch] specification: discuss "listenable" and "connectable" addresses

0002-specification-discuss-listenable-and-connectable-add.patch (text/plain), 7.78 KB, created by Simon McVittie on 2013-02-22 19:04:52 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-02-22 19:04:52 UTC

Size: 7.78 KB

patch

obsolete

>From 05c473d0ccba3b92b1fe731002e95ed1e6370890 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Tue, 19 Feb 2013 13:45:50 +0000
>Subject: [PATCH 2/8] specification: discuss "listenable" and "connectable"
> addresses
>
>The --with-dbus-session-bus-connect-address configure option and the
>DBUS_SESSION_BUS_DEFAULT_ADDRESS CMake variable expect a connectable
>address, while the --with-dbus-session-bus-listen-address option and
>the DBUS_SESSION_BUS_LISTEN_ADDRESS variable expect a listenable address.
>
>DBUS_SYSTEM_BUS_DEFAULT_ADDRESS currently has to be an address that
>is simultaneously listenable and connectable.
>
>Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
>---
> doc/dbus-specification.xml |   91 +++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 86 insertions(+), 5 deletions(-)
>
>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index 5d1cd10..fe632ea 100644
>--- a/doc/dbus-specification.xml
>+++ b/doc/dbus-specification.xml
>@@ -2912,6 +2912,35 @@
>       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
>     </para>
> 
>+    <para>
>+      Some addresses are <firstterm>connectable</firstterm>. A connectable
>+      address is one containing enough information for a client to connect
>+      to it. For instance, <literal>tcp:host=127.0.0.1,port=4242</literal>
>+      is a connectable address. It is not necessarily possible to listen
>+      on every connectable address: for instance, it is not possible to
>+      listen on a <literal>unixexec:</literal> address.
>+    </para>
>+
>+    <para>
>+      Some addresses are <firstterm>listenable</firstterm>. A listenable
>+      address is one containing enough information for a server to listen on
>+      it, producing a connectable address (which may differ from the
>+      original address). Many listenable addresses are not connectable:
>+      for instance, <literal>tcp:host=127.0.0.1</literal>
>+      is listenable, but not connectable (because it does not specify
>+      a port number).
>+    </para>
>+
>+    <para>
>+      Listening on an address that is not connectable will result in a
>+      connectable address that is not the same as the listenable address.
>+      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>
>+      might result in the connectable address
>+      <literal>unix:abstract=/tmp/dbus-U8OSdmf7</literal>.
>+    </para>
>   </sect1>
>   
>   <sect1 id="transports">
>@@ -2944,6 +2973,13 @@
>       <para>
>         Unix domain sockets are not available on Windows.
>       </para>
>+      <para>
>+        Unix addresses that specify <literal>path</literal> or
>+        <literal>abstract</literal> are both listenable and connectable.
>+        Unix addresses that specify <literal>tmpdir</literal> are only
>+        listenable: the corresponding connectable address will specify
>+        either <literal>path</literal> or <literal>abstract</literal>.
>+      </para>
>       <sect3 id="transports-unix-domain-sockets-addresses">
>         <title>Server Address Format</title>
>         <para> 
>@@ -2973,11 +3009,16 @@
>           <row>
>             <entry>abstract</entry>
>             <entry>(string)</entry>
>-            <entry>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</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>
>         </tbody>
>         </tgroup>
>        </informaltable>
>+       <para>
>+         Exactly one of the keys <literal>path</literal>,
>+         <literal>abstract</literal> or
>+         <literal>tmpdir</literal> must be provided.
>+       </para>
>       </sect3>
>     </sect2>
>     <sect2 id="transports-launchd">
>@@ -3001,6 +3042,9 @@
>       <para>
>         launchd is not available on Microsoft Windows.
>       </para>
>+      <para>
>+        launchd addresses are listenable and connectable.
>+      </para>
>       <sect3 id="transports-launchd-addresses">
>         <title>Server Address Format</title>
>         <para>
>@@ -3025,6 +3069,9 @@
>         </tbody>
>         </tgroup>
>        </informaltable>
>+       <para>
>+         The <literal>env</literal> key is required.
>+       </para>
>       </sect3>
>     </sect2>
>     <sect2 id="transports-systemd">
>@@ -3047,6 +3094,11 @@
>       <para>
>         The systemd transport defines no parameter keys.
>       </para>
>+      <para>
>+        systemd addresses are listenable, but not connectable. The
>+        corresponding connectable address is the <literal>unix</literal>
>+        or <literal>tcp</literal> address of the socket.
>+      </para>
>     </sect2>
>     <sect2 id="transports-tcp-sockets">
>       <title>TCP Sockets</title>
>@@ -3059,9 +3111,16 @@
>         over a network is unsecure. 
>       </para>
>       <para>  
>-        Windows notes: Because of the tcp stack on Windows does not provide sending
>-        credentials over a tcp connection, the EXTERNAL authentification 
>-        mechanismus does not work. 
>+        On Windows and most Unix platforms, the TCP stack is unable to transfer
>+        credentials over a TCP connection, so the EXTERNAL authentication
>+        mechanism does not work for this transport.
>+      </para>
>+      <para>
>+        All <literal>tcp</literal> addresses are listenable.
>+        <literal>tcp</literal> addresses in which both
>+        <literal>host</literal> and <literal>port</literal> are
>+        specified, and <literal>port</literal> is non-zero,
>+        are also connectable.
>       </para>
>       <sect3 id="transports-tcp-sockets-addresses">
>         <title>Server Address Format</title>
>@@ -3133,6 +3192,12 @@
>         key-value pair and send it over the socket. After that, the
>         transport behaves like an unsecured tcp transport.
>       </para>
>+      <para>
>+        All nonce-tcp addresses are listenable. nonce-tcp addresses in which
>+        <literal>host</literal>, <literal>port</literal> and
>+        <literal>noncefile</literal> are all specified,
>+        and <literal>port</literal> is nonzero, are also connectable.
>+      </para>
>       <sect3 id="transports-nonce-tcp-sockets-addresses">
>         <title>Server Address Format</title>
>         <para> 
>@@ -3170,7 +3235,10 @@
>           <row>
>            <entry>noncefile</entry>
>            <entry>(path)</entry>
>-           <entry>file location containing the secret</entry>
>+           <entry>File location containing the secret.
>+             This is only meaningful in connectable addresses:
>+             a listening D-Bus server that offers this transport
>+             will always create a new nonce file.</entry>
>           </row>
>          </tbody>
>         </tgroup>
>@@ -3193,6 +3261,10 @@
>       <para>
>         Executed subprocesses are not available on Windows.
>       </para>
>+      <para>
>+        <literal>unixexec</literal> addresses are connectable, but are not
>+        listenable.
>+      </para>
>       <sect3 id="transports-exec-addresses">
>         <title>Server Address Format</title>
>         <para>
>@@ -3251,6 +3323,15 @@
>      <para>The autolaunch transport provides a way for dbus clients to autodetect
>        a running dbus session bus and to autolaunch a session bus if not present.
>      </para>
>+      <para>
>+        On Unix, <literal>autolaunch</literal> addresses are connectable,
>+        but not listenable.
>+      </para>
>+      <para>
>+        On Windows, <literal>autolaunch</literal> addresses are both
>+        connectable and listenable.
>+      </para>
>+
>      <sect3 id="meta-transports-autolaunch-addresses">
>        <title>Server Address Format</title>
>        <para>
>-- 
>1.7.10.4
>

Actions: View | Splinter Review

Attachments on bug 61303: 75347 | 75348 | 75349 | 75350 | 75351 | 75352 | 89097 | 91550 | 91551 | 111959 | 111960 | 112940 | 112942 | 112943 | 113366 | 113367 | 113401 | 113402 | 113415 | 113417 | 113759

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.