LAN Names and Local Discovery

This page tells you how to use names across your noBGP network in two directions:

• From the network to a LAN. A node can reach a device on the LAN of another node by name: a printer, a NAS, a speaker. The node owner decides which LAN names the node serves.
• From the network to your local apps. A macOS or Linux node can show the other nodes and their services to its own apps — Finder and other Bonjour browsers on a Mac, anything that resolves .local on Linux — with names that end in -nobgp.local.

Nothing on this page announces anything on your LAN. The names and services stay in the apps of the machine that runs the agent.

Reach LAN devices by name

A node in your network can answer for a name that it finds on its own LAN. Other nodes then reach that device through it. Type the bare name on any node:

ping printer
ssh admin@nas

A name one member reaches on its own LAN explains how noBGP records these names and how traffic gets to the device.

Every platform carries the traffic from agent 0.4.131

A node on any platform — macOS, Windows or Linux — serves LAN names, with nothing to configure. Only TCP, UDP and ICMP echo reach the device, over IPv4. See How the traffic reaches the device and Reaching the device through that member.

Through agent 0.4.128 a macOS or Windows node served no LAN name at all, and in 0.4.129 and 0.4.130 it did so only with lan-delivery: socket set.

Devices that have only an mDNS name

Many devices publish their name only over mDNS (Bonjour), as <name>.local: speakers, TVs, some printers and cameras. They have no entry in the LAN DNS server.

From agent 0.4.128, a node also finds these devices:

1. The node looks for the name in its hosts file.
2. If the hosts file does not know it, the node asks its LAN DNS servers and sends an mDNS query for <name>.local on each of its LAN links.
3. If a device answers, the node serves the name to the network.

Rules:

• Use the bare name (speaker), not speaker.local. Most systems send a .local name only to their own LAN, so it does not reach the noBGP network.
• The node asks only on links that have a private IPv4 address. It never asks on its internet (WAN) link or on the noBGP interface.
• When the node is answering for the network, the two lookups run at the same time and the first answer wins, from agent 0.4.137, and the whole lookup is bounded at 800 ms. Through agent 0.4.136 the mDNS query was sent only after every DNS server had been tried, within a two-second budget — longer than noBGP waits for a member, so a device that answers only a resent query, or a LAN whose first nameserver does not reply, could cost the node the name. See A claim whose member is connected and stays silent is dropped.
• For a lookup the node makes for its own applications the two run in turn, with up to 1 second for the mDNS query. A name that no device knows takes up to 1 second longer to fail.
• A name that has a dot and does not end in .local is not sent to mDNS.
• From agent 0.4.140 the node asks for the device's IPv4 and IPv6 addresses together. A device that answers with an IPv6 address first is given a further 300 ms for its IPv4 answer, since the two arrive separately and in no order; both are kept, IPv4 first. Through agent 0.4.139 only the IPv4 address was asked for, so a device that has only an IPv6 one was never found.
• Bare Windows names that only LLMNR or NetBIOS answer are not found.
• The node that serves the name must run agent 0.4.128. The other nodes need no upgrade.

The same lookup also helps the node's own apps. When the machine can reach an mDNS-only device on its own LAN, a lookup goes to the device directly and not through another node. From agent 0.4.139 the agent answers such a lookup with the device's LAN address itself, which is what makes these names work on a machine whose resolver never asks the LAN for a bare name. See A name this machine reaches itself.

Devices whose name is not a host name

Some devices hand the DHCP server a name nobody can type as a host name. A WiiM speaker leases as WiiM Mini-9D84, with a space in it: the LAN DNS server keeps the lease and publishes no record for it, and a resolver sends a name containing a space nowhere — so until agent 0.4.147 no node could reach such a device by name at all.

From agent 0.4.147, a node that runs its LAN's DHCP server also serves that device under its label: the same name with everything a host name cannot hold turned into hyphens.

ping WiiM-Mini-9D84
ssh admin@Benoits-MacBook

The device's DHCP name	The name to type
WiiM Mini-9D84	WiiM-Mini-9D84
Benoit's MacBook	Benoits-MacBook
Living_Room TV	Living-Room-TV

How the label is made:

• Each run of characters a host name cannot hold — a space, _, ., other punctuation — becomes one -, and so does a run of -.
• An apostrophe and any character that is not plain ASCII is dropped, so Benoit's becomes Benoits — the name macOS gives the same machine.
• A leading or trailing - is removed, and the label is cut to 63 characters.
• Case is kept, and does not matter when you type the name.

Rules:

