You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Supervisor mDNS announcement API backed by systemd-resolved DNS-SD
#1458
Apps (formerly "add-ons") have no good way to make their services discoverable on the LAN. Today the practical route is host_network: true plus the app bringing its own mDNS stack — for what is really a host-level concern.
This proposes a Supervisor API modeled on the existing discovery API. The app declares which service types it may announce in config.yaml, and registers the announcement at runtime when its service is ready. Supervisor publishes it through systemd-resolved — the host's mDNS service — and withdraws it when the app stops. No host_network, no additional mDNS stack, IPv4 and IPv6.
Background
systemd-resolved already provides mDNS at the host level, in both directions: it resolves (.local hostnames) and it announces (the host's own hostname, plus DNS-SD services registered with it). Supervisor uses the resolve side today — the DNS plugin's CoreDNS forwards .local queries to resolved — so every app gets mDNS resolution without running a resolver of its own. The announce side has no equivalent path: an app that wants to announce a service is on its own.
What apps do instead:
Run their own responder on the host network. Spotify Connect, AirCast, and the CUPS apps all bring an mDNS stack (libmdns, avahi) and announce from there. In the "Implementing mDNS into custom addon" forum thread, authors doing this hit conflicts with resolved's own responder, or piggyback on Core's zeroconf via Pyscript instead.
Every app-own responder is another mDNS stack on the same host. mDNS is by design a per-host service — one responder answering for the machine — and parallel stacks interfere: they contend for port 5353, warn about each other, and multiply announcements. Fewer mDNS responders and resolvers per host is the architectural goal. Resolution has already moved to the system service; this proposal does the same for announcement, publishing app services under the host's hostname with the host's real addresses, on IPv4 and IPv6, on every mDNS-enabled link.
One property of resolved's registration API shapes the design: resolved withdraws a registration the moment the registering D-Bus client disconnects. (Verified in the systemd source; the behavior exists since at least v243.) Whoever registers must keep a bus connection open for the whole lifetime of the announcement. A one-shot gdbus call, as in home-assistant/apps#4742, registers a service that disappears right away.
So some long-lived process has to own the bus connection. Supervisor already maintains a resolved D-Bus connection and already watches app container state. It is the natural owner.
Proposal
A runtime API modeled on the existing discovery API, rather than static service declarations in config.yaml.
Permission gate in config.yaml
The app declares which service types it may announce, exactly like discovery: works today. Store review stays meaningful, and apps cannot impersonate sensitive types (_home-assistant._tcp, _hap._tcp, _matter._tcp, …) without it showing up in review.
Registration at runtime
The app announces when its service is actually ready: POST /mdns with service type, port, and optional instance name and TXT records, returning a uuid. DELETE /mdns/{uuid} withdraws. A bashio helper makes it one line.
Runtime registration is deliberate. mDNS clients cache aggressively, so announcing before the socket listens means visible breakage for users — and only the app knows when it is ready. It also lets the app decide based on its own options (Samba already has a network_discovery toggle) and fill in TXT records with runtime values. A static declaration can express none of that.
Supervisor owns the lifecycle
When the app's container stops, crashes, or the app is uninstalled, Supervisor withdraws its announcements. Container state is already watched.
When Supervisor itself restarts or updates, app containers keep running and would not re-announce on their own. Supervisor therefore persists announcements and re-registers them on startup.
If Supervisor crashes, all registrations vanish with its bus connection. Stale announcements cannot occur.
On app start, nothing is announced automatically. The app announces again when it is ready.
For the app developer the result is: one declared permission, one call at readiness. A bridge-network app additionally needs its announced port published to the host via ports:, since the records point at the host.
Design notes
Identifiers and instance names: resolved's registration takes two names. The service identifier is a purely local handle, never visible on the network; Supervisor generates it (e.g. {app_slug}_{uuid}) to satisfy resolved's uniqueness requirement, and a repeated POST for the same service upserts instead of erroring. The instance name — what users see when browsing — defaults to the app name and is not namespaced. On a name conflict on the network, resolved does not rename: it withdraws the service and emits a Conflicted signal. Supervisor reacts to that signal; the simple policy is to re-register under an altered name (e.g. with a counter appended), and whether that happens silently or is surfaced to the app is left open for discussion.
systemd floor: the D-Bus API exists since systemd v243, well below anything Supervisor runs on.
resolved restarts: Supervisor re-registers from its persisted state when resolved reconnects.
Scope: this covers announcing services under the host identity. LAN browsing from bridge apps, and apps running their own mDNS responder, are out of scope; that class of need is addressed by L2 network presence (Supervisor isolated physical network access/macvlan support #1034).
Relation to the multicast plugin deprecation
A separate proposal covers deprecating the multicast plugin (see #1457). The two are independent. The plugin has not carried app announcements out to the LAN since February 2022 (home-assistant/plugin-multicast#44), so this API is not a replacement racing a removal. It answers demand that exists today, whatever happens to the plugin, and each can proceed on its own timeline.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
TL;DR
Apps (formerly "add-ons") have no good way to make their services discoverable on the LAN. Today the practical route is
host_network: trueplus the app bringing its own mDNS stack — for what is really a host-level concern.This proposes a Supervisor API modeled on the existing discovery API. The app declares which service types it may announce in
config.yaml, and registers the announcement at runtime when its service is ready. Supervisor publishes it through systemd-resolved — the host's mDNS service — and withdraws it when the app stops. Nohost_network, no additional mDNS stack, IPv4 and IPv6.Background
systemd-resolved already provides mDNS at the host level, in both directions: it resolves (
.localhostnames) and it announces (the host's own hostname, plus DNS-SD services registered with it). Supervisor uses the resolve side today — the DNS plugin's CoreDNS forwards.localqueries to resolved — so every app gets mDNS resolution without running a resolver of its own. The announce side has no equivalent path: an app that wants to announce a service is on its own.What apps do instead:
_smb._tcpthrough resolved'sRegisterService— which requireshost_dbus: true, full host bus access for one call. Samba: Add configuration option to disable WSDD apps#4738 (merged) does the same for WS-Discovery.Every app-own responder is another mDNS stack on the same host. mDNS is by design a per-host service — one responder answering for the machine — and parallel stacks interfere: they contend for port 5353, warn about each other, and multiply announcements. Fewer mDNS responders and resolvers per host is the architectural goal. Resolution has already moved to the system service; this proposal does the same for announcement, publishing app services under the host's hostname with the host's real addresses, on IPv4 and IPv6, on every mDNS-enabled link.
One property of resolved's registration API shapes the design: resolved withdraws a registration the moment the registering D-Bus client disconnects. (Verified in the systemd source; the behavior exists since at least v243.) Whoever registers must keep a bus connection open for the whole lifetime of the announcement. A one-shot
gdbus call, as in home-assistant/apps#4742, registers a service that disappears right away.So some long-lived process has to own the bus connection. Supervisor already maintains a resolved D-Bus connection and already watches app container state. It is the natural owner.
Proposal
A runtime API modeled on the existing discovery API, rather than static service declarations in
config.yaml.Permission gate in
config.yamlThe app declares which service types it may announce, exactly like
discovery:works today. Store review stays meaningful, and apps cannot impersonate sensitive types (_home-assistant._tcp,_hap._tcp,_matter._tcp, …) without it showing up in review.Registration at runtime
The app announces when its service is actually ready:
POST /mdnswith service type, port, and optional instance name and TXT records, returning a uuid.DELETE /mdns/{uuid}withdraws. A bashio helper makes it one line.Runtime registration is deliberate. mDNS clients cache aggressively, so announcing before the socket listens means visible breakage for users — and only the app knows when it is ready. It also lets the app decide based on its own options (Samba already has a
network_discoverytoggle) and fill in TXT records with runtime values. A static declaration can express none of that.Supervisor owns the lifecycle
For the app developer the result is: one declared permission, one call at readiness. A bridge-network app additionally needs its announced port published to the host via
ports:, since the records point at the host.Design notes
{app_slug}_{uuid}) to satisfy resolved's uniqueness requirement, and a repeatedPOSTfor the same service upserts instead of erroring. The instance name — what users see when browsing — defaults to the app name and is not namespaced. On a name conflict on the network, resolved does not rename: it withdraws the service and emits aConflictedsignal. Supervisor reacts to that signal; the simple policy is to re-register under an altered name (e.g. with a counter appended), and whether that happens silently or is surfaced to the app is left open for discussion.Relation to the multicast plugin deprecation
A separate proposal covers deprecating the multicast plugin (see #1457). The two are independent. The plugin has not carried app announcements out to the LAN since February 2022 (home-assistant/plugin-multicast#44), so this API is not a replacement racing a removal. It answers demand that exists today, whatever happens to the plugin, and each can proceed on its own timeline.
References
Changelog
All reactions