docs: document mDNS dual-interface hostname conflict#19
Conversation
Connecting a device to the same network over both Ethernet and WiFi makes Avahi hear its own announcements echoed between interfaces and rename itself (halos-2.local), after which halos.local stops resolving. This can't be fixed in software while both interfaces share a subnet, so document the constraint and recovery for users. Add a symptom-driven troubleshooting entry and a cross-linked note under Hostname and mDNS in the networking guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
||
| ### One interface per network | ||
|
|
||
| Don't connect the device to the same network over both Ethernet and WiFi at the same time. On a multi-homed host, Avahi hears its own mDNS announcements echoed between interfaces and renames the device (e.g. to `halos-2.local`), after which `halos.local` stops resolving. If you need both interfaces active, put them on different networks. See [Troubleshooting — Device disappears or shows up as `halos-2.local`](troubleshooting.md#device-disappears-or-shows-up-as-halos-2local). |
There was a problem hiding this comment.
Wording is a bit strong; sometimes the user has good reasons for doing that, and normally it won't break anything. Renaming the device only happens during some corner cases (mDNS hostname is connected to the wifi interface which then gets disabled, for example). It's enough to just state that it may happen.
There was a problem hiding this comment.
Softened in b0833f5 — now says connecting both usually works fine, and the rename "may" happen in some cases rather than stating it as a rule.
|
|
||
| **Symptom**: `halos.local` stops resolving, or the device starts appearing under a numbered name like `halos-2.local`. This often happens after connecting the device to the same network over both Ethernet and WiFi at once. | ||
|
|
||
| **Cause**: When a device is on the same network through two interfaces (wired and wireless) at the same time, its mDNS announcements sent on one interface are heard back on the other. Avahi reads its own echo as a second device claiming the same name, and defensively renames itself by appending a number. The original `.local` name is then claimed by nobody and no longer resolves. |
There was a problem hiding this comment.
This is not what actually happens.
- Let's say wlan0 gets halosdev.local
- eth0 gets halosdev-1.local
- wlan0 is disabled
- Only halosdev-1.local remains
No need to go deeply into specifics; better to just note that Avahi may act up if multiple interfaces are connected to the same network.
There was a problem hiding this comment.
Rewrote the cause in b0833f5. Dropped the self-echo explanation; it now says the hostname is registered per interface, the later one falls back to a numbered name, and the plain name disappears only when the interface holding it is disabled. Kept it brief per your note.
Review feedback: the rename only happens in corner cases, and the described cause was wrong. The hostname is registered per interface; the later one falls back to a numbered name, and the plain name disappears only when the interface holding it is disabled. Reword to "may happen" and drop the inaccurate self-echo mechanism. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Review feedback addressed in b0833f5.
Verification: |
1 participant
Why
A HaLOS device connected to the same network over both Ethernet and WiFi at once can have
halos.localstop resolving, with the device renaming itself tohalos-2.local. Avahi hears its own mDNS announcements echoed between the two interfaces and reads them as a foreign host claiming the name, so it defensively renames.This is a standard Avahi/mDNS limitation on multi-homed hosts on a single subnet — it can't be enforced or fixed in software, so it needs to be a documented operational constraint for users.
(This also corrects an earlier mis-diagnosis that assumed a second physical device was holding the name; the actual cause is the device's own cross-interface echo.)
What
user-guide/troubleshooting.md— new symptom-driven entry "Device disappears or shows up ashalos-2.local": symptom, cause, and the fix (one interface per network, or separate subnets), plus anavahi-daemonrestart to re-register the original name.user-guide/networking.md— short "One interface per network" note under Hostname and mDNS, cross-linked to the troubleshooting entry.Verification
uv run mkdocs build --strictpasses (no broken anchors / link warnings).🤖 Generated with Claude Code