• A real name always wins. The lease is the last source the node looks at: hosts file, then LAN DNS, then mDNS, then the leases. A device whose own name already is a host name keeps it, from whichever source has it.
• Only on the node that runs the LAN's DHCP server, and only where that server is dnsmasq — an OpenWrt or GL.iNet router, a Pi-hole, a Linux box serving DHCP. A node behind an ISP router has no lease to read. ISC dhcpd, Kea, odhcpd, systemd-networkd and Windows DHCP Server are not read, and a Windows node reads no leases at all.
• Only a live lease. An expired one is skipped, because its address may belong to another device by now.
• lan-names is asked twice — on the label you typed and on the device's own name — so the node owner can exclude such a device by either.
• Two devices can map to one label (WiiM Mini and WiiM_Mini). The one with the later lease wins — a lease that never expires counts as the latest of all — and then the lower address, so the answer is the same every time and on every node.
• The lease file has to be the DHCP server's own. It is refused if any user can write it, if it is a symbolic link or not an ordinary file, or if it is not root's and sits in a directory any user can write — a lease decides where another node's traffic goes.
• mDNS names are not guessed this way. A device that answers mDNS almost always gives its host a proper label there — the WiiM above answers to Panasonic.local — and that name is already served by the mDNS lookup. Only DHCP carries the unusable one.
• Only the node that serves the name needs agent 0.4.147. The other nodes need no upgrade.
• On that node, net_reach reports the device's own name as resolution.lan_name, so you can see which host answered a label.

Limit the LAN names a node serves: lan-names

By default, a node serves every LAN name that it can find. The node owner can make this list smaller with the lan-names setting.

A name outside the list is never resolved for the rest of the network. The node does not ask its hosts file, its LAN DNS servers or mDNS on the network's behalf, so no other node gets the address. net_reach reports it as resolution.refused: "lan_names".

⚠ It withholds the address, not the existence. The node's own lookups are not filtered, and one of them still runs on the miss path for a refused name, so a remote caller can tell a refused name that exists on your LAN from one that does not, by the shape of the refusal. It never gets the address. Closing that gap changes the miss path rather than this setting (agent#1167).

Set it on the node itself:

# Every name (the default)
sudo nobgp config --lan-names='*'

# Only the NAS devices and the printer
sudo nobgp config --lan-names='nas*,printer'

# Every name except the router
sudo nobgp config --lan-names='*,!router'

# No names
sudo nobgp config --lan-names=off

On Windows, run the same command without sudo, in an Administrator terminal.

The value is a comma-separated list of patterns:

Entry	Meaning
*	Any number of characters
?	One character
nas*	Every name that starts with nas
!pattern	Exclude the names that match. An exclusion always wins, in any position: *,!router and !router,* are the same
A list of only exclusions	Starts from every name: !router,!nas* means *,!router,!nas*
off, none or an empty value	No names

How a name is matched:

• Case does not matter, and a dot at the end is ignored.
• A name matches when its full name or its first label matches. So nas* matches nas, nas-2 and nas.lan. It also matches nas.example.com.
• An exclusion matches in the same way. !router also excludes router.lan.
• An IP address matches on the full address only, for example 192.168.1.*.
• Spaces around entries are removed, and empty entries are ignored.

What the setting does and does not change:

• Only the node owner can change it. Set it on the machine with nobgp config --lan-names, or with the environment variable NOBGP_LAN_NAMES in the agent's environment. See Which LAN names this node serves. node_config_set refuses it, and node_config_get does not show it.
• The node's own apps are not filtered. The setting controls only the names that the node serves to other nodes.
• It applies within a few seconds. The agent applies the change without a restart.
• A name that you remove stops working within a few seconds. When the node served the name before, it stops delivery to that device. The node stops answering for it, so noBGP drops the node's claim about two minutes later: the name then resolves through another node that reaches the device, or stops resolving at all. See When several members claim one name.
• A bad pattern is refused. nobgp config refuses a pattern that is not valid and saves nothing. If you put a bad pattern into the file by hand, the node serves no names, and nobgp show and nobgp status tell you why.

Read the setting back:

nobgp show      # the lan-names line
nobgp status    # network.lan_names, and network.lan_names_invalid for a bad pattern

network.lan_names is [] when the node serves no names.

How the traffic reaches the device

From agent 0.4.131 a node always delivers from its own socket, on every platform, and there is nothing to set. The agent ends the flow from the other node itself and opens an ordinary connection to the device, so the machine's kernel picks its own LAN address as the source and the reply comes back. No firewall rule is involved.

