Mod xml curl
From FreeSWITCH Wiki
Contents |
Overview
mod_xml_curl can be used to dynamically control the behaviour of FreeSWITCH™. FreeSWITCH™ will call mod_xml_curl when it needs to get information that it would normally read from the XML configuration files. By using mod_xml_curl, you can provide the same configuration to multiple instances of FreeSWITCH™ without having to duplicate the configuration. As you can imagine, this is the way to go when you want to scale up your system with multiple switches.
The module can be used to get any information that would be in freeswitch.xml.
Section names are passed to the script(s) on the webserver; currently, section names include:
- configuration - configuration items, ie. for mod_sofia or mod_dingaling
- directory - user directory
- dialplan - Dialplan items (for call routing)
- phrases - phrases for the SAY api (Speech Phrase Management)
Once you load the xml_curl module, all future attempts to access XML will be sent to the web server for any of the subscribed sections ("bindings"). To process only partial parts of a section (the public context of the dialplan, for example), just return nothing for all other requests, and FreeSWITCH will attempt to find the rest of the section in the static XML files, in /dialplan/default.xml. At a minimum you must have a modules.conf section which loads the mod_xml_curl module, a mod_xml_curl configuration section, and it is recommended that you have a logger module installed so you can see if anything goes wrong. Additional modules are loaded via the post_load_modules.conf file, which has basically the same format as modules.conf.
There is a PHP example that does everything from a webserver, with per switch configuration capability in FreeSWITCH™ SVN (scripts/contrib/trixter/xml-curl). This can be used for total switch provisioning from a webserver, providing a template for a web based management and control suite for FreeSWITCH™.
Activate
First at all, do not forget to activate mod_xml_curl in modules.conf.xml.
mod_xml_curl is disabled by default on fresh install.
<load module="mod_xml_curl"/>
Please put the xml_curl entry more to the top of your modules.conf.xml file, do not put it at the end. Otherwise most of the configurations will not be requested from the external server. In setting the xml_curl entry more to the end of the file you may thus control, for which module a request is being sent to the external server and thus reduce the number of external requests (and save time).
Configuring
The file conf/xml_curl.conf.xml is used in the default FreeSWITCH™ setup.
Here is a minimum configuration file, it will fetch a dialplan from localhost, port 8080.
<configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
<binding name="dialplan fetcher">
<param name="gateway-url" value="http://localhost:8080" bindings="dialplan"/>
</binding>
</bindings>
</configuration>
Here is a slightly more advanced configuration, with a backup webserver that will be used if the primary server is non-responsive. The binding blocks are processed in sequential order, in a failover manner.
<configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
<binding name="dialplan fetcher">
<param name="gateway-url" value="http://localhost:8080" bindings="dialplan"/>
</binding>
<binding name="backup dialplan fetcher">
<param name="gateway-url" value="http://anotherhost:8080" bindings="dialplan"/>
</binding>
</bindings>
</configuration>
If you're using lighttpd as your web server, you may want receive some errors regarding "Expect: 100". You can turn them off by adding this string to your binding:
<param name="disable-100-continue" value="true"/>
Bindings
You may have more than one 'bindings' section, each fetching one type of information from somewhere. mod_xml_curl will POST a query string to the webserver with information about what it wants to fetch. More about this in the section below.
You may also have multiple bindings of the same type, FreeSWITCH™ will then visit each binding until it receives a match back from the server.
Binding
A binding provides information about the webserver that mod_xml_curl will visit, and what type of information to fetch.
You can also provide authentication options, although only HTTP-Basic will be used. This means that you should not use any sensitive passwords. You may be able to get around this issue by using HTTPS on the webserver.
Here is a binding example where you provide authentication (should be placed in the <bindings> tag)
<binding name="dialplan fetcher with authentication">
<param name="gateway-url" value="http://localhost:8080" bindings="dialplan"/>
<param name="gateway-credentials" value="muser:mypass"/>
</binding>
- binding name - The binding name is only added for your convenience, used only to describe the binding.
- gateway-url - The URL that should be visited to fetch information
- bindings - The bindings that this URL can give you information about, separate bindings with a 'pipe' character (|), example: dialplan|directory
You may also create 3 binding structures, one each for dialplan, directory and configuration
Examples
- Perl/CGI example - (by James Jones <james _at_ virtualrealmsoftware.com>)
- PHP example
- C# example
- Ruby dialplan example - very simple database (MySQL) driven Dialplan XML routing. (Jonathan Towne <jontow _at_ zenbsd.net>)
- Ruby directory example - very simple database (PostgreSQL) driven User Directory. (Jonathan Towne <jontow _at_ zenbsd.net>)
- Python/Django example - directory
bindings="configuration"
Request
FreeSWITCH™ will make a series of POST requests to your webserver to retrieve configuration information for each module.
The POST will contain a query string with the following values:
- key_value = iax.conf|event_socket.conf|sofia.conf|...
- key_name = name
- section = configuration
- tag_name = configuration
The format of the query string is:
key_value=<value>&key_name=<name>§ion=configuration&tag_name=configuration
Response
The response must look like this:
<document type="freeswitch/xml">
<section name="configuration">
<!--The content of the tag SECTION is identical to what you find in the default config files.-->
<configuration name="SECTIONNAME.conf" description="SECTIONDESCRIPTION">
<settings>
<!--ADD your parameters here-->
</settings>
</configuration>
</section>
</document>
At least for sofia.conf you should provide the whole XML structure between and including the <configuration> tags, not only the settings part. You can get a template for this section from log/freeswitch.xml.fsxml .
bindings="directory"
User directory: used to provide information about user agents, or prevent them from logging in (See: XML User Directory Guide)
Note that the parameter "accept-blind-reg" must be set to "false" in sofia.conf.xml, your web page will not get called otherwise.
Request
Some useful Request parameters
- name - name of the requested user
- domain - domain that the user has specified
- ip - IP address that the user sent the request from.
- profile - name of the sip profile the user agent is attempting to register with.
A complete query string (I've configured 192.168.0.58 as my domain in FreeSWITCH™):
section=directory&tag_name=domain&key_name=name&key_value=192.168.0.58&domain=192.168.0.58&name=jonas&ip=192.168.0.58
Reply
Sample reply:
<document type="freeswitch/xml">
<section name="directory">
<domain name="192.168.0.58">
<user id="jonas">
<params>
<param name="password" value="jonas" />
</params>
</user>
</domain>
</section>
</document>
bindings="dialplan"
See also: Dialplan
This option retrieves call routing details from the webserver in a similar manner to other binding methods.
Request
FreeSWITCH™ will POST a request to your webserver with information about the incoming call.
The query string will look like something like this (everything is sent in one line, it is wrapped for readability):
section=dialplan&tag_name=&key_name=&key_value=&context=default&destination_number=556 &caller_id_name=FreeSwitch&caller_id_number=5555551212&network_addr=&ani=&aniii=&rdnis= &source=mod_portaudio&chan_name=PortAudio/556&uuid=b7f0b117-351f-9448-b60a-18ff91cbe183 &endpoint_disposition=ANSWER
- section - What kind of information that is requested (dialplan, configuration or directory)
- tag_name -
- key_name -
- key_value -
- context - What configuration context to fetch, normally "default" unless you have multiple contexts.
- destination_number - Number called
- caller_id_name - Name of the calling user
- caller_id_number - Number of the calling user
- network_addr - IP address of the called user.
- ani - Phone number that the user called from (if calling from PSTN)
- aniii -
- rdnis -
- source - source technology, ie. mod_sofia, mod_portaudio, mod_dingaling, etc.
- chan_name - parsable channel name
- uuid - Unique identifier for this call, will follow the call as long as it's in FreeSWITCH™
- endpoint_disposition - Call state when mod_xml_curl requests information
Reply
Here is a sample reply. You will only need to send one extension back, and a condition is required to parse properly.
Your condition may be elaborate or simply '<condition>'.
<?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="test9">
<condition field="destination_number" expression="^83789$">
<action application="bridge" data="iax/guest@conference.freeswitch.org/888"/>
</condition>
</extension>
</context>
</section>
</document>
General "Not found" reply
If you do not have a match AND you would like FreeSWITCH™ to stop looking, you should return a "not found" result.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
<section name="result">
<result status="not found" />
</section>
</document>
Debugging
To help with debugging your configuration, type xml_curl debug_on at the command line in freeswitch. It will return a filename with the resulting XML for each xml_curl query.
