CLI reference

The nardeboon command controls the Nardeboon daemon, nardeboond, on the device where you run it. Every command accepts --json, and exit codes are fixed, so everything on this page works in scripts.

Running commands

nardeboon talks to the daemon through the control socket /run/nardeboon/nardeboond.sock. Run commands as root, or add your user to the nardeboon group to run them without sudo:

sudo usermod -aG nardeboon "$USER"

The group membership applies from your next login. Without either, commands exit with code 7 (permission). On this page, commands that change settings are shown with sudo.

Files and names

Commands at a glance

Connection

nardeboon up

nardeboon up [flags]

Joins the network and brings the connection up. If the device isn't logged in yet, up prints a login URL. Run up again at any time to change settings: it changes only the flags you pass.

When what you pass is for the control plane to answer (an auth key, a new hostname, routes or an exit node to offer), up waits for that answer, and a refusal, such as a key that isn't valid, is its error. --timeout sets how long it waits; the daemon keeps trying after that.

sudo nardeboon up --auth-key "$NB_AUTH_KEY" --hostname web-1

nardeboon down

nardeboon down

Disconnects this device. The daemon keeps running and the device stays logged in, so nardeboon up reconnects it.

sudo nardeboon down

nardeboon login and nardeboon logout

nardeboon login
nardeboon logout

login prints a link. Open it in a browser, sign in, choose the network, and the device joins it as yours, under the network's rules for approval. The link works once, for ten minutes. login also renews a device whose key expired.

logout signs the device out: its key expires, and the device forgets it. The device stays in the dashboard, so login brings it back with its name and address.

sudo nardeboon login

To connect this device, open this link and sign in:

  https://app.nardeboon.io/connect/C6qEHb3wExNT

Connected: web-1 (100.83.20.5) on home.

nardeboon status

nardeboon status

Shows the connection, the network, this device's addresses, its peers and any warnings, such as an unreachable control plane. The table lists this device first, then each peer with the endpoint it's reached at (a direct address, or the relay it goes through) and the transport that carries it.

nardeboon status

Connected to network home as mypc (10.77.12.4)
  Control plane: direct

DEVICE    ADDRESS       OS     ENDPOINT                    TRANSPORT  STATUS
mypc      10.77.12.4    linux  -                           -          this device
gateway   10.77.3.17    linux  198.51.100.8:41641          nb-udp     online
hetzner   10.77.20.5    linux  via Frankfurt (Global Relay)  nb-udp   active, 12s ago
laptop    10.77.40.7    linux  -                           -          offline

The Control plane line says how the device reaches the control plane: direct, through its front door, or through a peer or one of the network's relays that passes its session on, by name (control in --json, with via, through and since). On a network that cuts the connections the device starts and lets in those others start (as Iran's strict datacenters do), a line says so: the device then never starts a connection to a device elsewhere, it asks that device to start it (callee in --json). On a device that relays for its network, or one of Nardeboon's Global Relays, a line says so, with how many devices send through it now, how much it passed on since it started, and the ports it listens on, for a firewall in front of it to let in (relaying in --json). A peer is active while traffic flows with it. status exits with 0 when the device is connected, 4 when it isn't on a network, and 5 when it's disconnected; with --json it reports the state either way.

Paths and diagnostics

nardeboon path status

nardeboon path status

Shows each peer's path: how its traffic goes, over which transport and through which relay, and, while the path answers, its live quality.

nardeboon path status

PEER      STATE    PATH                          TRANSPORT   RTT     LOSS   JITTER   CAPACITY     FEC
hetzner   active   via Frankfurt (Global Relay)  nb-udp      96 ms   2.1%   3 ms     48 Mbit/s    +40%, 12 rebuilt
laptop    active   direct                        nb-udp      1 ms    0.0%   1 ms     610 Mbit/s   -
nas       idle     direct                        nb-udp      -       -      -        -            -
phone     offline  -                             -           -       -      -        -            -

STATE is what's known of the path: active while it answers; idle when there's been no traffic with the peer lately, so nothing measures the path, which is where its next packet goes; searching while there's traffic and no path answers yet; offline when the control plane sees the peer offline and no path answers; no path when there's none to try. Figures are shown only for a path that answers.