• macOS, Windows and Linux all serve LAN names. Only the node that sits on the device's LAN needs agent 0.4.131; the nodes that reach the device need no change.
• ⚠ Only TCP, UDP and ICMP echo reach the device. Anything else addressed to such a name is dropped. A ping gets an answer only when the device answers the node — nothing is invented for a device that is silent.
• IPv4 and, from agent 0.4.140, IPv6. The node reaches the device on every address its name resolves to, preferring IPv4 where the device has both. A device that has only an IPv6 address is served by a node that has a route to it over IPv6, and is refused — so that noBGP asks another member — by one that has not. ⚠ Through agent 0.4.140 a ping to such a device was not answered by a Windows node, though TCP and UDP to it worked; 0.4.141 answers it. Through agent 0.4.139 a device with only an IPv6 address was not served at all.
• A node carries at most 512 TCP connections and 256 UDP flows to LAN devices at one time. Over that, a new one is refused and the node writes one log line a minute.
• A LAN answer of 0.0.0.0, a loopback address, a multicast address or the broadcast address is refused. Pi-hole and hosts-file blocklists answer 0.0.0.0, and connecting to it would reach services on the node itself.
• On Linux, the firewall rules that earlier releases needed are no longer added, and an agent removes any that an earlier release left behind.

Earlier releases handed the packet to the host's kernel to forward, which needs a source rewrite that only Linux supplies. Agents 0.4.129 and 0.4.130 offered both paths through a lan-delivery setting; that setting is retired, and the agent removes it from the profile the next time it writes the file. See How a node delivers to a LAN device.

See other nodes in your local apps

A macOS or Linux node can show the other nodes in your network, and the services that they offer, to its own apps. For example:

• ping pi5-nobgp.local and ssh admin@pi5-nobgp.local work in a terminal, on either platform.
• On a Mac, the Finder sidebar shows pi5 (noBGP) under Network when pi5 shares files, and apps that browse for services, such as Terminal's New Remote Connection, list the nodes that offer them.
• On Linux, any program that resolves .local names through avahi-daemon sees them — getent hosts pi5-nobgp.local, a file manager's network view, avahi-browse.

Local apps only

The node announces these names and services only to its own apps. It sends no announcement on the LAN, and it does not answer LAN devices that ask for them. The address behind each name is valid only on that machine. On macOS the entries are registered local-only; on Linux they are published on the loopback interface, which was measured to send nothing on the LAN.

When an app looks up a -nobgp.local name, the machine's own system sends a normal mDNS query for that name on the LAN. The query contains no address, but a device on the LAN can see the name.

Turn it on

The setting mdns-announce is off by default. Turn it on, on the node that is to show the names:

sudo nobgp config --mdns-announce

To turn it off again:

sudo nobgp config --mdns-announce=false

The = is necessary for false. The agent applies the change without a restart. You can also set the environment variable NOBGP_MDNS_ANNOUNCE in the agent's environment.

• Only the node owner can change it. node_config_set refuses it.
• nobgp show prints the value. nobgp status shows whether it works: see Check the announcer.
• The node must run agent 0.4.128.
• On Linux the node needs avahi-daemon. With the setting on and avahi absent, the agent keeps the names and publishes them as soon as avahi starts, so nothing is lost — but nothing resolves until then. Most headless installs do not have it.
• On Windows the setting has no effect: Windows has no way to announce a name to local apps only. See Platform support.

Check the announcer

Run nobgp status on that node and read network.mdns_announce:

  network:
    mdns_announce:
      state: "on"
      registered: 12

Field	Description
state	off: mdns-announce is false. unsupported: the setting is on, but this platform has no announcer (Windows). on: the node announces names
registered	How many names and services are announced now. Only when state is on
waiting	How many names and services failed to register. The agent tries them again later. Only when state is on and the number is not 0
capped	true when the node knows more names and services than the limit of 128, so some are not announced. Only when true

The names

Host names. The node adds one name for each other node that it knows: <name>-nobgp.local. The name is in lower case. The address is the same address that the bare name gives you on that machine.

LAN hosts that another node serves. The node also adds a name for each LAN device that it reaches through another node. For example, when a Linux node serves the LAN device glkvm, an announcing node publishes glkvm-nobgp.local. Only the host name is announced for these devices, never services. The lan-names setting of the node that serves the device controls which of these names exist.

