net: UniFi .localdomain and Bonjour, mDNS .local debugging

Since I last posted on the difference between .local and .localdomain where you get automatic naming from the hostnames, this really undocumented set of features has been useful and hard to debug. So some notes:

  1. The default with Unifi controllers is that when clients register with hostnames, it will automatically register them to a “phantom domain” called .localdomain. This is set in the very obscure corner of their interface: Settings > Networks > Default > DHCP > DHCP Service Management > Domain Name which is set to localdomain. As an aside, the information message here is entirely useless it talks about the browser names, but it really all DNS names.
  2. There is one default here, which is set to the UniFi controller typically x.x.x.1 of each Network.
  3. As an aside if you are down in this interface, you might use as DHCP NTP Server which is what is used as Option 42 to give time service to all the clients. It has to be set to a real IP address and you cannot use domain names but real IP addresses (the official US NIST server) and (the Google time server).

Debugging .local

Last year, the .localdomain was just the reflection of the hostname and appended to that domain, so for instance, if you named your machine in Settings > General > About to Rich's MacBook Pro 2021 then for .local, then Bonjour on the Mac would remove all special characters and replace spaces with dashes, so you can access this using the name you can find in Settings > General Sharing > Hostname which by default is richs-macbook-pro-2021.local. Note that you can click on the Edit button to manually change this. Or you can use sudo scutil --get LocalHostName to see it and also set it. And the user-friendly name is in scutil --get ComputerName

What is going on here is an Apple protocol called Bonjour formally called multicast DNS (or mDNS) and implemented as Avahi where you can use DNS service discovery (DNS-SD) which retrieves records that mDNS provides.

Note that because Bonjour came from Apple and is a DNS service, you can even query things remotely if the DNS has records so dns-sd -q actualkly works and see thee records

On the Mac, you can use applications like Discovery which does the work of figuring out the hostname from the mDNS name by being cleaver with DNS-SD queries. What happens is that you send a DNS-SD query over the network and then wait for various devices to reply back. Since this is distributed, these things just hang as it waits for responses. On Linux there is avahi-browse, so here is the process to discover these services:

  1. Use dns-sd -E which enumerates all the domains (typically there is only one .local). There is dns-sd -F which tells you readable domains and this is normally .local as well
  2. They have a concept of types which is in the format, the name of the service, and then whether it uses TCP or UDP. They put a confusing underscore first, so a web server uses the type _http._tcp. So for instance on our network, there is _belkin-linkplay._tcp.local. and as an aside, you can see this is the full and correct name which is the service then the IP protocol then the domain name and the following dot means that this is it.
  3. It is hard to find, but there is a meta service that lets you look for all the bonjour-enabled services (they are called types in dns-sd) by running dns-sd -B _services._dns-sd._udp and you will get all the services that are around which is a lot since everyone can add their own.
  4. Some of the common interesting Bonjour services or DNS-SD Types are _http._tcp for webserver, _ssh._tcp to login into other machines, _smb._tcp for file access, _airplay._tcp to route audio around
  5. You can check to see what is around for instance for ssh dns-sd -B _ssh._tcp which says for the ssh capable hosts that use or for web servers internally with dns-sd -B _http._tcp or Airplay devices like the HomePod mini with dns-sd -B _airplay._tcp but these do not give you the hostnames to ping to, they give you an Instance Name which is the friendly name but not the Hostname.
  6. You can get the real dns hostname for using ssh using the command dns-sd -L "Richs-UDM-Pro" _ssh._tcp but the main question is how to deal with the single quotes. You can use quotes to take care of spaces, but MacBooks typically have a special character the single quote, to escape this is a little tricky and I have not found a way to do this as the naive dns-sd -L "Rich's Macbook Pro 2021" doesn’t return anything, so I have to use Discovery to find it, so it looks like quoting doesn’t work too well for this.
  7. You can get an IP address with dns-sd -Q richs-macbook-pro-2021.local will return the IP address.

Net, net by using dns-sd and Bonjour you can go through everything that is on the network and except for the problem with the single quote, you can do it all from the command line. Note that it is really hard to script this stuff since dns-sd doesn’t actually end, it just hangs there, so if you are using it for scripting, you need a way to run it for awhile stop it and then capture input. There is a utility called timeout that let’s you do this with timeout 5s dns-sd -E > dns.out for instance runs the enumerate for five seconds and then stops.

Or to automate this, you can use a hacking tool called nmap and run scripts that do this:

  1. To look at all open ports on at an IP address: nmap -F
  2. To determine the operating system use nmap -A richs-macbook-pro-2021.local and this will be pretty slow
  3. If you want to get really detailed information sudo nmap -O unifi.localdomain

Debugging .localdomain with a Mac

