How do I register/unregister a service dynamically using the AVAHI D-Bus API (and what’s the simplest example flow)?

Most developers who arrive at the D-Bus API already know Avahi’s core behavior: the avahi-daemon runs a single mDNS/DNS-SD stack on the host, and your application talks to it over D-Bus to publish and browse services. Dynamic registration/unregistration is just “create an entry group, add a service, commit, and later reset or free that group.”

Below is a concrete, minimal flow you can copy and adapt: how to register a service dynamically, how to remove it again, and which D-Bus objects/methods are involved.

Where the D-Bus API Fits (and When to Use It)

Avahi exposes three main integration surfaces:

C client API (libavahi-client + avahi-daemon) – full-featured, uses Avahi’s event-loop abstraction (AvahiSimplePoll, AvahiGLibPoll, avahi_qt_poll_get()).
Core API (libavahi-core) – runs its own mDNS/DNS-SD stack; intended for embedded appliances. Not recommended for normal desktops, because multiple stacks on one host fight each other.
D-Bus API – an extensive D-Bus interface for browsing and registering services via avahi-daemon. Recommended for software written in any language other than C (e.g., Python, Rust with dbus bindings, etc.).

This article focuses on the D-Bus API path: your program connects to the system bus, talks to org.freedesktop.Avahi, and uses an EntryGroup object to manage services dynamically.

High-Level Flow: Dynamic Registration/Unregistration Over D-Bus

For “register/unregister a service dynamically using the Avahi D-Bus API,” the essential sequence is:

Connect to the system D-Bus.
Talk to org.freedesktop.Avahi.Server:
- Check server state (optional but recommended).
- Create a new EntryGroup object.
On the EntryGroup:
- Add one or more services.
- Commit the group so Avahi publishes them.
Later, when you want to remove the service:
- Call Reset() on the EntryGroup to unregister, or
- Free() the EntryGroup entirely.
Watch for server state changes (daemon restart, collisions) and re-register if necessary.

The C client library implements this logic with the algorithm documented in the Avahi docs:

avahi_entry_group_new()
avahi_entry_group_add_service()
Handle AVAHI_SERVER_COLLISION / AVAHI_SERVER_REGISTERING states
avahi_entry_group_commit()

On D-Bus, you mirror the same idea using D-Bus methods and signals instead of the C functions.

Core D-Bus Objects and Methods You’ll Use

All of this happens on the system bus under the service name org.freedesktop.Avahi.

The key pieces:

Service name: org.freedesktop.Avahi
Server object path: /
Server interface: org.freedesktop.Avahi.Server
EntryGroup interface: org.freedesktop.Avahi.EntryGroup
Common enums interface: org.freedesktop.Avahi.Server (ServerState constants, IF_UNSPEC, etc.)

You typically perform these operations:

On org.freedesktop.Avahi.Server:

GetState() → int
EntryGroupNew() → (o group_path)
Returns a new EntryGroup object path.

On org.freedesktop.Avahi.EntryGroup:

AddService(int interface, int protocol, uint32 flags, string name, string type, string domain, string host, uint16 port, a(sv) txt)
Add a service to this group.
Commit()
Actually publish the services in the group.
Reset()
Unregister all services in this group.
Free()
Destroy the group; it can’t be reused.
GetState() → int

Signals (you should at least be aware of these):

org.freedesktop.Avahi.Server.StateChanged(int state, string error)
Signals server state transitions (e.g., AVAHI_SERVER_COLLISION).
org.freedesktop.Avahi.EntryGroup.StateChanged(int state, string error)
Tells you when a group is established, collides, or fails.

The constants for interface/protocol (e.g., IF_UNSPEC, PROTO_UNSPEC) map to integers on D-Bus. If you don’t care about pinning a specific interface, use “unspecified” to let Avahi choose.

Minimal Example Flow in Plain Steps

This is the simplest “register/unregister a service dynamically using the Avahi D-Bus API” flow, stripped down to just what you need.

1. Connect to system D-Bus and the Avahi server

In most dbus bindings (Python shown as a stand-in):

import dbus

bus = dbus.SystemBus()

server = dbus.Interface(
    bus.get_object('org.freedesktop.Avahi', '/'),
    'org.freedesktop.Avahi.Server'
)

You can optionally query the current state:

state = server.GetState()
# Expect values like AVAHI_SERVER_RUNNING (2)

In a robust client, you’d also subscribe to the StateChanged signal and handle daemon restarts.

2. Create an EntryGroup for your services

group_path = server.EntryGroupNew()
group = dbus.Interface(
    bus.get_object('org.freedesktop.Avahi', group_path),
    'org.freedesktop.Avahi.EntryGroup'
)

