FreeSwitch for OpenSim: Windows Installation and Configuration

Stephen Potter, AIAI, 2010-11-03

Installation

To install, open the file freeswitch.msi, and follow the on-screen instructions. Install FreeSwitch in some convenient location on the computer.

FreeSwitch Configuration

There are a number of configuration settings that need to be made/checked (details sourced from http://opensimulator.org/wiki/Freeswitch_Module):

Enable mod_xml_curl

Ensure that mod_xml_curl is activated in [freeswitch-dir]\conf\autoload_configs\modules.conf.xml

If commented out, uncomment the lines...

    <load module="mod_xml_curl"/>

and

    <load module="mod_siren"/>

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 [freeswitch-dir]\conf\autoload_configs:

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

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.

The file [freeswitch-dir]\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 [freeswitch-dir]\conf\autoload_configs\conference.conf.xml. Locate the "default" profile and comment out 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 Configuration

Add the following section to OpenSim.ini. You will also need to enable voice in the regions estate settings. Make sure the freeswitch server is started BEFORE bringing the region up.

  [FreeSwitchVoice]
  enabled = true
  ; FreeSwitch server is going to contact us and ask us all sorts of things.
  freeswitch_server_user = freeswitch
  freeswitch_server_pass = password
  freeswitch_api_prefix = /api
  ; IP address of an opensim region with voice enabled
  freeswitch_service_server = youropensimregionip
  ; the port your Opensim region is running on
  freeswitch_service_port = 9000
  ; your freeswitch IP address
  freeswitch_realm = yourfreeswitchserverip
  freeswitch_sip_proxy = yourfreeswitchserverip:5060
  ; STUN = Simple Traversal of UDP through NATs
  ; See http://wiki.freeswitch.org/wiki/NAT_Traversal
  freeswitch_attempt_stun = false
  freeswitch_stun_server = stun.freeswitch.org
  ; Echo server MAY not used but information MAY be
  ; required to relay to Freeswitch server (TBC?)
  freeswitch_echo_server = yourfreeswitchserverip
  freeswitch_echo_port = 50505
  freeswitch_well_known_ip = yourfreeswitchserverip
  freeswitch_default_timeout = 5000
  freeswitch_subscribe_retry = 120
  ; freeswitch_password_reset_url =
  ; opensim_well_known_http_address = youropensimregionip
  ; CHECK THIS...  should be Address_Of_Your_SIM_HTTP_Server_Hostname_Allowed

Note that if you are running in OpenSim grid mode, a single Freeswitch service on yourfreeswitchserverip can support multiple regions on one or more Opensim.exe running on one or more hosts. And the Freeswitch server need not be on the same host as the Opensim.exe used to anchor the connection.

Note STUN server "stun.freeswitch.org" is an example only, and its availability should not be relied upon for a service.

Firewall Configuration

Make sure that the ports used by Freeswitch are acessible 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 Signaling) and dynamically assigned ports for specific call traffic. The usual H.323 and SIP traffic dynamic port handling on modern firewalls usually enables this.

(Note, not clear that port 50505 is actually used, or is 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 & Solutions

NOTE: FreeSwitch is not a core OpenSime module and help may not be forthcoming from that source.

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.