OpenH323 Gatekeeper - The GNU Gatekeeper 使用手冊

作者： 黃志偉 <cwhuang@linux.org.tw>

v2.0.2, 27 November 2002

這是 OpenH323 Gatekeeper - The GNU Gatekeeper 的中文版使用手冊。說明如何編譯、安裝、設定與監看 OpenH323 Gatekeeper - The GNU Gatekeeper。

1. 介紹

1.1 關於此計畫

OpenH323 Gatekeeper - The GNU Gatekeeper 是一個自由軟體(或稱開放原始碼)計劃，目的在實作一個 H.323 gatekeeper。 H.323 gatekeeper 為 H.323 端點(endpoint)提供通話控制的服務，它是 H.323 標準的一部份。

根據 H.323 規格書的標準，gatekeeper 應提供下列服務：

GNU Gatekeeper 依據 OpenH323 實作出以上大部份的功能。

H.323 規格書是由 ITU 公佈的國際標準，做為網際網路上語音、影像及資料的通訊標準。詳細的說明見 Paul Jones' primer on H.323。

關於 gatekeeper 功能的詳細描述，可見 這裡。

1.2 版權聲明

GNU Gatekeeper 是自由軟體計劃，受 GNU 通用公共許可證 (GNU GPL) 所保護及規範。此外，我們特別允許執行檔可與 OpenH323 及 OpenSSL 的函式庫連接。

簡單的說，GNU 通用公共許可證允許你可以自由的複製、散佈、出售或者修改本軟體。但是要求所有的衍生作品也必須以 GNU 通用公共許可證的規範釋出。這表示，你必須公開所有你修改本軟體的程式碼，以及任何你加進本軟體的程式(如果有的話)。細節請見 COPYING 這個檔案的說明。GNU 通用公共許可證的中文翻譯可在 CLDP 取得。

關於自由軟體的概念或理想，可參考 軟體自由基金會 網站的說明。

如果你不願這樣做，你必須透過狀態介面以 TCP 連線的方式與 Gatekeeper 溝通。利用此方式你可以只將最基本的功能加入 Gatekeeper 中，而不公開你程式的其它部份。

1.3 名稱

本計劃的正式名稱是 OpenH323 Gatekeeper - The GNU Gatekeeper， 簡稱 OpenH323GK 或 GnuGK。請不要將本計劃與其它類似計劃搞混了!

目前有好幾個使用 OpenH323 的開放原始碼的 gatekeeper 計劃：

這幾個 gatekeeper 的計劃都使用非常類似的名稱，的確困擾了大多數的使用者。然而我們的 "OpenH323 Gatekeeper" 是其中最早開始的，因此選擇如此類似的名稱並不是我們的錯。然而為了讓人們能與其它計劃做出更清楚的區別，我們決定加上 "The GNU Gatekeeper" 的子標題，並且使用 gnugk 做為執行檔的名稱。

因此請記得，當你向我們回報問題或提供建議時，請使用本計劃正確的名字：OpenH323GK 或 GnuGK。不要再說成是 OpenGatekeeper 或 OpenGK 了!

1.4 特色

2.0.2 版新增的主要功能包括：

此外當然還包括了下列已存在於 2.0 版的功能：

1.5 下載

最新的穩定及發展中的版本都可從這個 下載網頁 取得。

若你想使用 CVS，可從 Sourceforge ( Web-GUI) 的下載網頁取得。請注意，那是最新的發展版本，很可能會不穩定。

你也可以從 Sourceforge 下載預先編譯好的執行檔，不過只有某些平台的版本而已。

1.6 通信論壇

本計劃有兩個通信論壇(mailing list)，一個是給開發者用的，另一個是給一般的使用者用。

一般的使用、設定問題請寫信到 users mailing list。你可以在此找到所有的 郵件收集。欲加入此通信論壇，請點 此處。

若要回報問題，或提供錯誤更正，請寫信到 developers mailing list。點選 此處 可以找到所有的郵件收集。請注意，一般的使用問題不要寄到這裡，而該寄到上述的使用者論壇。這個論壇是給開發者使用的。當然，如果你想對此計劃有所貢獻，請 加入此論壇。