OK, it looked like the very poorly document .localdomain was not working, but it turns out that you first have to make sure that you are using the local dns server that is provided by Unifi. So assuming you have not mucked around with defaults here’s the process:

  1. See if the local DNS server out of the UniFi controller is working by doing nslookup unifi.localdomain. The magic here is that Unifi Controller like the Dream Machine always calls itself Unifi.
  2. If the nslookup doesn’t work, look at the top two lines, it shows the DNS Server that is being used for the query and the IP address should be in your subnet, so compare it with the address you see when you run dns-sd -B _ssh._tcp assuming you’ve turned on ssh on your UniFi Controller. Typically if the network address of your machine is then it will be the .1 of that system so Note that the UniFi appears to automatically convert your console names spaces to dashs and removes special characters, so in the UI if you named it, “Rich’s UDM Pro” it becomes “richs-udm-pro.local”
  3. If do not see this then something is putting in a DNS server that is not the default. On my machine, I found that NordVPN was doing this. You will only see some strange IP addresses, but do a whois check to see who owns that server to get a hint. Then the easiest place to look is in the System Settings > Network > WiFi > Details > DNS (if you are on WiFi) and if you see hard addresses use - to delete them. You should see in grey the IP address of the UniFi controller and the search domain should be localdomain also greyed out.
  4. You can see all the active machines with nmap -sP which is very handy if you are wondering what is alive on the network where -sP means to scan for active and available so you can see what is up now also the .localdomain address if they exist (that is if the device provides a hostname when it asks for a DHCP address.
  5. Finally, if you are wondering what addresses are what, you can also use the Unifi web interface at to find names and try to figure out the mapping. By inspection, you can see the hostnames are used from the nmap report

Figuring out the mapping from .local to .localdomain with a Mac

Now one problem is that you can’t tell what network addresses are but here nmap can help, so try nmap -sL richs-macbook-pro-2021.local will return the IP address and the localdomain address. Note that nmap uses a non-standard syntax so -sL means List Scan or list all the information on the target.

You can also use this for bare IP address, so for instance if you have a device named “Obihai 200” in the Unifi portal user interface and see it is at 10.0.1146, you can use nmap -sL and then it will show you the domain name which by the way for this device is obi200.localdomain which I would not have guessed. I think some of these things are somehow

Debugging .local and .localdomain with Ubuntu

If you have Ubuntu you have a different set of tools namely the avahi-browse package:

  1. Ubuntu 20.04 includes this by default and you can do timeout 10s avahi-browse --all to get a list and this is a little more convenient in that unlike dns-sd you get all the protocols in one go and these are usually sorted in host order although usually, it is the cache of things on your local machine of m-DNS broadcasts.
  2. You can also resolve names avahi-resolve -n hive1.local to find the IP address (or you can just ping it).
  3. If you want a graphical view, then sudo apt-get install avahi-discover and this gives you a nice graphical view like Discovery on the Mac side.
  4. By default, Ubuntu does not advertise any services at all so you will not see it anywhere, but interestingly you can still access it with $(hostname).local

When there is no .local or .localdomain name fixes

Some devices do not report any hostname at all, for instance, the Rainmachine 16 that I have when I do a nmap -SL does not show anything, and looking at the Discovery application it is not a bonjour device. If this happens, the UniFi-friendly name is the MAC address and there is a generic icon. But you can fix this by adding a friendly name and submitting it to the icon database.

So for example I have a Tailwind garage door opener and the friendly name reported by Unifi Console is Tailwind iQ3 which reports as an expressif (which is the OEM software it uses), so I can change the friendly name but I can’t change that localdomain name used.

Net, net, you can add a pretty name to the Unifi user interface, but other than setting a fixed IP address and adding a fake DNS hostname but there is no simple way just to add a name to the localdomain DNS server.

Some of these hostnames are pretty useless as many devices do not set a meaningful hostname, so you get something pretty crazy like the OEM of the embedded software. If the system does not see a hostname, then it uses MAC address fingerprinting to try to get a reasonably pretty name and icon. But this doesn’t add anything to the .localdomain database.

This works for instance with our Meross smart outlets, it detects and names them nicely. With the Lutron hub, it finds a hostname that is randomly generated and puts the right icon in.

To fix the pretty name and the icon in the Unifi user interface you can add this manually in and then you can access it by going to Controller > Network > Client Devices > _the name of the device_ > Settings > Name and I thought this would also add a localdomain name.

The other thing is that there is an icon system inside Unifi, so you can add icons that are misidentified as well in _Controller_ > Network > Client Devices > _name of the device_ > Overview> Report Missing Icon and look for the icon and the proper name.

The Meta/Facebook Portal as a rogue Airplay device

Well, this was the most confusing thing on the network, we had a rogue device that was transmitting with a strange name, so if you have this is the debugging protocol. We have a few although they appear to be about to be canceled:

  1. We saw the strange name on the Airplay list of receivers on the Mac
  2. So given the above, you know that dns-sd -B _airplay._tcp will give the list
  3. Then dns-sd -L "Strange Name" _airplay._tcp will give you the mDNS name which was confusingly localhost.local which is not the same as localhost
  4. So then going to the Unifi console or trying nmap -A localhost.local we see that it is one of our Meta/FaceBook Portals that is acting like an Airplay receiver with a strange name. Mystery solved
  5. The thing that is interesting is that it was correctly broadcasting to .localdomain, but the .local was very strange. The UI doesn’t even say that it can act as an Airplay receiver, but it reports as an AppleTV3,2 so it can apparently take video but interesting our other Portal doesn’t report this at all.

The Puzzle that is MacBook Pro shortened .localdomain names by Ventura?

And in previous releases of UniFi controllers, richs-macbook-pro-2021.localdomain which were lengthy but easy to understand. However as of December 2022, this has changed with either Unifi or MacOS Ventura, so Unifi appears to have changed this, now you can determine the new hostname by the hostname command on your Macintosh which tells you that it takes the so that on a Mac hostname returns the name and the domain which is richs-mbp-2021.localdomain. This surprised me since on Ubuntu, the hostname is manually set hostnamectl set-hostname but here it automagically changes. I’m thinking this is probably something smart that MacOS Ventura is doing as it just started here.

You can also see this in the Unifi Controller name as well which is Richs-MBP-2021 and I’m not sure how this was derived. Did MacOS Venture change this to be shorter or did Unifi? it’s not clear but just beware that the .local and the .localdomain names may not match anymore.

I’m Rich & Co.

Welcome to Tongfamily, our cozy corner of the internet dedicated to all things technology and interesting. Here, we invite you to join us on a journey of tips, tricks, and traps. Let’s get geeky!

Let’s connect