Freeswitch: Конфигурация при помощи Lua

serving configuration with Lua

Created by Belaid Areski, last modified by John Boteler Переведено и дополнено Олег Звездочкин

Описание

mod_lua позволяет заменить статические XML файлы на Lua скрипты. Это предоставляет дополнительные возможности для расширения функциональности диалплана, динамического предоставления данных, создания интерфейсов или приложений. Например, FusionPBX построен на этом принципе.

Lua скрипты вызываются из XML инструкций, (как URL в модуле mod_xml_curl).

Когда FreeeSWITCH обнаруживает вызов Lua в XML реестре, он выполняет его. Скрипт может обращаться к базе данных или выполнять другие действия на ваше усмотрение и возвращать данные в виде XML строки или переменных диалплана.

Конфигурация mod_lua находится в файле ../autoload_configs/lua.conf.xml.

Если вы редактируете lua.conf.xml, команды reloadxml недостаточно для применения изменений, требуется перезагрузить FreeSWITCH, чтобы распознать xml-handler-script.

Если Lua скрипт вызывается из диалплана или подключается в sip_profile, достаточно выполнить reloadxml или sofia profile <name> restart rescan reloadxml соответственно.

Далее приведен базовый пример подключения Lua скрипта для обслуживания диалплана в файле lua.conf.xml.

<configuration name="lua.conf" description="LUA Configuration">
  <settings>
    <param name="xml-handler-script" value="dp.lua"/>
    <param name="xml-handler-bindings" value="dialplan"/>
  </settings>
</configuration>
В этом случае FS будет считать, что весь диалплан находится в dp.lua. Для перехода в XML можно воспользоваться командой transfer.

Рассмотрим несколько примеров для параметра xml-handler-bindings в его возможных значениях: dialplan , directory и configuration, имена которых, говорят сами за себя.

Скрипт принимает объект - XML_REQUEST который содержит

  • section - секция
  • tag_name - имя тега
  • key_name - имя ключа
  • key_value - значение ключа

В FS возвращаются данные помещенные в объект - XML_STRING.

Также данные могут возвращаться в таблице ACTIONS (рассматривается в описании секции dialplan) или выполняются прямо в скрипте методом session:execute (не рассматривается в этом материале). Используемые методы выбираются в зависимости от точки подключения скрипта.

Доступ к объекту XML_REQUEST в Lua скрипте получается при помощи переменных XML_REQUEST["section"], XML_REQUEST["tag_name"], XML_REQUEST["key_name"], и XML_REQUEST["key_value"]

Пример:

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

В консоль будет выведено значение section, например dialplan.

Также для configuration, directory и dialplan запросов, набор событий объекта передается в скрипт при помощи переменной params.

Под «событиями объекта» понимаются все переменные и данные получаемые при инициации вызова или вызове модуля.

Основным поставщиком данных для params, являются sip заголовки и модули FS.

Доступ к определенным данным params в скрипте можно при помощи переменной params:getHeader("name") или сериализировать весь массив - params:serialize("xml").

В описании секции directory приведены подробные списки params для некоторых важных событий, например таких как INVITE или REGISTER и др.

Configuration

Конфигурация модулей при помощи Lua

Если mod_lua загружен при старте, тогда другие модули, загружаемые после, могут получать данные из связанных скриптов по запросу, каждый раз когда это требуется.

<configuration name="lua.conf" description="LUA Configuration">
  <settings>
    <param name="xml-handler-script" value="configuration.lua"/>
    <param name="xml-handler-bindings" value="configuration"/>
  </settings>
</configuration>

Теперь когда модуль запущен, XML_REQUEST объект в Lua скрипте получит следующие данные:

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

Первоначальный запуск

Во время первоначального запуска/чтения, из directory считываются данные для gateways и связанных доменов.

Когда модуль запущен, XML_REQUEST объект в Lua скрипте должен иметь значения:

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

А также params принадлежащие данному объекту.

directory читаются один раз для каждого профиля в конфигурации sofia.

Переменные без значений '' являются пустыми строками, не nil.

Params event headers

External profile

External profile REQUEST_PARAMS

External profile REQUEST_PARAMS

Event-Name: REQUEST_PARAMS
Core-UUID: <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

Internal profile REQUEST_PARAMS

Internal profile REQUEST_PARAMS

Event-Name: REQUEST_PARAMS
Core-UUID: <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
Network lists

