Sofia.conf.xml

From FreeSWITCH Wiki

(Redirected from Sofia Configuration Files)

1 What Sofia Does
2 Sofia Provides Multiple User Agents
- 2.1 Multiple User Agents (Profiles) and the Dialplan
3 Structure of a Profile
4 Directory of Users
5 Default Configuration File
6 Reloading
7 Security Features

What Sofia Does

Sofia is the module that provides SIP connectivity to Freeswitch. Sofia is a "user agent"; that is, Sofia receives calls sent to Freeswitch from other SIP User Agents (UAs), sends calls to other UAs, acts as a client to register Freeswitch with other UAs, lets clients register with Freeswitch, and connects calls (e.g., to local extensions).

If you are looking to add a new SIP Provider to your FreeSWITCH stack please see SIP Provider Examples and add your profile under the conf/directory/default/ location.

[edit]

Sofia Provides Multiple User Agents

The file sofia.conf.xml contains a reference to profiles contained within the conf/sip_profiles directory. Each profile contains a complete description of a SIP UA. When Freeswitch starts, it reads sofia.conf.xml and starts up a separate UA for each profile in the configuration file.

This has an interesting implication: the separate UAs in the config file cannot interfere with each other. For example, each UA has a port that it uses to accept connections, by default port 5060. If multiple profiles are present, each one must select a different port.

[edit]

Multiple User Agents (Profiles) and the Dialplan

Why would I want to create multiple User Agents? Here's an example. In my office, I use a firewall; this means that calls I make to locations outside the firewall must use a STUN server to transverse the NAT in the firewall, while calls within the office don't use a STUN server. In order to accommodate these requirements, I've created two different UAs. One of them uses a STUN server and for that matter also connects up to the PSTN through a service provider. The other UA is purely for local SIP calls.

Now I've got two UAs defined by my profiles, each of which can handle a call. When dialing a SIP address or telephone number, which UA is used? That determination is made in the dialplan. One syntax for making a call via Sofia in the dialplan is

 sofia/profile_name/destination

So, the task becomes rather straightforward. Dialplans use pattern matching and other tricks to determine how to handle a call. My dialplan examines what I've dialed and then determines what profile to use with that call. If I dial a telephone number, the dialplan selects the UA that connects up to the PSTN. If I dial a SIP address outside the firewall, the dialplan selects that same UA because it uses the STUN server. But if I dial a SIP address that's inside the firewall, the dialplan selects the "local" UA.

To understand how to write dialplans, use pattern matching, etc., see Dialplan

[edit]

Structure of a Profile

Each profile may contain several different subsections. At the present time there's no XSD or DTD for sofia.conf.xml — and any volunteer who can create one would be very welcome indeed.

[edit]

Gateway

Each profile can have several gateways:

<gateways>
 <gateway>
   elements...
 </gateway>
</gateways>

A gateway has an attribute "name" by which it can be referred. A gateway describes how to use a different UA to reach destinations. For example, the gateway may provide access to the PSTN, or to a private SIP network. The reason for defining a gateway, presumably, is because the gateway requires certain information before it will accept a call from the FS User Agent.

To reach a particular gateway from the dial plan, use

sofia/gateway/<gateway_name>/<dialstring>

The following is a list of param elements that are children of a gateway element:

<!-- /// account username *required* /// -->
<param name="username" value="foo"/>

<!--/// auth realm: *optional* same as gateway name, if blank ///-->
<!-- realm -->
<param name="realm" value="sip.example.com"/>

<!--/// account password *required* ///-->
<param name="password" value="a password"/>

<!--/// replace the INVITE from user with the channel's caller-id ///-->
<!--/// this is false by default because outbound calls generally need username in the INVITE ///-->
<param name="caller-id-in-from" value="false"/>

<!--/// extension for inbound calls: *optional* same as username, if blank ///-->
<param name="extension" value=""/>

<!--/// proxy host: *optional* same as realm, if blank ///-->
<param name="proxy" value="proxy.example.com"/>

<!--/// expire in seconds: *optional* 3600, if blank ///-->
<param name="expire-seconds" value="3600"/>

<!-- supress CNG on this profile or per call with the 'supress_cng' variable -->
<param name="supress-cng" value="true"/>

<!--/// false: do not register. True: register ///-->
<param name="register" value="false"/>

<!-- check gateway availability: *optional* -->
<param name="ping" value="15"/>

Param "register," is used when this profile acts as a client to another UA. By registering, FS informs the other UA of its whereabouts. This is generally used when FS wants the other UA to send FS calls, and the other UA expects this sort of registration. If FS uses the other UA only as a gateway (e.g., to the PSTN), then registration is not generally required.

The latter param, "ping" is used to check gateway availability. By setting this option, FS will send SIP OPTIONS packets to gateway. If gateway responds with 200 or 404, gateway is pronounced up, otherwise down. If any call is routed to gateway with state down, FS will generate NETWORK_OUT_OF_ORDER hangup cause. Ping frequency is defined in seconds (value attribute).

[edit]

Settings

