Xiaomi NBNS Proxy

简体中文 | English

A small, targeted NBNS discovery proxy that helps Xiaomi cameras find an SMB server across routed networks, WireGuard, or another layer-3 VPN.

It was built from packet captures of a Xiaomi camera's NAS setup flow. The camera broadcasts a wildcard NetBIOS Name Service (NBNS) query on UDP port 137. Because broadcasts do not cross routers, a remote SMB server never appears in the Mi Home app. A normal UDP relay is not enough: the tested firmware connects to the source IP of the NBNS reply, not the address inside the answer.

This proxy forwards only the expected wildcard query to one configured server, validates its response, and sends the response back with the SMB server's IP as the source:

Xiaomi camera          Router running this proxy          Remote SMB server
192.168.1.50           LAN / VPN gateway                  10.99.0.10
      |  NBNS broadcast         |                                |
      |------------------------>|  unicast NBNS query             |
      |                         |------------------------------->|
      |                         |<-------------------------------|
      |<------------------------|  reply sourced from 10.99.0.10 |
      |  NBSTAT and SMB connect directly to 10.99.0.10           |
      |--------------------------------------------------------->|

The proxy handles discovery only. SMB traffic and credentials never pass through it.

Requirements

• Linux or OpenWrt on the Xiaomi camera's LAN, preferably the layer-3 gateway.
• IPv4 routing between the camera subnet and the SMB server.
• UDP 137 allowed from the proxy to the SMB server.
• TCP 445 allowed directly between the camera and the SMB server.
• A stable IP address for the camera, ideally a DHCP reservation.
• Samba nmbd or another NBNS responder enabled on the SMB server.
• Root, or the CAP_NET_RAW and CAP_NET_BIND_SERVICE capabilities.

You do not need to enable SMB1. The camera tested during development negotiated SMB 3.1.1 after discovery.

Download

Download the static x86-64 Linux binary from GitHub Releases:

gh release download --repo tinymins/xiaomi-nbns-proxy \
  --pattern 'xiaomi-nbns-proxy-linux-amd64*'
sha256sum -c xiaomi-nbns-proxy-linux-amd64.sha256
chmod +x xiaomi-nbns-proxy-linux-amd64

The release binary is statically linked and works on x86-64 Linux/OpenWrt. Build from source for other architectures.

Build

make
make check

To build the static release artifact:

make release VERSION=v1.0.0

Usage

Run the proxy on the camera's LAN before opening the NAS setup page:

sudo ./xiaomi-nbns-proxy-linux-amd64 \
  --interface br-lan \
  --client 192.168.1.50 \
  --upstream 10.99.0.10 \
  --idle-timeout 900

Arguments:

• --interface IFACE: camera-facing network interface, such as br-lan.
• --client IPv4: the single Xiaomi camera allowed to use the proxy.
• --upstream IPv4: the remote SMB/NBNS server.
• --idle-timeout SECONDS: exit after this many seconds without a valid camera query. The default is 120; the accepted range is 1–3600.
• --self-test: run built-in packet parser tests.
• --version: print the version.

Then, in Mi Home:

1. Open the camera's NAS/network-storage settings.
2. Wait for the remote NetBIOS server name to appear.
3. Select it and enter the SMB username and password.
4. Select the desired share.
5. Stop the proxy after setup, or let the idle timeout stop it.

The saved SMB connection normally reconnects directly without this proxy. Run the proxy again if the NAS entry is deleted or the camera is reset and must repeat discovery.

OpenWrt example

Copy the release binary to the router and run it on demand:

scp xiaomi-nbns-proxy-linux-amd64 root@192.168.1.1:/tmp/
ssh root@192.168.1.1
chmod +x /tmp/xiaomi-nbns-proxy-linux-amd64
/tmp/xiaomi-nbns-proxy-linux-amd64 \
  --interface br-lan \
  --client 192.168.1.50 \
  --upstream 10.99.0.10 \
  --idle-timeout 900

Use a DHCP reservation so --client cannot unexpectedly point at another device.

Troubleshooting

Confirm that the remote server answers wildcard NBNS queries:

nmblookup -U 10.99.0.10 '*'

Watch discovery and SMB traffic on the router:

tcpdump -ni any \
  'host 192.168.1.50 and (udp port 137 or tcp port 445)'

A successful setup looks like:

1. Camera broadcasts a 50-byte wildcard query to UDP 137.
2. The proxy logs a validated response sourced from the upstream address.
3. Camera sends an NBSTAT query directly to the upstream server.
4. Camera establishes TCP 445 directly with the upstream server.

If the server name appears but login fails, check that the TCP 445 destination is the remote SMB server, that routing is symmetric, and that the account can access at least one share.

Security and scope

• The process creates raw IPv4 packets with a spoofed source address. Run it only on a trusted LAN and only for a server you control.
• It accepts packets only from the configured client address and only the exact wildcard NB/NBSTAT query shape observed from Xiaomi firmware.
• It validates the transaction ID, response type, response status, returned address, and NBSTAT file-server record before replying.
• It is IPv4-only and supports one camera/server pair per process.
• Compatibility may vary by camera model and firmware.

License

MIT