CAPACITY is how much the path is measured to carry (see Paths and relays); - until it has been, which happens only while this device sends the peer enough for it to matter.

FEC is forward error correction on a path that loses packets: the parity this device adds to what it sends the peer (+40%), and how many of the peer's packets it rebuilt from the parity the peer adds.

nardeboon path optimize

nardeboon path optimize

Measures and re-evaluates paths now, instead of waiting for the next measurement.

nardeboon path optimize

nardeboon path explain

nardeboon path explain <peer>

Shows the full scoring for one peer: every candidate path, direct or relayed, with its metrics and total score out of 100, and why the current one was chosen. A path that isn't used says why when that's known, and every relay the device may use is listed, the ones it isn't attached to with why. See Paths and relays.

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
direct 203.0.113.9:41641      nb-udp      -       -      -        -           no path
direct 203.0.113.9:47391      nb-tls      -       -      -        -           no path
via am-vps                    -           -       -      -        -           this device isn't attached to it: it doesn't answer this device's hellos

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

On a network that cuts the connections a device starts, a direct path can say waits for the peer to call: the device leaves starting the connection to the other side (see Transports).

nardeboon path pin

nardeboon path pin <peer> <route>
nardeboon path unpin <peer>

Pins this device's path to a peer: it takes that route while it answers, and chooses as usual while it doesn't. The route is direct, one of the network's relays by name, or a Global Relay region by its name or code. This device's pin wins over a pin the network's admins made for the same peer, on this device only. Needs a plan that includes pinning paths. See Paths and relays.

sudo nardeboon path pin hetzner tr1

The path to hetzner is pinned via tr1: it takes that route while it answers, and is chosen as usual while it doesn't.

nardeboon ping

nardeboon ping [--transport <name>] <peer>

Without --transport, it tests whether a peer is reachable along the path the device uses for it right now, and the answer says which transport the path took. It sends a ping every second until one is answered, for up to ten seconds: the first packet to a peer that's been idle waits for the tunnel's handshake. If the peer is known but no path works right now, ping exits with code 10 (unreachable).

--transport <name> (nb-udp, nb-udp-dco, nb-tls or nb-wss) instead tests reaching the peer directly over that transport — useful to check whether, say, nb-tls gets through to a peer. nb-udp-dco, nb-tls and nb-wss go to the ports the peer announces for them (its front door, for the last two). A peer reached only through a relay has no direct path over any transport, so the command exits 10.

nardeboon ping --transport nb-tls hetzner

pong from hetzner (100.83.20.5): direct 203.0.113.9:47391, nb-tls, 112 ms

The answer says which way it came: direct and the peer's address, or via a relay, either one of your network's own (relay) or one of Nardeboon's Global Relays, named by its region (Global Relay); then the transport of the first hop (nb-tls on a network that blocks UDP). Right after a device starts, a path may not be settled yet, and the answer says only how long it took. With --json, a Global Relay's region code is in relay_region and the transport in transport, as they are for each peer in status.

nardeboon netcheck

nardeboon netcheck

Reports what the current network allows: how the NAT maps this device, where it's seen from outside, whether it has IPv6, how a port was opened on the NAT (if one was), which transports can carry traffic, and the relays it can reach. A device behind an address- and port-dependent ("hard") NAT needs a relay until a direct path opens; one behind an endpoint-independent ("easy") NAT reaches most peers directly.

nardeboon netcheck

NAT type:         endpoint-independent mapping (easy)
Seen from:        198.51.100.20
Flows it starts:  let through
IPv6:             no
Port mapping:     NAT-PMP
On battery:       no
Metered:          no

Transports:
  nb-udp     ok
  nb-tls     ok
  nb-wss     ok

Relays:
  Frankfurt (Global Relay)  reaching, 31 ms
  node4                     reaching, 4 ms

Seen from is where the control plane sees the device; when the control plane can't be asked, it's where its peers see it, marked (by peers). Flows it starts says what the network does with a connection the device opens itself: let through, or cut after a few packets on networks such as Iran's strict datacenters, which let in what others start and cut what the device starts; peers then call the device. It's measured from a port of its own, so the tunnel's connections aren't touched.