Также во время первоначальной загрузки список сетей (network lists) может быть прочитан из directory. В этой точке XML_REQUEST имеет вид:

  • key_value = <name-of-domain> (e.g. 192.168.1.11)
  • key_name = 'name'
  • section = 'directory'
  • tag_name = 'domain'

Network list GENERAL

Network list GENERAL

Event-Name: GENERAL
Core-UUID: <uuid>
FreeSWITCH-Hostname: hostname
FreeSWITCH-IPv4: 192.168.1.11
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2010-08-06%2014%3A04%3A46
Event-Date-GMT: Fri,%2006%20Aug%202010%2018%3A04%3A46%20GMT
Event-Date-Timestamp: 1281117886025842
Event-Calling-File: switch_core.c
Event-Calling-Function: switch_load_network_lists
Event-Calling-Line-Number: 1040
domain: 192.168.1.11
purpose: network-list

Полезные данные:

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

Когда регистрируется или вызывается user, FS ищет пользователя в конкретном домене.

XML_REQUEST имеет вид:

  • key_value = '<name-of-domain>'
  • key_name = 'name'
  • section = 'directory'
  • tag_name = 'domain'

И params которые имеются в событиях объекта:

При регистрации (REGISTER)

При регистрации (REGISTER)

Event-Name: REQUEST_PARAMS
Core-UUID: <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: <auth_nonce_uuid>
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: <auth_response - md5sum?>
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)

Когда запрашивается соединение (INVITE)

Event-Name: REQUEST_PARAMS
Core-UUID: <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

1001 вызывает 1000.

Полезные данные:

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
...
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

Когда вызывается (другим extension)

Когда вызывается (другим extension)

Event-Name: REQUEST_PARAMS
Core-UUID: <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

Dialplan

XML

Приведенный ниже пример диалплана dp.lua генерирует XML_STRING и возвращает в FS, когда скрипт обработан.

Такая форма скрипта может быть использована, когда Lua диалплан подключен, через lua.conf.xml.
-- 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 version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="dialplan" description="RE Dial Plan For FreeSwitch">
    <context name="default">
      <extension name="freeswitch_public_conf_via_sip">
        <condition field="destination_number" expression="^9(888|1616)$">
          <action application="bridge" data="sofia/${use_profile}/$1@conference.freeswitch.org"/>
        </condition>
      </extension>
    </context>
  </section>
</document>
]]

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

Lua

Другой вариант использования: в sip профиле, вместо XML, можно указать Lua скрипт для генерации диалплана:

<profile name="phones">
  <!-- ... -->
  <settings>
    <param name="dialplan" value="LUA"/>
    <param name="context" value="dialplan-from-phones.lua"/>
    <!-- ... -->
  </settings>
</profile>

После этого создайте скрипт диалплана ../scripts/dialplan-from-phones.lua вроде этого:

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

table.insert(ACTIONS, "answer")
table.insert(ACTIONS, {"log", "NOTICE after your script"})

Все сохраненные в table (Array) данные, будут выполнены (EXECUTE), после того как скрипт остановится.

Это работает также, как и XML диалплан, когда сначала генерируется лист действий (<action application…/>), который затем выполняется, когда все данные собраны и обработаны.

Таким образом можно не активировать медиа потоки непосредственно во время выполнения скрипта.
(Обратный пример session:answer() в реализации IVR.)
Преимущество этого метода, над ответом на вызов непосредственно во время выполнения скрипта, в том что во время вызова скрипт уже завершил работу и все инструкции уже переданы ядру FS. Если ваше IVR приложение обрабатывает тысячи вызовов одновременно, это снизит нагрузку на интерпретатор Lua.

Также Lua скрипт может быть вызван непосредственно из XML диалплана для получения переменных, чтобы затем использовать их при последовательном вызове приложений диалплана прямо в скрипте или передав в XML.

Или же можно генерировать XML блок, как было показано в первом примере.

И конечно можно передавать управление из одной формы диалплана в другую.:

Из Lua в XML:

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

Из XML в Lua:

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

Not found

Если Lua приложение получает запрос, но не находит соответствующий диалплан нужно вернуть результат «not found»

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="result">
    <result status="not found" />
  </section>
</document>

Если возвращается пустой ответ, вместо not found, будет вызвано следующее сообщение о ошибке:

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

Original Page

original pdf

Только авторизованные участники могут оставлять комментарии.
  • freeswitch/db/fs_lua_serv_conf.txt
  • Последние изменения: 2018/11/01