Sofia SIP Stack

Sofia is a SIP stack used by FreeSWITCH. When you see “sofia” anywhere in your configuration, think “This is SIP stuff.” It takes a while to master it all, so please be patient with yourself. SIP is a crazy protocol and it will make you crazy too if you aren’t careful. Read on for information on setting up SIP/Sofia in your FreeSWITCH configuration.

mod_sofia exposes the Sofia API and sets up the FreeSWITCH SIP endpoint.

Endpoint

A FreeSWITCH endpoint represents a full user agent and controls the signaling protocol and media streaming necessary to process calls. The endpoint is analogous to a physical VoIP telephone sitting on your desk. It speaks a particular protocol such as SIP or Verto, to the outside world and interprets that for the FreeSWITCH core.

Configuration Files

sofia.conf.xml contains the configuration settings for mod_sofiaSee Sofia Configuration Files.

SIP profiles

See SIP profiles section in Configuring FreeSWITCH.

What if these commands don’t work for me?

Make sure that you are not running another SIP server at the same time as FreeSWITCH. It is not always obvious that another SIP server is running. If you type in Sofia commands such as ‘sofia status profile default’ and it doesn’t work then you may have another SIP server running. Stop the other SIP server and restart FreeSWITCH.On Linux, you may wish to try, as a superuser (often “root”):netstat -lunp | less# -l show listeners, -u show only UDP sockets,# -n numeric output (do not translate addresses or UDP port numbers)# -p show process information (PID, command). Only the superuser is allowed to see this infoWith the less search facility (usually the keystroke “/”), look for :5060 which is the usual SIP port.To narrow the focus, you can use grep. In the example configs, port 5060 is the “internal” profile. Try this:netstat -lnp | grep 5060See if something other than FreeSWITCH is using port 5060.

Sofia Recover

sofia recoverYou can ask Sofia to recover calls that were up, after crashing (or other scenarios).Sofia recover can also be used, if your core db uses ODBC to achieve HA / failover.For FreeSWITCH HA configuration, see Freeswitch HA.

Flushing and rebooting registered endpoints

You can flush a registration or reboot specific registered endpoint by issuing a flush_inbound_reg command from the console.freeswitch> sofia profile <profile_name> flush_inbound_reg [<call_id>|user@host] [reboot]If you leave out <call_id> and/or user@host, you will flush/reboot every registered endpoint on a profile.

Note: For polycom phone, the command causes the phone to check its configuration from the server. If the file is different (you may add extra space at the end of file), the phone will reboot. You should not change the value of voIpProt.SIP.specialEvent.checkSync.alwaysReboot=“0” to “1” in sip.cfg as that allows potential a DOS attack on the phone.

You can also use the check_sync command:sofia profile <profile_name> check_sync <call_id> | user@domain

Note: The polycom phones do not reload -directory.xml configuration in response to either of these commands, they only reload the configuration. If you want new speed dials to take effect, you’ll need to do a full reboot of the phone or enable the alwaysReboot option. (Suggestions from anyone with more detailed PolyCom knowledge would be appreciated here.)

Starting a new profile

If you have created a new profile you need to start it from the console:freeswitch> sofia profile <new_profile_name> start

Reloading profiles and gateways

You can reload a specific SIP profile by issuing a rescan/restart command from the consolefreeswitch> sofia profile <profile_name> [|] reloadxmlThe difference between rescan and restart is that rescan will just load new config and not stop FreeSWITCH from processing any more calls on a profile.** Some config options like IP address and (UDP) port are not reloaded with rescan.**

Deleting gateways

You can delete a specific gateway by issuing a killgw command from the console. If you use all as gateway name, all gateways will be killedfreeswitch> sofia profile <profile_name> killgw <gateway_name>

Restarting gateways

You can force a gateway to restart ( good for forcing a re-registration or similar ) by issuing a killgw command from the console followed by a profile rescan. This is safe to perform on a profile that has active calls.freeswitch> sofia profile <profile_name> killgw <gateway_name>freeswitch> sofia profile <profile_name> rescan

Adding / Changing Existing Gateways

It will be assumed that you have all your gateways in the /usr/local/freeswitch/conf/sip_profiles/external directory and that you have just created a new entry. You can add a new gateway to FreeSWITCH by issuing a rescan reloadxml command from the console as seen in the example below. This will load the newly created gateway and not affect any calls that are currently up.freeswitch> sofia profile external rescan reloadxml

You now realize that you have screwed up the IP address in the new gateway and need to change it. So you edit your gateway file and make any changes that you want. You will then need to issue the following commands to destroy the gateway, and then have FreeSWITCH reload the changes with affecting any existing calls that are currently up.

