Paths and relays

There's usually more than one way between two of your devices: directly, or through a relay. Nardeboon measures the candidates and uses the path with the best overall score, not the first one that works.

How paths are scored

Every candidate path is scored out of 100 on:

The measurements come only from the keep-alive pings a node already sends, so scoring costs no extra traffic. A trusted direct path is preferred to a relay, except when one of your network's own relays is clearly faster: at least a quarter faster and 15 ms quicker, as a relay with a better route abroad often is. A Global Relay never replaces a working direct path, since its traffic is billed. Among paths of the same kind, the highest score wins, and a path at least a fifth faster takes over too.

Direct paths come from full NAT traversal: obfuscated endpoint discovery, coordinated hole punching, port mapping (PCP, NAT-PMP, UPnP) and LAN peer discovery, over IPv4 and IPv6. Each node uses a random free port, keeps it across restarts, and picks a new one only if it's taken.

Switching paths

• No flapping. When two paths score about the same, traffic stays where it is.
• Fast failover, without false alarms. When the active path stops answering, it's asked again at once, and traffic moves to the next best path within a second if it stays silent. A path that loses packets is checked more often, so a few lost answers on a lossy network don't send traffic elsewhere and back for nothing.
• Fast start. A new connection comes up quickly, through a relay if needed, and moves to a direct path without interruption once one is possible.
• Roaming. Connections survive sleep, network changes and roaming, with nothing for you to do.

Choose what "best" means

Each network has a path selection method, set in the dashboard under the network's Settings → Connectivity. It decides what devices put first when they score their paths:

Whichever you choose, the rules above stay: a working direct path still comes before a relay, near-ties don't flap, and a failing path is left at once. A change reaches every device in the network within seconds, and nardeboon path status ends with the method in use. Devices on a version older than 0.1.43 keep using Auto until they update.

Measuring throughput

While a device sends a peer a megabit a second or more, it measures how much each path can carry: what the path in use already carries, and now and then a short burst of full-size pings, about 28 KB every few minutes, on that path and on any of the same kind that could take over. How far apart the answers come back shows the path's speed. Nothing is measured for a peer with little traffic, on battery or on a metered connection, and a path that hasn't been measured neither gains nor loses by it. A reply held up for a moment, or a few that arrive together, doesn't throw a measurement off: the spacing is read across all of them. nardeboon path status and path explain show what each path carries once it's measured, and path explain --json the last few measurements (trains_mbps).

Probe budget

Measurements aren't all-to-all, so they use little traffic, and a node probes even less on low battery or a metered connection (a mobile one, or one marked metered: in NetworkManager on Linux, in its settings on Windows), when it stretches its keep-alives and searches. nardeboon netcheck shows whether a node is on battery and whether its connection is metered. To measure and re-evaluate paths right away, run nardeboon path optimize.

Relays

Relaying is a capability of the Nardeboon node itself, not a separate kind of server.

A user relay relays only within its own network. To make a node one, tick Also use this node as a relay for it in the dashboard. On any node, nardeboon status lists the relays it can send through.

A relay with a public address also opens a front door on a TCP port of its own, so devices on networks that block UDP still reach it over nb-tls; anyone who connects without your network's secret sees an ordinary website. The port is a free one the relay keeps across restarts, never 443 or 80, so there's no well-known number for a network to single out; devices learn it from the network map. nardeboon status on the relay shows its ports: if the machine has a firewall, let them in. nardeboond -front-port sets the front door's port yourself (anything but 443 or 80), and -front off keeps the door shut.

A device on a network that cuts the connections it starts can't say hello to a relay first, so the relay greets it where it is, when the control plane says so: it can relay through your relays and the Global Relays even when its country blocks a relay's address. See networks that cut what a device starts.

Relays only move encrypted traffic. They never hold keys, never see content and never bridge two different networks.

Community relays

Some Global Relays are servers that people outside Nardeboon give for everyone to use. A network uses them only if it turns on Community relays (network Settings → Connectivity), which is off by default and needs Global Relays in the plan. They're held to the same rules as Nardeboon's own: your traffic stays encrypted end to end and they can't read it, and they can't reach your devices or anything else. What they do see is what any relay sees: your devices' public addresses, and when and how much they send. Off, your networks never use them, aren't told about them, and their devices' addresses are never handed to them.

Global Relay quota

Paid plans include Global Relay traffic as an amount of GB per device per month, pooled across the organisation. Relay bandwidth is counted per organisation. A relay's count isn't taken on its word: a network is counted only for relays its own devices say they're using, and never for more in a day than its devices say they moved that day.

When the pool runs out, Global Relays are cut off until next month, while direct paths and your own relays keep working. To get Global Relays back sooner, the organisation can buy a GB pack or turn on pay-as-you-go, which deducts each GB from its wallet.

See which path is in use

nardeboon path status shows each peer's path, transport and relay, and, while the path answers, its live quality; a peer with no traffic lately is idle, its path not measured until there's traffic:

$ nardeboon path status
PEER      STATE    PATH                          TRANSPORT   RTT     LOSS   JITTER   CAPACITY     FEC
hetzner   active   via Frankfurt (Global Relay)  nb-udp      96 ms   0.1%   3 ms     48 Mbit/s    -
laptop    active   direct                        nb-udp      1 ms    0.0%   1 ms     610 Mbit/s   -
nas       idle     direct                        nb-udp      -       -      -        -            -

nardeboon path explain <peer> lists every candidate and why one was chosen, and every relay the device may use, with why the ones it isn't attached to aren't tried:

$ nardeboon path explain hetzner
PATH                          TRANSPORT   RTT     LOSS   JITTER   CAPACITY    SCORE
via Frankfurt (Global Relay)  nb-udp      96 ms   0.1%   3 ms     48 Mbit/s   84  ✓ chosen
via am-vps                    nb-udp      93 ms   1.6%   9 ms     12 Mbit/s   79
direct 203.0.113.9:41641      nb-udp      -       -      -        -           no path

Chose via Frankfurt (Global Relay): the best overall score of the paths that work.

In the dashboard, the path view shows the same for each connection: which path and transport it uses, its quality, and why that path was chosen. Where a device's network cuts the connections it starts, it also says who opened the connection: the peer that called the device in, or the relay that greeted it.

Pinning a path

A network admin can pin the path between two devices, in the dashboard: the network's Paths tab, under Pinned paths. A path goes straight between them, through one of the network's relays, or through a Global Relay in a region you choose. Both devices take the pinned route to each other while it answers. When it stops answering, they choose as usual, and go back to it as soon as it answers again, so a pin never cuts a connection. Pinning paths needs a plan that includes it.

On a device, you can also pin its own path to a peer, for example to try a route or to troubleshoot:

sudo nardeboon path pin hetzner tr1
sudo nardeboon path pin hetzner direct
sudo nardeboon path pin hetzner germany

The route is direct, one of the network's relays by name, or a Global Relay region by its name or code. A device's own pin wins over the network's pin to the same peer, on that device only; sudo nardeboon path unpin hetzner takes it off. nardeboon path status lists the pinned paths and says when a pinned route doesn't answer, and nardeboon path explain <peer> says why the path is where it is.