From b1859fc050c8a07c4986d2fdc001476466fb15f0 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Thu, 29 Jan 2026 23:08:07 -0600
Subject: docs(assets): add mDNS resolution fix reference

---
 assets/2026-01-29-mdns-resolution-fix.org | 120 ++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 assets/2026-01-29-mdns-resolution-fix.org

diff --git a/assets/2026-01-29-mdns-resolution-fix.org b/assets/2026-01-29-mdns-resolution-fix.org
new file mode 100644
index 0000000..54b4983
--- /dev/null
+++ b/assets/2026-01-29-mdns-resolution-fix.org
@@ -0,0 +1,120 @@
+#+TITLE: mDNS Resolution Issue and Fix
+#+DATE: 2026-01-29
+
+* Problem
+
+Local network devices advertising via mDNS (multicast DNS) cannot be resolved by hostname. Specifically, =.local= domain names fail to resolve.
+
+** Symptom
+
+When attempting to connect to a network printer by its mDNS hostname:
+
+#+begin_example
+$ lpadmin -p "Brother-MFC-J6945DW" -E -v "ipp://Brother%20MFC-J6945DW._ipp._tcp.local/" -m everywhere
+lpadmin: Unable to connect to BRW7440BBC7D1BE.local:631: Temporary failure in name resolution
+#+end_example
+
+The device is discoverable via Avahi:
+
+#+begin_src bash
+avahi-browse -t _ipp._tcp
+#+end_src
+
+But the hostname (e.g., =BRW7440BBC7D1BE.local=) cannot be resolved to an IP address by applications.
+
+** Root Cause
+
+Two issues combine to prevent mDNS resolution:
+
+1. The =nss-mdns= package is installed but not configured in =/etc/nsswitch.conf=
+2. =systemd-resolved= (the =resolve= entry) intercepts =.local= queries before =mdns_minimal= can handle them
+
+This means:
+- =avahi-daemon= is running and can discover mDNS services
+- =avahi-browse= and =avahi-resolve= work correctly
+- But standard glibc name resolution never queries Avahi because =resolve= handles (and fails) the =.local= lookup first
+
+** Original Configuration
+
+#+begin_example
+hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns
+#+end_example
+
+The =mdns_minimal= NSS module is missing, and =resolve= (systemd-resolved) comes too early in the chain.
+
+* Solution
+
+Add =mdns_minimal [NOTFOUND=return]= to the hosts line in =/etc/nsswitch.conf=, positioned *before* the =resolve= entry.
+
+** Corrected Configuration
+
+#+begin_example
+hosts: mymachines files mdns_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] myhostname dns
+#+end_example
+
+** Explanation of the Fix
+
+- =mdns_minimal= - Resolves =.local= hostnames via Avahi/mDNS (minimal version only handles =.local=)
+- =[NOTFOUND=return]= - If a =.local= name is not found via mDNS, don't fall through to other resolvers (prevents delays)
+- *Order matters:* =mdns_minimal= must come *before* =resolve= (systemd-resolved) because =resolve= will attempt to handle =.local= queries and fail, stopping the resolution chain
+- =files= is moved before =mdns_minimal= so =/etc/hosts= entries are checked first
+
+** Why Order Matters
+
+NSS processes entries left-to-right. With the original order:
+
+1. =resolve= receives the =.local= query
+2. systemd-resolved has mDNS disabled (=-mDNS= in =resolvectl status=)
+3. It returns NOTFOUND, and =[!UNAVAIL=return]= allows fallthrough
+4. But =mdns_minimal= was never in the chain to receive the query
+
+With the corrected order:
+
+1. =files= checks =/etc/hosts= first
+2. =mdns_minimal= handles =.local= queries via Avahi
+3. =[NOTFOUND=return]= prevents =.local= queries from going further if not found
+4. =resolve= handles other queries normally
+
+** How to Apply
+
+#+begin_src bash
+# Transform the hosts line to insert mdns_minimal before resolve
+sudo sed -i 's/mymachines resolve/mymachines files mdns_minimal [NOTFOUND=return] resolve/' /etc/nsswitch.conf
+sudo sed -i 's/files files/files/' /etc/nsswitch.conf  # Remove duplicate 'files' if present
+#+end_src
+
+Or manually edit =/etc/nsswitch.conf= to match the corrected configuration above.
+
+** Verification
+
+After applying the fix:
+
+#+begin_src bash
+# Should resolve the .local hostname to an IP
+getent hosts BRW7440BBC7D1BE.local
+
+# Or ping the device by hostname
+ping -c 1 BRW7440BBC7D1BE.local
+#+end_src
+
+* Workaround (If Fix Cannot Be Applied)
+
+If the fix cannot be applied immediately, use the device's IP address directly instead of the mDNS hostname:
+
+#+begin_src bash
+# Find the IP via avahi
+avahi-browse -rpkt _ipp._tcp | grep "MFC-J6945"
+# Output shows: 192.168.86.37
+
+# Use IP instead of hostname
+sudo lpadmin -p "Brother-MFC-J6945DW" -E -v "ipp://192.168.86.37/ipp/print" -m everywhere
+#+end_src
+
+* Status
+
+Applied to this system on 2026-01-29. Verified working with Brother MFC-J6945DW printer setup using mDNS hostname.
+
+* References
+
+- Arch Wiki: Avahi - https://wiki.archlinux.org/title/Avahi
+- nss-mdns documentation - https://github.com/avahi/nss-mdns
-- 
cgit v1.2.3