ROAMSWITCH SERVER 1.1.0+ · 最後更新：2026-09-18

RoamSwitch伺服器版操作手冊

云 VPS（AWS、GCP、Azure、Linode、DigitalOcean）、裸机数据中心和容器主机的官方安装、部署和操作参考。

1. 概述及要求

RoamSwitch 伺服器版是一個 無頭（零 GUI 依賴）自主防禦和完整性監控套件 ，專為暴露於公共互聯網的 Linux 伺服器而設計。

與基於 Wi-Fi 狀態動態切換設定檔的用戶端版本不同，伺服器版本強制執行 入站預設丟棄、關鍵路徑檔案完整性監控 (FIM)、預防性核心 LPE 緩解（Frag Gap）、eBPF 執行時威脅偵測、SSH 鎖定預防和自動多通道緊急警報（Telegram / LINE / Webhook）__X、SSH 鎖定。

零遙測架構
RoamSwitch 將零診斷遙測、主機 IP 元資料、檔案雜湊或系統日誌傳輸到外部伺服器。守護程式二進位檔案中不存在外部網路庫，從而保證了完全的本地機密性。

系統需求

  • 支援的發行版：Ubuntu 22.04 / 24.04 LTS、Debian 12+、AlmaLinux / Rocky Linux / RHEL 9+、Fedora 39+、openSUSE Leap 15.5+、Raspberry Pi OS（64 位元）
  • 架構：x86_64 (amd64) 或 aarch64 (arm64)
  • Kernel：Linux 5.10+（建議nftables、cgroups v2、eBPF BTF）
  • Footprint：20–30 MB 駐留內存，空閒/正常工作負載期間 <0.1% CPU

2. 安裝步驟

使用官方簽署的儲存庫可確保透過標準系統套件管理器自動解決相依性並進行無縫更新。

2.1 APT（Ubuntu / Debian / Raspberry Pi 作業系統）

# 1. 註冊儲存庫簽署金鑰
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. 新增儲存庫
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/roamswitch.list

# 3. 安裝
sudo apt update && sudo apt install roamswitch-server

2.2 DNF / RPM（Fedora / RHEL / AlmaLinux / Rocky Linux）

# 1. 匯入 GPG 金鑰
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. 新增儲存庫設定檔
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. 安裝
sudo dnf install roamswitch-server

2.3 openSUSE（zypper）

sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch
sudo zypper addrepo https://lafine.net/rpm/opensuse/roamswitch.repo
sudo zypper refresh && sudo zypper install roamswitch-server
包互斥（衝突）
客戶端版本 (roamswitch) 和伺服器版本 (roamswitch-server) 聲明相互的套件衝突。在無頭伺服器環境中始終選擇 roamswitch-server。

3. 初始設定和服務驗證

3.1 服務狀態

安裝後，roamswitch-server.service 立即啟動並在系統引導時啟用。

sudo systemctl status roamswitch-server.service

3.2 互動式設定嚮導

使用以下指令啟動互動式設定精靈，以互動方式設定連接埠、維護來源 IP、通知管道與圍堵操作（按 Enter 採用各項預設值）。

sudo roamswitch server setup
  1. 連接埠：分別以逗號分隔輸入 SSH 維護連接埠（預設 22）與公開服務連接埠（預設 80,443）。
  2. 維護來源 IP：指定 SSH 跳板機或監控來源的 IP/CIDR（例如 203.0.113.50/32）；留空則允許來自任意 IP 的 SSH。
  3. 通知管道設定：分別啟用 Telegram Bot、LINE Messaging API、通用 Webhook（Slack / Discord / Teams）。
  4. eBPF 重大事件時的回應：選擇 isolate（隔離主機）/ freeze（凍結該行程）/ alert_only（僅通知）。儲存後會確認發送測試通知並重新啟動服務。
  5. 核心 CVE 資料自動更新（預設 n）：選擇是否讓容器隔離稽核所用的核心 CVE 資料庫每天一次從 lafine.net 匿名取得（不含查詢字串、Cookie 或識別性標頭）。即使保持停用，稽核本身仍會依內建基準運作。這是 Server Edition 零網路程式碼原則中唯一的例外，預設為停用（需手動開啟）。
  6. File Scan Guard 設定：設定是否為郵件中繼、共用資料夾、上傳目標啟用病毒掃描（§13）及目標目錄。可選功能，預設關閉。
  7. Resource Guard 設定：設定是否啟用偵測網路公開服務持續 RSS 增長（記憶體洩漏/DoS）或當機迴圈的資源耗盡防護。
  8. 常駐核心防護說明：顯示無需透過精靈、始終生效的核心防護功能清單，如入站預設拒絕、FIM、eBPF 整合等（無需輸入）。
  9. 調查代理協作（investigation）設定：設定是否將 eBPF 重大事件，或關鍵路徑 FIM／相依鎖定檔篡改偵測（均為僅通知判定時）的初步調查自動委託給外部 AI 代理 CLI（Claude Code / agy / Codex CLI / OpenCode，或自訂指令）（§10.1）。預設關閉。