注意： 請不要將你的問題用私人信件寄給個別的開發者。我們通常非常忙碌。我們並不想做你的私人顧問，除非你願意付錢給我們。將你的問題送到公開而適當的通信論壇，讓更多的人有機會可以幫你。

也請注意不要將 GnuGK 專屬的問題寄到 OpenH323 的通信論壇，或者相反。否則一定沒有人會理你。這是兩個不同的計劃，雖然關係密切。兩個計劃的開發者也不相同，雖然他們常以某種方式互相合作。

在你問問題之前，請先確定你已經小心地讀過了相關的文件。清楚並精確的描述你的問題。如果有任何錯誤訊息或記錄檔的話，請附上。如果你不知道怎麼在一個公共的論壇中提問題的話，請先閱讀 Eric S. Raymond 著名的文章 How To Ask Questions The Smart Way(這兒有篇略舊的 中譯)。

1.7 貢獻者

目前本計劃的主持人是 Jan Willamowius <jan@willamowius.de>。

2.0 版主要的功能與特性是由台灣的 黃志偉 <cwhuang@linux.org.tw> 和 呈祺資訊網路 所實作，包括重新設計以適合在多執行緒並行仍安全無慮的註冊及通話管理表格，新的路由模式(routed mode)架構、H.323 代理器(proxy)、H.235 認證模組以及 MySQL 後端連接。

位於德國的 mediaWays 公司正在為本計劃加入 LDAP 資料庫子系統，重疊遞送(overlapped sending)以及先進路由機制。

本計劃最初是由 Xiang Ping Chen, Joe Metzger and Rajat Todi 所發展。

譯註：本使用手冊是先寫成英文版再翻譯為中文。特別感謝張崇嚴和吳恆昇協助翻譯。

2. 編譯與安裝

2.1 編譯 Gatekeeper

要編譯 Gatekeeper，你需要 PWLib 1.2 版和 OpenH323 1.8 版或以上。開發中的 Gatekeeper 版本通常需要搭配最新版的 OpenH323。

相關的函式庫可以到 OpenH323 下載網頁 取得。編譯 OpenH323 的方式，請參考 這裡 的指示。

編譯的順序：

  1. PWLib (release 版 + debug 版)
  2. OpenH323
  3. OpenH323 test application (不一定要, 只是用來確定到目前為止一切正常。)
  4. Gatekeeper

在 Unix 作業系統下，請先移至 Gatekeeper 目錄。執行 make debug 來編譯 debug 版，或執行 make opt 來編譯 release 版。執行 make both 則可同時編譯兩種版本。

注意：你必須使用 GCC 2.95.2 版或以上，舊版的 GCC 可能無法正常編譯。

在 Windows 作業系統下，需開啟 Microsoft Visual C++ 6.0 or 7.0 (Visual C++ 5.0 太舊)來編譯所提供的 project (gk.dsw) 。

從 2.0 版開始 GnuGK 支援以 MySQL 和 LDAP 做為後端資料庫。如果你不需要這些支援，可以在 make 之前加上參數： 

$ NO_MYSQL=1 make both

若要取消 LDAP 的支援： 

$ NO_LDAP=1 make both

或是取消兩者： 

$ NO_MYSQL=1 NO_LDAP=1 make both

自 2.0.1 版起 GnuGK 實作新的 fd_set 結構，使得 GnuGK 能在路由模式下能支援上千通電話。欲使用此項功能，可在編譯時加上 LARGE_FDSET 參數，指定欲開啟的最大檔案數目。例如： 

$ LARGE_FDSET=16384 make opt

2.2 安裝 Gatekeeper

安裝 Gatekeeper 不需要什麼特殊的安裝步驟，只需將編譯好的可執行檔拷貝到你想存放的目錄裡，然後再手動新增一個設定檔。

設定檔的範例放在原始程式碼的 etc/ 子目錄內。請參閱 設定檔 一節，有更詳盡的說明。

