- Rust 82.3%
- Shell 9.4%
- PHP 3.1%
- Python 3.1%
- Volt 2%
- Other 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| dist | ||
| examples | ||
| opnsense | ||
| packaging/freebsd | ||
| scripts | ||
| src | ||
| .gitignore | ||
| .imagesmithignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| Cross.toml | ||
| imagesmith.yaml | ||
| LICENSE | ||
| README.md | ||
mdns-bridge
Unicast mDNS bridge between two or more sites connected via a routed
link (typically IPsec). Runs on OPNsense/FreeBSD and on Linux. Lets
.local mDNS/DNS-SD announcements — e.g. ESPHome devices — reach a
Home Assistant instance at a different site, without exposing full
multicast across the tunnel.
The repository contains the daemon (mdns-bridged, Rust) and the
OPNsense plugin os-mdns-bridge (GUI under Services: mDNS Bridge, see
opnsense/README.md).
How it works
- Capture — joins
224.0.0.251:5353on each configured local interface and reads the mDNS traffic that verifiably came from that link: multicast to the group (queries from any port, responses only from port 5353), and unicast responses from port 5353 of a sender in one of the interface's subnets (or with an IPv6 link-local address) — the answers to questions the bridge reinjected with the unicast-response bit. Everything else that reaches port 5353 is ignored and counted asdropped_source: unicast arriving on an interface that is not bridged or routed in from another network, unicast queries, responses from other ports. mDNS trusts the local link, and receivers check that a packet really came from there (RFC 6762 sections 6 and 11); what the bridge re-sends at another site passes those checks, so the bridge has to make them where the packet arrives. - Filter — only records matching a configured service name (e.g.
_esphomelib._tcp.local.) are considered; everything else is ignored at the source, so you don't flood the tunnel with printer/Chromecast chatter. The host names that SRV records of matching services point to are learned, and packets naming those hosts (their A/AAAA records, address queries) pass as well — otherwise the remote side would know the service but could not resolve its address. Unrelated hosts stay local. - Dedup — a short time-windowed hash cache collapses the repeat packets a responder typically sends per announcement burst.
- Forward — matching packets are wrapped in a small binary frame
(origin site, relay path, raw packet bytes, see
src/protocol.rs) and streamed over a long-lived TCP connection to each configured peer daemon. The connection is expected to ride inside an already-encrypted IPsec tunnel — this daemon does not add its own transport crypto (see #15). Connections are one-directional: the dialing side sends, the listening side receives. For both directions, each site lists the other under[[peers]]. Right after connecting, the dialing side replays the locally captured state (see below), so a restarted site is in sync immediately instead of waiting for the next announcement. - Accept — the receiving daemon only accepts connections from its
allowlist, runs the handshake (protocol version, optional PSK — see
Authentication) and applies its own
service_filtersto every received packet before doing anything with it. - Reinject — the receiving daemon re-sends the raw packet as local multicast mDNS on its own configured interfaces, so devices there (e.g. Home Assistant's Avahi/zeroconf) discover it exactly as if it had originated locally.
Replay. Each daemon keeps the packets it captured locally (not those received from peers). An entry expires after the smallest TTL of its records, a goodbye (TTL 0) removes every entry containing that record, and a newer packet replaces older ones whose records it fully covers. A dropped connection is noticed right away (the peer closes it) or, if the peer vanished silently, via TCP keepalive after about a minute; the reconnect then triggers the replay. A peer is dialled again after half a second, then after twice as long each time, up to 30 seconds; the delay starts over once a connection has lasted 30 seconds.
A path field in each envelope records every site_id a record has
passed through, so a topology of more than two bridged sites doesn't
loop packets back and forth forever.
Limits. What the daemon keeps and how much work a packet causes is bounded, whatever a device on the LAN or a peer sends:
- packets of at most 9000 bytes (RFC 6762) and relay paths of at most 32 sites; a peer sending more is disconnected;
- names of at most 255 bytes, as DNS allows - a packet spelling out longer ones through compression pointers is malformed and ignored;
- 4096 entries in the record table and 4096 learned SRV target hosts; when full, those not seen for the longest time make room;
- 2048 packets and 4 MiB in the replay cache, oldest out first; a packet with more than 64 distinct records is forwarded but not replayed;
- 65536 packets in the dedup cache; when full, those seen longest ago are forgotten early, so a late copy of one of them is forwarded once more;
- learned hosts and replay entries stay 24 hours at most, whatever TTL a record claims;
- 500 packets a second per capture interface and per peer address,
2500 at once after a quiet spell (
max_packets_per_second,max_packet_burst); what is over the limit is dropped and counted asdropped_rate. Real mDNS for a few bridged services is a few packets a second; a flood from one device or peer would otherwise be reinjected at every other site at full rate. The burst covers the replay after a reconnect (at most 2048 packets); - 64 peer connections at a time, 8 from one address; further ones are
closed at once and counted as
rejected_peers; - ten log lines a minute for each kind of event that someone else can
cause as often as they like (rejected connections, failed handshakes,
failing reinjections, ...). The log says when lines are being left
out and, afterwards, how many;
rejected_peers,auth_failedandhandshake_failedin the status report count every one.
Configuration
See examples/site-a.toml and examples/site-b.toml for a working
two-site pair. Key fields:
site_id— unique per site, used for loop prevention. Two connected sites with the same ID would drop everything they get from each other; the receiving side logs a warning and countssite_id_conflicts. A peer'ssite_idequal to this site's is an error.interfaces— which local interface(s) to capture from and reinject onto, by OS interface name. Group membership and the sending interface are bound to the interface index, not its address — nothing to configure there, and address changes (DHCP) need no restart. An interface without an IPv4 address at startup is only a warning. Every 30 s the daemon checks the interfaces: one destroyed and recreated (new index, or a lost membership) is joined again, address changes are logged. A name that does not exist at startup is an error. Per interface:ipv6(defaulttrue),multicast_loop(defaultfalse, see Linux below),multicast_ttl(default 255 as required by RFC 6762 — leave it).peers— remote bridge daemons to dial and send to, reachable through the routed IPsec subnet (not through NAT).addrishost:port(IPv6 in brackets,[2001:db8::1]:5354) and is checked when the config is loaded.service_filters— allow-list of mDNS service/record names, matched exactly or as a suffix on a label boundary. Applied on capture and on receive. A packet is forwarded as a whole when any name in it matches (#4). An empty list bridges nothing (logged as a warning, also by--check-config); up to 0.1.1 it bridged everything.forward_all_services = truebridges every mDNS packet - lab use only.dedup_window_ms— how long a packet is remembered as a duplicate; default 2000, at least 100.max_packets_per_second,max_packet_burst— rate limit per capture interface and per peer address (see Limits); defaults 500 and 2500,max_packets_per_second = 0switches it off.listen_addr— address the peer listener binds to. Defaults tosource_addr, else0.0.0.0(logged as a warning).allowed_peers— extra IPs allowed to connect to the listener. The resolved addresses of all[[peers]]are always allowed; this is only needed for receive-only setups. An empty effective allowlist rejects everything.allow_any_peer = truedisables the check (lab only).
Unknown keys are logged as a warning at startup (typos, or options of
other versions such as the former resync_interval_secs), instead of
being silently ignored.
Protocol versions
All bridged sites must speak the same protocol version; the handshake
checks it. Version 2 (binary frames, current) replaced the JSON frames
of version 1 (0.1.0 snapshot builds before the first release). Until
both sides of a connection are updated, both logs report protocol version mismatch: this side speaks v2, peer v1 and nothing is bridged
between them, so update the sites one right after the other.
Authentication (optional PSK)
Every peer connection starts with a short handshake: both sides send a
HELLO (magic, protocol version, "PSK on/off", random nonce). Talking to
something that isn't mdns-bridge, a different protocol version, or a
PSK configured on only one side is reported immediately with a clear
message, e.g.
auth_psk is set here but not set on the peer - configure the same PSK on both sides, or on neither.
With a pre-shared key, both sides then prove knowledge of it (mutual HMAC-SHA256 challenge/response over both HELLOs, with role labels — no replay, no reflection, no downgrade of the flags). Same key on all bridged sites:
auth_psk_file = "/usr/local/etc/mdns-bridge.psk" # first line = key
# or inline (then keep the config file non-world-readable):
# auth_psk = "..."
openssl rand -base64 24 > /usr/local/etc/mdns-bridge.psk
chown root:mdnsbridge /usr/local/etc/mdns-bridge.psk && chmod 0640 /usr/local/etc/mdns-bridge.psk
The daemon warns about a world-readable key (inline in a world-readable
config, or a world-readable key file) and about keys shorter than 16
characters; an empty key is an error. On Linux, use systemd credentials
(see the commented lines in dist/linux/mdns-bridged.service).
The PSK keeps anything else that can reach the port (broad firewall
rules, other tenants on a shared hub, scanners) from injecting records,
and keeps a daemon from sending its records to an impostor. It does not
encrypt the frames that follow — that is the IPsec tunnel's job; mTLS
with the internal PKI is the heavier alternative (#15). --status
counts failures as auth_failed (wrong key) and handshake_failed
(everything else).
Running
cargo build --release
./target/release/mdns-bridged --config examples/site-a.toml
Logging is via tracing; set RUST_LOG=debug for packet-level detail.
mdns-bridged --check-config validates a config file (syntax, unknown
keys, PSK) without starting anything; exit code 0 means usable.
Status
- IPv6 — each interface joins
ff02::fbin addition to224.0.0.251unlessipv6 = falseis set for it. A failed IPv6 join (no link-local address yet, IPv6 disabled on the host) is logged as a warning and the interface keeps working on IPv4 only — verified in this sandbox, which has no IPv6 at all: the daemon warned and ran cleanly on v4. - Status endpoint —
mdns-bridged --statusconnects to a Unix socket (status_socketin config, default/var/run/mdns-bridged/mdns-bridged.sockon FreeBSD,/run/mdns-bridged/mdns-bridged.sockon Linux) and prints a JSON snapshot: uptime, per-counter packet stats (captured / forwarded / received / reinjected / dropped-by-dedup / dropped-by-loop-guard / dropped-by-filter / dropped-by-source-check / dropped-by-rate-limit / site_id_conflicts / rejected peer connections / auth_failed / handshake_failed / replayed), the number of cached replay packets (replay_cache_entries),authentication(pskornone), the outbound connections per peer (peers: connected, authenticated, since) and the inbound ones by remote address (inbound: authenticated, since). Used byservice mdns_bridged reportand the Status tab of the OPNsense plugin. - Configurable source address —
source_addr(top-level, and optionally per-peer as an override) binds outbound peer connections to a specific local address before connecting. Matters for policy-based IPsec: without this, the OS picks the source address via its normal routing decision — typically the WAN interface — which doesn't match an SA whose selectors are defined for LAN-to-LAN traffic. Verified end-to-end: pointed a real TCP listener at 127.0.0.1, setsource_addr = "127.0.0.2", confirmed the listener actually observed the connection arriving from 127.0.0.2. - Record table —
mdns-bridged --recordsprints every distinct record the daemon has seen, local or remote: name, type, the start of its data (data, at most 64 characters: the address of an A/AAAA record, the strings of a TXT record, the target of a PTR,priority weight port targetof an SRV, hex otherwise), TTL, source (local/remote), where it came from (interface name or peer address), which site originally captured it, how long ago it was first/last seen, and whether its stated TTL has elapsed. Purely a debugging aid — has no bearing on bridging decisions, which are handled separately via packet-hash dedup and the loop guard. Entries older thanrecord_max_age_secs(default 3600) are pruned every minute, and the table holds at most 4096 entries (see Limits), so this doesn't grow unbounded on a busy network. Verified end-to-end: sent a real mDNS A-record announce over multicast, confirmed it shows up correctly in both--recordsand thecapturedcounter in--status.
Installing on OPNsense / FreeBSD (package)
The build-freebsd workflow produces mdns-bridged-<version>.pkg
(artifact mdns-bridged-pkg-freebsd15) and the OPNsense plugin
os-mdns-bridge-<version>.pkg (artifact os-mdns-bridge-pkg-freebsd15);
both are attached to releases. It must
be built on the same FreeBSD major version as the target (OPNsense
currently runs on 15.x).
pkg add ./mdns-bridged-0.1.0.pkg
cp /usr/local/etc/mdns-bridge.toml.sample /usr/local/etc/mdns-bridge.toml
vi /usr/local/etc/mdns-bridge.toml
sysrc mdns_bridged_enable=YES
service mdns_bridged start
service mdns_bridged report # JSON status: counters, peers
The package creates the unprivileged user/group mdnsbridge with a
fixed ID below 2000 (803, or the next free one up to 999): OPNsense
deletes users and groups with IDs 2000-65000 that are not in its own
configuration, e.g. on a firmware update. Installations from 0.1.2 and
earlier may have ID 2000; the next package update moves them and hands
the config and PSK back to the group. Before each start the rc script
recreates the account if it is missing (default user/group only). The
rc script runs the daemon as that user under daemon(8) (restart on
crash, output to syslog with tag mdns_bridged). rc.conf knobs:
mdns_bridged_config, mdns_bridged_user, mdns_bridged_group,
mdns_bridged_env (default RUST_LOG=info). Packaging files live in
packaging/freebsd/; build locally on FreeBSD with
cargo build --release && sh packaging/freebsd/build-pkg.sh.
Updates and removal. After an upgrade the package restarts a
running daemon, so a fix takes effect right away - unless the new
version rejects the existing config: then the old daemon is left
running, and the upgrade output says why (fix the config, then
service mdns_bridged restart). Removing the package stops the daemon
first. Your mdns-bridge.toml stays. (Up to 0.1.1 neither happened: a
running daemon kept the old binary until restarted by hand, and one left
behind by a removal could only be stopped with kill.)
On OPNsense, install the plugin instead (pkg add ./os-mdns-bridge-<version>.pkg pulls in the daemon package from the
same directory) and configure everything under Services: mDNS Bridge,
see opnsense/README.md. Either way, allow TCP
listen_port from the peers on the tunnel interface.
Package repository
Pushes to master and tags v* also publish both packages as a signed
pkg repository in the Forgejo package registry
(packaging/freebsd/publish-repo.sh), channel testing resp.
release:
https://git.bocc.de/api/packages/jochen/generic/mdns-bridge-freebsd15/<channel>
The OPNsense plugin brings the repository configuration and the public key along (see opnsense/README.md). On plain FreeBSD, add them yourself:
mkdir -p /usr/local/etc/pkg/repos /usr/local/etc/pkg/keys
fetch -o /usr/local/etc/pkg/keys/mdns-bridge.pub \
https://git.bocc.de/jochen/mdns-bridge/raw/branch/master/packaging/freebsd/repo/mdns-bridge.pub
cat > /usr/local/etc/pkg/repos/mdns-bridge.conf <<'EOF'
mdns-bridge: {
url: "https://git.bocc.de/api/packages/jochen/generic/mdns-bridge-freebsd15/release",
signature_type: "pubkey",
pubkey: "/usr/local/etc/pkg/keys/mdns-bridge.pub",
enabled: yes
}
EOF
pkg update -r mdns-bridge && pkg install -r mdns-bridge mdns-bridged
(Fetching the key over HTTPS from the repository trusts git.bocc.de's TLS certificate; compare it with a copy from a trusted checkout if that matters.)
Setting it up once (maintainer):
- Create the signing key on a trusted machine and keep the private
key out of the repository:
openssl genrsa -out mdns-bridge-repo.key 4096,openssl rsa -in mdns-bridge-repo.key -pubout -out mdns-bridge.pub - Repository secret
PKG_REPO_KEY: the content ofmdns-bridge-repo.key. - Secret
REPO_REGISTRY_TOKEN: a Forgejo access token with the scopewrite:package(set as a user secret of jochen, so other repositories can use it too; the workflow passes it to the script asPKG_REGISTRY_TOKEN). - Commit
mdns-bridge.pubaspackaging/freebsd/repo/mdns-bridge.pub.
Until all of this is in place, the workflow skips publishing with a
warning. The publish step checks that the private key matches the
committed public key, and reads the repository back like a client
(signature, package versions) before it succeeds. The runner needs
curl (pkg install curl).
Troubleshooting
service mdns_bridged statussays running butreportfails: thedaemon(8)supervisor runs, butmdns-bridgeditself keeps exiting. Look for itsERRORline in syslog (OPNsense:grep mdns_bridged /var/log/system/latest.log). Fatal startup errors are logged as one line, e.g. a non-existent interface (with the list of existing ones), alisten_addr/source_addrthat is not configured on the host, or a busy port.reportexplains a missing socket (daemon not running, socket could not be created, or a differentstatus_socketin the config) and a stale one (daemon exited).dropped_sourcein the report grows: datagrams reached port 5353 that did not verifiably come from a bridged link (see How it works, Capture). WithRUST_LOG=debugeach one is logged asdatagram ignoredwith sender, destination, arrival interface and reason.- Nothing arrives at the other site although the peer is connected and
forwardedgrows there: checksite_id_conflictsin this site's report and the log forthe peer uses this site's site_id- give every site its own ID. Also check for the warningservice_filters is emptyon either side. dropped_rategrows: something sends more thanmax_packets_per_secondpackets of bridged services, on a LAN (packet over the rate limitwith the interface and sender in the log) or from a peer (with the peer address). Find the device; raise the limit only if the traffic is wanted.- Run it in the foreground as the service user to see everything at
once:
service mdns_bridged stop; su -m mdnsbridge -c 'RUST_LOG=debug /usr/local/bin/mdns-bridged'
Running on Linux
The daemon builds and runs natively on Linux; CI produces a static
x86_64-unknown-linux-musl binary (artifact of the ci workflow).
install -m 0755 mdns-bridged /usr/local/bin/
install -m 0644 examples/linux.toml /etc/mdns-bridge.toml # then edit
install -m 0644 dist/linux/mdns-bridged.service /etc/systemd/system/
systemctl daemon-reload && systemctl enable --now mdns-bridged
mdns-bridged --status
The unit runs unprivileged (DynamicUser, ports > 1024), hardened and
with a memory limit (MemoryMax=256M; the daemon needs a few MB).
Linux-specific points:
IP_MULTICAST_ALL/IPV6_MULTICAST_ALLare switched off on every capture socket, so the daemon only receives the mDNS traffic of the bridged interfaces (Linux default would deliver every interface's mDNS to every socket). A packet is booked on the interface it arrived on as reported by the kernel (IP_PKTINFO), not on the socket it was read from: with several bridged interfaces, newer kernels hand a packet to any of the daemon's sockets.- If Home Assistant or Avahi run on the same host, set
multicast_loop = trueon that interface — otherwise local processes never see the reinjected records. Our own capture socket then sees the reinjection too; the dedup cache drops that echo. - Open TCP
listen_port(default 5354) from the peer sites in the host firewall.
Container
The container workflow publishes an image (distroless, runs as uid
65532, no shell):
| Tag | Built from |
|---|---|
git.bocc.de/jochen/mdns-bridged:latest, :<version> |
tags v* |
git.bocc.de/jochen/mdns-bridged:testing, :<version>-s<run> |
every push to master |
It needs a network that is the LAN segment itself: mDNS is
link-local multicast, which a NATed container network (the default
bridge) does not reach. Use the host's network, or a network that puts
the container directly on the LAN, e.g. macvlan or an OVS/OVN network
(netavark-ovs) - then interfaces and source_addr in the config are
the container's own interface and address, not the host's. Everything
else can be locked down:
podman run -d --name mdns-bridged --network host \
--read-only --cap-drop all --security-opt no-new-privileges \
--tmpfs /run/mdns-bridged:mode=1777 \
-v /etc/mdns-bridge.toml:/etc/mdns-bridge.toml:ro \
git.bocc.de/jochen/mdns-bridged:latest
podman exec mdns-bridged mdns-bridged --status # or --records
(docker run takes the same options.) For a systemd service with
Podman, install dist/container/mdns-bridged.container as a Quadlet
unit in /etc/containers/systemd/; with AutoUpdate=registry,
podman auto-update pulls new releases.
- The config must be readable for uid 65532. Keep the PSK out of it:
podman secret create mdns-bridge-psk psk, run with--secret mdns-bridge-psk,uid=65532,gid=65532,mode=0400and setauth_psk_file = "/run/secrets/mdns-bridge-psk". - The tmpfs holds the status socket (
--status,--records, health check); without--read-onlyit is not needed. Podman rejectsuid=/gid=there (unknown mount option), hencemode=1777. - The image's health check runs
mdns-bridged --status; Podman keeps it only with--format docker, which the workflow uses. - Build by hand:
imagesmith build --no-push, orpodman build -f dist/container/Dockerfile .
CI (Forgejo Actions)
.forgejo/workflows/ci.yml— on every push/PR,runs-on: docker: fmt, clippy (-D warnings), tests, OPNsense plugin checks (PHP/XML syntax, templates rendered and validated with--check-config),cargo checkfor FreeBSD,cargo audit(blocking: a RustSec advisory fails the build), static Linux musl build..forgejo/workflows/build-freebsd.yml— onv*tags, on PRs touching code or packaging, or manually: native build on a FreeBSD runner (runs-on: freebsd-15), builds and checks themdns-bridgedandos-mdns-bridgepackages (ABI, file owners, base-only linkage, plugin dependency) and attaches binary and package to the Forgejo release on tags. Needs the runner from #14: FreeBSD VM on the same major version as the OPNsense base (currently 15.x — pkg refuses packages built for another major ABI),pkg install forgejo-act_runner git rust node, registered with labelfreebsd-15:host,capacity: 1, unprivileged user..forgejo/workflows/container.yml— container image with imagesmith on thepodmanrunner (see Container): pull requests only build, master and tagsv*push; afterwards the image is started once (--help,--check-config, user 65532).
Cross-compiling for OPNsense locally (FreeBSD/amd64)
A plain OPNsense box doesn't have a Rust toolchain and isn't meant to
grow one — lang/rust isn't in OPNsense's package repo, and adding the
full FreeBSD pkg repo to get it is explicitly unsupported. The practical
path is cross-compiling elsewhere and copying the binary over.
./scripts/build-freebsd.sh
# → target/x86_64-unknown-freebsd/release/mdns-bridged
scp target/x86_64-unknown-freebsd/release/mdns-bridged root@opnsense:/usr/local/bin/
This uses cross-rs, which ships a
FreeBSD sysroot in a container image — no local FreeBSD toolchain
needed. Defaults to Podman (CROSS_CONTAINER_ENGINE=podman); set it to
docker if that's what you have instead. The script installs cross
from git if it isn't already present (the crates.io release tends to
lag behind what's needed for newer targets).
In CI the FreeBSD binary is built natively on a FreeBSD runner instead (see above); the cross route is for ad-hoc local builds.
Not verified end-to-end — I don't have Docker/Podman or a
container-registry-reachable network in the sandbox I built this in,
so I couldn't actually run cross build here the way I tested the
native build and the IPv6/status changes. The cross build --target x86_64-unknown-freebsd recipe itself is a known-working, commonly used
one (used in FreeBSD/pfSense-adjacent Rust projects and referenced in
taiki-e/setup-cross-toolchain-action CI matrices), but you'll want to
be the first one to actually run it here.
Troubleshooting: Error: invalid toolchain \rust-1.9x``
cross needs a rustup-managed toolchain — it inspects rustup's
active toolchain to pick which container image/tag to pull. If rustc --version on your build host reports something other than a normal
rustup install (e.g. (built from a source tarball), meaning it came
from a distro/pkg build rather than rustup), cross can't derive a
sane toolchain name from it and fails like this before it even touches
Podman/Docker. scripts/build-freebsd.sh now checks for this and
installs rustup itself if it's missing — but if you still hit it,
check that ~/.cargo/bin is ahead of the system rustc in PATH
(which cargo should point there, not at /usr/bin/cargo or similar).
Open items
Tracked as issues on Forgejo:
- #4 — filter forwards whole packets, not just matching records
- #15 — mTLS between peers using the internal PKI (PSK available as the lightweight option)
- Multi-hop relay (3+ sites) is implemented but untested beyond the loop-guard logic itself — validate on a real topology before relying on it.
--statusoutput is raw JSON; a--status --prettyor table mode would be nicer for interactive use.