opensips
opensips 在SIP 環境的定位是提供 registrar, proxy, redirect, location services。最重要的是，可高速處理 sip headers 並提供封包的 routing 功能。其他的部份，例如 NAT traversal, IMS, load balancing 等等功能則是由 3rd party modules 提供。
registrar 可管理某個 domain 下的 SIP UA，讓這些 UA 註冊並受該 server 管理。
proxy server的用途是，接收 UA 的 request，當受話端不在同一個 domain 時，就把 request 轉送到另一個 SIP proxy server。
redirect server 接收 request 之後，直接以 302 Moved Temporarily 回應給 UA。
opensips history
在 2004 年，德國 FhG Fokus research institute 以 GPL 發布了 SER，其後 OpenSERs fork 該專案，開發 SER 的單位輾轉成立了 Voice System 公司，繼續維護 OpenSER。
OpenSERs 在 2008 年又經歷了一次分裂，成了兩個專案：Kamailio 與 OpenSIPs。opensips 核心非常小，但以上百個 modules 來延伸其功能，目前可以用來提供 SIP firewals, session border controllers(SBCs), load balancers 等等功能。
以下列出重要的 module 與功能
- dispatcher, path: 這兩個模組用來提供 load balancing 的功能
- mediaproxy, rtpproxy, nathelper: 提供 NAT traversal 的功能
- presence: 處理 presense server
- IMC, XMPP: instant messaging
安裝 opensip 的程序，可參閱這篇OpenSIPS and Control Panel Install Guide，雖然版本有點差異，安裝過程可套用在目前的版本 opensips 1.11.1, opensips-cp 5.0 上。
opensips.cfg
該設定檔可分成三大區塊: Global Configuration, Modules, Routing Logic。
# Global Configurations
debug=3
log_stderror=no
log_facility=LOG_LOCAL0
fork=yes
children=4
# Modules Section
mpath="/usr/lib64/opensips/modules/"
### Module Loading: 用 loadmodule 載入 modules
loadmodule "signaling.so"
loadmodule "sl.so"
loadmodule "tm.so"
### Module Specific Parameters
modparam("tm", "fr_timer", 5)
modparam("tm", "fr_inv_timer", 30)
modparam("tm", "restart_fr_on_each_reply", 0)
modparam("tm", "onreply_avp_mode", 1)
# Routing Logic
### Main routing block: SIP request 處理的起點，每個 request 都會經過這裡
### Secondary routing blocks: 可定義 route()，用起來類似 subroutines
### Reply routing blocks: 處理 reply messages, 包含 provisional, successfule final replies, negative final replies，通常是 200 OK
### Failure routes blocks: 處理錯誤狀況, 例如 busy or timeout
### Branch route blocks: 在把 request forward 出去之前，每一條 branch 都可執行一段 logic
### Local routing blocks: 當 opensips 內部產生 request (通常只作為 UAS)，就使用 Transaction Module(TM)
### Error routing block: 當 sip request parsing error 發生時，就執行這個
Sessions, dialogs, and transactions
在處理 opensips processing 之前，我們要先知道這三個名詞的意思
SIP transaction: A SIP request，包含了 resends 與 direct responses，也就是 REGISTER 與 200 OK
SIP dialog: 兩個 SIP entities 在某個時間點，存在的相互關係，換句話說，就是在兩個 UACs 之間，從 INVITE 到 BYE 之間，建立的一個對話
SIP Session: 在兩個 SIP entities 之間傳送的 media flow，可能是 audio/video/text
SIP proxy: stateless or stateful
stateless 的作法，proxy server 會在 forward 訊息之後，把所有 message 的 internal information 丟棄。單純地只會把資料轉送到 request 裡面提供的下一個節點。
如果需要提供 billing, call forwarding, voicemail 功能，就需要使用 stateful mode，每個 transaction 都需要存在記憶體中，並處理 failure, response, retransmissions 等等狀況。這是 Transaction Module(TM) module 提供的功能。
要注意，stateful 的狀態維護是針對 transaction 處理而不是 dialog，因此從 INVITE 到 200 OK response 的處理是 stateful，而不是從 INVITE 到 BYE request，這個是 dialog。
stateful operation 的處理過程
Script and Routing Basics
一般安裝好 opensips 之後，沒有調整什麼特別的設定的時候，設定檔會放在 /usr/etc/opensips 這個目錄中，我們可以自己做個 link，改用 /etc/opensips 這個目錄。
根據上面 opensips.cfg 那個段落的內容，這個設定檔裡面可分為 (1) Global Parameters (2) Load Modules (3) Module Parameters (4) Routing Script 這四個部份。
將 opensips 設定完成後，最基本可以達成以下任務。
- 建立一個 SIP Server
- 可讓內部網路的 UACs 連接
- 在不同 UACs 之間互相撥打電話
- 話機不需要驗證，不使用資料庫
- 不支援 PSTN，只能在話機之間通話
Global Parameters
Listen Interfaces
不設定 listen 時，系統將會自動綁定所有的網路界面。
port 參數只是針對 SIP Server 設定 UDP service port
listen=udp:192.168.152.148:5060
listen=tcp:192.168.152.148:5061
listen=tls:192.168.152.148:5062
port=5060
Logging
在正式環境，就設定 debug=3，在 debug 環境，就設定 debug=9。
可以用這個 MI command 調整 log level
opensipsctl fifo debug 1
在 opensips.cfg 裡面的 log 相關設定範例如下
debug=3
log_stderror=no
log_facility=LOG_LOCAL0
Number of processes
opensips process 可運作在 foreground 或background，可設定 fork=yes，指定運作在 background。如果設定運作在 foreground，opensips就無法 listen 多個網路界面，tcp與tls 也會自動 disabled。
children 是設定每一個網路界面有幾個 processes 提供服務。
fork=yes
children=4
tcp_children=6
disable_tcp=no
disable_tls=no
Daemon options
gid/group=sip # unix group
uid/user=sip # unix user
wdir="/" # working directory
chroot="/usr/local/opensips-1.6"
SIP identity
設定 SIP request/response 裡面的標準參數。
server_header="Server: My openSIpS
#default is "openSIpS (<version> (<arch>/<os>))"
server_signature = yes
user_agent_header="User-Agent: My openSIpS
其他
alias 很重要，這是設定 SIP server 支援的 domain name。
alias="mydomain.sip" # to set alias hostnames for the server
auto_aliases=no # discover aliases via reversed DNS
disable_dns_failover = yes
sip_warning=yes #add a debugging header in replies
global parameters 區塊
####### Global parameters #########
debug=3 # set the debug leve to 3
log_stderror=no # log to syslog
log_facility=LoG_LoCAL0 # Log to facility LoG_LoCAL0
fork=yes # Run as a daemon
children=4 # open 4 child process for
each UDpaddress
/* uncomment the next line to disable TCp(default on) */
#disable_tcp=yes
/* uncomment the next line to enable the auto temporary blacklisting of not available destinations (default disabled) */
#disable_dns_blacklist=no
/* uncomment the next line to enable Ipv6 lookup after Ipv4 dns lookup failures (default disabled) */
#dns_try_ipv6=yes
/* uncomment the next line to disable the auto discovery of local aliases based on revers DNS on Ips (default on) */
#auto_aliases=no
/* uncomment the following lines to enable TLS support (default off) */
#disable_tls = no
#listen = tls:your_Ip:5061
#tls_verify_server = 1
#tls_verify_client = 1
#tls_require_client_certificate = 0
#tls_method = TLSv1
#tls_certificate = "//etc/opensips/tls/user/user-cert.pem"
#tls_private_key = "//etc/opensips/tls/user/user-privkey.pem"
#tls_ca_list = "//etc/opensips/tls/user/user-calist.pem"
port=5060 # Run on port 5060
/* uncomment and configure the following line if you want opensips to bind on a specific interface/port/proto (default bind on all available) */
#listen=udp:192.168.1.2:5060
Modules
指定 modules 的路徑
#set module path
mpath="/usr/lib64/opensips/modules/"
設定 FIFO file 的路徑，用來處理與暫存外部指令。
#### FIFO Management Interface
loadmodule "mi_fifo.so"
modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")
modparam("mi_fifo", "fifo_mode", 0666)
Scripting Basics
opensips 使用類似 C 語言的 scripting language，這可以用來 routing SIP requests 與處理 SIP replies。
除了 core functions/values 之外，其他 functions 都是由 modules 提供。
Core functions
- forward();
Route the request "stateless" (based on R-URI)
- drop();
停止執行 script
- exit();
立即終止 script processing
其他 core functions:
seturi()
setflag()
isflagset()
strip()
prefix()
rewritehostport()
Core values
script 裡面預先定義了一些 values 可以使用
- INET/INET6
IPv4 or IPv6
- TCP/TLS/UDP
protocol
- myself
a reference to the list of local IP addresses, hostnames, and aliases
Core keywords
可用來識別 SIP message裡面的特殊欄位的值
- af
Address family(INET/INET6)
- proto
Protocol(TCP/TLS/UDP)
- dst_ip
在 SIP message 中收到的 local interface 的 IP
- method
SIP method of this message
- Status
用在 onreply_route 時，這個變數會參考到 reply 的 status code
- retcode
上一個 function 處理的結果
- uri
request URI
- from_uri
FROM header 裡面的 URI
- to_uri
TO header 裡面的 URI
使用範例
if(af==INET6) {
log("Message received over Ipv6 link\n");
};
if(is_method("INVITE") && from_uri=~".*@opensips.org")
{
log("the caller is from opensips.org\n");
};
Pseudo-variables
就是 system variables，例如 SIP Messages 可取得 headers, R-URI, source IP。從 opensips 可取得 time, process ID。
Pseudo-variables 是以 $ 開頭，如果 script 裡面要使用該符號，就要加上 esacape $$，完整的 Pseudo-variables 可在這個網頁取得。
Script variables
可在 config script 裡面使用的變數，這些變數只存在於 script 的執行期，執行結束後，就會被刪除。該變數可儲存數字或字串。
$var(name)
範例
$var(b)=1;
$var(b)="1";
$var(b)="$fu"+"$tu";
$var(b)=1+2;
可使用以下的 operations
+
-
/
*
%: modulo division
|: Bitwise OR
&: Bitwise AND
^: Bitwise XOR
~: Bitwise NOT
也可使用下列的字串處理方法
{s.len}
{s.int}
{s.substr,offset,length}
{s.select,index,separator}
{uri.user}
{uri.host}
{uri.params}
{param.value,name} - returns the value of parameter "name"
範例
"a=1;b=2;c=3"{param.value,c} = "3"
Attribute-Value Pair (AVP)
這個變數是在 statefule mode，附屬在 SIP message 的變數，所以 AVP 是 transaction-persistent variables。AVP 會在 transaction 開始時被配置，而在 transaction 結束時被釋放。
AVP 的格式:
$avp(id[N])
id
(1) si:name
AVP identifier name, s 與 i 是字串或數字
(2) name
AVP alias name, 字串或數字
範例:
$avp(i:700)
$avp(s:blacklist)
AVPs 相關的函數
- avp_db_load: 由 DB 將 AVPs 載入至記憶體
- avp_db_store: 將 AVPs 存到 DB
- avp_db_delete
- avp_db_query: 進行 DB 查詢，並將結果存至 AVP
- avp_delete: 刪除記憶體中的 AVP
- avp_pushto: 將 AVP 放入 SIP message 中
- avp_check: 用 operator(equal, greater than, and a value) 取得值，例如 avp_check("i:500", "lt/i:501");
- avp_copy: 複製 avp
- avp_printf: 格式化 AVP
- avp_subst: 在 AVP 內尋找並取代某個值
- avp_op: 對 AVPs 做 math operations
- is_avp_set: check if this AVP's name is set
- avp_print: 列印記憶體中的 AVP
從 DB 中取得 user_preference table 變成 AVPs。
範例：在 call forward 時，可取得該 user 的 user_preference 資料。
user_preference table structure:
- id: auto-increment field
- uuid: unique user id
- username: username
- domain: domain
- attribute: AVP name
- type: 0–Avp str|Val Str,1–Avp str|Val Int,2–Avp int|Val Str,3-Avp int|Val int
- value: AVP value
- last modified: 上次修改的時間
Flags
用來 trigger some processes 例如 accouting, dialog control, NAT handling。有三種 flags: message, script, branch flags。
| Type |
Persistence |
Function |
Purpose |
| Message flag |
transaction |
setflag(flag_idx) |
在 transaction level 啟動 some functions |
| Branch flag |
Branch |
setbflag(flag_idx) |
在 branch level 啟動 some functions |
| Script flag |
Top-level Routing |
setsflag(flag_idx) |
儲存其他 flags |
pseudo-variables: $mf (message flags), $bf (branch flags), $sf (script flags)
module GFLAGS
只能用在 external flags，這是用在 MI commands，可在 MI interface 的 external program 中，使用 set_gflag(), is_gflag(), reset_gflag() 這些 functions。
Statements
if-else
if ( t_check_trans() ) {
t_relay();
exit;
} else {
exit;
}
Switch
switch($retcode)
{
case -1:
log("process INVITE requests here\n");
break;
case 1:
log("process REGISTER requests here\n");
break;
case 2:
case 3:
log("process SUBSCRIBE and NoTIFY requests here\n");
break;
default:
log("process other requests here\n");
}
Subroutes
route[1]{
if(is_method("INVITE"))
{
return(-1);
};
if(is_method("REGISTER"))
return(1);
}
if(is_method("SUBSCRIBE"))
return(2);
}
if(is_method("NoTIFY"))
return(3);
}
return(-2);
}