舉例：在 Linux x86 平台下，最佳化的執行檔 gnugk 會產生在 obj_linux_x86_r/ 子目錄裡。你可以把它拷貝到 /usr/sbin/ 目錄，然後再新增設定檔 /etc/gnugk.ini 。最後，輸入以下指令來啟動 Gatekeeper： 

$ /usr/sbin/gnugk -c /etc/gnugk.ini -o /var/log/gnugk.log -ttt

請參閱 命令列參數 一節，有更詳盡的說明。

2.3 預先編譯好的執行檔

如果你不想下載原始程式碼來自行編譯，在 SourceForge 裡有一些已經編譯好的套件可供使用。但並非所有的版本都有預先編譯好的執行檔，下載前請先看清楚。

Red Hat packages (.rpm)

請先下載 RPMs ，再以 root 身份，輸入以下的指令來安裝 Gatekeeper： 

$ rpm -Uvh gnugk-x.x.x.rpm（你下載的檔案的名稱）

Debian packages (.deb)

如果你是使用 stable (woody) 版本的 Debian，請以 root 身份，輸入以下的指令來安裝 Gatekeeper： 

$ apt-get install openh323gk

3. 入門指引

3.1 第一個簡單的試驗

選兩台連上區域網路的 Linux 工作站，裡面要安裝 OpenH323 1.1 版或以上和 OhPhone。在第一台機器上開兩個主控台，分別執行 Gatekeeper 和 ohphone。 

jan@machine1 > gnugk -ttt

上一行指令表示：Gatekeeper 現在以直接信號模式執行。-ttt 參數指示 Gatekeeper 把除錯訊息顯示在主控台。你也可以用 "-o logfile" 把除錯訊息存到一個檔案裡。關於信號模式的說明，請參閱 下一節 的說明。 

jan@machine1 > ohphone -l -a -u jan

上一行指令表示：OhPhone 現在正在等候來電(-l)，而且會自動接聽來電(-a)。此外，OhPhone 會自動偵測 Gatekeeper，然後用 jan 這個使用者名稱來註冊到 Gatekeeper。(在某些原因下，若 OhPhone 無法自動偵測到 Gatekeeper，可以用 "-g 1.2.3.4" 來指定運行 Gatekeeper 那一台機器的 IP 位置。)

在第二台機器上只需執行 OhPhone。 

peter@machine2 > ohphone -u peter jan

上一行指令表示：第二台機器上的 OhPhone 會以 peter 這個使用者名稱來註冊到成功偵測到的 Gatekeeper，然後試著打電話給使用者 jan。Gatekeeper 會把使用者名稱 jan 轉換成 jan 所在的那一台機器的 IP 位置(在這個情形下是第一台機器)。如此一來，第二台機器上的 OhPhone 就知道應該要打給第一台機器才能找到 jan。

當有來電時，第一台機器上的 OhPhone 就會自動接通，最後 Peter 和 Jan 就能開始閒聊。

3.2 用狀態界面來監控 Gatekeeper

現在我們試著來看看 Gatekeeper 處理了哪些信息。在第一台機器開一個新的主控台，然後用 telnet 來連到 Gatekeeper。 

jan@machine1 > telnet machine1 7000

這時，你很有可能會收到 "Access forbidden!" 這個訊息。這是因為並非所有的人都能任意監控 Gatekeeper。現在我們新增一個檔案叫 gatekeeper.ini，放到我們啟動 Gatekeeper 的那個目錄裡。gatekeeper.ini 的內容包括以下四行： 

[Gatekeeper::Main]
Fourtytwo=42
[GkStatus::Auth]
rule=allow

請先用 Ctrl-C 停止 Gatekeeper，然後再重新啟動一次 Gatekeeper。當我們再次執行 telnet machine1 7000，就能與 Gatekeeper 保持連線了。

現在再重複 Peter 打給 Jan 的那個試驗，看看 Gatekeeper 在直接信號模式下處理了哪些訊息。在 telnet session 裡，有很多指令可以被執行。你可以鍵入"help" 來列出可用的指令。如果你要結束與 Gatekeeper 的 telnet session ，則先鍵入 "quit" ，再按 Enter。

