利用mod_lua实现动态配置FreeSwtich

        FreeSwtich默认的配置体系是XML文件，修改配置后需要reloadxml生效。这对于大型线上系统，是不可接受的。FreeSwitch本身提供了几种不同的动态配置接口，比如mod_xml_curl，本文介绍利用mod_lua动态配置FS的方法。

        通过mod_lua模块，你可以利用lua实现动态配置。绑定一个脚本处理XML请求，就像mod_xml_curl那样，动态地把所需要的XML片段喂给FS，指示FS的执行。实现应用与数据的分离。FreeSWITCH需要某种XML信息时，它查询注册的钩子，调用指定的脚本。在脚本中，你可以为所欲为，只是不要忘记返回XML就行了。

配置mod_lua

        FreeSwitch启动时会加载conf/autoload_configs/lua.conf.xml配置。

        以下是一个极简配置实例：

---

  编辑lua.conf.xml之后，FreeSWITCH控制台命令reloadxml不能识别 "xml-handler-script" 参数，你必须重启FS才会生效 FreeSWITCH.

---

可配置标签

        对于"xml-handler-bindings"参数，可配置值有："dialplan" "directory" "configuration" "dialplan|directory|configuration"

• FS会向脚本传递一个XML_REQUEST对象，它包含以下成员：section、tag_name、key_name和key_value。它可用于查询模块配置、目录信息、拨号方案，还可能传递一个'params'属性，携带一个 event对象
• 脚本执行完毕之后，你所设置的XML_STRING对象将返回给FS，无论你在里面设置了什么内容

        在Lua脚本中，可以访问XML_REQUEST对象获取必要的信息。比如：

freeswitch.consoleLog("notice", "SECTION " .. XML_REQUEST["section"] .. "\n")

模块配置

        如果mod_lua加载时有如下配置：

那么之后加载的模块，可以把mod_lua当成配置服务器，需要配置信息时，调用绑定的lua实时查询。

        查询模块配置的lua脚本中，隐含一个XML_REQUEST对象，其典型的属性值：

• key_value = 'iax.conf'|'event_socket.conf'|sofia.conf'|...
• key_name = 'name'
• section = 'configuration'
• tag_name = 'configuration'

 

'params' event object
acl.conf	no	N/A
event_socket.conf	no	N/A
post_load_switch.conf	no	N/A
sofia.conf	yes	Event-Name: REQUEST_PARAMS Core-UUID: 0f8afb73-2183-a1e2-2316-71053c746130 FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.12 FreeSWITCH-IPv6: %3A%3A1 Event-Date-Local: 2010-08-06%2014%3A04%3A38 Event-Date-GMT: Fri,%2006%20Aug%202010%2018%3A04%3A38%20GMT Event-Date-Timestamp: 1281117878629975 Event-Calling-File: sofia.c Event-Calling-Function: config_sofia Event-Calling-Line-Number: 2637
switch.conf	no	N/A
syslog.conf	no	N/A

目录(directory)

启动初始化时

 

        在启动初始化过程中，会读取profile配置，为网关和别名域读取目录信息。

        在模块加载时，Lua脚本中的XML_REQUEST对象的属性值：

• key_value = ''
• key_name = ''
• section = 'directory'
• tag_name = ''

此外，"params" 携带一个event 对象。

        对sofia中的每个profile，directory都会读取一次。The directory is read once for each profile in the sofia configuration

---

    注意上面的变量值有“空字符串”，不是nil

---

Params event事件

对于External profile：

Event-Name: REQUEST_PARAMS
Core-UUID: 
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2014%3A04%3A40
Event-Date-GMT: Fri,%2006%20Aug%202010%2018%3A04%3A40%20GMT
Event-Date-Timestamp: 1281117880813532
Event-Calling-File: sofia.c
Event-Calling-Function: config_sofia
Event-Calling-Line-Number: 3481
purpose: gateways
profile: external

重要字段：

purpose: gateways profile: external ... FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.11

对于 Internal profile 

Event-Name: REQUEST_PARAMS
Core-UUID: 
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2014%3A04%3A41
Event-Date-GMT: Fri,%2006%20Aug%202010%2018%3A04%3A41%20GMT
Event-Date-Timestamp: 1281117881174514
Event-Calling-File: sofia.c
Event-Calling-Function: config_sofia
Event-Calling-Line-Number: 3481
purpose: gateways
profile: internal

 

重要字段：

purpose: gateways profile: internal ... FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.11

 

