[avahi] Re: Some notes on designing the Avahi DBUS API

Sat Jun 25 00:59:20 PDT 2005

2005/6/25, Lennart Poettering <mzzhgg at 0pointer.de>:
> On Sat, 25.06.05 01:34, Sebastien Estienne (sebastien.estienne at gmail.com) wrote:
> 
> > Hi!
> 
> Hi!
> 
> > Just a short mail to let you know, that i'm working on small cli tool
> > (equivalent of mdnspublish, mdnsbrowse) for the moment i'm using the
> > simple protocol , and then i'll rewrite them using dbus.
> 
> The simple protocol currently supports just three useful commands
> (RESOLVE-HOSTNAME, RESOLVE-ADDRESS, BROWSE-DNS-SERVERS and an easter
> egg) which I needed to hook nss-mdns and avahi-dnsconfd up to avahi. I
> am somewhat reluctant to make that simple protocol full-fledged,
> because I see the DBUS API as more important and flexible and as the
> API everybody should use. There ain't any official client library for
> the simple protocol or anything.
> 
> Things like mdnspublish/mdnsbrowse are impossible with the current
> state of the simple protocol.
> 
> You could beef up the simple protocol, but this would require careful
> thinking of a sensible syntax:
> 
>  - you need to support adding multiple services at the same time
>    (i.e. a personal FTP/HTTP/WEBDAV server needs to register three
>    services with the same name. If one of the three conflicts, the
>    others should not be added. This kind of atomic adding of multiple
>    records to the server is a special feature of avahi, which
>    shouldn't get lost.
> 
>  - you need to support notifications to the client program about
>    host/domain name changes, because it may need to reestablish its
>    services. (i.e. when the server name changes from "foo" to "bar",
>    the SSH service needs to be changed from the name "Remote Terminal
>    on foo" pointing to "foo:22" to "Remote Terminal on bar" pointing
>    to "bar:22". Host name changes can happen at any time due to
>    name conflicts with other machines.
> 
>  - the same is required for detecting service name conflicts
> 
>  - the same is required not only when registering services, but for
>    queries, too. i.e. if the domain changes from ".local" to ".home",
>    the browse objects need to be recreated for the new domain.
> 
> This all isn't simple, and I must admit that im a little to lazy to
> think about a sane textual syntax for all these things. The current
> simple protocol only supports very high-level and unflexible
> commands due to this. I added them just to be able to implement
> nss-mdns/dnsconfd. They are good enough for that, but not any better.
> 
> Another difficult topic is authentication. While it may be OK to
> browse for services as any user, the administrator might be interested
> in disallowing normal users to register services. If we'd beef up the
> simple protocol with authentication functions, it would get much to
> complicated. DBUS already has this auth stuff.
> 
> In short: the simple protocol is nothing we should want other people to
> know of. Let's keep it for our internal use, but not documented and
> known to the public. The people shall use the DBUS interface, not the
> so called "simple protocol." Therefore: please use the DBUS API for
> these tools, especially when your code is intended as an example.

I think that i misunderstood something, when i said "simple protocol"
i was refering to the api used by avahi-discover: avahi-core/core:h.
Is this really an Api, and do we want people to know about this?

It seems that the simple protocol was infact the protocol using the
unix socket, right? I must confess that i don't have a clear picture
of how things work together (internally).

I thought that when i wrote some code linked to avahi-core like
avahi-discover using core.h, the link between avahi-daemon and
avahi-discover was the unix socket, and that the simple protocol was
used there
And that dbus could replace this unix socket.
But it seems, i was wrong :)

How does dbus integrate with avahi-daemon, will it be implemented on
top of core:h (linking to avahi-core)? or is it directly built in
avahi-daemon like it seems when reading dbus-protocol.c.

> 
> To match with the rest of the avahi tool set it might be a good idea
> to name those tools "avahi-browse" and "avahi-publish", though. ;-)
yes i could do this way, or the "avahi-cli --browse/--publish"

> 
> > I'm doing for 3 main reasons:
> > 1) being familiar and testing the code and api.
> > 2) they could be usefull for debugging/testing purpose.
> > 3) making this the base of a tutorial on using avahi, so other
> > developpers have a working example of using avahi for basic and most
> > common needs namely publishing and browsing.
> >
> > So i've the project to write some kind of tutorial on using avahi with :
> > -simple protocol
> > -dbus api using glib
> > -and maybe some reference client in python,qt, c-sharp (any language
> > that have dbus bindings)
> 
> Great! I really appreciate this!
> 
> > So our helloworld would be mdns publish and browse.
> > I'm doing this because i think a good example is always the best
> > starting point on using a technology. And also because i want
> > avahi/zeroconf to be widely used by other softwares.
> 
> Yep. Me too.
> 
> > I wanted to let you know about this to not duplicate effort on this
> > topic and have your opinions/ideas/recommendations on the subject.
> 
> If not started with any real documentation besides some doxygen
> comments for avahi-core.
> 
> I really like your idea, however, since there's no client API yet,
> it's probably a little early. :-(
I think i could start by documenting the internals (for future avahi
contributors), doing some schemas to explain the big picture when i'll
have understand it well :)
(some schemas a bit like this
http://www.nrg4u.com/qmail/the-big-qmail-picture-103-p1.gif but for
avahi architecture)

> 
> > on a side note, with us we could even have the tutorial available in 3
> > languages namely english, german and  french.
> 
> Although I am german I rarely read german technical documentation if
> an english version is available. Most of the time the translations are
> a little awkward and almost always out of date. And I think that most
> german Linux developers think this way, too. (that's a little
> different with end users, but the tutorial is intended for developers,
> isn't it?)
Yes that's true that english is the reference language for technical
documentation. About "out of date", i think that we are doing a
tutorial for an Api, so we'll only mention the bases so it's not a
moving target in my opinion.
But you are right, translation is not a top priority, only a plus.

> 
> 
> Lennart
> 
> --
> name { Lennart Poettering } loc { Hamburg - Germany }
> mail { mzft (at) 0pointer (dot) de } gpg { 1A015CC4 }
> www { http://0pointer.de/lennart/ } icq# { 11060553 }
> 

-- 
Sebastien Estienne