HomeKit Device integration/discovery requires mDNS service access through firewall

[egburr (Edward)]

TLDR: For HomeKit Device discovery, open your firewall for mDNS service (UDP port 5353). This should be noted in the HomeKit Device documentation as a prerequisite.

Ignore all the ranting below, unless you really want to see everything I tried before figuring this out.

I just installed an Ecobee Premium thermostat, and as I have no iOS devices I can’t do the Apple Homekit pairing/unpairing to somehow trigger the automatic HA pairing. I have searched and read just about every post on here about this, and can’t find any consistent answer other than essentially “pair it with iOS and then unpair it and it will magically show up” and am getting quite frustrated.

The thermostat is connected to my WiFi (manual entry directly on the thermostat screen), and HomeKit pairing is enabled via the settings menus on the thermostat. A QR code and 8 digit setup code number is displayed on the screen. The QR code just gives me “that app is not available” on my Android.

HA persistently insists when I try to add a HomeKit integration device “No unpaired devices could be found.” It doesn’t even hesitate, like it isn’t even trying. The message just comes up instantly. I can find no logs anywhere suggesting any check is occurring. Is there any way to force a scan?

HA 2025.4.1 on RHEL 9.5 on x86_64 hardware (not a VM) on the same local network as the thermostat. From linux, I can ping the thermostat’s IP address.

I was able to connect the thermostat via ecobee’s app on my phone, which also made it accessible through their website. Even though the HomeKit pairing option was still available (showing unpaired and letting me enable it), I disconnected the thermostat from my ecobee account, just in case. No luck.

(so, I had this written up to here and was still poking around but had just about given up for the evening, when I found this…)

I found one post on some other site that mentioned needing to allow port 5353 across their VLAN to get this working. And sure enough, I found that hass is listening in on port 5353 on my server. After enabling the mdns service (port 5353) in the firewall (and running to the other side of the house to re-enable pairing yet again), HA finally saw my thermostat! Why is this not mentioned anywhere?! At least, not for HomeKit. A quick search finds it mentioned as required for casting to Chromecast devices, which I haven’t got around to yet.

Anyway, I hope this helps someone in the future! Open the firewall for mDNS service.

[robertklep]

@egburr

HA 2025.4.1 on RHEL 9.5 on x86_64 hardware (not a VM) on the same local network as the thermostat.

They’re clearly not if there’s a firewall in between. Perhaps they use the same physical cables, but in terms of networking, they are on different networks.

[knebb]

@robertklep Just to be nitpicking:
Well, a firewall is often installed on the computer (here: RHEL) itself. (If this makes sense is a different topic).
However, as @egburr said they are on the same network. Unless he has installed some mDNS repeater on the router…
So before blaming please re-think.

@egburr : Well, somehow I have to agree to @robertklep : if you are unaware of basic configuration you should not blame it to the product…

Homekit is an Apple product and Apple uses mDNS a lot. RHEL does not by default but I assume you have some mDNS support installed on your RHEL box. If you did, there is ALWAYS the need to check local firewall rules.

So yes, when using mDNS you need to activate it and you need to know what you are doing.

If not, use the ready-to-be used version of HA.

Just my thoughs, now start ranting.

[robertklep]

@knebb

However, as @egburr said they are on the same network. Unless he has installed some mDNS repeater on the router…
So before blaming please re-think.

Fair enough.

But in my experience, when people say “they are on the same network” they often don’t know that they aren’t. A lot of people are inadvertently using double-NAT because their WiFi AP is running in router mode, not in bridge mode, for example.

I don’t have any RHEL experience, but are you telling me that it comes, by default, with a firewall that blocks incoming mDNS/multicast packets? If so, I will stay clear of that distro.

[knebb]

@robertklep

don’t have any RHEL experience, but are you telling me that it comes, by default, with a firewall that blocks incoming mDNS/multicast packets? If so, I will stay clear of that distro.

