netbird-selfhosted/ssh-access.md

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？

只有在這些情境有用：

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

驗證

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 白名單：

  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（增加新裝置）自動取得存取權，不用改防火牆