3.3 以路由信號模式啟動 Gatekeeper

啟動 Gatekeeper 於路由信號模式，就是表示 Gatekeeper 會要求所有的通話信號都要經過 Gatekeeper 來轉送。由於所有的信號都會通過 Gatekeeper，因此可以讓 Gatekeeper 對通話行為有更大的控制權。 

jan@machine1 > gnugk -r

上一行指令表示以路由模式來執行 Gatekeeper。再一次 telnet 到埠號 7000，打一通電話看看 Gatekeeper 現在會處理哪些信息。注意：所有與多媒體相關的封包（包括聲音和影像），仍然是在兩個端點(就是試驗中那兩個 OhPhone)間直接傳送。注意：因為 Gatekeeper 路由模式更加的複雜，所以你很有可能在這個模式下遇到 Gatekeeper 程式上的錯誤。不過也無所謂，再執行一次就好囉。;-)

3.4 虛擬的交換機：中斷通話

到目前為止，Gatekeeper 所表現出來的功能只是將符號名稱轉換成 IP 位置。雖然這是一個重要的功能，但卻不足以令人感到驚奇。

事實上，Gatekeeper 能夠對通話進行多樣化的控制，例如：中斷通話。當你連接到 Gatekeeper 的狀態界面，可以鍵入 "PrintCurrentCalls" 來列出所有進行中的通話。如果你要終止兩個端點間的通話，你可以任意選擇其中一台的 IP 位置，然後鍵入 Disconnectip xxx.xxx.xxx.xxx 來中斷此通話。

你也可以寫一個簡單的程式，連線到 Gatekeeper 的狀態界面來監控所有進行中的通話。或是限制最長的通話時間為五分鐘，以免有人濫用系統資源。

Gatekeeper 也能做到來電轉接(call transfers)和來電跟隨(call forwarding)的功能。不過，目前尚未進行實作。

3.5 將通話轉送給一般電話

要是沒有用 H.323 閘道器(Gateway)，網路電話的使用者只能撥打給其他網際網路上擁有網路電話的使用者。如果要撥打給傳統電話的用戶，就必須使用閘道器。 

_________________          ______________
| endpoint "jan"|          |            |
| 192.168.88.35 |--------->| Gatekeeper |
|_______________|          |            |
_________________          |            |
| gateway "gw1" | outgoing |            |
| 192.168.88.37 |<---------|____________|
|_______________|

使用閘道器時， Gatekeeper 本身必須先知道哪些通話必須先被轉送到閘道器才能撥號出去，而哪些通話可以直接透過 Gatekeeper 做內部撥號。你可修改 Gatekeeper 設定檔的 [RasSrv::GWPrefixes] 小節來加以規範，告知 Gatekeeper，當撥打號碼的前幾個號碼符合設定條件時，就應該要轉送到閘道器。 

[RasSrv::GWPrefixes]
gw1=0

以上的設定指示 Gatekeeper ，如果被撥打的 E.164 號碼開頭是 0 時，就將這通電話轉送給用 "gw1" H.323 alias 註冊到 Gatekeeper 的那一台閘道器，然後再由閘道器撥給目的地。這時如果沒有任何一台閘道器是用 "gw1" 這個 H.323 alias 註冊到 Gatekeeper，那電話就無法接通(注意：設定時，必須使用 Gateway 的 alias ，不能使用閘道器的 IP 位置來設定)。

3.6 改寫 E.164 號碼

若你使用了閘道器，你通常會在閘道器內部使用不同的號碼。Gatekeper 在收到被撥的號碼時，可以先將號碼改寫，然後再將改寫後的號碼轉送到閘道器，進入電話網路撥號出去。你可以使用 RasSrv::RewriteE164 這一小節來作號碼的改寫。

以下的例子中，你可以用網路電話撥打一個喜歡的號碼 12345 ，事實上，卻是接通到 "gw1" 這台 gateway 後的電話，實際號碼卻是 08765。 

[RasSrv::GWPrefixes]
gw1=0

[RasSrv::RewriteE164]
12345=08765