网络列表

        启动初始化过程中，还会从directory中读取网络列表，但这时的XML_REQUEST属性值有些差异：

• key_value =  (比如 192.168.1.11)
• key_name = 'name'
• section = 'directory'
• tag_name = 'domain'

Event 报文

Event-Name: REQUEST_PARAMS
Core-UUID: 
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2014%3A04%3A43
Event-Date-GMT: Fri,%2006%20Aug%202010%2018%3A04%3A43%20GMT
Event-Date-Timestamp: 1281117883173795
Event-Calling-File: sofia_reg.c
Event-Calling-Function: sofia_reg_parse_auth
Event-Calling-Line-Number: 1797
action: sip_auth
sip_profile: internal
sip_user_agent: IP-Phone-V3.2.49T5.13%20-%20G729
sip_auth_username: 1000
sip_auth_realm: 192.168.1.11
sip_auth_nonce: 
sip_auth_uri: sip%3A192.168.1.11
sip_contact_user: 1000
sip_contact_host: 192.168.88.202
sip_to_user: 1000
sip_to_host: 192.168.1.11
sip_to_port: 5060
sip_from_user: 1000
sip_from_host: 192.168.1.11
sip_from_port: 5060
sip_request_host: 192.168.1.11
sip_auth_qop: auth
sip_auth_cnonce: 829326
sip_auth_nc: 00000001
sip_auth_response: 
sip_auth_method: REGISTER
key: id
user: 1000
domain: 192.168.1.11
ip: 192.168.88.202

重要字段：

domain: 192.168.1.11 purpose: network-list ... FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.11

 

查找用户

        FreeSWITCH以特定域标签查找用户，这时XML_REQUEST对象的属性值：

• key_value = ''
• key_name = 'name'
• section = 'directory'
• tag_name = 'domain'

and 'params' will have an event object

注册时(REGISTER)

Event 报文：

Event-Name: REQUEST_PARAMS
Core-UUID: 
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2014%3A04%3A43
Event-Date-GMT: Fri,%2006%20Aug%202010%2018%3A04%3A43%20GMT
Event-Date-Timestamp: 1281117883173795
Event-Calling-File: sofia_reg.c
Event-Calling-Function: sofia_reg_parse_auth
Event-Calling-Line-Number: 1797
action: sip_auth
sip_profile: internal
sip_user_agent: IP-Phone-V3.2.49T5.13%20-%20G729
sip_auth_username: 1000
sip_auth_realm: 192.168.1.11
sip_auth_nonce: 
sip_auth_uri: sip%3A192.168.1.11
sip_contact_user: 1000
sip_contact_host: 192.168.88.202
sip_to_user: 1000
sip_to_host: 192.168.1.11
sip_to_port: 5060
sip_from_user: 1000
sip_from_host: 192.168.1.11
sip_from_port: 5060
sip_request_host: 192.168.1.11
sip_auth_qop: auth
sip_auth_cnonce: 829326
sip_auth_nc: 00000001
sip_auth_response: 
sip_auth_method: REGISTER
key: id
user: 1000
domain: 192.168.1.11
ip: 192.168.88.202

重要字段:

key: id user: 1000 domain: 192.168.1.11 ... action: sip_auth sip_profile: internal FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.11 ip: 192.168.88.202

呼出 (INVITE)

Event 报文

Event-Name: REQUEST_PARAMS
Core-UUID: 
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2016%3A28%3A08
Event-Date-GMT: Fri,%2006%20Aug%202010%2020%3A28%3A08%20GMT
Event-Date-Timestamp: 1281126488274011
Event-Calling-File: sofia_reg.c
Event-Calling-Function: sofia_reg_parse_auth
Event-Calling-Line-Number: 1797
action: sip_auth
sip_profile: internal
sip_user_agent: IP-Phone-V3.2.49T5.13%20-%20G729
sip_auth_username: 1001
sip_auth_realm: 192.168.1.11
sip_auth_nonce: 1fe3d1fa-a199-11df-b392-b105e374638e
sip_auth_uri: sip%3A1000%40192.168.1.11
sip_contact_user: 1001
sip_contact_host: 192.168.88.99
sip_to_user: 1000
sip_to_host: 192.168.1.11
sip_to_port: 5060
sip_from_user: 1001
sip_from_host: 192.168.1.11
sip_from_port: 5060
sip_request_user: 1000
sip_request_host: 192.168.1.11
sip_auth_qop: auth
sip_auth_cnonce: 10560d0
sip_auth_nc: 00000001
sip_auth_response: b99d1213022480a2b6c4e14432661821
sip_auth_method: INVITE
key: id
user: 1001
domain: 192.168.1.11
ip: 192.168.88.99