Telegram Chat ID 注意事項
超級群組的 Chat ID 是以 -100 開頭的負數（例如 -1001234567890）。可在 curl -s "https://api.telegram.org/bot<token>/getUpdates" 回應中的 "chat":{"id":...} 欄位確認正確的值。

3.3 30項伺服器安全審計

sudo roamswitch status --server

對防火牆規則、Frag Gap 緩解、Yama LSM 限制、權限和 Docker 連接埠暴露執行即時 30 項檢查審核，產生 0-100 的安全評分和等級（S 到 C）。

4. 防火牆和連接埠規則

設定檔 /etc/roamswitch/server.conf 為保護機密資訊，強制要求權限為 0600（僅 root 可讀寫）。格式為扁平的 key=value，形如 [network] 的區段標題列會被忽略。

# --- 防火牆 ---
ssh_ports=22                     # SSH 管理連接埠（緊急隔離時也保留）
allowed_ports=80,443             # 公開服務連接埠
whitelist_ips=203.0.113.10/32    # 維護來源 IP / CIDR（留空 = 全部允許，舊名 admin_source_ips 亦可）
protect_docker_ports=true        # DOCKER-USER 保護（阻止容器繞過防火牆）
preserve_ssh_on_isolation=true   # 緊急隔離時也保留 SSH 管理通道（設為 false 則完全阻斷）

# --- eBPF 執行時防護 ---
action_on_critical=isolate       # isolate | freeze（SIGSTOP+網路阻斷） | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Egress / C2 阻擋與 DNS 黑洞 ---
egress_ip_blocklist_enabled=true # 預設 true。情報來源尚未填入時無害（不會阻擋任何內容）
dns_sinkhole_enabled=false       # 預設 false（避免破壞內部 DNS/split-horizon 環境）
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- 容器隔離 CVE 資料（選用啟用） ---
cve_kernel_map_updates_enabled=false # 預設 false。唯一的外部通訊例外（每天一次‧匿名）

# --- 通知 ---
telegram_enabled=false
telegram_bot_token=
telegram_chat_id=
line_enabled=false
webhook_enabled=false
webhook_url=

# --- 系統 ---
language=ja
fim_check_interval_secs=300      # 舊名 scan_interval 亦可

若直接編輯了設定，需重新啟動服務才會生效（roamswitch-server 不支援 reload）：

sudo roamswitch server restart

4.1 依嚴重程度設定政策（guard.yaml，選用）

若僅靠 action_on_critical 無法滿足更精細的控制需求，可建立 /etc/roamswitch/guard.yaml（發布範本位於 /etc/roamswitch/guard.yaml.example）。若該檔案不存在，會依 server.conf 中的 action_on_critical 自動合成等效政策，不影響現有運作。

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # 同一行程再次發生時自動升級為主機隔離
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # 主機隔離後，若在此秒數內無 ack 則自動恢復（0 為停用）

安全計時器：主機隔離（Air-Gap）觸發後，管理員在排查原因後使用以下指令進行確認回應（ack）。若在 safety_timer_secs 內未收到回應，RoamSwitch 會自動解除隔離，以避免誤判導致伺服器無限期與網路斷線。

sudo roamswitch server ack

4.2 Egress / C2 阻擋與 DNS 黑洞

設定 egress_ip_blocklist_enabled=true（預設）後，會透過 nftables 阻擋對已知惡意 IP 的外發連線。優先使用 /var/lib/roamswitch/threatfeed/malicious_ips.txt（由更新機制維護）的情報來源，若不存在則回退至套件內建的空種子檔（/usr/share/roamswitch/threatfeed/），因此在情報來源尚未填入資料前，預設值 true 不會阻擋任何流量。