Now getting off-topic but anyways:
My personal opinion regarding these “on-host-firewalls” is possibly the same as yours: they are simply adding complexitity but do really improve security. They were initially introduced to equalize the low security level of the Windows OS (I guess W98) instead of doing a proper coding under security views…
And due to market all other vendors (Linux, Mac, whatever) simply followed. I do not know any OS which does not have these crappy firewalls nowadays.

But as the target market for RHEL (RedHat ENTERPRISE Linux) usually does not use mDNS (because they have proper DNS up and running) I would say it is perfectly fine to have this port disabled by default.

Anyways, enough offt-opic!

CU
/KNEBB

[robertklep]

@knebb

I do not know any OS which does not have these crappy firewalls nowadays.

My Ubuntu, Unraid, macOS and Synology machine don’t have a firewall that, by default, blocks any local network traffic

But as the target market for RHEL (RedHat ENTERPRISE Linux) usually does not use mDNS (because they have proper DNS up and running) I would say it is perfectly fine to have this port disabled by default.

If that’s the case, I don’t see why OP wants the HA documentation to point out that, apparently, on certain enterprise OS’es mDNS, and therefore one of the most common service discovery protocols, is blocked. Perhaps you shouldn’t be running an enterprise OS if you don’t know its limitations.

[knebb]

@robertklep

My Ubuntu, Unraid, macOS and Synology machine don’t have a firewall that, by default, blocks any local network traffic

And all of these target the SOHO user… not enterprise…

Perhaps you shouldn’t be running an enterprise OS if you don’t know its limitations.

I totally agree and this is what I wanted to say initially…

/KNEBB

[WallyR (Wally)]

@robertklep

My Ubuntu, Unraid, macOS and Synology machine don’t have a firewall that, by default

Wrong!

Ubuntu comes with it by default.
https://help.ubuntu.com/community/IptablesHowTo

Ubraid too.
https://forums.unraid.net/topic/83907-persist-iptables-changes-on-reboot/

MacOS have it too. It is called packet filter and can be controlled with the prctl command.

[peterxian]

@WallyR

MacOS have it too. It is called packet filter and can be controlled with the prctl command.

The macOS host-based firewall (“Firewall” in System Network Settings) underlying process is socketfilterfw (I believe this was inherited from its BSD roots).

Also, the prctl command appears to be for managing processes on gnu/linux; it is not shipped with macOS. Maybe you’re thinking of Linux seccomp filters?

Ubuntu’s default host-based firewall is now wrapped as ufw (“uncomplicated firewall”) commands to be more user-friendly. Still iptables (now nftables) under the hood, similar to OP’s RHEL system.

HAOS, to be slightly more on-topic, does NOT ship with a host-based firewall (which, in my opinion, is a little risky considering how many people port-forward to the Internet, but I’m sure it avoids a LOT of support questions) and the HA documentation is heavily HAOS-biased, which is why there is little to no information in the docs about what ports are required by which integrations and people end up here searching or asking questions.

That said, to clarify this topic the title should probably specify “host” firewall because a lot of people are confused lately about mDNS not traversing vlan (subnet) boundaries (it being multicast and all) and seeing a topic suggesting opening firewall ports could lead to further confusion.

[robertklep]

@WallyR

Wrong!

Only if you selectively quote what I wrote

I’ll add the relevant part back: “…don’t have a firewall that, by default, blocks any local network traffic”

[robertklep]

@peterxian

The macOS host-based firewall (“Firewall” in System Network Settings) underlying process is socketfilterfw (I believe this was inherited from its BSD roots).

Also, the prctl command appears to be for managing processes on gnu/linux; it is not shipped with macOS. Maybe you’re thinking of Linux seccomp filters?

That’s a typo, it should be pfctl (“The pfctl program and the packet filter mechanism first appeared in OpenBSD 3.0”).

AFAIK, socketfilterfw is an Apple development.

[WallyR (Wally)]

@robertklep

“…don’t have a firewall that, by default, blocks any local network traffic”

Have you made a print out of the rules?
My guess is that there will be things blocked by default.
The blocked things might not be some you have encountered, since a SOHO setup blocks different things than a server setup.
A server setup is generally hardened more from the start than a SOHO setup.

[robertklep]

@WallyR

Have you made a print out of the rules?

