# SSH via NetBird：兩種 SSH 不要搞混

NetBird 使用者看到 Dashboard 上的 "SSH Access" 功能時常困惑 — 明明我可以 SSH 到 peer，為何 Dashboard 說 "SSH Access is disabled"？

答案：**Dashboard 的 "SSH Access" 跟你 terminal 打的 `ssh` 指令是兩個不同的東西**。

## 對照表

| | 一般 SSH | NetBird 內建 SSH |
|---|---|---|
| 服務來源 | peer 上跑的 OpenSSH (通常 port 22) | NetBird client daemon 內建 SSH server |
| 觸發方式 | `ssh user@<ip-or-fqdn>` | Dashboard 的 Connect → SSH 按鈕<br>或 CLI `netbird ssh <peer-fqdn>` |
| 認證 | SSH key / 密碼（目標機器管理的） | NetBird mesh 身份（peer 之間 trust） |
| 網路 | 走 NetBird 隧道，但封包內容是標準 SSH | NetBird 自己的通道，不用 port 22 |
| Dashboard policy | 不管（只要 peer 間互通、port 22 可達） | 需要，且要啟用 `SSH Enabled` on peer + SSH policy |
| 預設是否可用 | 是（peer 裝好 OpenSSH 且允許登入就行） | 否（預設 disabled） |

## 實例：從 Mac SSH 到 CT124

```
% ssh 192.168.42.124
Welcome to Ubuntu 24.04.2 LTS (GNU/Linux 6.8.12-16-pve x86_64)
root@CT124:~#
```

這條連線的路徑：

```
Mac ──(NetBird overlay)──▶ CT100 (subnet router)
                            │ masquerade
                            ▼
                         192.168.42.124:22  ←── CT124 原生 OpenSSH
```

走的是 CT124 **本機的 sshd**（由 CT124 管理的 `/etc/ssh/sshd_config`、`~/.ssh/authorized_keys`）。這跟 Dashboard 的 "SSH Access" 功能**完全無關**。

即使 Dashboard 顯示 "SSH Access is disabled"，`ssh 192.168.42.124` 依然能用。

## 什麼時候需要啟用 NetBird 內建 SSH？

只有在這些情境有用：

1. **Dashboard 網頁端直接開 terminal** — 手機 Dashboard 上按 Connect → SSH，瀏覽器內直接操作
2. **不想管 target 機器的 SSH key 分發** — 信任 NetBird peer 身份就好
3. **目標機器的 OpenSSH 有問題**（但這種時候 CT 通常更多事）
4. **想走 gRPC 通道而非 port 22**（少見，特殊合規需求）

家用自架環境**多半不需要**。已經有：
- Peer 上正常的 OpenSSH
- `~/.ssh/authorized_keys` 裡的 key
- 直接 `ssh` 或 `ssh <peer-fqdn>.netbird.selfhosted` 就行

## 如果真的要啟用

### 在 peer 上

編輯 `/etc/netbird/config.json` 或啟動時加 `--enable-ssh`，然後重啟 daemon。對 Docker 部署的客戶端，可以在 `docker-compose.yml` 加 env var `NB_ENABLE_SSH=true`，然後 `docker compose up -d` 重建。

### 在 Dashboard

1. 點 Peer 那一列的 ... → Edit → 打開 **SSH**
2. Access Control → Policies → **Add Policy**：
   - Name: `ssh-access`
   - Source: `personal`（允許誰 SSH）
   - Destination: 目標 group（例 `servers`）
   - Protocol: **SSH** (或 TCP + port 22，取決於 NetBird SSH server 監聽的 port — 內建 SSH server 跑在固定 port `44338`)
   - Enabled

### 驗證

```bash
netbird ssh ct100.netbird.selfhosted
# 或 Dashboard 上 Peer 旁邊的 Connect → SSH 按鈕變亮
```

## 小結

- **Dashboard "SSH Access" disabled 跟你 SSH 得不得進去沒關係** — 前者是 NetBird 自己的通道功能，後者是你一般用的 SSH
- 家用環境通常**不需要啟用** NetBird SSH，用原生 OpenSSH 就夠
- 有需要再開，兩種不衝突，可以並存

## 實務應用：用 NetBird 取代 SSH 源 IP 白名單

### 情境

遠端 VM 的 SSH (port 22) 被 iptables 白名單限制只有特定源 IP 能進：

```
ACCEPT  tailscale0 *   0.0.0.0/0  tcp dpt:22   /* via Tailscale */
ACCEPT  *  *  211.23.141.206  tcp dpt:22       /* specific IP */
ACCEPT  *  *  125.229.110.50  tcp dpt:22       /* HiNet WAN */
DROP    *  *  0.0.0.0/0       tcp dpt:22       /* drop everything else */
```

你的 Mac 從咖啡店連不到，因為當下 ISP 出口 IP 不在白名單。

### 兩個解法對比

**A. 暫時跳板**（不改遠端 VM）：

```
ssh -J root@<whitelisted-peer>.netbird.selfhosted root@141.11.93.252
```

Mac → NetBird → 家裡有白名單的 peer → 借它的公網 IP → VM。原生 OpenSSH 的 `ProxyJump`，跟 NetBird 的 SSH Access 功能無關。

**B. 把 VM 加進 NetBird mesh**（長期治本）：

1. 在 VM 部署 NetBird client 容器（見 `peer-deployment-ops.md`）
2. 在 VM 的 iptables 加一條鏡像 tailscale0 的規則：
   ```
   iptables -I INPUT <位置> -i wt0 -p tcp --dport 22 -j ACCEPT \
     -m comment --comment "Allow SSH from NetBird interface"
   ```
   插入點：在「DROP all other SSH」那條之前
3. 之後 Mac / iPhone / 任何 NetBird peer 都能直接 SSH 到 VM，**不用再跳板**

### 本部署的實例（`virmach-lax`，2026-04-18）

`141.11.93.252`（VirMach VPS，Los Angeles）原本 SSH port 22 只認 `tailscale0` + `211.23.141.206` + HiNet。Mac 從另一個 ISP 連不到。採用方案 B：

- NetBird IP `100.71.121.88`，FQDN `virmach-lax.netbird.selfhosted`
- 加 `iptables -I INPUT <位置> -i wt0 -p tcp --dport 22 -j ACCEPT`
- 踩到同一個 **Tailscale kernel-mode iptables-legacy 衝突**（見 `peer-deployment-ops.md`），加 systemd oneshot 解決
- `auto_groups=[servers]` 直接進正確 group，policy 自動套用

結果：Mac 直接 `ssh root@virmach-lax.netbird.selfhosted` 即可進入，RTT ~175ms（走 Relay，跨區 P2P 不易打通但不影響 SSH）。

### 配置策略建議

遠端 VM 的 SSH 白名單**保留 NetBird interface 這條**、**砍掉固定 IP 白名單**：

```diff
  ACCEPT  tailscale0 *   tcp dpt:22
+ ACCEPT  wt0        *   tcp dpt:22
- ACCEPT  *  *  211.23.141.206  tcp dpt:22   ← 砍掉
- ACCEPT  *  *  125.229.110.50  tcp dpt:22   ← 砍掉
  DROP    *  *  0.0.0.0/0       tcp dpt:22
```

好處：
- 不用再維護公網 IP 白名單（HiNet 動態 IP 變了就斷線）
- SSH 強制走 overlay 網路，減少暴露面
- 新加入的 NetBird peer（增加新裝置）自動取得存取權，不用改防火牆