vfreex / mdns-reflector

a lightweight and performant multicast DNS (mDNS) reflector with modern design, supports zone based reflection and IPv6

mDNS Reflector

mDNS Reflector (mdns-reflector) is a lightweight and performant multicast DNS (mDNS) reflector with a modern design. It reflects mDNS queries and responses among multiple LANs, which allows you to run untrusted IoT devices in a separate LAN but those devices can still be discovered in other LANs.

Highlights

• Low footprint, no dynamic memory allocation during reflecting
• Rootless - can be run as either root or non-root
• Supports zone based reflection
• Supports both IPv4 and IPv6
• Leverages epoll on Linux and kqueue on BSD and macOS

It provides a command line interface (CLI) familiar to the discontinued mdns-repeater.

---

Installation of mDNS Reflector using prebuilt binaries

Docker

docker pull yuxzhu/mdns-reflector:latest

Podman

podman pull yuxzhu/mdns-reflector:latest

Fedora / CentOS 8 / CentOS Stream 8

dnf copr enable -y yux/networking
dnf install -y mdns-reflector

CentOS 7

curl -fLo /etc/yum.repos.d/yux-networking-epel-7.repo  https://copr.fedorainfracloud.org/coprs/yux/networking/repo/epel-7/yux-networking-epel-7.repo
yum install -y mdns-reflector

Debian / Ubuntu

Available in Debian 'experimental' branch:

• https://packages.debian.org/experimental/mdns-reflector

It can happen that the version in experimental is outdated. In that case experienced users can either build the .deb package themselves

• by using this the Debian Salsa repo: https://salsa.debian.org/debian-edu-pkg-team/mdns-reflector
• by using the included debian/ folder.

OpenWRT

Coming soon.

---

Installing mDNS Reflector from Source

git clone https://github.com/vfreex/mdns-reflector
cd mdns-reflector && mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=release ..
make install

---

Usage

mdns-reflector is easy to use. Just run the following command on a multi-homed host:

mdns-reflector -fn eth0 eth1

where eth0 and eth1 are the interfaces that you want to reflect mDNS for.

Run mdns-reflector -h for help.

Similarly, run with Docker in the foreground:

docker run --net=host yuxzhu/mdns-reflector:latest mdns-reflector -fn eth0 eth1

Or run with Docker as a daemon:

docker run -d --restart=always --net=host yuxzhu/mdns-reflector:latest mdns-reflector -fn eth0 eth1

---

Systemd service

You can enable the systemd service with:

systemctl enable --now mdns-reflector

The main configuration file for the service daemon is located at: /etc/mdns-reflector/mdns-reflector.conf

Although you can add files to /etc/mdns-reflector/conf.d/ to overwrite the main configuration file.

Quick Tip: Adding a number and an underscore like 10_ as a prefix to your filename is good practice and ensures a predictable priority of the config files. 99_* files have a higher priority than 00_* files which means that the settings in file 20_example.conf would overwrite settings from 10_example.conf.

Multiple systemd services

mDNS Reflector supports multiple services running in parallel. You can achieve this by creating files like /etc/mdns-reflector/%i.conf.

Now enable the systemd service with this specific config file:

systemctl enable --now mdns-reflector@$(systemd-escape "%i")

NOTE: Replace %i with your config filename without the .conf at the end. The .conf filename suffix is still necessary though.

Important information about multiple services running in parallel

Let us define a few networks to make an example frame <iface_name>: <network_name>:

• eth_home: Homenetwork
• eth_smart: Smarthome-Devices
• eth_print: Printers

We want the devices in Printers to announce their services into the Homenetwork. Likewise the devices in Smarthome-Devices should also announce their services into the Homenetwork.

mDNS Reflector does not support an interface occuring in more than one reflection planes. For example:

mdns-reflector eth_home eth_smart -- eth_home eth_print # Wrong!

At the moment this is only possible if multiple mDNS Reflector services are running in parallel.

Uni-directional service announcement is not supported at the moment but is planned.

So, for this example you'll need two config files.

/etc/mdns-reflector/smarthomestuff.conf:

INTERFACES="eth_home eth_smart"
More stuff...

/etc/mdns-reflector/printerstuff.conf:

INTERFACES="eth_home eth_print"
More stuff...

Enabling the service of course:

systemctl enable --now mdns-reflector@$(systemd-escape "smarthomestuff")
systemctl enable --now mdns-reflector@$(systemd-escape "printerstuff")