nb-tls and nb-wss are checked against up to three relays' front doors at once, five seconds at most: ok when one answers, blocked when none does, unavailable when no relay has one. A device uses them only when nb-udp doesn't get through, so on a network where UDP works it opens no fallback connection of its own. nb-udp is ok when the control plane's reflector or a peer answers over it. The whole check takes a few seconds; each relay shows the round trip of its last answer.

Port mapping shows how a port was opened on the NAT — NAT-PMP, PCP or UPnP — or nothing. Port mapping is on by default; a network can turn it off in the dashboard.

Network

nardeboon dns

nardeboon dns status
nardeboon dns query <name>

dns status shows the DNS setup this device uses: the network's domain, split DNS, where other names go and how the system's resolver is pointed at Nardeboon. dns query resolves a name, or an address in reverse, the same way this device does and shows where the answer came from. See DNS and device names.

nardeboon dns query hetzner

hetzner.home.nb.internal   A   100.83.20.5

nardeboon route

nardeboon route list
nardeboon route advertise [<ranges…>]
nardeboon route accept [on|off]

Unlike up, advertise and accept change only that setting: a connected device stays connected and a disconnected one stays disconnected.

sudo nardeboon route accept

See Subnet routes.

nardeboon exit-node

nardeboon exit-node list
nardeboon exit-node set <name>
nardeboon exit-node clear

list shows the exit nodes this device can use, and which one it uses. set sends this device's internet traffic through one of them, by name or address, and clear stops using it. If the exit node goes offline, internet traffic stops rather than going out directly. Like route, these change only that setting. See Exit nodes.

sudo nardeboon exit-node set hetzner

nardeboon whois

nardeboon whois <ip|name>

Identifies a peer by its IP address or name. If nothing matches, it exits with code 6 (not-found).

nardeboon whois 100.83.20.5

Maintenance

nardeboon update

nardeboon update check
nardeboon update apply
nardeboon update channel <c>

Devices update automatically. check says which version the device runs, on which channel, how it was installed and whether a newer signed release is out; apply installs it now; channel shows or switches the channel, stable or beta. Only signed versions are installed, never an older one: if a signature or integrity check fails, the command exits with code 9 (verify). nardeboon set auto-update off stops automatic updates on this device. See Install on Linux.

nardeboon update check
sudo nardeboon update apply

nardeboon version

nardeboon version

Prints the node, protocol and obfuscation versions. Include them when you report a problem.

nardeboon bugreport

nardeboon bugreport [--out <file>]

Builds a diagnostics bundle on this device and writes it to the current directory, or to --out, readable only by you. It has the device's settings and status, its peers' names, addresses and paths, what the network it's on allows, the tunnel's addresses, routes and DNS setup, and the daemon's latest log lines. It contains no keys or sensitive data: not the device's keys or state, not the network map, not a login link. It stays on the device until you share it, so you can review it first.

nardeboon set

nardeboon set <setting> <value>

Changes one setting on this device and leaves the connection as it is. The settings are the ones up takes as flags:

sudo nardeboon set accept-routes on

JSON output

Add --json to any command. The output always uses the same envelope:

{"schema": "nardeboon.<command>/v1", "ok": true, "data": { ... }}
{"schema": "nardeboon.<command>/v1", "ok": false, "error": {"code": "offline", "message": "..."}}

• schema names the command and the version of its output.
• ok says whether the command succeeded. Check it before you read data.
• On failure, error replaces data: code is for programs and message is for people. The code is the specific reason, such as needs_login, invalid_auth_key, not_found or unreachable; the exit code groups reasons.

nardeboon status --json | jq '.ok'

Exit codes

Exit codes are fixed and documented:

For code 3, check the service with systemctl status nardeboond.

Scripts can branch on them:

nardeboon ping hetzner > /dev/null
case $? in
  0)  echo "hetzner is reachable" ;;
  5)  echo "not connected: run nardeboon up" ;;
  10) echo "hetzner is known, but no path works right now" ;;
  *)  echo "ping failed" ;;
esac