NC STATE LINUX USERS’ GROUP · OCTOBER 16 · RALEIGH

How two machines
find each other.

WireGuard is the tunnel. NetBird handles the keys, NAT traversal, and the fallback when a direct path is impossible.

Brandon Hopkins · Head of Content and Developer Relations, NetBird

Brandon Hopkins

When I was younger I tinkered with Xbox, ran a side business fixing computers, and built Minecraft servers.

TechHut

Linux, homelabs, and self-hosting.
Videos and guides at techhut.tv.
NetBird

I work on the docs, demos, and explaining what happens after netbird up.

Two machines behind NAT

I want to SSH from my laptop to my homelab.

A laptop on campus wants to reach a homelab at home. Both have private addresses behind a router. Neither has an inbound port forward.

Encryption needs a working path before it can help.

What WireGuard handles

A public key identifies the peer.

AllowedIPs ties that key to tunnel addresses.

Sending

The destination address selects the peer.
Receiving

The decrypted source address must match that peer’s AllowedIPs.
Transport

Encrypted packets over UDP. No built-in TCP fallback.

Key distribution, address assignment, and NAT traversal live outside WireGuard.

Speaker notes and sources

~2 min. WireGuard is deliberately small. You configure a private key locally and give it the public keys of the peers it should trust. AllowedIPs does two jobs. Outbound, the destination picks a peer. Inbound, WireGuard checks the decrypted source address against the authenticated peer’s allowed addresses. That’s cryptokey routing. The handshake uses Noise with Curve25519, and the data uses ChaCha20-Poly1305. There’s no cipher menu to negotiate. On Linux, the tunnel can run in the kernel or through wireguard-go in userspace. But WireGuard doesn’t distribute those keys, choose your overlay addresses, or discover a path through two NATs. That’s the work NetBird does around it.

WireGuard cryptokey routing WireGuard protocol

How the peers connect

Register: clients send public keys to Management, which provides addresses and policy.
Find a path: STUN discovers public addresses. Signal exchanges encrypted candidates.
Connect: WireGuard carries traffic directly when possible, or through a relay.

1. RegisterSign in. Get the network map.
2. Find a pathDiscover addresses. Test candidates.
3. ConnectSend encrypted traffic.

Speaker notes and sources

~3 min. This is the whole sequence. First, each client generates its keypair locally and registers using sign-in or a setup key. Management receives the public key and sends back an overlay address, authorized peers, and policy. Advance once. Each client asks STUN what public address and port it sees. Signal carries the encrypted candidate exchange between peers. The clients test possible paths with ICE. Advance again. Once a path works, WireGuard carries the session. If a direct path fails, the native NetBird relay forwards the encrypted packets. Management and Signal don’t carry that application traffic. You can use NetBird Cloud or run these services yourself.

How NetBird works Relay and ICE behavior

Management distributes trust

Both clients register their public keys and receive a network map. Their private keys stay on the machines. Management distributes policy; each client applies access rules locally.

Overlay addresses

An account uses a /16 within 100.64.0.0/10.

Access rules

Management distributes policy. Clients enforce it locally.

Speaker notes and sources

~2 min. Management knows the public keys, addresses, and access policy. The private key stays on the client. The account gets an IPv4 range within 100.64.0.0/10, separate from the usual private LAN ranges. That isn’t a promise that it can never overlap another VPN. Management distributes the network map, policies, and DNS configuration. The client applies the access rules locally. Joining the account and being allowed to reach a service are separate decisions. Check the actual policy, including any default policy, before assuming the network is restricted.

How NetBird works

Discover an address, then test it

STUN observes Peer A at 203.0.113.10:33978 and Peer B at 198.51.100.20:48654. These are example addresses.
Peers exchange encrypted candidates through Signal.
The clients test those candidates. A STUN response alone does not establish a tunnel.

STUN reports what it sees. ICE checks which candidate pairs actually work.

Speaker notes and sources

~2 min. STUN sees the source address and port after NAT has rewritten them. Those example ports are 33978 and 48654. They are candidates, not proof that the other peer can reach us there. The client also knows local interface addresses. Signal passes the candidate messages to the other peer, encrypted between the clients. The peers then test candidate pairs with ICE and nominate a working pair. The pair selection uses priorities and connectivity checks; it isn’t simply whichever packet answers first. Signal remains available for coordination when connections need to change, even though it doesn’t carry the WireGuard session.

How NetBird works ICE connectivity checks and nomination

The relay carries encrypted packets

The laptop encrypts traffic with WireGuard. The relay forwards the ciphertext to the homelab, which decrypts it. The same end-to-end encryption applies in the reverse direction.

Two transports race

QUIC over UDP/443 and WebSocket over TCP/443. The first connection wins.

A separate fallback path

The native relay is separate from ICE. An ICE relay candidate means legacy TURN.

A relay can change latency and throughput. It cannot decrypt the WireGuard payload.

Speaker notes and sources

~2 min. If the direct path is unavailable, both peers use a relay connection. WireGuard encryption stays between the endpoints. The relay forwards ciphertext. Current clients try QUIC and WebSocket in parallel and keep whichever connects first. WebSocket can win while UDP is working. Allowing TCP 443 helps, but a proxy or TLS inspection can still interfere. The native relay is a separate path from ICE. The relay candidate type in ICE is the legacy TURN path, not this native relay. In status output, a native relayed connection normally shows no selected ICE candidate pair. We’ll look for that in the demo.

Relay transports and firewalls Native relay and TURN status

Demo time

1
Connect the laptop and homelabnetbird up
2
Inspect the actual pathnetbird status -d
3
Reach the service over its NetBird addressssh <user>@<homelab-netbird-ip>

Watch the overlay IP, connection type, and WireGuard handshake.

docs.netbird.io GitHub repository

Speaker notes and sources

~30 sec, then demo. We’ve got our two machines. Now I’ll connect them, inspect the route they actually took, and open an SSH session. Use the server’s real username and NetBird IP in that last command. SSH must already be running, and the NetBird access policy must allow TCP 22 between these peers. A relayed result still demonstrates the design. Before the talk, sign in on both machines, check the SSH credentials, confirm the policy, and keep the backup example below ready. Aim for 8 to 10 minutes here, then questions.

Demo backup: this illustrative excerpt uses the documented status fields. It is not a live capture. If the live setup fails, use it to explain the expected evidence without claiming the demo worked.

netbird status -d

homelab.netbird.cloud:
  NetBird IP: 100.75.226.48
  Status: Connected
  Connection type: Relayed
  ICE candidate (Local/Remote): -/-
  Last WireGuard handshake:
    25 seconds ago

Connected plus a recent handshake indicates an active encrypted tunnel. Relayed plus the dash pair indicates the native relay path, with no selected direct ICE pair. A successful SSH session also checks that the service is listening, policy permits the port, and SSH authentication succeeds.

Detailed connection status NetBird quickstart

How two machinesfind each other.

Brandon Hopkins

TechHut

NetBird

Two machines behind NAT

What WireGuard handles

Sending

Receiving

Transport

How the peers connect

Management distributes trust

Overlay addresses

Access rules

Discover an address, then test it

The relay carries encrypted packets

Two transports race

A separate fallback path

Demo time

How two machines
find each other.