freeswitch> sofia profile external killgw <gateway_name>freeswitch> sofia profile external rescan reloadxml

View SIP Registrations

You can view all the devices that have registered by running the following from the console.freeswitch> sofia status profile regfreeswitch> sofia status profile default regfreeswitch> sofia status profile outbound regYou can also use the xmlstatus key to retrieve statuses in XML format. This is specially useful if you are using mod_xml_rpc.Commands are as follows:freeswitch> sofia xmlstatus profile regfreeswitch> sofia xmlstatus profile default regfreeswitch> sofia xmlstatus profile outbound reg

List the status of gateways

For the gateways that are in-service:freeswitch> sofia profile gwlist upFor the gateways that are out-of-service:freeswitch> sofia profile gwlist downNotes:

It should be used together with . See Sofia_Configuration_Files
It can also be used to feed into mod distributor to exclude dead gateways.

List gateway data

To retrieve the value of an inbound variable:sofia_gateway_data <gateway_name> ivar To retrieve the value of an outbound variable:sofia_gateway_data <gateway_name> ovar To retrieve the value of either use:sofia_gateway_data <gateway_name> var This first checks for an inbound variable, then checks for an outbound variable if there’s no matching inbound.

View User Presence Data

Its possible to retrieve only one valuesofia_presence_data status */2005Away

You can use this value in the dialplan, e.g.

Debugging Sofia-SIP

The Sofia-SIP components can output various debugging information. The detail of the debugging output is determined by the debugging level. The level is usually module-specific and it can be modified by module-specific environment variable. There is also a default level for all modules, controlled by environment variable #SOFIA_DEBUG.The environment variables controlling the logging and other debug output are as follows:- #SOFIA_DEBUG Default debug level (0..9)- #NUA_DEBUG User Agent engine (nua) debug level (0..9)- #SOA_DEBUG SDP Offer/Answer engine (soa) debug level (0..9)- #NEA_DEBUG Event engine (nea) debug level (0..9)- #IPTSEC_DEBUG HTTP/SIP authentication module debug level (0..9)- #NTA_DEBUG Transaction engine debug level (0..9)- #TPORT_DEBUG Transport event debug level (0..9)- #TPORT_LOG If set, print out all parsed SIP messages on transport layer- #TPORT_DUMP Filename for dumping unparsed messages from transport- #SU_DEBUG su module debug level (0..9)The defined debug output levels are:- 0 SU_DEBUG_0() - fatal errors, panic- 1 SU_DEBUG_1() - critical errors, minimal progress at subsystem level- 2 SU_DEBUG_2() - non-critical errors- 3 SU_DEBUG_3() - warnings, progress messages- 5 SU_DEBUG_5() - signaling protocol actions (incoming packets, …)- 7 SU_DEBUG_7() - media protocol actions (incoming packets, …)- 9 SU_DEBUG_9() - entering/exiting functions, very verbatim progressStarting with 1.0.4, those parameters can be controlled from the console by doingfreeswitch> sofia loglevel <all|default|tport|iptsec|nea|nta|nth_client|nth_server|nua|soa|sresolv|stun> [0-9]“all” Will change every component’s loglevelA log level of 0 turns off debugging, to turn them all off, you can dofreeswitch> sofia loglevel all 0To report a bug, you can turn on debugging with more verbosesofia global siptrace onsofia loglevel all 9sofia tracelevel alertconsole loglevel debugfsctl debug_level 10

Debugging presence and SLA

As of Jan 14, 2011, sofia supports a new debugging command: sofia global debug. It can turn on debugging for SLA, presence, or both. Usage is:sofia global debug slasofia global debug presencesofia global debug noneThe first two enable debugging SLA and presence, respectively. The third one turns off SLA and/or presence debugging.

Sample Export (Linux/Unix)

Alternatively, the levels can also be read from environment variables. The following bash commands turn on all debugging levels, and is equivalent to “sofia loglevel all 9”export SOFIA_DEBUG=9export NUA_DEBUG=9export SOA_DEBUG=9export NEA_DEBUG=9export IPTSEC_DEBUG=9export NTA_DEBUG=9export TPORT_DEBUG=9export TPORT_LOG=9export TPORT_DUMP=/tmp/tport_sip.logexport SU_DEBUG=9To turn this debugging off again, you have to exit FreeSWITCH and type unset. For example:unset TPORT_LOG

Sample Set (Windows)

The following bash commands turn on all debugging levels.set SOFIA_DEBUG=9set NUA_DEBUG=9set SOA_DEBUG=9set NEA_DEBUG=9set IPTSEC_DEBUG=9set NTA_DEBUG=9set TPORT_DEBUG=9set TPORT_LOG=9set TPORT_DUMP=/tmp/tport_sip.logset SU_DEBUG=9To turn this debugging off again, you have to exit FreeSWITCH and type unset. For example:set TPORT_LOG=You can also control SIP Debug output within fs_cli, the FreeSWITCH client app.freeswitch> sofia profile siptrace on|offOn newer software release, you can now be able to issue siptrace for all profiles:sofia global siptrace [on|off]

