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

[Trent Lloyd]

On Sat, Jun 25, 2005 at 09:59:20AM +0200, Sebastien Estienne wrote:
> 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.

Right, basically you are confused :)

avahi-core (the API used by avahi-discover) is the 'core' of avahi, its
the mdns engine, this API can be used to write a daemon for speaking
dbus, or for embedded applications, etc.

the 'simple protocol' is a very simple communication overa unix socket
to the avahi-daemon (already implemented) that allows for resolving
hostnames, ip reverses and search for dns servers.

This is used for use with libnss-mdns, which is a system library, needs
to be fast with no deps and hence not using dbus.

avahi-daemon will implement a d-bus interface to this engine, as well as
the existing socket protocol, and maybe some other stuff in future.

People should almost never be using 'avahi-core' directly, unless
writing an embedded app or the daemon -- in your case writing a test
mdnsbrowse/publish with the API would be usefull, because you plan to
help me write the dbus daemon, which would involve using that API
directly (unlike most people, who would use the dbus api).

Hope that clears things up. :)

PS: lennart: Why are we not using the mailing list for this?

Cheers,
Trent


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

-- 
Trent Lloyd <lathiat at bur.st>
Bur.st Networking Inc.