• Ubuntu: “ufw by default is initially disabled”
• macOS:
  
  
• Synology:
  
  

These are all the default settings, since I never changed them.

[WallyR (Wally)]

Okay, never worked much with Ubuntu, but knew a firewall was installed.
Pretty much all Linux distributions have it, maybe with exception of the Kali Linux.

[egburr (Edward)]

@robertklep

@knebb

I do not know any OS which does not have these crappy firewalls nowadays.

My Ubuntu, Unraid, macOS and Synology machine don’t have a firewall that, by default, blocks any local network traffic

But as the target market for RHEL (RedHat ENTERPRISE Linux) usually does not use mDNS (because they have proper DNS up and running) I would say it is perfectly fine to have this port disabled by default.

If that’s the case, I don’t see why OP wants the HA documentation to point out that, apparently, on certain enterprise OS’es mDNS, and therefore one of the most common service discovery protocols, is blocked. Perhaps you shouldn’t be running an enterprise OS if you don’t know its limitations.

I always keep my firewall “deny everything not explicitly allowed”. As for most common… this is the first I’ve ever encountered mDNS and had to read up on it. This is the first Apple-related product I’ve ever introduced to my network, and general reading about HomeKit hadn’t run across the mDNS requirement. Too much is just assumed by people who already know it, a very common problem when writing documentation. Hence the suggestion here to document this requirement in the requirements section.

[robertklep]

mDNS isn’t specific to Apple, a lot of brands use it (or protocols based on it) for autodiscovery. It will work for the vast majority of users, because it’s a ubiquitous protocol that is almost never blocked.

I think it is assumed that if you decide to set up firewalls on the machine you run HA on, you are aware of the consequences. It doesn’t feel realistic to document, for every integration, which ports and/or which IP ranges (relevant in the case of multicast) should be accessible.

[knebb]

@egburr

I always keep my firewall “deny everything not explicitly allowed”

Which - at least for most Linux Distros - is overkill as they do not offer unneccesary services listening on ports…
Anyways, EOT bc off-topic.

/KNEBB

[WallyR (Wally)]

mDNS started as a part of the Apple Bonjour protocol, but have since been adopted by many other brands.

[egburr (Edward)]

@robertklep

mDNS isn’t specific to Apple, a lot of brands use it (or protocols based on it) for autodiscovery. It will work for the vast majority of users, because it’s a ubiquitous protocol that is almost never blocked.

I think it is assumed that if you decide to set up firewalls on the machine you run HA on, you are aware of the consequences. It doesn’t feel realistic to document, for every integration, which ports and/or which IP ranges (relevant in the case of multicast) should be accessible.

I decided to setup HA on the already existing Linux server in my house, that already had the firewall in place, not the other way around. Yes, I understand the consequences of firewalls, but without documentation giving some hint of the requirement, how do I even know a hole needs to be opened up for it?

Dealing with networked games, I have often cursed the game developers/documenters for not providing the info about what ports their games use. Not just for firewall purposes, but for NAT configuration purposes.

I think it is very reasonable to ask to document what ports a required protocol uses (or at least that the protocol is a requirement!) if it is critical to the function, instead of assuming that everyone just knows everything.

But anyway, I’ve got past it. I was just wanting to provide this possible answer for others to find, as I could find the question asked a lot but very few actual solutions described.

[robertklep]

@egburr

I decided to setup HA on the already existing Linux server in my house, that already had the firewall in place, not the other way around. Yes, I understand the consequences of firewalls, but without documentation giving some hint of the requirement, how do I even know a hole needs to be opened up for it?

PREREQUISITES:

• If you do not have the default_config integration, add zeroconf to your configuration.yaml file.

Then in the zeroconf documentation, under Troubleshooting, there’s already a clear hint that multicast/Zeroconf traffic must be allowed to pass.

Back to the HomeKit Device documentation, under “Troubleshooting”, there’s a lot of talk on how your network should be set up. “If your devices are on a different VLAN to Home Assistant you must have an mDNS reflector for discovery and pairing to work”.

(yes, I know you’re not on a separate VLAN)