To have the SIP Debug details put in the /usr/local/freeswitch/log/freeswitch.log file, usefreeswitch> sofia tracelevel info (or any other loglevel name or number)To have the SIP details put into the log file automatically on startup, add this to sofia.conf.xml:<global_settings>……</global_settings>

and the following to the sip profile xml file:…………

Profile Configurations

Track Call

ACL

You can restrict access by IP address for either REGISTERs or INVITEs (or both) by using the following options in the sofia profile.See ACL for other access controlsSee acl.conf.xml for list configuration

Disabling Hold

Disable all calls on this profile from putting the call on hold:

See also: rtp_disable_hold variable

Using A Single Domain For All Registrations

You can force all registrations in a particular profile to use a single domain. In other words, you can ignore the domain in the SIP message. You will need to modify several sofia profile settings.

challenge realm

auto_from - uses the from field as the value for the SIP realm.
auto_to - uses the to field as the value for the SIP realm.
- you can input any value to use for the SIP realm.

force-register-domain

Preference Weight Transport Port Address================================================================================1 0.500 udp 5060 74.51.38.151 0.500 tcp 5060 74.51.38.15

Flushing Inbound Registrations

From time to time, you may need to kill a registration.You can kill a registration from the CLI, or anywhere that accepts API commands with a command similar to the following:sofia profile <profile_name_here> flush_inbound_reg [optional_callid]

Dial out of a gateway

Basic form:sofia/gateway//<number_to_dial>Example 1:sofia/gateway/asterlink/18005551212gateway: is a keyword and not a “gateway” name. It has special meaning and tells the stack which credentials to use when challenged for the call. is the actual name of the gateway through which you want to send the call

