Document nblink (#1013)

* Document nblink

nblink forwards local ports into a NetBird network from an unprivileged
process, so it covers the cases where the agent cannot be installed: managed
laptops without administrator rights, rootless containers, and short-lived CI
jobs.

Covers the download, the forward syntax, the container environment variables,
and the access control and userspace limits that decide whether it fits.

* Add use cases to the nblink page

The page explained what nblink does and how to run it, but not when to reach
for it, which is the first thing a reader needs to decide.

Covers the three cases it fits best: an MCP server or local AI agent calling
an internal API, Agent Network access from a machine where the client cannot
be installed, and a sidecar for an application that ignores proxy settings.

* Note what the mounted nblink setup key requires

The container example referenced a secret path it never mounted, so it
could not have worked as written. The mount also needs calling out, because
the container runs as an arbitrary UID while a bind mount keeps the host
file's owner and mode, and a key written with the usual private mode is
unreadable to it.

* Document the nblink Host and Origin checks

A loopback forward answers only where Host names the loopback interface and
refuses a cross-site Origin, because a page the reader visits can point its
own hostname at 127.0.0.1 and would otherwise reach the upstream through the
listener under their identity.

* Describe the nblink cross-site check and its residual

The page described only the Host and Origin checks. A page can also embed the
loopback address directly, where Sec-Fetch-Site is the signal that stops it,
and a browser too old to send that header still gets through.

* Publish the nblink container port on loopback only

The container example published port 8080 on every host interface while the
forward inside listened on 0.0.0.0 with public bind enabled, so anything that
could reach the Docker host could use the forward under the peer's identity.
The paragraph beneath it justified that by saying the container boundary
restricts access, which it does not once the port is published.

The example now publishes on 127.0.0.1, with the reason the listener still
has to bind 0.0.0.0 inside the container.

The same section had drifted from the binary in two other places. The
key-file note described what -v does with a missing source path, while the
example uses --mount, which refuses to start. And a public forward now
answers 421 to a name it was not told about, which the page never mentioned:
--allowed-host is added to the container section, the configuration table and
the access-control section, including that a listed name is trusted and
applies to every forward.
This commit is contained in:
Maycon Santos
2026-10-12 14:49:04 +02:00
committed by GitHub
parent 6804d6b194
commit c2198f9956
2 changed files with 248 additions and 0 deletions
+1
View File
@@ -904,6 +904,7 @@ export const docsNavigation = [
title: 'CLIENT',
links: [
{ title: 'Desktop App', href: '/client/desktop-app' },
{ title: 'nblink', href: '/client/nblink' },
{ title: 'Profiles', href: '/client/profiles' },
{ title: 'gRPC Daemon Socket', href: '/client/grpc-socket' },
{ title: 'HTTP/JSON Daemon Socket', href: '/client/json-socket' },