Bug 66915 - update document about listenable address in dbus spec and dbus-damon manpage
Summary: update document about listenable address in dbus spec and dbus-damon manpage
Status: RESOLVED MOVED
Alias: None
Product: dbus
Classification: Unclassified
Component: core (show other bugs)
Version: 1.5
Hardware: All All
: low trivial
Assignee: D-Bus Maintainers
QA Contact: D-Bus Maintainers
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-07-15 07:36 UTC by Chengwei Yang
Modified: 2018-10-12 21:16 UTC (History)
2 users (show)

See Also:
i915 platform:
i915 features:


Attachments
[PATCH 1/2] DBus Spec: clearly speaking listenable address (1.73 KB, patch)
2013-07-19 03:04 UTC, Chengwei Yang
Details | Splinter Review
[PATCH 2/2] Doc: update dbus-daemon manpage about listenable address (1.41 KB, patch)
2013-07-19 03:04 UTC, Chengwei Yang
Details | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Chengwei Yang 2013-07-15 07:36:47 UTC
Copied from http://lists.freedesktop.org/archives/dbus/2013-July/015718.html

Hi List,

I just found that there is an inconsistent issue of message bus server
address.

There are two ways to specify the message bus server addresses, from
command line option "--address" or configure "<listen>" element in bus
config file.

However, they behave a little different as below.

Quote from DBus Spec

 [FIXME clarify if attempting to connect to each is a requirement or
 just a suggestion] When connecting to a server, multiple server
 addresses can be separated by a semi-colon. The library will then try
 to connect to the first address and if that fails, it'll try to connect
 to the next one specified, and so forth. For example

 unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2

Quote from dbus-daemon(1)

 ยท   <listen>

     Add an address that the bus should listen on. The address
	 is in the standard D-Bus format that contains a transport
	 name plus possible parameters/options.

	 Example: <listen>unix:path=/tmp/foo</listen>

	 Example: <listen>tcp:host=localhost,port=1234</listen>

	 If there are multiple <listen> elements, then the bus listens
	 on multiple addresses. The bus will pass its address to
	 started services or other interested parties with
	 the last address given in <listen> first. That
	 is, apps will try to connect to the last <listen>
	 address first.

So seems that we're saying: there is no way to listen on multiple
address if you're using '--address' option, if that is your case,
configure '<listen>' in config file instead.

Should this to be fixed?

If so, how? Align '<listen>(man page)' with '--address(dbus spec)' or
the reverse?

--
Thanks,
Chengwei
Comment 1 Chengwei Yang 2013-07-15 08:05:35 UTC
In current implementation, every <listen> element handled as a '--address', so if there are multiple addresses in <listen>, only the first working one will taken. From this POV, it is consistent.

The *inconsistent* is that multiple <listen> elements could be specified in message bus conf while only one --address option can be given to command line.

So to me, there are below ways to fix up thing a bit.

0. no change.

1. no change but update a bit in dbus spec to say explicitly if you're tring to ask message bus listen on multiple address, do not specify '--address' option but configure multiple <listen> elements instead.

2. multiple '--address' options allowed, this is not good and unlikely to see.

3. only one <listen> allowed, not good neither.
Comment 2 Simon McVittie 2013-07-16 12:11:04 UTC
Why would you want your dbus-daemon to listen on multiple addresses not specified in the configuration file? Triaged to low/trivial unless there's something going on here beyond "it's inconsistent and the inconsistency annoys me".

