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

[Lennart Poettering]

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.

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. ;-)

> 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. :-(

> 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?)



Lennart

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