Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Avahi Runbook

When debugging mDNS issues with Avahi on a LAN, particularly when a .local hostname like ats.local suddenly disappears despite the host being up, here’s a systematic approach to debug it:

1. Check if the host is still advertising via Avahi

On another machine on the LAN, run:

avahi-browse -a -t

Look for the ats.local hostname in the output.

You can also be more specific:

avahi-resolve-host-name ats.local

If this fails, then it confirms that the mDNS record is no longer available or has expired.

2. Check Avahi status on the target host (e.g., ats)

On the ats host, run:

sudo systemctl status avahi-daemon

If it’s not active, start or restart it:

sudo systemctl restart avahi-daemon

Also check for errors in logs:

journalctl -u avahi-daemon

Look for signs of:

  • Interface failures
  • Conflicts (e.g., another device trying to register ats.local)
  • Crashes or socket errors

3. Check hostname and Avahi publishing config on ats

Ensure that ats is still using the expected hostname:

hostname

Check if Avahi is advertising it correctly:

avahi-publish -a -v ats.local <IP_ADDRESS>

If ats.local has been “taken” by another host due to a race condition or network issue, Avahi might auto-rename it (e.g., to ats-2.local). Look for such names with:

avahi-browse -a

4. Confirm networking and firewall settings

Make sure:

  • UDP port 5353 is open (used by mDNS)
  • Your firewall isn’t blocking multicast traffic
  • You’re on the same subnet

You can test multicast reachability with:

ping -b 224.0.0.251

Or use tcpdump to confirm mDNS traffic:

sudo tcpdump -i <interface> port 5353

Watch for queries and responses involving ats.local.

5. Restart Avahi and re-announce services

If things still look stale or broken, try a full Avahi restart on the ats host:

sudo systemctl restart avahi-daemon

Then re-check service announcements with avahi-browse.

6. Tools for further debugging

  • avahi-discover: GUI tool to browse mDNS services.
  • dns-sd (on macOS): e.g., dns-sd -B _services._dns-sd._udp
  • nss-mdns: make sure the system resolves .local via Avahi (not some other resolver or caching DNS system).

In /etc/nsswitch.conf you should see:

hosts: files mdns4_minimal [NOTFOUND=return] dns