Your available gateways (usually configured in conf/sip_profiles/external/*.xml) will show up in sofia status:freeswitch#> sofia status

Name Type Data State=================================================================================================default profile sip:mod_sofia@2.3.4.5:5060 RUNNING (2)mygateway gateway sip:username@1.2.3.4 NOREGphonebooth.example.com alias default ALIASED=================================================================================================1 profile 1 alias

Modifying the To: header

You can override the To: header by appending ^.Example 1:sofia/foo/user%192.168.1.1^101@$${domain}

Specifying SIP Proxy With fs_path

You can route a call through a specific SIP proxy by using the “fs_path” directive. Example:sofia/foo/user@that.domain;fs_path=sip:proxy.this.domain

Safe SIP URI Formatting

As of commit https://freeswitch.org/stash/projects/FS/repos/freeswitch/commits/76370f4d1767bb0dcf828a3d6cde6e015b2cfa03 the User part of the SIP URI has been “safely” encoded in the case where spaces or other special characters appear.

Channel Variables

Adding Request Headers

You can add arbitrary headers to outbound SIP calls by prefixing the string ‘sip_h_’ to any channel variable, for example:Note that for BYE requests, you will need to use the prefix ‘sip_bye_h_’ on the channel variable.

While not required, you should prefix your headers with “X-” to avoid issues with interoperability with other SIP stacks.All inbound SIP calls will install any X- headers into local variables.This means you can easily bridge any X- header from one FreeSWITCH instance to another.To access the header above on a 2nd box, use the channel variable ${sip_h_X-Answer}It is important to note that the syntax ${sip_h_custom-header} can’t be used to retrieve any custom header not starting with X-.It is because Sofia only reads and puts into variables custom headers starting with X-.

Adding Response Headers

There are three types of response header prefixes that can be set:

Response headersip_rh_
Provisional response headersip_ph_
Bye response headersip_bye_h_

Each prefix will exclusively add headers for their given types of requests - there is no “global” response header prefix that will add a header to all response messages.For example:

Adding Custom Headers

For instance, you may need P-Charge-Info to append to your INVITE header, you may do as follows:Then, you would see it in SIP message:INVITE sip:19099099099@1.2.3.4 SIP/2.0Via: SIP/2.0/UDP 5.6.7.8:5080;rport;branch=z9hG4bKyg61X9v3gUD4gMax-Forwards: 69From: “DJB” sip:2132132132@5.6.7.8;tag=XQKQ322vQF5gKTo: sip:19099099099@1.2.3.4Call-ID: b6c776f6-47ed-1230-0085-000f1f659e58CSeq: 30776798 INVITEContact: sip:mod_sofia@5.6.7.8:5080User-Agent: FreeSWITCH-mod_sofia/1.2.0-rc2+git~20120713T162602Z~0afd7318bd+unclean~20120713T184029ZAllow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, UPDATE, INFO, REGISTER, REFER, NOTIFYSupported: timer, precondition, path, replacesAllow-Events: talk, hold, conference, referContent-Type: application/sdpContent-Disposition: sessionContent-Length: 229P-Charge-Info: sip:2132132132@5.6.7.8;npi=0;noa=3X-FS-Support: update_display,send_info.Remote-Party-ID: “DJB” sip:2132132132@5.6.7.8;party=calling;screen=yes;privacy=off

Strip Individual SIP Headers

Sometimes a SIP provider will add extra header information. Most of the time they do that for their own use (tracking calls). But that extra information can cause a lot of problems. For example: I get a call from the PSTN via a DID provider (provider1). Since im not in the office the call gets bridged to my cell phone (provider2). Provider1 add’s extra information to the sip packet like displayed below:X-voipnow-did: 01234567890X-voipnow-extension: 987654321…In some scenario, we bridge this call directly to provider2 the calls get dropped since provider2 doesnt accept the X-voipnow header, so we have to strip off those SIP headers.To strip them off, use the application UNSET in the dialplan (the inverse of SET):…

Strip All custom SIP Headers

If you wish to strip all custom headers while keeping only those defined in dialplan:…

Additional Channel variables

Additional variables may also be set to influence the way calls are handled by sofia.For example, contacts can be filtered by setting the ‘sip_exclude_contact’ variable. Example:Or you can perform SIP Digest authorization on outgoing calls by setting sip_auth_username and sip_auth_password variables to avoid using Gateways to authenticate. Example:Changing the SIP Contact user FreeSWITCH normally uses mod_sofia@ip:port for the internal SIP contact. To change this to foo@ip:port, there is a variable, sip_contact_user:{sip_contact_user=foo}sofia/my_profile/1234@192.168.0.1;transport=tcp

sip_renegotiate_codec_on_reinvite

true|false

sip_recovery_break_rfc

true|false

Transcoding Issues

G729 and G723 will not let you transcode because of licensing issues. Calls will fail if for example originating endpoint has set G729 with higher priority and receiving endpoint has G723 with highest priority. The logic is to fail the call rather than attempt to find a codec match. If you are having issues due to transcoding you may disable transcoding and both endpoints will negotiate the compatible codec rather than just fail the call.disable-transcoding will take the preferred codec from the inbound leg of your call and only offer that codec on the outbound leg.Add the following command along with to your sofia profile

Example:

Custom Events

The following are events that can be subscribed to via Event Socket

Registration

sofia::register* sofia::pre_register* sofia::register_attempt* sofia::register_failure* sofia::unregister - explicit unregister calls* sofia::expire - when a user registration expires

Gateways

sofia::gateway_add* sofia::gateway_delete* sofia::gateway_state - when a gateway is detected as down or back up

Call recovery

sofia::recovery_send* sofia::recovery_recv* sofia::recovery_recovered

Other

sofia::notify_refer* sofia::reinvite* sofia::error

FAQ

Does it use UDP or TCP?

By default it uses both, but you can add ;transport=tcp to the Sofia URL to force it to use TCP.For example:sofia/profile/foo@bar.com;transport=tcpAlso there is a parameter in the gateway config:That will cause it to use the TCP transport for the registration and all subsequent SIP messages.Not sure if this is needed or what it does, but the following can also be used in gateway settings:

Endpoint#

Configuration Files#

SIP profiles#

What if these commands don’t work for me?#

Sofia Recover#

Flushing and rebooting registered endpoints#

Starting a new profile#

Reloading profiles and gateways#

Deleting gateways#

Restarting gateways#

Adding / Changing Existing Gateways#

View SIP Registrations#

List the status of gateways#

List gateway data#

View User Presence Data#

Debugging Sofia-SIP#

Debugging presence and SLA#

Sample Export (Linux/Unix)#

Sample Set (Windows)#

Profile Configurations#

Track Call#

ACL#

Disabling Hold#

Using A Single Domain For All Registrations#

challenge realm#

force-register-domain#

Flushing Inbound Registrations#

Dial out of a gateway#

Modifying the To: header#

Specifying SIP Proxy With fs_path#

Safe SIP URI Formatting#

Channel Variables#

Adding Request Headers#

Adding Response Headers#

Adding Custom Headers#

Strip Individual SIP Headers#

Strip All custom SIP Headers#

Additional Channel variables#

sip_renegotiate_codec_on_reinvite#

sip_recovery_break_rfc#

Transcoding Issues#

Custom Events#

FAQ#

Does it use UDP or TCP?#