4. 參考手冊

Gatekeeper 的行為完全取決於命令列選項和其設定檔案。一些命令列選項可能會覆蓋掉設定檔中的設定。例如: -l 選項將會覆蓋過設定檔中的 TimeToLive 設定。

4.1 命令列選項

幾乎每一個選項都有短格式及長格式，例如: -c 和 --config 是相同的意思。

基本選項

-h --help

顯示所有可獲得的選項。

-c --config filename

指定要使用的設定檔名。

-s --section section

指定要使用設定檔中的那一節做為主要章節。預設是 [Gatekeeper::Main]。

-i --interface IP

指定 Gatekeeper 監聽的界面(IP)。你可以省略這個選項讓 Gatekeeper 自動選擇監聽的 IP，除非你想要讓 Gatekeeper 監聽特定的 IP。

-l --timetolive n

指定端點註冊後有效存在的時間，單位為秒。這個選項將會覆蓋掉設定檔中的 TimeToLive 設定。更詳細的說明請參考 下一小節。

-b --bandwidth n

指定 Gatekeeper 可獲得的總頻寬。不指定這個選項的話，頻寬管理功能預設將關閉。

--pid filename

指定 pid 檔案,僅 Unix 版本有效。

信號模式

這裡所列出的選項將會覆蓋掉設定檔中 [RoutedMode] 小節的設定。

-d --direct

使用直接信號模式。

-r --routed

使用路由信號模式。

-rr --h245routed

使用路由信號模式，並且啟動 H.245 路由模式。

除錯訊息

-o --output filename

將除錯訊息寫到指定的檔案中。

-t --trace

加越多的 -t ,輸出的訊息將會越多越詳細。 例如: 使用 -ttttt 將除錯等級設成 5。

4.2 設定檔

本程式的設定檔是一標準的文字檔。基本的格式是： 

[Section String]
鍵值=設定字串

