83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
|
# Runbook — Enrolling a NetBird client (road-warrior device)
|
||
|
|
|
||
|
|
Joins a **client/road-warrior device** (laptop, desktop, phone) to the boma NetBird mesh
|
||
|
|
so it can reach `ubongo` and other peers from anywhere. The self-hosted coordinator is on
|
||
|
|
`askari` (ADR-016, M4b); enrollment lands a device on the `100.64.0.0/10` overlay.
|
||
|
|
|
||
|
|
> **Hosts vs clients.** Managed **Linux hosts** join via the `base` role's `mesh` concern
|
||
|
|
> (`base__mesh_enabled: true` + the reusable key in `vault.netbird.setup_key`) — see
|
||
|
|
> ADR-016 / the `base` README, *not* this runbook. This runbook is for **user devices**
|
||
|
|
> NetBird doesn't manage with Ansible.
|
||
|
|
|
||
|
|
verified: NetBird client install + self-hosted `--management-url` flow · docs.netbird.io
|
||
|
|
(`/get-started/install/windows`, `/get-started/cli`) · 2026-06-17
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- The coordinator's first-boot `/setup` admin exists and you can log in at
|
||
|
|
`https://netbird.askari.wingu.me`.
|
||
|
|
- **Auth, pick one:**
|
||
|
|
- **SSO** (recommended for a personal device) — your dashboard account; no secret to copy.
|
||
|
|
- **Setup key** — dashboard → **Settings → Setup Keys** → a reusable key (mint a
|
||
|
|
client-specific one for clean ACL grouping, or reuse the existing reusable key).
|
||
|
|
- Local **admin rights** on the device (the client installs a service).
|
||
|
|
- **Coordinator facts:** management URL `https://netbird.askari.wingu.me`; `ubongo`
|
||
|
|
= `100.99.146.14` (`ubongo.netbird.selfhosted`); `askari` = `100.99.226.39`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Part A — Windows 11
|
||
|
|
|
||
|
|
1. **Install:** download + run the MSI **https://pkgs.netbird.io/windows/msi/x64**
|
||
|
|
(official x64 client; installs the tray app + the `netbird` service).
|
||
|
|
2. **Connect** from an **elevated** Windows Terminal / PowerShell ("Run as administrator"):
|
||
|
|
```powershell
|
||
|
|
netbird up --management-url https://netbird.askari.wingu.me
|
||
|
|
```
|
||
|
|
A browser opens — sign in with your dashboard account. (SSO won't open a browser?
|
||
|
|
use a key: `netbird up --setup-key <KEY> --management-url https://netbird.askari.wingu.me`.)
|
||
|
|
3. Proceed to **Part C** (verify).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Part B — Other platforms (same management URL)
|
||
|
|
|
||
|
|
- **macOS / Linux desktop:** install the client (macOS: NetBird app / Homebrew; Linux:
|
||
|
|
`pkgs.netbird.io` per the distro — same apt/rpm flow as `base`'s `mesh` concern), then
|
||
|
|
`netbird up --management-url https://netbird.askari.wingu.me` (Linux: prefix `sudo`).
|
||
|
|
- **Android / iOS:** install the **NetBird** app, then in **Settings → Advanced /
|
||
|
|
Server** set the management server to `https://netbird.askari.wingu.me` **before**
|
||
|
|
logging in; connect and complete the SSO login. (Setup keys are supported in-app too.)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Part C — Verify + use
|
||
|
|
|
||
|
|
```sh
|
||
|
|
netbird status # expect: Management: Connected, Signal: Connected, a 100.x NetBird IP
|
||
|
|
netbird status -d # peer detail — ubongo (100.99.146.14) + askari (100.99.226.39) listed
|
||
|
|
```
|
||
|
|
Reach `ubongo` over the mesh:
|
||
|
|
```sh
|
||
|
|
ssh sjat@100.99.146.14 # or: ssh sjat@ubongo.netbird.selfhosted
|
||
|
|
```
|
||
|
|
**SSH auth is separate from the mesh:** `ubongo` is key-only (passwords disabled), so the
|
||
|
|
device needs an SSH key authorised for `sjat@ubongo`. The mesh provides the network path;
|
||
|
|
the SSH key provides auth.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Notes
|
||
|
|
|
||
|
|
- **Split-tunnel:** NetBird routes only the `100.x` overlay by default — normal/work
|
||
|
|
networking is unaffected.
|
||
|
|
- **Persistence:** the service auto-starts on boot and reconnects; the tray app has
|
||
|
|
Connect/Disconnect; CLI `netbird down` / `netbird up` (no flags after first setup).
|
||
|
|
- **Troubleshooting** — *"failed while getting Management Service public key"* / won't
|
||
|
|
register: confirm `https://netbird.askari.wingu.me` loads in a browser from the device
|
||
|
|
(DNS + TLS + the gRPC routing through Caddy are reachable), the URL is exact, and the
|
||
|
|
terminal is elevated. If a peer shows Disconnected, NAT traversal is falling back to the
|
||
|
|
relay (over 443) — usually transient.
|
||
|
|
- **Removing a device:** `netbird down` then uninstall; revoke its peer in the dashboard
|
||
|
|
(and the setup key if one-off).
|