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.

Only a Linux node carries the traffic

A macOS or Windows node cannot forward traffic to a device on its LAN. Put a Linux node on the LAN of the device that you want to reach. See Reaching the device through that member.

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 and in its LAN DNS servers.
2. If both do not know the name, the node asks for <name>.local over mDNS 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.
• The node waits at most 1 second for an answer. 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.
• 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. See A name this machine reaches itself.

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.
• 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.

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 the node's primary address (network.local_ip in nobgp status). The service gets the default name from the table.
   • A program that listens only on 127.0.0.1 or on another address is not reported, because other nodes cannot reach it.
   • 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)	No: it cannot carry the traffic	Yes	No: it cannot 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 the node's primary address (network.local_ip), not only on 127.0.0.1.

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. When a firewall on that node blocks the port for noBGP traffic, the service still shows but does not connect. Allow the port on that node, or turn reporting off there.

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. Make sure that the node on that LAN runs Linux. See Platform support.
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.