timmy
b6138095f0
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.
81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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 就夠
|
||
- 有需要再開，兩種不衝突，可以並存
|