將 dns_sinkhole_enabled=true 設為啟用後，會強制透過過濾型 DNS 解析器（Quad9 / Cloudflare / AdGuard / CleanBrowsing）解析網域，阻擋對已知惡意網域的解析。因可能破壞內部 DNS 或 split-horizon 環境，預設值為 false。

4.3 入站連接埠掃描偵測防護

透過將 nftables 日誌規則與 journald 進行比對，偵測在短時間內連線了大量不同連接埠的來源 IP（預設啟用）。高置信度的掃描來源可在一定時間內自動封鎖。與 RoamSwitch Sensor 一起使用時（與 §10.1 是不同的功能——已配對 Sensor 的全連接埠稽核探測會作為誤判對策被排除），Sensor 一側的 IP 會自動排除在外。

# --- 入站連接埠掃描偵測（預設啟用） ---
port_scan_detect_enabled=true              # false 表示停用
port_scan_detect_min_distinct_ports=15     # 連線到不少於此數量的不同連接埠時判定為掃描
port_scan_detect_window_secs=300           # 判定的統計視窗（秒）
port_scan_block_enabled=true               # 自動封鎖偵測到的掃描來源 IP
port_scan_block_duration_secs=600          # 自動封鎖的持續時間（秒）

可透過 roamswitch port-scan 指令查看偵測歷史。

5. SSH 鎖定預防故障保護

由於防火牆配置錯誤而導致的意外鎖定是無法容忍的操作災難。 RoamSwitch 伺服器版包含多層保護措施：

  • 已建立/相關無條件透過：在規則重新載入期間，活動會話永遠不會被刪除。
  • Air-Gap 上的 SSH 保留：即使在敵對攻擊遏制下，preserve_ssh_on_isolation = true 仍保持來自授權 CIDR 的管理存取權以進行調查。
  • Atomic nftables 載入並回滾：規則語法錯誤立即觸發零停機回滾到先前已驗證的規則集。

6.容器保護（Docker/Podman）

Docker 的預設行為會建立繞過標準主機防火牆的自訂 iptables 規則，將容器連接埠（例如 -p 8080:8080）直接暴露到網際網路。

當 protect_docker_ports=true（預設）時，RoamSwitch 會在 DOCKER-USER 鏈的最前面插入檢查規則，使發往容器的流量也遵循 allowed_ports 與 whitelist_ips 政策，確實防止開發用資料庫容器等被意外暴露到外部。

此外，監控 docker events 的即時防護會在以 --privileged 啟動的容器或掛載了 /var/run/docker.sock 的容器（存在容器逃逸風險）啟動後立即偵測並發出通知。無需設定、始終啟用，偵測僅用於通知（不會自動阻斷）。

7. 關鍵路徑檔案完整性監控（FIM）

使用 SHA-256 雜湊監視 150 多個基本二進位檔案（/bin/login、/usr/bin/sudo、/usr/sbin/sshd）、驗證設定（/etc/shadow、/etc/pam.d/）和 systemd 單元。

7.1 手動哈希驗證

sudo roamswitch fim verify

7.2 事件驅動偵測（即時）

受監控檔案透過 fanotify（FAN_CLASS_NOTIF，寫入完成事件）被逐一監視，無需等待下一次週期性掃描，竄改發生的瞬間即會重新驗證雜湊。週期性掃描（預設 fim_check_interval_secs=300 秒間隔）仍會作為漏偵測事件的後備保障並存。

7.3 作業系統更新時自動基線同步

在 Debian/Ubuntu 上，安裝套件時會自動設定 /etc/apt/apt.conf.d/99roamswitch-fim 的 DPkg::Post-Invoke 掛鉤。在 Fedora/RHEL/Rocky/AlmaLinux/openSUSE 上，監控 /var/lib/rpm 的 systemd.path 單元（roamswitch-fim-update.path）承擔相同職責。

在 Debian/Ubuntu 上，/etc/apt/apt.conf.d/99roamswitch-fim 附加一個 DPkg::Post-Invoke 掛鉤。透過 sudo apt upgrade 進行的合法軟體包更新會自動刷新 FIM 基線，從而消除誤報警報。

sudo roamswitch fim update

8. eBPF 運行時防護和 Falco 集成