一行的開頭若是井號(#)或分號(;)代表是註解。

在 etc/ 子目錄下的 complete.ini 包含了所有的章節及選項。一般來說你並不需要使用全部，那是沒有意義的。選擇你需要的章節使用。該目錄下還有許多有用的範例可供參考，你可以視情況修改後使用。

程式執行時也可以更改設定檔以改變 Gatekeeper 的行為。當你修改完後，記得要從狀態界面下 reload 指令，或者，在 Unix 上可以送 HUP 給 Gatekeeper 的行程。如： 

kill -HUP `cat /var/run/gnugk.pid`

注意： 有人指出在 GnuGK 2.0 的設定檔中有些小節名稱是 [RasSrv::*]，而有些卻是 [RasSvr::*]。這個不一致的名稱使人困惑。在 2.0.1 版中所有的名稱已修正為 [RasSrv::*]。如果你是從 2.0 或以前的版本升級的，請記得更改名稱，否則程式會拒絕啟動。

Section [Gatekeeper::Main]

大多數的使用者不需要更改以下的設定。這些主要是用來做為測試，或是非常特殊的情況下使用。

Section [RoutedMode]

當端點發出通話請求時，通話的信號傳送的方式有兩種。第一種稱為直接信號模式，這個模式下信號直接送到受話的端點。第二種稱為路由信號模式，此種模式下信號會經由 Gatekeeper 轉送到受話的端點。採用何種信號模式是由 Gatekeeper 來決定。

在路由信號模式下，Gatekeeper 還可以選擇是否再轉送 H.245 控制通道，以及語音、影像或資料的邏輯通道。因此衍生出下列模式：

情況一

不轉送。也就是，H.245 通道及邏輯通道皆由兩個端點直接建立。

情況二

轉送 H.245 控制通道，但邏輯通道仍由兩個端點直接建立。這種情況稱為 H.245 路由模式。

情況三

所有通道皆由 Gatekeeper 轉送，包括語音、影像的 RTP/RTCP 資訊，以及 T.120 的資料通道。這種情況下，兩個端點之間沒有直接的通信量，因此又稱為 H.323 代理器(Proxy)，可視為一種 H.323 到 H.323 的閘道器(gateway)。

本小節定義與信號路由模式相關的一些選項，包括情況一及二。情況三的選項定義在 下一小節。本節所有的設定都可在執行時期透過 reload 指令調整。

Section [Proxy]

本節定義 Gatekeeper 作為 H.323 proxy 的一些特性。在 proxy 模式下，Gatekeeper 將轉送所有從發話端到受話端的所有資料，因此兩個端點之間沒有直接的通信。如果你有一些端點位於 NAT 伺服器之後使用私有 IP，而有些端點在 NAT 外使用公用 IP 的話，proxy 模式將對你非常有用。

GNU Gatekeeper 支援轉送傳送聲音及影像的 RTP/RTCP 通道，以及傳送資料的 T.120 通道。不論是透過快速連接(fast-connect)程序或是 H.245 tunnelling 模式開啟的邏輯通道都能夠支援。

請注意，要讓 proxy 模式順利運作，Gatekeeper 對發話端和受話端兩邊的網路必須要有直接的連線。

Section [GkStatus::Auth]

定義狀態界面的存取權限。

Section [RasSrv::GWPrefixes]

本節指定那些 E.164 號碼應轉送到指定的閘道器。

格式：

gw-alias=prefix[,prefix,...]

表示將所有以此處指定之前置碼開頭的號碼轉送至某一擁有此 alias 的閘道器，請注意你必須以閘道器的 alias 來指定，不可用 IP。

範例：

test-gw=02,03

Section [RasSrv::RewriteE164]

本節定義 dialedDigits (E.164 號碼)的改寫規則。

格式：

[!]original-prefix=target-prefix[,target-prefix,...]

若所撥的號碼以 original-prefix 開頭，將被改寫為 target-prefix。可指定多種改寫方式，Gatekeeper 會任選其中一種。如果在 original-prefix 之前加 `!'，則意義剛好相反。

範例：

08=18888

若撥 08345718 將被改寫為 18888345718。

選項：

Section [RasSrv::PermanentEndpoints]

本節你可以放入不支援 RAS 的端點，或是放入你不希望會過期被踢掉的端點。這裡指定的端點記錄將會一直保持在 Gatekeeper 的註冊表格中。不過，你仍可透過狀態界面手動移除之。

格式：

IP[:port]=alias[,alias,...;prefix,prefix,...]

範例：

閘道器：

10.0.1.5=Citron;009,008
終端機：
10.0.1.10:1720=700

Section [RasSrv::Neighbors]

如果 ARQ 中的目的地不存在於此 Gatekeeper 所管理的區域，Gatekeeper 會嘗試送 LocationRequest (LRQ) 到鄰近的 gatekeeper 詢問，這些鄰近的 gatekeeper 稱為此 Gatekeeper 的 neighbors。Gatekeeper 會詢問那些 neighbors 取決於號碼是否符合該 neighbor 的前置碼。若前置碼為 ``*'' 表示都符合。目前一個 neighbor 只能指定一個前置碼。

另一方面，Gatekeeper 僅會回應從本節定義的 neighbors 送來的 LRQ。你可以指定空的前置碼，這種情況下 Gatekeeper 不會送 LRQ 到那個 neighbor，但會接受那個 neighbor 送來的 LRQ。

password 欄位用來認證 LRQ 是否確從 neighbors 送來。見 [Gatekeeper::Auth] 的詳細說明。

格式：

GKID=ip[:port;prefix;password;dynamic]

範例：

GK1=192.168.0.5;*
GK2=10.0.1.1:1719;035;gk2
GK3=gk.citron.com.tw;;gk3;1

Section [RasSrv::LRQFeatures]

定義 LRQ 及 LCF 的一些特性。

Section [RasSrv::RRQFeatures]

Section [RasSrv::ARQFeatures]

Section [CallTable]

Section [Endpoint]

GNU Gatekeeper 可以註冊至其它的 Gatekeeper 成為一個端點。利用此一特性，你可以輕易的建立 Gatekeeper 的階層架構。

Section [Endpoint::RewriteE164]

一旦你指定註冊到上層 Gatekeeper 的前置碼後，上層 Gatekeeper 會將以此前置碼開頭的撥號送到下層 Gatekeeper。下層 Gatekeeper 可以據此節定義的規則來改寫目的地號碼。相對的，由下層 Gatekeeper 發出到上層的通話也會經由此節改寫其來源號碼。

格式：

external prefix=internal prefix

例如，你有如下的系統： 

                        [Parent GK]
                        ID=CitronGK
                        /         \
                       /           \
                      /             \
                     /               \
                [Child GK]          [EP3]
                ID=ProxyGK          E164=18888200
                Prefix=188886
                /       \
               /         \
              /           \
           [EP1]         [EP2]
           E164=601      E164=602

定義這樣的改寫規則： 

188886=6

若 EP1 打 18888200 呼叫 EP3，在 Q.931 Setup 中的 CallingPartyNumber 欄位會被改寫為 18888601。相反的，EP3 可打 18888601 或 18888602 來呼叫 EP1 或 EP2。換句話說，每一個註冊在 Child GK 上開頭號碼為 '6' 的端點，對註冊在 Parent GK 的端點來說，看起來就像是直接註冊在 Parent GK 且開頭號碼為'188886'。

本小節與 RasSrv::RewriteE164 的設定無關，而且後者會優先生效。

Section [Gatekeeper::Auth]

本節定義 Gatekeeper 的認證機制。

語法：

authrule=actions

 <authrule> := SimplePasswordAuth | AliasAuth | PrefixAuth | ...
 <actions>  := <control>[;<ras>,<ras>,...]
 <control>  := optional | required | sufficient
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
每一條規則都有三個結果：ok、fail 及 next。 每一規則也有三種方式可以控制：

目前支援的模組有：

另外，你可以設定某一模組只針對某些 RAS 訊息做檢查。例如下例中，SimplePasswordAuth 被定為 optional，僅針對 RRQ 及 ARQ 做檢查。若某個 RRQ 未被 SimplePasswordAuth 認可，再交由 AliasAuth 模組檢查。預設是接受所有的請求。

範例：

SimplePasswordAuth=optional;RRQ,ARQ
AliasAuth=sufficient;RRQ
default=allow

Section [Password]

本節定義 SimplePasswordAuth 模組的使用者 ID 及密碼。請使用 `make addpasswd' 產生 addpasswd 工具程式來加入 ID 及密碼。

用法： 

addpasswd config userid password

選項：

Section [MySQLAuth]

定義 MySQLPasswordAuth 模組使用的資料庫、表格和欄位以取得的使用者 ID 和密碼。

上面的設定將產生如下的 SQL 查詢指令： 

SELECT $PasswordField FROM $Table WHERE $IDField = %id [AND $ExtraCriterion]

Section [ExternalPasswordAuth]

指定一外部程式以取得密碼做為認證。此程式應從 stdin 輸入 ID 並從 stdout 輸出密碼。

Section [RasSrv::RRQAuth]

指定 AliasAuth 模式認證用的樣式。首先以 RRQ 中的 alias 為鍵值來查詢，若找到的話則應用該規則決定是否接受此 RRQ。規則可以包含以 `&' 隔開的多個條件。

語法：

<authrules> :=  empty  |  <authrule> "&" <authrules>

  <authrule>  := <authtype> ":" <authparams>
  <authtype>  := "sigaddr" | "sigip"
  <autparams> := [!&]*

<authparams> 記號的意義依 <authtype> 而定：

Section [MySQLAliasAuth]

定義 MySQLAliasAuth 模組使用的資料庫、表格和欄位以取得某一 alias 的認證樣式。

上面的設定將產生如下的 SQL 查詢指令： 

SELECT $IPField FROM $Table WHERE $IDField = %alias [AND $ExtraCriterion]

Section [PrefixAuth]

本節定義 PrefixAuth 模組的認證規則。目前，本模組僅能用來認證 ARQ 及 LRQ。

首先，依據 RAS 請求中的 destinationInfo 選擇最長的前置碼，然後根據以最符合的網段決定是否接受該請求。如果找不到適當的前置碼規則，而有指定 default 選項，則依據 default 來決定，否則的話就根據模組的設定決定將請求轉給下一模組或是直接拒絕。

格式：

prefix=authrule[|authrule|...]

語法：

<authrule> :=  <result> <authrule>

  <result>    := deny | allow
  <authrule>  := [!]ipv4:<iprule> | [!]alias:<aliasrule>
其中 <iprule> 可用點表示法或 CIDR 表示法，而 <aliasrule> 須為正規表示法。如果前面加 `!' 旗號表示意義相反。

範例：

555=deny ipv4:10.0.0.0/27|allow ipv4:0/0
5555=allow ipv4:192.168.1.1|deny ipv4:192.168.1.0/255.255.255.0
86=deny !ipv4:172.16.0.0/24
09=deny alias:^188884.*
ALL=allow ipv4:ALL

在此設定中，除了 10.0.0.0/27 網段外所有的端點都可以打 555 但非 5555 開頭的號碼。除了 192.168.1.1 外 192.168.1.0/24 網段來的端點都不能撥 5555 開頭的號碼。除了 172.16.0.0/24 網段外的端點都不能撥 86 開頭的號碼。而 alias 開頭為 188884 的端點不能撥 09。此外所有的情形都是允許的。

Section [GkLDAP::LDAPAttributeNames]

本節定義 LDAP 資料庫使用的屬性名稱。

Section [GkLDAP::Settings]

本節定義 LDAP 伺服器及客戶端的一些參數。

5. 狀態監控

5.1 狀態界面

狀態界面是一個用來監視和控制 gatekeeper 的外部界面。Gatekeeper 將會傳送關於撥打出去之電話的訊息給所有有接通的用戶端，並且可以透過這個界面接受指令。

這個界面是一個簡單的 TCP port (預設是 7000)，你可以使用 telnet 或是其他相關程式來連線。另一個不同的用戶端程式範例即是 Java GUI，亦稱為 GkGUI。

應用程式

你要利用狀態界面來做些什麼事取決於你自己，但這裡有一些建議：

範例

假設你對通話明細記錄有興趣並且想要在固定間隔內批次執行它們。

這裡有個簡單的 Perl script (gnugk_cdr.pl)，它啟動 gatekeeper 並且產生一個狀態界面的簡單用戶端子程式，並且把 CDRs 寫入到一個記錄檔中。 

#!/usr/bin/perl
# sample program that demonstrates how to write the CDRs to a log file
use strict;
use IO::Socket;
use IO::Handle;

my $logfile = "/home/jan/cdr.log";
my $gk_host = "localhost";
my $gk_port = 7000;
my $gk_pid;

if ($gk_pid = fork()) {
        # parent will listen to gatekeeper status
        sleep(1);       # wait for gk to start
        my $sock = IO::Socket::INET->new(PeerAddr => $gk_host, PeerPort => $gk_port, Proto => 'tcp');
        if (!defined $sock) {
                die "Can't connect to gatekeeper at $gk_host:$gk_port";
        }
        $SIG{HUP} = sub { kill 1, $gk_pid; };   # pass HUP to gatekeeper
        $SIG{INT} = sub { close (CDRFILE); kill 2, $gk_pid; };  # close file when terminated

        open (CDRFILE, ">>$logfile");
        CDRFILE->autoflush(1);  # don't buffer output
        while (!$sock->eof()) {
                my $msg = $sock->getline();
                $msg = (split(/;/, $msg))[0];   # remove junk at end of line
                my $msgtype = (split(/\|/, $msg))[0];
                if ($msgtype eq "CDR") {
                        print CDRFILE "$msg\n";
                }
        }
        close (CDRFILE);
} else {
        # child starts gatekeeper
        exec("gnugk");
}

圖形化使用者界面

目前有數個圖形化使用者前端界面，分別由不同的人們或單位所開發。

5.2 命令

help 或 h 命令將會顯示出所有可獲得的命令清單。

5.3 訊息

本節說明輸出至狀態界面的所有訊息及其格式。