• The -nobgp suffix prevents a conflict with a real LAN device of the same name. So pi5.local stays your LAN device, and pi5-nobgp.local is the noBGP node.
• A name that is not a valid host label is not announced. A valid label has only letters, digits and hyphens, has no dot, and has at most 57 characters.
• When a node leaves the directory, for example because it is deleted or offline, its name is removed.
• A node announces at most 128 names and services in total. Host names come first.

Service names. Each service shows as <node> (noBGP), for example pi5 (noBGP). When one node offers two services of the same type, each one shows as <service name> on <node> (noBGP). If two names are still the same, the announcing node adds #2, #3.

Which services

A node reports only these service types:

Service	Type	Port	Apps that use it	Name when found listening
File sharing (SMB)	_smb._tcp	445	Finder	SMB
File sharing (AFP)	_afpovertcp._tcp	548	Finder	AFP
Screen sharing (VNC)	_rfb._tcp	5900	Finder, VNC viewers	Screen Sharing
Remote login (SSH)	_ssh._tcp	22	Terminal, SSH clients	SSH
File transfer (SFTP)	_sftp-ssh._tcp	22	SFTP clients	only when the host announces it
Remote desktop (RDP)	_rdp._tcp	3389	Remote desktop clients	RDP

A node does not report any other service. These services are not the services that you publish through noBGP.

Where the services come from

Each node finds its own services. You do not declare them. A node finds a service in one of two ways:

1. The host announces it. The node reads the services that its host already announces over mDNS, and keeps their real names.
   • macOS: the sharing services that you turn on in System Settings → General → Sharing (File Sharing, Screen Sharing, Remote Login).
   • Linux: the service files of avahi, in /etc/avahi/services/, when avahi-daemon runs. A service that a program registers with avahi while it runs is not seen here. Step 2 still finds it when its port is in the table above.
   • Windows: nothing. Windows does not announce these services.
2. It listens on the node. The node reads its own list of listening TCP ports. It reports a service from the table when a program listens on its port on an address a peer reaches — every address, the node's primary address (network.local_ip in nobgp status), and from agent 0.4.140 127.0.0.1 or [::1] as well. The service gets the default name from the table.
   • From agent 0.4.140 a program listening only on loopback is reported, because another node now reaches loopback on the machine. Earlier releases left it out, and a machine whose agent is not delivering peer traffic that way still does.
   • A program listening on another address — a container bridge, 127.0.0.53 — is not reported, because other nodes do not reach it there.
   • Port 22 gives only SSH, never SFTP. An SSH server does not always include SFTP.
   • On Windows, port 445 listens on every host, so a listener alone does not show that files are shared. A Windows node reports SMB only when it has at least one share that is not a default administrative share (C$, ADMIN$, IPC$ and similar).
   • The node only reads a list. It does not connect to the port, so no log line is written on the host.

The node checks at start and then every 5 minutes. It sends the list only when the list changes. Other nodes get the change within a few minutes.

A node sends its services only to the nodes that can already see it. A node in an isolated network sends them to nobody.

You can see what each node reports in network_directory, in info.host_services. On the node itself, read the host_services block of nobgp status.

Turn reporting off: mdns-report-services

A node reports its services by default. A report adds only discovery: other nodes in the network can already reach these ports.

To stop the report, run this command on that node:

sudo nobgp config --mdns-report-services=false

The = is necessary for false. To turn reporting on again, use --mdns-report-services. You can also set the environment variable NOBGP_MDNS_REPORT_SERVICES in the agent's environment.

• The node then looks for no services and reports an empty list. The empty list removes its services from every other node.
• Only the node owner can change it. node_config_set refuses it.
• nobgp show prints the value, and nobgp status shows host_services.reporting: false.

Platform support

	macOS	Linux	Windows
Serve LAN names to the network (with lan-names)	Yes, from agent 0.4.131. Before that it could not carry the traffic	Yes	Yes, from agent 0.4.131. Before that it could not carry the traffic
Show other nodes in local apps (mdns-announce)	Yes	Yes, through avahi-daemon, which the node needs	No: Windows has no way to announce a name only to local apps
Report services it announces	Yes	Yes, with avahi service files	No: Windows announces none
Report services found listening	Yes	Yes	Yes. SMB only with a share that is not a default administrative share

Troubleshooting

A -nobgp.local name does not resolve

1. Make sure that the node runs agent 0.4.128 or later: nobgp version.
2. Run nobgp status and read network.mdns_announce.state:
   • off: turn it on with sudo nobgp config --mdns-announce.
   • unsupported: this machine is Windows, which cannot announce names to local apps only.
   • on: continue with the next steps.