掛鉤內核空間 eBPF 事件 (Falco / Tetragon) 以偵測 Frag Gap 核心權限升級、容器逃逸和未經授權的反向 shell。

8.1 抗膨脹架構

傳統安全代理程式遭受嚴重的系統日誌爆炸和磁碟磨損。 RoamSwitch 透過專用 UNIX 域套接字 (/run/roamswitch/events.sock) 直接連接到 Falco：

  • 捆綁的 /etc/falco/config.d/99-roamswitch-optimized.yaml 將事件直接串流到守護程式中，磁碟 I/O 為零。
  • /etc/logrotate.d/roamswitch-falco 確保任何後備檔案輸出的每日乾淨輪替。

8.2 自主收容

一旦偵測到嚴重攻擊，RoamSwitch 會立即發出 SIGSTOP 來凍結違規進程 PID 並套用 nftables 氣隙隔離。

9. 緊急警報（Telegram / LINE / Webhook）

當發生連接埠異常、FIM 篡改或 eBPF 遏制事件時，立即向外部通知通道發送警報：

[notifications]
language = ja
# Telegram：Bot Token 與 Chat ID
telegram_bot_token = "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
telegram_chat_id = "-1001234567890"

# LINE：Messaging API 頻道存取權杖與使用者 ID
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# 通用 Webhook（Slack、Discord、Teams、自建監控平台）
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

即使未設定這些外部通知管道，已傳送的通知也會在本機保留最近1週。可透過 roamswitch notifications 查看。

10.AI代理/MCP整合（模型上下文協定）

RoamSwitch 伺服器版包含 roamswitch-mcp，可讓 AI 代理程式（Claude、Gemini、Cursor）監控基礎設施健康狀況和狀態。

只讀安全保證
為了防止即時注入攻擊損害基礎設施，MCP 介面嚴格是唯讀的。 AI 代理無法透過 MCP 開啟連接埠、取消隔離或變更安全性配置。修復需要經過身份驗證的本地 TTY shell 存取權。

配置範例（`claude_desktop_config.json`）

{
  "mcpServers": {
    "roamswitch": {
      "command": "/usr/bin/roamswitch-mcp",
      "args": []
    }
  }
}

10.1 調查代理協作（investigation，將初步自動調查委託給 AI 代理）

§10 的 roamswitch-mcp 面向「人類透過 AI 用戶端發起的查詢」，而investigation 協作是另一種機制：由守護行程自身在偵測到事件時自主啟動外部 AI 代理 CLI。其對象是被判定為僅通知（未觸發自動隔離或行程凍結）的 eBPF 重大事件，以及關鍵路徑 FIM、相依鎖定檔篡改偵測。啟用後，守護行程會先產生本機啟發式一次判定報告（誤判可能性、依據、下一步調查建議），隨後附帶該報告以子行程方式啟動已設定的 AI 代理 CLI，委託其進行進一步調查與總結。預設關閉。

# 追加到 /etc/roamswitch/guard.yaml（與 server.conf 是不同的檔案）
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | 任意自訂指令
  args: ["-p"]                      # 提示詞會自動作為末尾參數附加
  timeout_secs: 180

同樣內容也可在 sudo roamswitch server setup 的互動式精靈（§3.2 最後一步）中設定。可選擇 Claude Code（claude -p）/ agy（agy -p --dangerously-skip-permissions）/ Codex CLI（codex exec）/ OpenCode（opencode run）預設，或任意自訂指令。再次執行時會根據已儲存的設定自動選取對應預設。

關於提示詞注入的注意事項
investigation 協作會將偵測事件的詳細資訊（行程名稱、檔案路徑等攻擊者可能部分控制的字串）作為提示詞的一部分傳遞給 AI 代理。尤其是將工具設定為以跳過權限確認的模式（例如 --dangerously-skip-permissions）執行，會提高惡意輸入導致代理執行非預期操作的風險。選擇 agy 時精靈會顯示此警告。在存在不可信日誌輸入路徑的環境中，建議使用不跳過權限確認的工具設定。

在網路中斷期間（如 Air-Gap 觸發時等，相當於 isolate_host_all 的狀態）不會呼叫 investigation 協作。

11. CLI 指令備忘單

