From dc070bdff89da504f74c7c2d07f9d35ab7cc3ec3 Mon Sep 17 00:00:00 2001
From: timmy <loyangchun@gmail.com>
Date: Sat, 18 Apr 2026 16:29:54 +0800
Subject: [PATCH] docs: add Tailscale kernel-mode iptables-legacy collision
 note

Discovered while deploying NetBird on CT124 (which already runs
Tailscale in kernel mode). Tailscale's ts-input/ts-forward chains
drop all 100.64.0.0/10 traffic not coming from tailscale0, and since
NetBird uses 100.71.0.0/16 (within that CGNAT range), its wt0
traffic gets silently dropped.

Captured:
- Symptom recognition (Connected in status but 100% ping loss)
- Distinguishing when it hits (kernel-mode Tailscale vs userspace)
- Fix: iptables-legacy -I INPUT/FORWARD allow rules on wt0
- Persistence: systemd oneshot + /usr/local/sbin script
  (iptables-persistent doesn't cover the legacy table)
---
 SUMMARY.md             |  1 +
 peer-deployment-ops.md | 53 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/SUMMARY.md b/SUMMARY.md
index d2ca1cc..a2e8512 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -87,6 +87,7 @@ reopen fd 8: permission denied
 | ping RTT 尖峰到 2-4 秒 | 當下 WiFi/ISP 有 bufferbloat | 用 `networkQuality -v` 確認（看 RPM），與 NetBird 無關 |
 | Mac `netbird status` 卡在 `Management: Disconnected, rpc error` | daemon 本身卡死，`netbird up`/`down` 救不回 | `sudo launchctl kickstart -k system/netbird`（服務名是 `netbird` 而非 `io.netbird.client`）；見 [peer-deployment-ops.md](./peer-deployment-ops.md) |
 | LXC CT100 SSH root 密碼被擋（`Permission denied`） | sshd_config 內有 `PermitRootLogin prohibit-password` 比 `yes` 先出現，first-match-wins | 加 `/etc/ssh/sshd_config.d/99-allow-root.conf` 覆蓋；socket activation 不需重啟 sshd |
+| 新 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) |
 
 ## 檔案位置
 
diff --git a/peer-deployment-ops.md b/peer-deployment-ops.md
index ee507da..3c0c1e1 100644
--- a/peer-deployment-ops.md
+++ b/peer-deployment-ops.md
@@ -85,6 +85,59 @@ docker exec netbird netbird status
 
 正常輸出應該有 `Management: Connected`、`Relays: 2/2 Available`、`Peers count: N/N Connected`。
 
+### 同主機已跑 Tailscale kernel-mode 的衝突
+
+**症狀**：NetBird 容器跑起來、status 顯示 `Connected`、`Peers count` 正確，但互 ping 完全不通（100% loss）。
+
+**原因**：Tailscale 的 kernel-mode 會在 `iptables-legacy` 加入兩條防禦規則：
+
+```
+-A ts-input   -s 100.64.0.0/10 ! -i tailscale0 -j DROP
+-A ts-forward -s 100.64.0.0/10 -o tailscale0 -j DROP
+```
+
+NetBird 的 `100.64.0.0/10` 介面 (`wt0`) 送進來的封包在 `ts-input` 被丟棄。iptables 與 iptables-legacy 是**雙軌**，兩邊都要過，NetBird 自己加的 nft 規則不影響 legacy 表。
+
+**辨識：** 主機 `docker ps` 有 `tailscale` 容器，且不是以 `--tun=userspace-networking` 模式運行，`iptables-legacy -L ts-input` 看得到 DROP 規則。CT100/CT101 不會中（它們是 userspace），CT124 會中（kernel）。
+
+**修復**：在 iptables-legacy 的 INPUT/FORWARD 鏈**最前面**插入 allow：
+
+```bash
+iptables-legacy -I INPUT   1 -i wt0 -j ACCEPT
+iptables-legacy -I FORWARD 1 -i wt0 -j ACCEPT
+iptables-legacy -I FORWARD 1 -o wt0 -j ACCEPT
+```
+
+**持久化**（iptables-persistent 只管 nft 那一軌不會存 legacy）— 用 systemd oneshot：
+
+```bash
+cat > /usr/local/sbin/netbird-iptables-legacy-fix.sh << 'EOF'
+#!/bin/sh
+iptables-legacy -C INPUT   -i wt0 -j ACCEPT 2>/dev/null || iptables-legacy -I INPUT   1 -i wt0 -j ACCEPT
+iptables-legacy -C FORWARD -i wt0 -j ACCEPT 2>/dev/null || iptables-legacy -I FORWARD 1 -i wt0 -j ACCEPT
+iptables-legacy -C FORWARD -o wt0 -j ACCEPT 2>/dev/null || iptables-legacy -I FORWARD 1 -o wt0 -j ACCEPT
+EOF
+chmod +x /usr/local/sbin/netbird-iptables-legacy-fix.sh
+
+cat > /etc/systemd/system/netbird-iptables-fix.service << 'EOF'
+[Unit]
+Description=Allow NetBird wt0 traffic past Tailscale iptables-legacy rules
+After=network.target docker.service
+Wants=docker.service
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/netbird-iptables-legacy-fix.sh
+RemainAfterExit=yes
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable --now netbird-iptables-fix.service
+```
+
 ### LXC 容器內的 TUN 問題
 
 **理論上**：NetBird 需要 `/dev/net/tun` 來建立 WireGuard kernel 介面。