(In reply to comment #1)
> 1. no change but update a bit in dbus spec to say explicitly if you're tring
> to ask message bus listen on multiple address, do not specify '--address'
> option but configure multiple <listen> elements instead.

I think that would be a change to the dbus-daemon man page, not the D-Bus protocol specification - dbus-daemon is just a reference implementation.

(In reply to comment #0)
>  [FIXME clarify if attempting to connect to each is a requirement or
>  just a suggestion] When connecting to a server, multiple server
>  addresses can be separated by a semi-colon. The library will then try
>  to connect to the first address and if that fails, it'll try to connect
>  to the next one specified, and so forth. For example
> 
>  unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2

This is talking about "connectable" addresses, not listening addresses. I think the fact that the semicolon syntax is accepted at all in <listen> and "dbus-daemon --address", which deal with *listening* addresses, is a quirk of the implementation.

("Listening" addresses are things the dbus-daemon or another DBusServer can listen on, like unix:tmpdir=/tmp or tcp:host=0.0.0.0. "Connectable" addresses are things a client-side DBusConnection can connect to, like unix:path=/tmp/gjspgjeio or tcp:host=127.0.0.1,port=53273.)
Comment 3 Chengwei Yang 2013-07-16 13:20:25 UTC
(In reply to comment #2)
> Why would you want your dbus-daemon to listen on multiple addresses not
> specified in the configuration file? Triaged to low/trivial unless there's
> something going on here beyond "it's inconsistent and the inconsistency
> annoys me".

OK, so far I can't find any other problem here.

> 
> (In reply to comment #1)
> > 1. no change but update a bit in dbus spec to say explicitly if you're tring
> > to ask message bus listen on multiple address, do not specify '--address'
> > option but configure multiple <listen> elements instead.
> 
> I think that would be a change to the dbus-daemon man page, not the D-Bus
> protocol specification - dbus-daemon is just a reference implementation.

OK.

> 
> (In reply to comment #0)
> >  [FIXME clarify if attempting to connect to each is a requirement or
> >  just a suggestion] When connecting to a server, multiple server
> >  addresses can be separated by a semi-colon. The library will then try
> >  to connect to the first address and if that fails, it'll try to connect
> >  to the next one specified, and so forth. For example
> > 
> >  unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2
> 
> This is talking about "connectable" addresses, not listening addresses. I
> think the fact that the semicolon syntax is accepted at all in <listen> and
> "dbus-daemon --address", which deal with *listening* addresses, is a quirk
> of the implementation.
> 
> ("Listening" addresses are things the dbus-daemon or another DBusServer can
> listen on, like unix:tmpdir=/tmp or tcp:host=0.0.0.0. "Connectable"
> addresses are things a client-side DBusConnection can connect to, like
> unix:path=/tmp/gjspgjeio or tcp:host=127.0.0.1,port=53273.)

I'm not quite understand you. As I learned so far, dbus-daemon can also listen on a address like unix:path=/tmp/dbus-test.
Comment 4 Simon McVittie 2013-07-16 15:01:25 UTC
(In reply to comment #3)
> > ("Listening" addresses are things the dbus-daemon or another DBusServer can
> > listen on, like unix:tmpdir=/tmp or tcp:host=0.0.0.0. "Connectable"
> > addresses are things a client-side DBusConnection can connect to, like
> > unix:path=/tmp/gjspgjeio or tcp:host=127.0.0.1,port=53273.)
> 
> I'm not quite understand you. As I learned so far, dbus-daemon can also
> listen on a address like unix:path=/tmp/dbus-test.

Yes, it can, but my point was that not every valid "listening" address is also a valid "connecting" address: you can't connect to unix:tmpdir=/tmp, or to "systemd:".

Similarly, not every valid "connecting" address is a valid "listening" address: on Unix, you can't listen on "autolaunch:", but you can connect to it. (Autolaunching on Windows is different.)
Comment 5 Chengwei Yang 2013-07-17 01:37:44 UTC
(In reply to comment #4)
> (In reply to comment #3)
> > > ("Listening" addresses are things the dbus-daemon or another DBusServer can
> > > listen on, like unix:tmpdir=/tmp or tcp:host=0.0.0.0. "Connectable"
> > > addresses are things a client-side DBusConnection can connect to, like
> > > unix:path=/tmp/gjspgjeio or tcp:host=127.0.0.1,port=53273.)
> > 
> > I'm not quite understand you. As I learned so far, dbus-daemon can also
> > listen on a address like unix:path=/tmp/dbus-test.
> 
> Yes, it can, but my point was that not every valid "listening" address is
> also a valid "connecting" address: you can't connect to unix:tmpdir=/tmp, or
> to "systemd:".
> 
> Similarly, not every valid "connecting" address is a valid "listening"
> address: on Unix, you can't listen on "autolaunch:", but you can connect to
> it. (Autolaunching on Windows is different.)

Got you, thank you.
Comment 6 Chengwei Yang 2013-07-18 05:32:31 UTC
Correct me if I am wrong.

Quote from DBus Spec again.

[FIXME clarify if attempting to connect to each is a requirement or just a suggestion] *When connecting to a server*, multiple server addresses can be separated by a semi-colon. *The library will then try to connect to the first address* and if that fails, it'll try to connect to the next one specified, and so forth. For example

unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2

The words confusing me

1. When connecting to a server, ... 
It seems it describe the *connectable address*  rather than the *listenable address*?

2. The library will then try to connect to the first address ...
Here too, *connect to* always used by client and *listen at* used by server.

However, from the implementation, apparently, the above address is the *listenable address*, because dbus_connection_open()/dbus_bus_register() will fail if there isn't a server listen at the first address, *and it will not try to connect to the next one specified.*, this is just not the case described in the specification.

I think we need update the DBus Sepc a bit about the server address section, document more about the *listenable address* and the *connectable address*.
Comment 7 Simon McVittie 2013-07-18 09:34:01 UTC
(In reply to comment #6)
> However, from the implementation, apparently, the above address is the
> *listenable address*, because dbus_connection_open()/dbus_bus_register()
> will fail if there isn't a server listen at the first address, *and it will
> not try to connect to the next one specified.*, this is just not the case
> described in the specification.

It's entirely possible that the specification describes what Havoc wanted, and not what has actually been implemented.

dbus_connection_open() (and its _private() equivalent) deals with connectable addresses; dbus_server_listen() deals with listenable addresses.

I was surprised to see "If there are multiple semicolon-separated address entries in the address, tries each one and listens on the first one that works" in the dbus_server_listen() docs - does that even make sense?

dbus_bus_get() gets a connectable address from various locations including $DBUS_SESSION_BUS_ADDRESS, which I'm fairly sure is interpreted as a semicolon-separated list.
Comment 8 Chengwei Yang 2013-07-19 02:16:03 UTC
(In reply to comment #7)
> (In reply to comment #6)
> > However, from the implementation, apparently, the above address is the
> > *listenable address*, because dbus_connection_open()/dbus_bus_register()
> > will fail if there isn't a server listen at the first address, *and it will
> > not try to connect to the next one specified.*, this is just not the case
> > described in the specification.
> 
> It's entirely possible that the specification describes what Havoc wanted,
> and not what has actually been implemented.
> 
> dbus_connection_open() (and its _private() equivalent) deals with
> connectable addresses; dbus_server_listen() deals with listenable addresses.
> 
> I was surprised to see "If there are multiple semicolon-separated address
> entries in the address, tries each one and listens on the first one that
> works" in the dbus_server_listen() docs - does that even make sense?

Yes, that's true for listenable address, at least, I think it's better to change dbus spec something like:

---------------8<----------------------------8<----------------------------
[FIXME clarify if attempting to connect to each is a requirement or just a suggestion] When listening to an address, multiple server addresses can be separated by a semi-colon. The library will then try to listen at the first address and if that fails, it'll try to listen at the next one specified, and so forth. For example
--------------8<-----------------------------8<----------------------------

> 
> dbus_bus_get() gets a connectable address from various locations including
> $DBUS_SESSION_BUS_ADDRESS, which I'm fairly sure is interpreted as a
> semicolon-separated list.

Yes, it is, as dbus_connection_open(), however, it will not try the next if there is no server listen at that address. That's the point, so I'd like to change a bit about the dbus spec to say clearly it's talking about listenable address.
Comment 9 Chengwei Yang 2013-07-19 03:04:07 UTC
Created attachment 82649 [details] [review]
[PATCH 1/2] DBus Spec: clearly speaking listenable address
Comment 10 Chengwei Yang 2013-07-19 03:04:36 UTC
Created attachment 82650 [details] [review]
[PATCH 2/2] Doc: update dbus-daemon manpage about listenable address
Comment 11 Chengwei Yang 2013-07-19 06:49:13 UTC
(In reply to comment #8)
> (In reply to comment #7)
> > (In reply to comment #6)
> > > However, from the implementation, apparently, the above address is the
> > > *listenable address*, because dbus_connection_open()/dbus_bus_register()
> > > will fail if there isn't a server listen at the first address, *and it will
> > > not try to connect to the next one specified.*, this is just not the case
> > > described in the specification.
> > 
> > It's entirely possible that the specification describes what Havoc wanted,
> > and not what has actually been implemented.
> > 
> > dbus_connection_open() (and its _private() equivalent) deals with
> > connectable addresses; dbus_server_listen() deals with listenable addresses.
> > 
> > I was surprised to see "If there are multiple semicolon-separated address
> > entries in the address, tries each one and listens on the first one that
> > works" in the dbus_server_listen() docs - does that even make sense?
> 
> Yes, that's true for listenable address, at least, I think it's better to
> change dbus spec something like:
> 
> ---------------8<----------------------------8<----------------------------
> [FIXME clarify if attempting to connect to each is a requirement or just a
> suggestion] When listening to an address, multiple server addresses can be
> separated by a semi-colon. The library will then try to listen at the first
> address and if that fails, it'll try to listen at the next one specified,
> and so forth. For example
> --------------8<-----------------------------8<----------------------------
> 
> > 
> > dbus_bus_get() gets a connectable address from various locations including
> > $DBUS_SESSION_BUS_ADDRESS, which I'm fairly sure is interpreted as a
> > semicolon-separated list.
> 
> Yes, it is, as dbus_connection_open(), however, it will not try the next if
> there is no server listen at that address. That's the point, so I'd like to
> change a bit about the dbus spec to say clearly it's talking about
> listenable address.

Sorry, I was confused myself. It does do try the next.
Comment 12 Chengwei Yang 2013-07-19 06:52:59 UTC
Comment on attachment 82649 [details] [review]
[PATCH 1/2] DBus Spec: clearly speaking listenable address

This was wrong! The original document is corret, to prevent latter ones like me from confusing, I think we need document more about listenable address and connectable address.
Comment 13 Simon McVittie 2014-01-06 15:38:20 UTC
Not for 1.8. Please re-keyword as "patch" when you have something you want reviewed, or comment with questions if there are things you want to clarify.
Comment 14 GitLab Migration User 2018-10-12 21:16:33 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/dbus/dbus/issues/87.


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.