重要字段:

key: id user: 1001 domain: 192.168.1.11 ... ip: 192.168.88.99 FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.11 action: sip_auth sip_profile: internal

 

呼入

Event 报文

Event-Name: REQUEST_PARAMS
Core-UUID: 
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2016%3A28%3A09
Event-Date-GMT: Fri,%2006%20Aug%202010%2020%3A28%3A09%20GMT
Event-Date-Timestamp: 1281126489462522
Event-Calling-File: mod_dptools.c
Event-Calling-Function: user_outgoing_channel
Event-Calling-Line-Number: 2662
as_channel: true
action: user_call
key: id
user: 1000
domain: 192.168.1.11

重要字段:

key: id user: 1000 domain: 192.168.1.11 ... FreeSWITCH-Hostname: hostname FreeSWITCH-IPv4: 192.168.1.11 as_channel: true Event-Calling-Function: user_outgoing_channel

 

拨号方案

配置

Lua 脚本 dp.lua示例

-- params is the event passed into us we can use params:getHeader to grab things we want.
io.write("TEST\n" .. params:serialize("xml") .. "\n");

mydialplan = [[


    

        
              
                        
                        
                        
                        
                    
               
         
     

]]

XML_STRING = mydialplan
-- comment the following line for production:
freeswitch.consoleLog("notice", "Debug XML:\n" .. XML_STRING .. "\n")

同一功能的另一个版本：

-- LUA dialplan
  
DIALPLAN = {}
freeswitch.consoleLog("notice", "SECTION " .. XML_REQUEST["section"] .. "\n")

table.insert(DIALPLAN, [[]])
table.insert(DIALPLAN, [[]])
table.insert(DIALPLAN, [[    
]])
table.insert(DIALPLAN, [[        ]])
table.insert(DIALPLAN, [[              o]])
table.insert(DIALPLAN, [[                        ]])
table.insert(DIALPLAN, [[                        ]])
table.insert(DIALPLAN, [[                        ]])
table.insert(DIALPLAN, [[                        ]])
table.insert(DIALPLAN, [[                    ]])
table.insert(DIALPLAN, [[               ]])
table.insert(DIALPLAN, [[         ]])
table.insert(DIALPLAN, [[     
]])
table.insert(DIALPLAN, [[]])

XML_STRING =  table.concat(DIALPLAN, "\n")

mydialplan = [[


    

        
              
                        
                        
                        
                        
                    
               
         
     

]]


-- comment the following line for production:
freeswitch.consoleLog("notice", "Debug XML:\n" .. XML_STRING .. "\n")

 

通过profile设置跳转

        上述实例，展示了lua是怎样生成XML片段并喂给FS执行的。但是拼接XML的过程显得有些繁琐。有没有办法简单一点呢？Dialplan的描述本质上无非就是一组的Action加上参数而已。

         lua_dialplan_hunt的实现中，允许使用ACTIONS表来传递这些信息，换句话说，在脚本里，构建一个ACTIONS table并传回给FS就可以了。那么我们需要怎样做呢？

profile设置

        编辑sip profile配置文件，比如说freeswitch/sip_profiles/internal.xml，修改以下两个属性：

用户目录配置

        修改用户的context属性为“luadp.lua”，比如说freeswitch/directory/default/1000.xml：

添加lua脚本

        在脚本目录下，添加一个名为luadp.lua的脚本，内容如下：

-- LUA dialplan
  
ACTIONS = {}
freeswitch.consoleLog("notice", "from your script")

table.insert(ACTIONS, {"sleep", "1000"})
table.insert(ACTIONS, "answer")
table.insert(ACTIONS, {"playback", "ivr/8000/ivr-welcome_to_freeswitch.wav"})
table.insert(ACTIONS, {"log", "NOTICE after your script"})

        这个实例是前面dialplan的第三个版本，脚本逻辑是不是简单得多了。

Lua调用XML dialplan:

 

table.insert(ACTIONS, {"transfer", "123 XML some-context"})

 XML 调用Lua dialplan:

<action application="transfer" data="123 LUA some-dialplan.lua"/>

Not found

        如果LUA 收到一个dialplan查询请求，但没有相应处理逻辑，那么应当返回 "not found" 结果（如下所示），不能返回空串：

如果返回一个空串，FS将处理报错：

[ERR] switch_xml.c:1534 switch_xml_locate() Error[[error near line 1]: root tag missing]