1 files changed, 125 insertions, 0 deletions
diff --git a/assets/2026-01-23-avahi-mdns-fixes.org b/assets/2026-01-23-avahi-mdns-fixes.org
new file mode 100644
index 0000000..89b005e
--- /dev/null
+++ b/assets/2026-01-23-avahi-mdns-fixes.org
@@ -0,0 +1,125 @@
+#+TITLE: Avahi/mDNS Configuration Fixes
+#+DATE: 2026-01-23
+
+* Problem Summary
+
+On velox, mDNS hostname resolution was not working correctly from other machines on the LAN (e.g., ratio). Attempting to access =http://velox.local:8384= (Syncthing web UI) failed, while accessing via IP address worked.
+
+* Issues Identified
+
+** Issue 1: Hostname Conflict (velox-3.local)
+
+*Symptom:* Avahi was running as =velox-3.local= instead of =velox.local=
+
+*Cause:* Avahi was publishing on multiple network interfaces including virtual ones:
+- =enp0s13f0u3= (physical LAN - correct)
+- =docker0= (Docker bridge)
+- =virbr0= (libvirt bridge)
+- =vnet0= (VM virtual NIC)
+- =tailscale0= (Tailscale VPN)
+
+Each interface was effectively registering as a separate host, causing mDNS hostname conflicts with itself.
+
+*Solution:* Restrict Avahi to only the physical LAN interface.
+
+#+begin_src conf
+# /etc/avahi/avahi-daemon.conf
+[server]
+allow-interfaces=enp0s13f0u3
+#+end_src
+
+** Issue 2: IPv6-Only Resolution
+
+*Symptom:* =velox.local= resolved to IPv6 link-local address (=fe80::...=) only, but Syncthing was listening on IPv4 only (=0.0.0.0:8384=).
+
+*Cause:* Default Avahi configuration does not publish A records (IPv4) in response to AAAA queries (IPv6).
+
+*Solution:* Enable =publish-a-on-ipv6= to ensure IPv4 addresses are returned.
+
+#+begin_src conf
+# /etc/avahi/avahi-daemon.conf
+[publish]
+publish-a-on-ipv6=yes
+#+end_src
+
+** Issue 3: Conflicting mDNS Stacks
+
+*Symptom:* Avahi logged warning: "Detected another IPv4 mDNS stack running on this host"
+
+*Cause:* Both =avahi-daemon= and =systemd-resolved= were configured to handle mDNS:
+
+#+begin_src conf
+# /etc/systemd/resolved.conf (before fix)
+[Resolve]
+MulticastDNS=yes
+#+end_src
+
+*Solution:* Disable mDNS in systemd-resolved, let Avahi handle it exclusively.
+
+#+begin_src conf
+# /etc/systemd/resolved.conf
+[Resolve]
+Domains=~local
+MulticastDNS=no
+#+end_src
+
+* Complete Fix Applied
+
+** Files Modified
+
+*** /etc/avahi/avahi-daemon.conf
+
+Changes made:
+#+begin_src diff
+-#allow-interfaces=eth0
++allow-interfaces=enp0s13f0u3
+
+-#publish-a-on-ipv6=no
++publish-a-on-ipv6=yes
+#+end_src
+
+*** /etc/systemd/resolved.conf
+
+Changes made:
+#+begin_src diff
+-MulticastDNS=yes
++MulticastDNS=no
+#+end_src
+
+** Services Restarted
+
+#+begin_src bash
+sudo systemctl restart systemd-resolved
+sudo systemctl restart avahi-daemon
+#+end_src
+
+* Verification
+
+After fixes:
+- Avahi runs as =velox.local= (not =velox-3.local=)
+- No mDNS stack conflict warning
+- From ratio: =avahi-resolve -n velox.local= returns =192.168.86.42=
+- From ratio: =curl http://velox.local:8384/= returns HTTP 200
+
+* Notes for archsetup
+
+These configurations should be added to the Arch setup scripts:
+
+1. Install avahi: =pacman -S avahi nss-mdns=
+
+2. Configure =/etc/avahi/avahi-daemon.conf=:
+   - Set =allow-interfaces= to physical LAN interface (determine dynamically or prompt user)
+   - Set =publish-a-on-ipv6=yes=
+
+3. Configure =/etc/systemd/resolved.conf=:
+   - Set =MulticastDNS=no= to avoid conflict with Avahi
+
+4. Enable and start avahi-daemon:
+   #+begin_src bash
+   systemctl enable --now avahi-daemon
+   #+end_src
+
+5. Ensure =/etc/nsswitch.conf= has mdns in hosts line:
+   #+begin_src conf
+   hosts: mymachines mdns_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] files dns
+   #+end_src