Anyone running Home Assistant as a container quickly runs into an issue with network services such as MPD or local scripts: hostnames ending in .local fail to resolve. The official Docker image is based on Alpine Linux, which uses the musl C library instead of the GNU C library and lacks native system-level support for mDNS. By configuring a DNS relay on the host and setting up proper network routing, you can easily restore this functionality.
What You Need
- Home Assistant running as a container
- A Linux host system with terminal access (root or sudo privileges)
dnsmasqandavahi2dnsinstalled on the host
1. Expose the Host’s mDNS Service to DNS
Because musl in Alpine Linux does not support conventional mDNS resolution via nsswitch.conf, you need to map mDNS queries through standard DNS requests. To do this, configure a helper utility like avahi2dns on a dedicated port (such as port 5354) on the host to handle requests for .local domains.
2. Configure dnsmasq as a Forwarder
Configure the dnsmasq service on your host to listen on an internal interface and route all queries ending in .local directly to the avahi2dns port.
# Example configuration line in dnsmasq
server=/local/127.0.0.1#5354dnsmasq will continue forwarding all other internet DNS queries to your regular router or upstream DNS server as usual.
3. Set Up a Macvlan Network for Docker
If you prefer not to run the container in host network mode or want isolated IP assignment, create a Macvlan network. This provides the Home Assistant container with its own virtual network interface, complete with a dedicated IP and MAC address on your local network.
Make sure the selected IP range falls outside your router’s DHCP pool to prevent address conflicts.
docker network create -d macvlan \
--subnet=192.168.10.0/24 \
--ip-range=192.168.10.20/28 \
--gateway=192.168.10.1 \
-o parent=eth0 MacVlan_NetworkAdjust the subnet, interface (eth0), and gateway to match your specific network environment.
4. Set the DNS Address in the Home Assistant Container
Assign the IP address of the host’s DNS service to the container in your Docker configuration (such as your docker-compose.yml). This ensures Alpine Linux directs all name resolution queries straight to your dnsmasq server, which then hands .local addresses off to avahi2dns.
Testing the Setup
Open a terminal session inside your running Home Assistant container and ping a local network device using its .local address:
docker exec -it homeassistant ping -4 mein-geraet.localIf the device’s IP address resolves and reply packets are returned, system services and integrations like MPD will once again be able to reach your local addresses without issue.
Troubleshooting
- “bad address” error: The container cannot reach the DNS server, or the forwarding rule in
dnsmasqfor port 5354 is not active. Verify yourdnsmasqconfiguration file and restart the service on the host. - IPv6 issues: When running dual-stack IPv6, resolution can sometimes fail; test the connection specifically using the
-4flag with the ping command. - Avahi reflectors with custom networks: If you are using a custom bridge network instead of host mode, you can alternatively enable reflectors in
/etc/avahi/avahi-daemon.confand restart theavahi-daemonservice.
This relay approach permanently works around Alpine Linux’s limitation, allowing you to run network-based media and command integrations without restrictions.
Sources: Forum: Home Assistant Community, community.home-assistant.io, community.home-assistant.io