Freeswitch Module
From OpenSimulator
|
|
*** THIS ARTICLE IS ABOUT THIRD PARTY SOFTWARE *** Although OpenSimulator encourages the development of third party software for OpenSimulator, no support can be provided on this. For help with this software, contact the developer of this software directly.Please do not contact the OpenSimulator team with questions about this software. |
USE THIS GUIDE ONLY FOR OpenSim 0.6.9, 0.7.0.1 and 0.7.0.2. The latest 0.7.1 dev versions have changed the configuration arrangements which are still being revised and checked. See
The FreeSWITCH module enables voice in OpenSim with no changes required to the Linden Labs Second Life viewer (must be between 1.22 and 1.23.5 - 2.x viewers do not work at present), Hippo viewer (0.5 or after), and perhaps others using SLvoice.exe module.
A little history on the development of the FreeSWITCH module is given here:
Contents |
FreeSwitch Install
Follow the instructions here on how to compile from source. We need to enable two specific modules. Please ensure you compile from the freeswitch trunk for now until we can post a minimum version number (there are known issues with older versions)
Make sure to install the hold music if you are not going to disable it in the "configure conference.conf.xml" section below.
When you get to the part in the instructions where it says "Edit modules.conf so that it will build the modules you desire." edit the modules.conf file and uncomment to make active the entries for xml_curl and the siren14 codec
codecs/mod_siren and xml_int/mod_xml_curl
Note: Freeswitch Git master as of 18th April 2011 already has codecs/mod_siren configured
FreeSwitch Config
enable mod_xml_curl
Next, do not forget to activate mod_xml_curl in /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml. mod_xml_curl is disabled by default on fresh install.
uncomment the lines...
<load module="mod_xml_curl"/>
and
<load module="mod_siren"/>
Note: Freeswitch Git master as of 18th April 2011 already has mod_siren configured
configure mod_xml_curl
mod_xml_curl is a freeswitch module which enables dynamic configuration of freeswitch from a web server. In this case, it is the opensim region server.
The xml_curl module configuration should point to an opensim region that has the Freeswitch voice module enabled (voice also needs to be enabled in the estate setting for all regions you wish to be supported).
example xml_curl.conf.xml found in /usr/local/freeswitch/conf/autoload_configs
The example below uses the OpenSim region server and port (default 9000) for standalones. It also uses an URL path of "/api" which is correct for 0.6.9, 0.7.0.1 and 0.7.0.2 for both standalones and grids.
<configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
<binding name="example">
<param name="gateway-url" value="http://youropensimregionip:9000/api/freeswitch-config" bindings="directory"/>
<param name="gateway-credentials" value="freeswitch:password"/>
<param name="disable-100-continue" value="true"/>
</binding>
<binding name="local">
<param name="gateway-url" value="http://youropensimregionip:9000/api/freeswitch-config" bindings="dialplan"/>
<param name="gateway-credentials" value="freeswitch:password"/>
<param name="disable-100-continue" value="true"/>
</binding>
</bindings>
</configuration>
For current OpenSim Git master use "/fsapi" and the appropriate server and port - youropensimregionip and default port 9000 for standalones and yourrobustserverip and default port 8002 for grids.
<configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
<binding name="example">
<param name="gateway-url" value="http://yourrobustserverip:8002/fsapi/freeswitch-config" bindings="directory"/>
<param name="gateway-credentials" value="freeswitch:password"/>
<param name="disable-100-continue" value="true"/>
</binding>
<binding name="local">
<param name="gateway-url" value="http://yourrobustserverip:8002/fsapi/freeswitch-config" bindings="dialplan"/>
<param name="gateway-credentials" value="freeswitch:password"/>
<param name="disable-100-continue" value="true"/>
</binding>
</bindings>
</configuration>
This configuration instructs freeswitch to obtain the "dialplan" and "directory" configuration from opensim (as mentioned by the bindings attributes). For the rest of the configuration, freeswitch will consult its static xml files. More details on mod_xml_curl module can be found here.
configure vars.xml
Note: Freeswitch Git master as of 18th April 2011 already has this configured
The /usr/local/freeswitch/conf/vars.xml requires modification to enable the siren14 codec
search within vars.xml for the global_codec_prefs and change the line to read
<X-PRE-PROCESS cmd="set" data="global_codec_prefs=G7221@32000h,G722,PCMU,PCMA,GSM"/>
or
<X-PRE-PROCESS cmd="set" data="global_codec_prefs=G7221@32000h,G7221@16000h,G722,PCMU,PCMA,GSM"/>
G7221@32000h is the siren14 codec
configure conference.conf.xml
By default, FreeSwitch plays hold music when there is only one avatar in the conference and beeps for everyone when avatars arrive and leave. To disable, edit /usr/local/freeswitch/conf/autoload_configs/conference.conf.xml. Locate the "default" profile and comment out the following lines as shown below:
[...]
<!-- File to play if you are alone in the conference -->
<!-- <param name="alone-sound" value="conference/conf-alone.wav"/> -->
[...]
<!-- File to play when you're alone (music on hold)-->
<!-- <param name="moh-sound" value="$${hold_music}"/> -->
<!-- File to play when you join the conference -->
<!-- <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/> [^] -->
<!-- File to play when you leave the conference -->
<!-- <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/> [^] -->
<!-- File to play when you ae ejected from the conference -->
<!-- <param name="kicked-sound" value="conference/conf-kicked.wav"/> -->
[...]
OpenSim Config for current Git master
Standalone
The configuration is explained in OpenSim.ini.example. Here's one example
[FreeSwitchVoice] ;; In order for this to work you need a functioning FreeSWITCH PBX set up. ;; Configuration details at http://opensimulator.org/wiki/Freeswitch_Module Enabled = true ;; You need to load a local service for a standalone, and a remote service ;; for a grid region. Use one of the lines below, as appropriate ;; If you're using Freeswitch on a standalone then you will also need to configure the [FreeswitchService] section LocalServiceModule = OpenSim.Services.FreeswitchService.dll:FreeswitchService ; LocalServiceModule = OpenSim.Services.Connectors.dll:RemoteFreeswitchConnector ;; If using a remote connector, specify the server URL ; FreeswitchServiceURL = http://my.grid.server:8003/fsapi [FreeswitchService] ;; !!!!!!!!!!!!!!!!!!!!!!!!!!! ;; !!!!!!STANDALONE ONLY!!!!!! ;; !!!!!!!!!!!!!!!!!!!!!!!!!!! ;; The IP address of your FreeSWITCH server. The common case is for this to be the same as the server running the OpenSim standalone ;; This has to be set for the FreeSWITCH service to work ServerAddress = 192.168.1.2 ;; The following configuration parameters are optional ;; By default, this is the same as the ServerAddress ; Realm = 127.0.0.1 ;; By default, this is the same as the ServerAddress on port 5060 ; SIPProxy = 127.0.0.1:5060 ;; Default is 5000ms ; DefaultTimeout = 5000 ;; The dial plan context. Default is "default" ; Context = default ;; Currently unused ; UserName = freeswitch ;; Currently unused ; Password = password ;; The following parameters are for STUN = Simple Traversal of UDP through NATs ;; See http://wiki.freeswitch.org/wiki/NAT_Traversal ;; stun.freeswitch.org is not guaranteed to be running so use it in ;; production at your own risk ; EchoServer = 127.0.0.1 ; EchoPort = 50505 ; AttemptSTUN = false
In this case, the FreeSWITCH server is running on 192.168.1.2. No other files need to be configured.
OpenSim Config for 0.7.0.2 and earlier
Standalone
Add the following to your OpenSim.ini
[FreeSwitchVoice] Enabled = true LocalServiceModule = "OpenSim.Services.FreeswitchService.dll:FreeswitchService" [FreeswitchService] ServerAddress = youropensimregionip Realm = "youropensimregionip"
Grid Mode
Add the following to your OpenSim.ini
[FreeSwitchVoice] Enabled = true LocalServiceModule = OpenSim.Services.Connectors.dll:RemoteFreeswitchConnector FreeswitchServiceURL = http://ip.of.your.robust.server.for.freeswitch.connector:8002/fsapi
Add the following to your Robust.ini or Robust.HG.ini
[FreeswitchService] LocalServiceModule = OpenSim.Services.FreeswitchService.dll:FreeswitchService ServerAddress = ip.of.your.robust.server.for.freeswitch.connector Realm = "ip.of.your.robust.server.for.freeswitch.connector"
If your Freeswitch complains about an unknown domain, you have probably mixed ips and host names. You should always use dotted quad IP addresses, as there are string compares done on them in Freeswitch code and a name and it's corresponding address are not considered to be the same!
Firewall Config
Basically open ports 1720 and 5060, and maybe 50505 must be open for listening.
Make sure that the ports used by Freeswitch are accessible though your firewall(s). In the example above the main port used is 5060 though other ports may be used for call initiation (port 1720 for H.323 Call Signalling) and dynamically assigned ports for specific call traffic. The usual H.323 and SIP traffic dynamic port handling on modern firewalls usually enables this.
Is port 50505 actually used, or is it just something that must be reported by OpenSim when the Freeswitch service makes contact?
More details on the Freeswitch ports used and firewall configuration details are at http://wiki.freeswitch.org/wiki/Firewall
If you have problems with NAT/Routers look at using STUN (Simple Traversal of UDP through NATs). More information at http://wiki.freeswitch.org/wiki/NAT_Traversal
Issues and Solutions
NOTE: FreeSwitch is not a core module and help may not be forthcoming to handle issues.
MAKE SURE the OpenSim region you point Freeswitch at IS NOT running when you start FreeSwitch.
ALSO make sure that you have enabled voice in the "About Land"->"Voice" dialogue in the region, you will need to be a region admin to do this.
Check the plot also has voice enabled. You must be a plot owner or have suitable permisison to do this. Recent Linden Labs Second Life viewers do not offer this option, so use Hippo or another client which does.
| Issue |
Resolution |
|---|---|
| --[ERR] mod_xml_curl.c:230 xml_url_fetch() Received HTTP error 0 trying to fetch: |
To solve this error, get the last GIT of FreeSwitch, follow this instructions (for Ubuntu) here |
| --mod_event_socket.c -> Socket Error Could not listen on 127.0.0.1:5060: |
This means something is using the port 5060, usually freeswitch is already running, on Ubuntu, try the following command: netstat -npl | grep 85060 If freeswitch is running, close is with: sudo freeswitch -stop OR sudo invoke-rc.d freeswitch stop |
| --[ERR] [WARNING] sofia_reg.c:1540 sofia_reg_parse_auth()Can't find user [x8cOXAiIzTVC6xqf-nquLkw==@"some ip or domain here"] etc ... | a solutions to this error is, mod your vars.xml replacing the domain lines <X-PRE-PROCESS cmd="set" data="domain=whatever is in the realm setting of your freeswitch config"/> <X-PRE-PROCESS cmd="set" data="domain_name=whatever is in the realm setting of your freeswitch config"/> - Now this will most likely break your freeswitch for anything other than your opensim. But should get you closer |
| --[WARNING] mod_local_stream.c:393 Unknown source moh, trying 'default'
[ERR] mod_local_stream.c:402 Unknown source default |
If you see these log messages continuously on the Freeswitch console, then you have either not disabled the conference sounds or you have not installed them (see earlier). |
Use some of the debugging features in FreeSWITCH:
- conference list <--- to see if you have any conferences setup (note you have to be inworld when you try this)
- xml_curl debug_on <--- this command will dump the transactions between OpenSim and FreeSWITCH into a file (on linux it is in /tmp)
- xml_curl debug_off <-- turn it off after you login/logout a few times
Notes from Openvue Grid setup for FreeSwitch
Using Windows Vista 32 bit OS. Works with FreeSwitch 1.0.4 and later (for a specific tested example, FreeSWITCH Version 1.0.head (git-e0c37c1 2010-11-05 18-20-09 -0500)).
Additional notes that might help:
1. We established a simple OpenSim.exe on the SAME host as the FreeSwitch.exe service and put a single simple island on that (we called it "Talk") as some folks observed that FreeSwitch had problems with connecting if it was CONFIGURED to link to another server, but we don't believe this is necessary.
2. FreeSwitch provides service to all OpenSim.exe instances on any servers you wish even though its only configured for one.
3. There is one FreeSwitch channel per region, change regions and you change channel. So all users to talk must be on the same region. All plots on one region share the same single region channel.
4. You appear as one user in the SL Viewers, ALL other users appear as a single "user" with a coded name for the other users on the channel - something like conf-x9999999999999999999.
5. You must have voice enabled at the region, AND the plot level. This is a pain, as the default setting in OpenSim is that PLOTS have voice turned off. The standard viewers 1.23 and 2.x do not allow you to turn this back on, so you must use a third party viewer to turn on PLOT voice. I have asked before that we change the default setting when a plot is created to have this on by default (or on if the region voice is on - which it is by default).
6. We are not sure if you MUST start FreeSwitch.exe before the regions that you want voice to work on. But we do so for safety. It works fine over OpenSim.exe restarts without FreeSwitch being started again.
7. If you wish to use FreeSwitch beyond your local network, remember to configure for EXTERNALLY accessible IP addresses. Use IP numbers for FreeSwitch... and if there are 192.168.x.x style local net addresses in there you will not get FreeSwitch to work with external users. It can work through a range of firewalls with suitable mechanisms such as port forwarding or DMZs, so long as you definitely map to the externally visible IP address. Ensure you have the appropriate ports open in your Firewall(s). See separate section in Wiki on ports required.
8. There are some red errors on startup of FreeSwitch - at least in our setup - which appears to be related to a missing config file that FreeSwitch tries to retrieve from OpenSim (opensim-region-server-url:port/api/freeswitch-config) that is not in the OpenSim setup... We have (safely?) ignored those without problems...
2010-11-13 14:42:55.252361 [ERR] mod_xml_curl.c:252 Received HTTP error 0 trying to fetch http://129.215.219.143:9000/api/freeswitch-config data: [hostname=shuna§ion=directory&tag_name=domain&key_name=name&key_value= 129.215.219.143&Event-Name=GENERAL&Core-UUID=cb64ea40-aa92-494b-be13-65d9c468efe c&FreeSWITCH-Hostname=shuna&FreeSWITCH-IPv4=129.215.219.143&FreeSWITCH-IPv6=2002 %3A81d7%3Adb8f%3A%3A81d7%3Adb8f&Event-Date-Local=2010-11-13%2014%3A42%3A54&Event -Date-GMT=Sat,%2013%20Nov%202010%2014%3A42%3A54%20GMT&Event-Date-Timestamp=12896 59374247361&Event-Calling-File=switch_core.c&Event-Calling-Function=switch_load_ network_lists&Event-Calling-Line-Number=984&domain=129.215.219.143&purpose=network-list]
9. By default, FreeSwitch plays hold music when there is only one avatar in the conference and beeps for everyone when avatars arrive and leave. To disable, edit /usr/local/freeswitch/conf/autoload_configs/conference.conf.xml. Locate the "default" profile and comment out the relevant lines. See examples above on this Wiki page.