命令 特權 描述
sudo roamswitch status --server root 顯示 30 項伺服器狀態評分並檢查細分
sudo roamswitch ports root 審計開放的監聽埠和綁定的進程
sudo roamswitch fim verify root 驗證關鍵路徑系統檔案的 SHA-256 完整性
roamswitch notifications 使用者 顯示過去1週的通知歷史（所有已傳送的警示）
sudo roamswitch server setup root 啟動互動式初始設定精靈
sudo roamswitch fim update root 刷新 FIM SHA-256 基線資料庫
sudo roamswitch server config set <key> <value> root 修改並儲存單一設定金鑰（清單見 §4）
sudo roamswitch airgap enable / disable root 手動觸發/解除 Air-Gap 緊急切斷
sudo roamswitch emergency-restore 根 解除全部 eBPF/防火牆緊急隔離，恢復至初始基準
roamswitch port-scan 一般使用者 顯示入站連接埠掃描偵測防護（§4.3）的偵測歷史（來源 IP、是否自動封鎖及封鎖時長）
roamswitch sensor [key|list|pair|unpair|request-audit|results] 一般使用者/root 與 RoamSwitch Sensor 之間基於配對碼的相互信任。pair --addr <IP> --code <配對碼> 完成配對，request-audit 請求主動弱點稽核（透過 results 取得結果）。需要 sensor_pairing_enabled: true（預設關閉）。詳情請參閱 Sensor 維運手冊

12. 故障排除和常見問題解答

Q1. RoamSwitch 會意外地斷開我的 SSH 會話嗎？

不會。RoamSwitch 無條件允許已建立的 ESTABLISHED/RELATED 連線狀態以及 ssh_ports（預設 22）。即使因嚴重攻擊觸發 Air-Gap 緊急隔離，preserve_ssh_on_isolation=true（預設）也會保留管理連線。

Q2。如果不小心被鎖定，如何重新獲得存取權限？

透過雲端服務商的 Web 管理主控台（VNC/序列主控台）登入，執行 sudo roamswitch emergency-restore 解除緊急隔離，或執行 sudo systemctl stop roamswitch-server 停止服務。

Q3。如何為新新增的 Web 服務（例如 Nginx）公開連接埠？

執行 sudo roamswitch server config set allowed_ports 80,443,3000（或直接編輯 /etc/roamswitch/server.conf），然後執行 sudo roamswitch server restart。

13. File Scan Guard（保護郵件中繼、共享資料夾與上傳目的地）

僅當此主機存在用於保存要交給他人的檔案的目錄（如郵件中繼、Samba/NFS 共享、檔案上傳目的地）時才需要關注的選用功能。內建 YARA 引擎無需外部依賴即可持續掃描 clamav_scan_dirs，設定 clamav_enabled=true 後還會加入 ClamAV 作為第二重判斷。確認的威脅會自動隔離至 /var/lib/roamswitch/quarantine，並通知維運人員。

# --- File Scan Guard（ClamAV，選用啟用） ---
# 內建 YARA 引擎始終無條件掃描 clamav_scan_dirs。
clamav_enabled=false             # 設為 true 可啟用 clamdscan 進行額外檢查
clamav_scan_dirs=                # 掃描目標的絕對路徑（以逗號分隔）
clamav_scan_interval_secs=86400  # 掃描間隔（秒，最小 3600）
clamav_freshclam_interval_secs=7200  # 特徵庫自動更新間隔（秒，最小 1800）

也可透過互動式精靈 sudo roamswitch server setup 進行設定，並可透過 get_file_scan_guard_status MCP 工具查看設定與隔離狀態。

14. Log Audit（記錄模式異常偵測與通知）

透過定期掃描 journalctl 將記錄訊息範本化，偵測新模式（前所未見的記錄形態）與頻率異常（統計激增，Z-score > 3.0）。由於不需要額外守護行程或外部相依性，這是一種輕量機制，預設已啟用。偵測到異常時會透過與 File Scan Guard 及 FIM 相同的通知管道（Telegram / LINE / Webhook）發送通知。記錄中可能出現的 API 金鑰或權杖，會在寫入通知內文之前自動遮罩。

# --- Log Audit（預設啟用） ---
log_audit_enabled=true           # 設為 false 可停用
log_audit_interval_secs=1800     # 掃描間隔（秒，最小 300）

也可透過互動式精靈 sudo roamswitch server setup 進行設定，並可透過 roamswitch audit-logs CLI 指令或 audit_security_logs MCP 工具查看最新的偵測結果。

← 伺服器版白皮書 前往 Linux 版安裝頁面 →