0. 手冊導覽

這份手冊依常見的部署情境,一步一步說明怎麼設定 rradius。每個情境都附一組可以直接啟動的設定檔、資料表和 Lua 腳本,放在 rradius-server/examples/scenarios/。所有欄位的完整說明在參考文件 docs/usage.md,手冊只講情境需要的部分,並標出對應的章節。

範例都有自動測試(rradius-server/tests/scenarios_test.rs):測試會照手冊的方式啟動每個情境,送出登入、計費、TACACS+ 和 CoA 請求,確認結果和手冊寫的一樣。所以範例改壞了,測試會失敗。測試做不到的部分(實體設備、真的漫遊聯盟、外部的服務),各章的「上線前」會寫明沒有測過什麼。

先讀這兩章

章內容
1. 基本概念rradius 怎麼處理一個請求、設定檔的結構、資料放在哪裡、怎麼測試
2. 快速開始單機、帳號存在資料表,十分鐘內收到第一個 Access-Accept

我要做什麼,看哪一章

我要…章
讓員工用帳號密碼或憑證連公司 Wi-Fi3,進階的撤銷和漫遊在 15
讓不會 802.1X 的設備連 Wi-Fi,但每人密碼不同12
讓裝了自家 SIM 卡的設備連 Wi-Fi13
讓印表機、IP 電話這類設備上有線網路4
讓 VPN 用公司的目錄登入,或加上驗證碼5
管理誰能登入路由器、能下哪些指令6,改用 TLS 在 16
經營寬頻:方案、同時上線數、踢人、計費7
任何一台停機都不中斷服務8
把別的單位的帳號轉給他們自己的伺服器9,加入漫遊聯盟在 11
NAS 在網際網路另一頭或 NAT 後面10
管理幾百台常變動的 NAS14
帳號已經在別的系統裡,不想複製目錄(LDAP/AD)看 5,HTTP API 看 18
從舊的認證系統搬過來,不想讓大家重設密碼17
上線之後的日常工作19
出了問題,從現象找原因20

依情境

章情境用到的功能範例目錄
3. 企業 Wi-Fi802.1X:公司電腦用憑證,員工手機用帳號密碼,依群組分 VLANEAP-TLS、PEAP、certificate_query、動態 VLANenterprise-wifi/
4. 有線網路 MAC 認證印表機、IP 電話這類不會 802.1X 的設備Lua 腳本、網段 clientwired-mab/
5. 遠端存取VPN 用公司目錄(LDAP/AD)登入,跳板機加 TOTP 驗證碼LDAP、群組、具名串接、Access-Challengeremote-access/
6. 網路設備管理管理員登入路由器,依角色限制指令並記錄TACACS+ 認證、授權、計費、授權群組device-admin/
7. 寬頻業者PPPoE/IPoE:方案速率、同時上線數、帳務系統踢人all_accept、計費、CoA 轉送、計費暫存broadband/
8. 高可用叢集三個節點,任一台停掉都能繼續服務hiqlite 叢集、WireGuard、migrationha-cluster/
9. 依 realm 轉送合作單位或總部的帳號轉給對方的伺服器[proxy]、容錯、RadSec 上游realm-proxy/
10. RadSecNAS 經過不信任的網路或在 NAT 後面;踢人的請求走 NAS 自己的連線[radius.tls]、tls_name、CoA 走 RadSec、coa_senderradsec/
11. 漫遊聯盟eduroam 這一類:來訪者轉給他的學校,自己的人從聯盟送回來[proxy.discovery](DNS)、負載平衡和比重、主動檢查、轉送計費的暫存roaming/
12. 每人一把 Wi-Fi 密碼同一個 WPA2-PSK 的 SSID,每人自己的密碼,依人分 VLAN[radius.dpsk]、dpsk-seal、依 MAC 回覆密碼psk-wifi/
13. 用 SIM 卡登入 Wi-Fi自己發的 USIM 卡,不用憑證也沒有密碼EAP-AKA’、aka-seal、主金鑰、頻率限制sim-wifi/
14. 幾百台分店的 NASNAS 寫在資料表,新增一台不必改設定檔[radius.dynamic_clients]、client 指令branch-nas/
15. 憑證的撤銷和快速重新連線遺失的筆電要撤銷;設備漫遊時不要每次重做握手CRL、OCSP、resumption_ms、shared_ticketswifi-certs/
16. TACACS+ over TLS設備管理從共用密碼移轉到 TLS 1.3 和設備憑證[tacacs.tls]、tls_name、tls_onlydevice-admin-tls/
17. 從舊系統搬帳號舊的密碼雜湊原樣搬過來,之後逐步換成新格式各種密碼格式、名稱正規化、[accounts]migrate-users/
18. 帳號在別的系統每次登入用 HTTPS 問會員系統的 API[lua.http]、http_request、verifies_passwordexternal-api/

上線之後

章內容
19. 日常維運帳號和設定的變更、重新載入、更換密碼和金鑰、監控指標、過載、計費暫存、升級、備份
20. 依症狀排查沒有回應、被拒絕、很慢、計費不見、TLS 連不上、啟動失敗,各從哪裡看起

範例的共同約定

  • 設定檔裡的相對路徑以設定檔所在目錄為準, 所以每個情境都能直接在 repo 裡啟動:

    cd rradius-server
    cargo build --release
    ./target/release/rradius-server --config examples/scenarios/quick-start/rradius.toml
    
  • 用發行檔時, 解開 rradius-<版本>-<平台>.tar.gz,裡面的目錄結構和 repo 相同。進到其中的 rradius-server/ 目錄,把各章的 ./target/release/rradius-server 換成 ../bin/rradius-server,其他指令和路徑都一樣,也不用 cargo build:

    cd rradius-0.1.0-linux-x86_64/rradius-server
    ../bin/rradius-server --config examples/scenarios/quick-start/rradius.toml
    
  • 有些情境要先執行一個腳本才能啟動, 因為憑證和金鑰不該放在 repo 裡:

    腳本情境產生什麼
    make-certs.shenterprise-wifi/、radsec/、roaming/、device-admin-tls/certs/ 裡示範用的 CA 和憑證
    setup.shpsk-wifi/、sim-wifi/、wifi-certs/金鑰檔(權限 0600),以及用它封存的示範資料或憑證

    這些都只供測試。setup.sh 不會覆蓋已經有的檔案;要從頭再來,停止伺服器後刪掉它產生的檔案和 data/。

  • 密碼檔(*.secret)都是示範值, 內容寫明 change-me。正式環境一定要換掉,見第 19 章。

  • 示範資料放在 migrations/2_demo_*.sql(搬帳號的情境是 2_imported_users.sql),結構放在 1_schema.sql。正式環境請刪掉示範資料的檔案,或在第一次啟動前換成自己的資料。檔案一旦套用就不能再改,見第 1 章。

  • 埠號用標準值(1812、1813、2083、3799、49、300)。在同一台機器上同時啟動兩個情境會衝突,一次啟動一個,或改埠。

  • 啟動後產生的 data/、spool/、certs/ 和金鑰檔不進 git。 要從頭再來一次,停止伺服器後刪掉 data/。

  • NAS 的位址都是示範用的私有網段。 本機測試時要把 client 的 address 改成 127.0.0.1(快速開始已經是),否則請求會被當成不認得的來源而沒有回應。

  • 幾個情境共用檔案: 多數情境的計費用 quick-start/accounting.lua,device-admin-tls/ 用 device-admin/ 的腳本和資料表。複製情境到別處時,把它引用的目錄一起帶走。

使用 Hugo 建立
主題 Stack 由 Jimmy 設計