From 05c473d0ccba3b92b1fe731002e95ed1e6370890 Mon Sep 17 00:00:00 2001 From: Simon McVittie 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 --- 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 @@ unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2 + + Some addresses are connectable. A connectable + address is one containing enough information for a client to connect + to it. For instance, tcp:host=127.0.0.1,port=4242 + 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 unixexec: address. + + + + Some addresses are listenable. 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, tcp:host=127.0.0.1 + is listenable, but not connectable (because it does not specify + a port number). + + + + 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 tcp:host=127.0.0.1 + might result in the connectable address + tcp:host=127.0.0.1,port=30958, + or listening on unix:tmpdir=/tmp + might result in the connectable address + unix:abstract=/tmp/dbus-U8OSdmf7. + @@ -2944,6 +2973,13 @@ Unix domain sockets are not available on Windows. + + Unix addresses that specify path or + abstract are both listenable and connectable. + Unix addresses that specify tmpdir are only + listenable: the corresponding connectable address will specify + either path or abstract. + Server Address Format @@ -2973,11 +3009,16 @@ abstract (string) - unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set. + 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. + + Exactly one of the keys path, + abstract or + tmpdir must be provided. + @@ -3001,6 +3042,9 @@ launchd is not available on Microsoft Windows. + + launchd addresses are listenable and connectable. + Server Address Format @@ -3025,6 +3069,9 @@ + + The env key is required. + @@ -3047,6 +3094,11 @@ The systemd transport defines no parameter keys. + + systemd addresses are listenable, but not connectable. The + corresponding connectable address is the unix + or tcp address of the socket. + TCP Sockets @@ -3059,9 +3111,16 @@ over a network is unsecure. - 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. + + + All tcp addresses are listenable. + tcp addresses in which both + host and port are + specified, and port is non-zero, + are also connectable. Server Address Format @@ -3133,6 +3192,12 @@ key-value pair and send it over the socket. After that, the transport behaves like an unsecured tcp transport. + + All nonce-tcp addresses are listenable. nonce-tcp addresses in which + host, port and + noncefile are all specified, + and port is nonzero, are also connectable. + Server Address Format @@ -3170,7 +3235,10 @@ noncefile (path) - file location containing the secret + 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. @@ -3193,6 +3261,10 @@ Executed subprocesses are not available on Windows. + + unixexec addresses are connectable, but are not + listenable. + Server Address Format @@ -3251,6 +3323,15 @@ 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. + + On Unix, autolaunch addresses are connectable, + but not listenable. + + + On Windows, autolaunch addresses are both + connectable and listenable. + + Server Address Format -- 1.7.10.4