This mirrors avahi_entry_group_new() from the C API.

3. Add a service to the group

Assume all interfaces, all protocols, no special flags:

Interface: -1 (IF_UNSPEC)
Protocol: -1 (PROTO_UNSPEC)
Flags: 0
Name: "My Test Service"
Type: "_myservice._tcp" (must be a valid DNS-SD type)
Domain: "" (default .local)
Host: "" (use local host)
Port: 12345
TXT records: optional key/value pairs

IF_UNSPEC = -1
PROTO_UNSPEC = -1
FLAGS = 0

service_name = "My Test Service"
service_type = "_myservice._tcp"
domain = ""
host = ""
port = 12345

# Simple TXT record: key=value
txt = dbus.Array([
    dbus.ByteArray(b"version=1"),
], signature='ay')

group.AddService(
    IF_UNSPEC,
    PROTO_UNSPEC,
    FLAGS,
    service_name,
    service_type,
    domain,
    host,
    dbus.UInt16(port),
    txt
)

This step is equivalent, conceptually, to avahi_entry_group_add_service().

You can add more services or subtypes the same way, as long as you do it before calling Commit().

4. Commit the group (actually publish the service)

group.Commit()

After Commit(), Avahi publishes the service via mDNS/DNS-SD on the LAN. Bonjour/Zeroconf clients on other machines can now discover "_myservice._tcp" and see “My Test Service” on the default .local domain.

If the local hostname changes or collides, Avahi may need to adjust. That’s why the docs recommend handling server state changes: when the server enters AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING, your services may not be reachable and may need to be moved or re-registered.

5. Unregister the service dynamically

To unpublish the service at runtime without destroying the EntryGroup object:

group.Reset()

Reset() removes all services from that group on the network.
You can then AddService() again and Commit() later if you want to republish.

To completely clean up the group when you’re done permanently:

group.Free()

After Free(), that EntryGroup path is no longer valid.
If you want to publish again, call EntryGroupNew() on the server to get a new group.

This is the dynamic “register/unregister” mechanism: allocate a group, add, commit; later reset or free.

Simple End-to-End Example (Pseudocode Summary)

Putting it all together, here’s a direct “simplest flow” summary that you can mirror in any D-Bus-capable language:

Connect to Avahi server:

bus = SystemBus()
server = bus.get_interface("org.freedesktop.Avahi", "/", "org.freedesktop.Avahi.Server")

Create an EntryGroup:

group_path = server.EntryGroupNew()
group = bus.get_interface("org.freedesktop.Avahi", group_path, "org.freedesktop.Avahi.EntryGroup")

Add service to group:

group.AddService(
    IF_UNSPEC = -1,
    PROTO_UNSPEC = -1,
    FLAGS = 0,
    name = "My Test Service",
    type = "_myservice._tcp",
    domain = "",
    host = "",
    port = 12345,
    txt = ["version=1"]
)

Commit group:

group.Commit()
# Service is now advertised on the LAN

Later, unregister:

group.Reset()   # removes the service
# or
group.Free()    # removes and destroys the group

On daemon restart/collision:
Watch Server.StateChanged and EntryGroup.StateChanged. When the server transitions into AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING, assume services may be unreachable; once it’s back in a running state, rebuild your entry group and re-register with AddService() + Commit().

Handling Daemon Restarts and Collisions (Operational Notes)

In real deployments, you’ll want behavior similar to the C-client documentation’s “How to Write a Client That Can Deal with Daemon Restarts”:

Subscribe to StateChanged on org.freedesktop.Avahi.Server.
When the daemon goes away and comes back:
- Recreate your EntryGroup (EntryGroupNew()).
- Re-add all services.
- Call Commit() again.
When the server enters AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING:
- Treat your services as temporarily invalid; either pause publication or wait until the server’s state indicates a stable hostname again and then rebuild the group.

This ensures your dynamic registration logic survives common real-world events: daemon restart, hostname conflicts, and interface churn.

Summary: Small Mental Model to Keep

For “how do I register/unregister a service dynamically using the Avahi D-Bus API (and what’s the simplest example flow)” keep this in your head:

The avahi-daemon owns the mDNS/DNS-SD stack.
Over D-Bus, the Server object gives you EntryGroup objects.
An EntryGroup is your handle for “some services I publish.”
Register = EntryGroupNew() → AddService() → Commit().
Unregister = Reset() (temporary) or Free() (permanent).
Robustness = listen to server and entry-group StateChanged and re-register when needed.

From there you can add more protocol details (subtypes, TXT records, specific interfaces), but that minimal flow covers the dynamic register/unregister path most applications need.

Get Started