docs: clarify NetBird built-in SSH vs regular SSH

Dashboard's 'SSH Access is disabled' warning confuses new users who can clearly ssh into peers just fine. These are two different systems: Dashboard's SSH Access is NetBird's own in-daemon SSH tunnel server (accessed via Dashboard Connect button or 'netbird ssh'), while the regular ssh command uses the target machine's OpenSSH running on port 22 and has nothing to do with the Dashboard SSH toggle. Home-lab use cases rarely need the NetBird built-in SSH — regular OpenSSH over the NetBird overlay is sufficient. Doc explains when you would actually want it (browser-based terminal from Dashboard, credential offloading to NetBird identity, etc) and how to enable if needed.
2026-04-18 22:43:34 +08:00
parent dadb455184
commit b6138095f0
3 changed files with 84 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@
 | [peer-deployment-ops.md](./peer-deployment-ops.md) | 在 LXC 用 Docker 部署客戶端、改名、Mac daemon 重啟 |
 | [groups-and-policies.md](./groups-and-policies.md) | Groups 與 Access Control Policies 概念、設計、API 操作 |
 | [network-routes.md](./network-routes.md) | Subnet Router：讓遠端 peer 存取 LAN 上沒裝 NetBird 的裝置 |
+| [ssh-access.md](./ssh-access.md) | 一般 SSH vs NetBird 內建 SSH — 常見混淆點釐清 |
 | [SUMMARY.md](./SUMMARY.md) | 部署摘要與疑難排解記錄 |

 ## 快速開始
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -90,6 +90,7 @@ reopen fd 8: permission denied
 | 新 peer `netbird status` 顯示 Connected 但互 ping 都不通 | 主機同時跑 Tailscale kernel-mode，`iptables-legacy ts-input` 把 `100.64.0.0/10` 非 tailscale0 封包全 drop，NetBird `100.71.0.0/16` 中彈 | `iptables-legacy -I INPUT 1 -i wt0 -j ACCEPT` + FORWARD 同理；systemd 持久化；詳見 [peer-deployment-ops.md](./peer-deployment-ops.md) |
 | 加 subnet route 後部分裝置拿不到路由（`Networks: -`、`Status: Connecting`） | 既有 NetBird daemon 不會自動重新套用 route，卡在舊 state | 各裝置重連 daemon：macOS `launchctl kickstart`、iOS App Disconnect→Connect、Docker `compose restart`；見 [network-routes.md](./network-routes.md) |
 | iPhone RTSP app 連不到 LAN 攝影機（Safari 打 HTTP 可以） | 某些 iOS app 不走系統 VPN 路由 | 換支援 VPN 的 app（VLC 等），或改用 NetBird FQDN |
+| Dashboard 顯示 "SSH Access is disabled" 但 `ssh` 指令照通 | Dashboard 的 "SSH Access" 是 NetBird 內建 SSH 通道，不等於目標機器的 OpenSSH | 兩種 SSH 是不同東西，不用理會那個提示；見 [ssh-access.md](./ssh-access.md) |

 ## 檔案位置

@@ -106,7 +107,8 @@ reopen fd 8: permission denied
 ├── client-troubleshooting.md         ← 客戶端 Force Relay / bufferbloat 排錯
 ├── peer-deployment-ops.md            ← Docker 部署客戶端、改名、Mac daemon 重啟
 ├── groups-and-policies.md            ← Groups 與 Access Control 設計與操作
-└── network-routes.md                 ← Subnet Router 讓 peer 存取 LAN 非 NetBird 裝置
+├── network-routes.md                 ← Subnet Router 讓 peer 存取 LAN 非 NetBird 裝置
+└── ssh-access.md                     ← 一般 SSH vs NetBird 內建 SSH 的差別
 ```

 ### 遠端伺服器（192.168.42.127:/opt/netbird/）
--- a/ssh-access.md
+++ b/ssh-access.md
@@ -0,0 +1,80 @@
+# 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 就夠
+- 有需要再開，兩種不衝突，可以並存