3. Read network.mdns_announce.waiting. A number that is not 0 means that some registrations failed, and the agent tries them again. Read the agent log with nobgp service logs for the reason.
4. Read network.mdns_announce.capped. When it is true, the node knows more than 128 names and services, and it does not announce some of them.
5. Make sure that the node is in network.targets of nobgp status. A node announces only the names that it knows.
6. Make sure that the bare name works: ping pi5. If it fails, the problem is not mDNS. See nobgp status.
7. Make sure that the name is a valid host label. A name with a dot, an underscore or a space is not announced.
8. On Linux, make sure that avahi-daemon runs: systemctl status avahi-daemon. Without it nothing resolves, and network.mdns_announce.waiting counts the names that are held.
9. On Linux, make sure that avahi is not configured to ignore the loopback interface. The agent writes one warning to its log when lo is outside allow-interfaces, lo is in deny-interfaces, use-ipv4=no, or enable-reflector=yes is set in /etc/avahi/avahi-daemon.conf — each of those hides the names from local apps.
10. Ask the system directly:

dscacheutil -q host -a name pi5-nobgp.local   # macOS
getent hosts pi5-nobgp.local                  # Linux

⚠ Only an IPv4 address is published. A program that asks for IPv6 first gets no answer for the name. The mdns4_minimal line that Debian, Ubuntu, Raspberry Pi OS and Fedora install asks only for IPv4, so this affects a hand-edited mdns_minimal line only.

A service does not show in Finder or another app

1. Make sure that the node that offers the service runs agent 0.4.128 or later.

2. Read host_services in nobgp status on that node:

   • reporting: false: the owner turned reporting off. Turn it on again with sudo nobgp config --mdns-report-services.
   • pending: true: the first check has not finished. Wait a few seconds.
   • error: the last check failed. The node keeps the list from the check before.
   • The service is not in services: continue with the next steps.

3. Make sure that the service type is in the table. A node reports no other type.

4. Make sure that the program listens on an address a peer reaches: every address, the node's primary address (network.local_ip), or — from agent 0.4.140 — loopback. A program bound to another address, such as a container bridge, is not reported.

5. On Linux, make sure that avahi-daemon runs if you expect the real service name. Without it, a service found listening shows its default name.

   • Samba always shows as SMB. Samba registers its service with avahi while it runs, and the node does not count that as announced. The node finds Samba by its listening port, with the default name.
   • On Windows, SMB shows only when the host has a share that is not a default administrative share (C$, ADMIN$, IPC$). Share a folder to make it show.

6. On the announcing node, list the announced services:

   dns-sd -B _smb._tcp local.        # macOS
   avahi-browse -rt _smb._tcp        # Linux

   A service with (noBGP) in its name is one that the agent announces. On macOS, press Ctrl+C to stop the command.

A service shows but does not connect

A node cannot see its own host firewall. Through agent 0.4.139, when a firewall on that node blocked the port for noBGP traffic, the service still showed but did not connect. Allow the port on that node, or turn reporting off there.

From agent 0.4.140 the host firewall no longer filters TCP or UDP from other nodes, because the traffic arrives as a local connection the agent makes — so a service that shows here and does not connect is a service that is not answering, not a firewall rule. See How another node reaches this machine's own services.

A LAN name resolves everywhere except on the node next to the device

Upgrade that node to agent 0.4.139. Until then the node that reaches the device answered its own lookups of the name with not found, expecting the machine's resolver to ask the LAN next — and systemd-resolved, which Ubuntu and most current Linux desktops use, sends a bare name to no ordinary nameserver, so it had nothing left to try. The name resolved on every other node through that machine and failed on the machine itself. See A name this machine reaches itself.

One case still answers not found on any release: a device that has an IPv6 address alone, on a node that has no IPv6 overlay address.

A LAN name does not resolve on other nodes

1. On the node on that LAN, run nobgp status and read network.lan_names.
   • []: the node serves no names. Check lan-names.
   • network.lan_names_invalid is present: the value has a bad pattern, so the node serves no names. Correct it with nobgp config --lan-names.
   • The list does not match the name: add the name, or remove the exclusion that matches it.
2. Remember that a name matches on its full name or on its first label. !nas also excludes nas.lan.
3. On a macOS or Windows node, make sure that it runs agent 0.4.131 or later: before that it could not carry the traffic and served no LAN name. See How the traffic reaches the device.
   • Check what reaches the device, too: only TCP, UDP and ICMP echo are carried, over IPv4.
4. For a device that has only an mDNS name, make sure that the node runs agent 0.4.128 or later, and use the bare name.