Settings include other, more general information about the profile, including whether or not STUN is in use. Each profile has its own settings element. Not only is this convenient — it's possible to set up one profile to use STUN and another, with a different gateway or working behind the firewall, not needing STUN — but it's also crucial. That's because each profile defines a SIP User Agent, and each UA must have its own unique "sip-port." By convention, 5060 is the default port, but it's possible to make calls to, e.g., "foo@sip.example.com:5070", and therefore you can define any port you please for each individual profile.

The conf directory contains a complete sample sofia.conf.xml file, along with comments:

<settings>
   <param name="debug" value="1"/>
   <param name="rfc2833-pt" value="101"/>
   <param name="sip-port" value="5060"/> '''remember: each profile must have unique UA'''
   <param name="dialplan" value="XML"/>
   <param name="dtmf-duration" value="100"/>
   <param name="codec-prefs" value="$${global_codec_prefs}"/>
   <param name="codec-ms" value="20"/>
   <param name="use-rtp-timer" value="true"/>
   <param name="rtp-timer-name" value="soft"/>
   <param name="rtp-ip" value="$${bind_server_ip}"/>
   <param name="sip-ip" value="$${bind_server_ip}"/>
   <!-- if you want to send any special bind params of your own -->
   <!--<param name="bind-params" value="transport=udp"/>-->
  
   <!--If you don't want to pass through timestampes from 1 RTP call to another (on a per call basis with rtp_rewrite_timestamps chanvar)-->
   <!--<param name="rtp-rewrite-timestampes" value="true"/>-->
  
   <!--If you have ODBC support and a working dsn you can use it instead of SQLite-->
   <!--<param name="odbc-dsn" value="dsn:user:pass"/>-->
  
   <!--Uncomment to set all inbound calls to no media mode-->
   <!--<param name="inbound-no-media" value="true"/>-->
  
   <!--Uncomment to let calls hit the dialplan *before* you decide if the codec is ok-->
   <!--<param name="inbound-late-negotiation" value="true"/>-->
  
   <!-- this lets anything register -->
   <!--  comment the next line and uncomment one or both of the other 2 lines for call authentication -->
   <param name="accept-blind-reg" value="true"/>
  
   <!--TTL for nonce in sip auth-->
   <param name="nonce-ttl" value="60"/>

   <!--Uncomment if you want to force the outbound leg of a bridge to only offer the codec 
   that the originator is using-->
   <!--<param name="disable-transcoding" value="true"/>-->

   <!-- authenticate all calls against the endpoint directory; if this is not
        set, parameters, such as those set in the <variables></variables> set
        in the directory will never be passed to freeswitch -->
   <!--<param name="auth-calls" value="true"/>-->

   <!-- on authed calls, authenticate *all* the packets not just invite -->
   <!--<param name="auth-all-packets" value="true"/>-->
  
   <!-- <param name="ext-rtp-ip" value="$${external_rtp_ip}"/>-->
  
   <!-- <param name="ext-sip-ip" value="100.101.102.103"/> -->
   <!-- VAD choose one (out is a good choice); -->
   <!-- <param name="vad" value="in"/> -->
   <!-- <param name="vad" value="out"/> -->
   <!-- <param name="vad" value="both"/> -->
   <!--<param name="alias" value="sip:10.0.1.251:5555"/>-->

   <!-- MOH: Music to play when a SIP endpoint puts a call on hold -->
   <!-- <param name="hold-music" value="/sounds/holdmusic.wav" /> -->
   <!--/// context: *optional* dialplan context you would like inbound calls to goto, default is 'default' ///-->
   <param name="context" value="incoming" />
</settings>

VAD stands for Voice Activity Detector. FreeSWITCH is capable of detecting speech and can stop transmitting RTP packets when no voice is detected.

[edit]

STUN

If you need to use a STUN server, here's a common working value:

<param name="ext-rtp-ip" value="stun:stun.fwdnet.net"/>
<param name="ext-sip-ip" value="world_reachable.real.numeric.ip"/>

stun.fwdnet.net is a publicly-accessible STUN server.

[edit]

NATing

PLEASE DOCUMENT

<param name="apply-nat-acl" value="rfc1918"/>

<param name="aggressive-nat-detection" value="true"/>

[edit]

Dialplan

The dialplan parameter is very powerful.

In the simplest configuration, it will use the XML dialplan. This means that it will read data from mod_xml_curl XML dialplans (eg, callback to your webserver), or failing that, from the XML files specified in freeswitch.xml dialplan section. (eg, default_context.xml)

<param name="dialplan" value="XML"/>

You can also add enum lookups into the picture (since mod_enum provides dialplan functionality), so enum lookups override the XML dialplan

<param name="dialplan" value="enum,XML"/>

Or reverse the order to enum is only consulted if XML lookup fails

<param name="dialplan" value="XML,enum"/>

It is also possible to specify a specific enum root

<param name="dialplan" value="enum:foo.com,XML"/>

Or use XML on a custom file

<param name="dialplan" value="XML:/tmp/foo.xm,XML,enum"/>

Where it will first check the specific XML file, then hit normal XML which also do a mod_xml_curl lookup assuming you have that configured and working.

[edit]

Directory of Users

To allow users to register with the server, the user information must be specified in the directory.conf.xml file. To dynamically specify what users can register, use Mod xml curl

[edit]