# 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).