Files

timmy b6138095f0 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

3.3 KiB

Raw Blame History

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 按鈕或 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？

只有在這些情境有用：

Dashboard 網頁端直接開 terminal — 手機 Dashboard 上按 Connect → SSH，瀏覽器內直接操作
不想管 target 機器的 SSH key 分發 — 信任 NetBird peer 身份就好
目標機器的 OpenSSH 有問題（但這種時候 CT 通常更多事）
想走 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

點 Peer 那一列的 ... → Edit → 打開 SSH
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

驗證

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

小結

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

3.3 KiB Raw Blame History Unescape Escape