This would make all mDNS services visible in Homenetwork. But beware this also makes all services from devices within the Homenetwork visible to the Smarthome-Devices and Printers networks.

Services within the Smarthome-Devices network won't be announced to the Printers network and vice-versa.

---

License

Copyright (C) 2021-2023 Yuxiang Zhu [email protected]

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

mdns-reflector's Issues

Help needed

probably my question / problem is not related to this software direct but i am trying to achieve some workarroud and i thing i should usue mds-reflector.

My goal:
Expose working homekit app on iphone roadwarior vpn client where my homekit accessories are in LAN where one of host is raspberry pi with openvpn server.

Now:

1. homeikt is woring only from local network when my iphone is connected
2. on my rasberry i can see service -> avahi-browse
   = wlan0 IPv4 openHAB _hap._tcp local
   hostname = [192-168-0-14.local]
   address = [192.168.0.14]
   port = [9123]
   txt = ["id=8a:e0:1f:83:2b:19" "md=openHAB" "pv=1.1" "ci=2" "sh=79UOzQ==" "sf=0" "ff=0" "s#=1" "c#=131"]
   the same is visible on iphone connected to lan

VPN:
i want to connect my iphone to openvpn on raspberry and see exactly the same mdns informations. My vpn interface on raspberry is tun0
mdns-reflector -fn eth0 tun0 (eth0 is the same as wlan0) raspberry has two ips.

What am i missing? how to check if mdns-reflector is working?

Filter link-local addresses

Currently it seems that packets are passed on transparently on the other interface.

This is potentially problematic when a link-local IPv6 address is passed. By default, and mDNS resolver assumes that a link-local address is reachable on the interface it received the mDNS packet on. mDNS resolvers pass the link-local address along with the interface it received the packet on as scope. However, since mdns-reflector forwards mDNS responses across network segments, those link-local addresses are not valid in that scope.

Depending on the service, it might just fallback to another address or handle the situation gracefully in some shape or form. But I think it would be better if the mdns-reflector removes all link-local addresses in general, to avoid mDNS resolvers picking them up and passing them along to their clients.

There is one corner case which pops into my mind: What if a link-local IPv6 address is the only address in the answer section. From my testing with systemd-resolved as mDNS responder, it seems that in this case simply no answer is sent back to the query. So I guess the equivalent behavior would be to simply drop such a packet.

I want to donate a few bucks

Hi,

your repo helped me very very much so I'd like to send you a few bucks as a sign of my appreciation for your work.

Do you have a buy me a coffe account or something similiar?

Debian upload?

Hey is something planned regarding a Debian Upload?

Maybe we want to use this program in our own project (Debian Edu Router).
A quick response would be appreciated since there is hope that we can make it into Debian 12 before its freeze.

I've tested this software on Debian Bookworm and it works.

"sendto: Destination address required"

I want to reflect mDNS to my Wireguard interface, however, when I start mdns-reflector, after a few seconds, it exits with sendto: Destination address required.

Feature: Uni-directional reflection.

In order to be able to use mdns-reflector in our schools (Debian Edu),
we need the option to announce the services unidirectionally from one network to the other and not arbitrarily bidirectionally (like right now).

I will provide patches for this and ideally we find a solution that pleases us both and they can be merged into this Repo.

Feature: mDNS service filter.

In order to be able to use mdns-reflector in our schools (or Debian Edu),
we need some kind of mDNS service filter, so that only the services
that we want are announced. For example printer (ipp) services.

I will provide patches for this and ideally we find a solution that pleases us both and they can be merged into this Repo.

No man page

There is no man page coming with mdns-reflector.

@dzatoah can you provide a PR during work hours? Thanks!

Feature: Running multiple mdns-reflector processes in parallel.

A nice future feature would be to have multiple systemd mdns-reflector services running in parallel.
All processes would have their own config file. Each process does a slightly different job.

For example:
You'd have 4 networks one of the networks is a printer-only network.
You want to let the printers announce their service via mDNS to the other networks.
But only into the other networks, NOT vice-versa. And only ipp services should get through. Everything else should be filtered.

You'd make 4 systemd-services with a config file each.

• printers_network (_ipp._tcp) -> network1
• printers_network (_ipp._tcp) -> network2
• printers_network (_ipp._tcp) -> network3
• printers_network (_ipp._tcp) -> network4

So this is the most generic approach we could find. This makes mdns-reflector extremely flexible while keeping it's memory and CPU footprint low.

We can copy this mechanic from openvpn. They're doing a pretty good job.

This feature is of course dependent on #5 and #6