About
Sofia is a FreeSWITCH™ module (mod_sofia) that provides SIP connectivity to and from FreeSWITCH in the form of a User Agent. A “User Agent” (“UA”) is an application used for handling a certain network protocol; the network protocol in Sofia’s case is SIP. Sofia is the general name of any User Agent in FreeSWITCH using the SIP network protocol. For example, 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 (i.e., to local extensions). To add a SIP Provider (Sofia User Agent) to your FreeSWITCH, please see the Interoperability Examples and add the SIP Provider information in an .xml file stored under conf/sip_profiles/
Click here to expand Table of Contents
Sofia allows for multiple User Agents
A “User Agent” (“UA”) is an application used for running a certain network protocol, and a Sofia UA is the same thing but the protocol in that case is SIP. When FreeSWITCH starts, it reads the conf/autoload_configs/sofia.conf.xml file. That file contains a “X-PRE-PROCESS” directive which instructs FreeSWITCH to subsequently load and merge any conf/sip_profiles/*.xml files. Each *.xml file so loaded and merged should contain a complete description of one or more SIP Profiles. Each SIP Profile so loaded is part of a “User Agent” or “UA”; in FreeSWITCH terms, UA = User Agent = Sofia Profile = SIP Profile. Note that the individual UAs so loaded are all merged together by FreeSWITCH and must not interfere with each other: In particular, each UA must have its own unique port on which it accepts connections (the default port for SIP is 5060).
Multiple User Agents (Profiles) and the Dialplan
Why might you 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 need to 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
The Relationship Between SIP Profiles and Domains
The following content was written in a mailing list thread by Anthony Minessale in response to questions about how SIP profiles relate to domain names in FreeSWITCH. The best thing to do is take a look at these things from a step back. The domains inside the XML registry are completely different from the domains on the internet and again completely different from domains in sip packets. The profiles are again entirely different from any of the above. Its up to you to align them if you so choose. The default configuration distributed with FreeSWITCH sets up the scenario most likely to load on any machine and work out of the box. That is the primary goal of that configuration, so, It sets the domain in both the directory, the global default domain variable and the name of the internal profile to be identical to the IP addr on the box that can reach the internet. Then it sets the sip to force everything to that value. When you want to detach from this behavior, you are probably on a venture to do some kind of multi-home setup. Aliases in the tag are a list of keys you want to use to use that lead to the current profile your are configuring. Think of it as the /etc/hosts file in Unix, only for profiles. When you define aliases to match all of the possible domains hosted on a particular profile, then when you try to take a user@host.com notation and decide which profile it came from, you can use the aliases to find it providing you have added to that profile. The tag is an indicator telling the profile to open the XML registry in FreeSWITCH and run through any domains defined therein. The 2 key attributes are: alias: [true/false] (automatically create an alias for this domain as mentioned above) parse: [true/false] (scan the domain for gateway entries and include them into this profile) name: [] (either the name of a specific domain or ‘all’ to denote parsing every domain in the directory)
As you showed in your question the default config has
If you apply what you have learned above, it will scan for every domain (there is only one by default) and add an alias for it and not parse it for gateways. The default directory uses global config vars to set the domain to match the local IP addr on the box. So now you will have a domain in your config that is your IP addr, and the internal profile will attach to it and add an alias so that value expands to match it. This is explained in a comment at the top of directory/default.xml: FreeSWITCH works off the concept of users and domains just like email. You have users that are in domains for example 1000@domain.com.
When freeswitch gets a register packet it looks for the user in the directory based on the from or to domain in the packet depending on how your sofia profile is configured. Out of the box the default domain will be the IP address of the machine running FreeSWITCH. This IP can be found by typing “sofia status” at the CLI. You will register your phones to the IP and not the hostname by default. If you wish to register using the domain please open vars.xml in the root conf directory and set the default domain to the hostname you desire. Then you would use the domain name in the client instead of the IP address to register with FreeSWITCH.
So having more than one profile with the default of
is going to end up aliasing the same domains into all profiles who call it and cause an overwrite in the lookup table and probably an error in your logs somewhere. If you had parse=“true” on all of them, they would all try and register to the gateways in all of your domains. If you look at the stock config, external.xml is a good example of a secondary profile, it has
so no aliases, and yes parse … the exact opposite of the internal so that all the gateways would register from external and internal would bind to the local IP addr. So, you probably want to use separate per domain per profile you want to bind it to in more complicated setups.
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.
Gateway
Each profile can have several gateways: elements… elements…
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 FreeSWITCH User Agent. Variables can be defined on a gateway. Inbound variables are set on the channel of a call received from a gateway, outbound variables are set on the channel of a call sent to a gateway. An example gateway configuration would be:
To reach a particular gateway from the dial plan, use sofia/gateway/<gateway_name>/
FreeSWITCH can also subscribe to receive notification of events from the gateway. For more information see Presence - Use FreeSWITCH as a Client
Parameters
The following is a list of param elements that are children of a gateway element:
Note: The username param for the gateway is not to be confused with the username param in the Profile settings config!
Note: extension parameter influence the contents of channel variable Caller-Destination-Number and destination_number. If it is blank, Caller-Destination-Number will always be set to gateway’s username. If it has a value, Caller-Destination-Number will always be set to this value. If it has value auto_to_user, Caller-Destination-Number will be populated with value ${sip_to_user} which means the real dialled number in case of an inbound call.
ping-min means “how many successful pings we must have before declaring a gateway up”. The interval between ping-min and ping-max is the “safe area” where a gateway is marked as UP. So if we have, for example, min 3 and max 6, if the gateway is up and we move counter between 3,4,5,6 the gateway will be up. If from 6 we loose 4 (so counter == 2) pings in a row, the gateway will be declared down. Please note that on sofia startup the gateway is always started as UP, so it will be up even if ping-min is > 1 . the “right” way starts when the gateway goes down.
Param “register,” is used when this profile acts as a client to another UA. By registering, FreeSWITCH informs the other UA of its whereabouts. This is generally used when FreeSWITCH wants the other UA to send FreeSWITCH calls, and the other UA expects this sort of registration. If FreeSWITCH uses the other UA only as a gateway (e.g., to the PSTN), then registration is not generally required. Param “distinct-to” is used when you want FS to register using a distict AOR for header To. It requires proper setting of related parameters. For example if you want the REGISTER to go with: From: sip:someuser@somedomain.com To: sip:anotheruser@anotherdomain.com
Then set the parameters as this:
The latter param, “ping” is used to check gateway availability. By setting this option, FreeSWITCH will send SIP OPTIONS packets to gateway. If gateway responds with 200 or 404, gateway is pronounced up, otherwise down. [N.B. It appears that other error messages can be returned and still result in the gateway being marked as ‘up’?] If any call is routed to gateway with state down, FreeSWITCH will generate NETWORK_OUT_OF_ORDER hangup cause. Ping frequency is defined in seconds (value attribute) and has a minimum value of 5 seconds. Param “extension-in-contact” is used to force what the contact info will be in the registration. If you are having a problem with the default registering as gw+gateway_name@ip you can set this to true to use extension@ip. If extension is blank, it will use username@ip.
if you need to insert the FROM digits to the Contact URI User Part when sending call to gateway BEFORE From: “8885551212” sip:88855512120@8.8.8.8 Contact: sip:gw+mygateway@7.7.7.7:7080 try adding these to gateway params
These channel variables will be set on all calls going through this gateway in the specified direction. However, see below for a special syntax to set profile variables rather than channel variables.
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. See Git examples: Internal, External
Basic settings
alias
This seems to make the SIP profile bind to this IP & port as well as your SIP / RTP IPs and ports. Anthony had this to say about aliases in a ML thread: Aliases in the tag are a list of keys you want to use to use that lead to the current profile your are configuring. Think of it as the /etc/hosts file in unix only for profiles. When you define aliases to match all of the possible domains hosted on a particular profile, then when you try to take a user@host.com notation and decide which profile it came from, you can use the aliases to find it providing you have added to that profile.
shutdown-on-fail
If set to true and the profile fails to load, FreeSWITCH will shut down. This is useful if you are running something like Pacemaker and OpenAIS which manage a pair of FreeSWITCH nodes and automatically monitor, start, stop, restart, and standby-on-fail the nodes. It will ensure that the specific node is not able to be used in a “partially up” situation.
user-agent-string
This sets the User-Agent header in all SIP messages sent by your server. By default this could be something like “FreeSWITCH-mod_sofia/1.0.trunk-12805”. If you didn’t want to advertise detailed version information you could simply set this to “FreeSWITCH” or even “Asterisk PBX” as a joke. Take care when setting this value as certain characters such as ‘@’ could cause other SIP proxies could reject your messages as invalid.
log-level
sip-trace
context
Dialplan context in which to dump calls that come in to this profile’s ip:port
sip-port
Port to bind to for SIP traffic:
sip-ip
IP address to bind to for SIP traffic. DO NOT USE HOSTNAMES, ONLY IP ADDRESSES
rtp-ip
IP address to bind to for RTP traffic. DO NOT USE HOSTNAMES, ONLY IP ADDRESSES
- Multiple rtp-ip support: if more rtp-ip parameters are added, they will be used in round-robin as new calls progress.
- IPv6 addresses are not supported under Windows at the time of writing. See FS-4445
ext-rtp-ip
This is the IP behind which FreeSWITCH is seen from the Internet, so if FreeSWITCH is behind NAT, this is basically the public IP that should be used for RTP. Possible values are: Any variable from vars.xml, e.g. $${external_rtp_ip}:
“specific IP address”
“when used for LAN and WAN to avoid errors in the SIP CONTACT sent to LAN devices, use”
“auto”: the guessed IP will be used (guessed by looking in the IP routing table which interface is the default route)
“auto-nat”: FreeSWITCH will use uPNP or NAT-PMP to discover the public IP address it should use
“stun:DNS name or IP address”: FreeSWITCH will use the STUN server of your choice to discover the public IP address
“host:DNS name”: FreeSWITCH will resolve the DNS name as the public IP address, so you can use a dynamic DNS host
ATTENTION: AS OF 2012Q4, ’ext–’ prefixed params cited above when populated with to-be-resolved DNS strings – e.g. name=“ext–sip–ip” value=“stun:stun.freeswitch.org” or name=“ext‑rtp–ip” value=“host:mypublicIP.dyndns.org” – are resolved to IP addresses once only at FS load time and const thereafter. FS is blind to (unaware of) any subsequent changes in your environment’s IP address. Thus, these ext– vars may become functionally incompatible with the environment’s current IP addresses with unspecified results in call flow at the network layer. FS restart is required for FS to capture the now-current, working IP address(es).
ext-sip-ip
This is the IP behind which FreeSWITCH is seen from the Internet, so if FreeSWITCH is behind NAT, this is basically the public IP that should be used for SIP. Possibles values are the same as those for ext-rtp-ip, and it is usually set to the same value.
tcp-keepalive
Set this to interval (in milliseconds) to send keep alive packets to user agents (UAs) registered via TCP; do not set to disable.
tcp-pingpong
tcp-ping2pong
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 (e.g., callback to your webserver), or failing that, from the XML files specified in freeswitch.xml dialplan section. (e.g. default_context.xml)
You can also add enum lookups into the picture (since mod_enum provides dialplan functionality), so enum lookups override the XML dialplan
Or reverse the order to enum is only consulted if XML lookup fails
It is also possible to specify a specific enum root
Or use XML on a custom file
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.
Media related options
See also: Proxy Media
resume-media-on-hold
When calls are in no media this will bring them back to media when you press the hold button. To return the calls to bypass-media after the call is unheld, enable bypass-media-after-hold.
bypass-media-after-att-xfer
This will allow a call after an attended transfer go back to bypass media after an attended transfer.
bypass-media-after-hold
This will allow a call to go back to bypass media after a hold. This option can be enabled only if resume-media-on-hold is set. Available from git rev 8fa385b.
inbound-bypass-media
Uncomment to set all inbound calls to no media mode. It means that the FreeSWITCH server only keeps the SIP messages state, but have the RTP steam go directly from end-point to end-point
inbound-proxy-media
Uncomment to set all inbound calls to proxy media mode. This means the FreeSWITCH keeps both the SIP and RTP traffic on the server but does not interact with the RTP stream.
disable-rtp-auto-adjust
ignore-183nosdp
enable-soa
Set the value to “false” to diable SIP SOA from sofia to tell sofia not to touch the exchange of SDP
t38-passthru
The following options are available
- ’true’ enables t38 passthru
- ‘false’ disables t38 passthru
- ‘once’ enables t38 passthru, but sends t.38 re-invite only once (available since commit 08b25a8 from Nov. 9, 2011)
Codecs related options
Also see:
inbound-codec-prefs
This parameter allows to change the allowed inbound codecs per profile.
outbound-codec-prefs
This parameter allows to change the outbound codecs per profile.
codec-prefs
This parameter allows to change both inbound-codec-prefs and outbound-codec-prefs at the same time.
inbound-codec-negotiation
set to ‘greedy’ if you want your codec list to take precedence
if ‘greedy’ doesn’t work for you, try ‘scrooge’ which has been known to fix misreported ptime issues with DID providers such as CallCentric. A rule of thumb is:
- ‘generous’ permits the remote codec list have precedence and ‘win’ the codec negotiation and selection process
- ‘greedy’ forces a win by the local FreeSWITCH preference list
- ‘scrooge’ takes ‘greedy’ a step further, so that the FreeSWITCH wins even when the far side lies about capabilities during the negotiation process
sip_codec_negotiation is a channel variable version of this setting
inbound-late-negotiation
Uncomment to let calls hit the dialplan before you decide if the codec is OK.
bitpacking
This setting is for AAL2 bitpacking on G.726.
disable-transcoding
Uncomment if you want to force the outbound leg of a bridge to only offer the codec that the originator is using
renegotiate-codec-on-reinvite
STUN
If you need to use a STUN server, here are common working examples:
ext-rtp-ip
stun.fwdnet.net is a publicly-accessible STUN server.
ext-sip-ip
stun-enabled
Simple traversal of UDP over NATs (STUN), is used to help resolve the problems associated with SIP clients, behind NAT, using private IP address space in their messaging. Use stun when specified (default is true).
stun-auto-disable
Set to true to have the profile determine stun is not useful and turn it off globally
NATing
apply-nat-acl
When receiving a REGISTER or INVITE, enable NAT mode automatically if IP address in Contact header matches an entry defined in the RFC 1918 access list. “acl” is a misnomer in this case because access will not be denied if the user’s contact IP doesn’t match.
aggressive-nat-detection
This will enable NAT mode if the network IP/port from which the request was received differs from the IP/Port combination in the SIP Via: header, or if the Via: header contains the received parameter (regardless of what it contains.) Note 2009-04-05: Someone please clarify when this would be useful. It seems to me if someone needed this feature, chances are that things are so broken that they would need to use NDLB-force-rport
VAD and CNG
VAD stands for Voice Activity Detector. FreeSWITCH is capable of detecting speech and can stop transmitting RTP packets when no voice is detected.
vad
suppress-cng
Suppress Comfort Noise Generator (CNG) on this profile or per call with the ‘suppress_cng’ variable
NDLB (A.K.A. No device left behind)
NDLB-force-rport
This will force FreeSWITCH to send SIP responses to the network port from which they were received. Use at your own risk! For more information see NAT Traversal.
- safe = param that does force-rport behavior only on endpoints we know are safe to do so on. This is a dirty hack to try to work with certain endpoints behind sonicwall which does not use the same port when it does nat, when the devices do not support rport, while not breaking devices that acutally use different ports that force-rport will break
NDLB-broken-auth-hash
Used for when phones respond to a challenged ACK with method INVITE in the hash
NDLB-received-in-nat-reg-contact
add a ;received=":" to the contact when replying to register for nat handling
NDLB-sendrecv-in-session
By default, “a=sendrecv” is only included in the media portion of the SDP. While this is RFC-compliant, it may break functionality for some SIP devices. To also include “a=sendrecv” in the session portion of the SDP, set this parameter to true.
NDLB-allow-bad-iananame
- Introduced in rev. 15401, this was enabled by default prior to new param.
Will allow codecs to match respective name even if the given string is not correct. i.e., Linksys and Sipura phones will pass G.729a by default instead of G.729 as codec string therefore not matching. If you wish to allow bad IANA names to match respective codec string, add the following param to your SIP profile.
Refer to RFC 3551, RFC 3555 and the IANA list(s) for SDP
Call ID
inbound-use-callid-as-uuid
On inbound calls make the uuid of the session equal to the SIP call id of that call.
outbound-use-uuid-as-callid
On outbound calls set the callid to match the uuid of the session
This goes in the “..sip_profiles/external.xml” file.
TLS
Please make sure to read SIP TLS before enabling certain features below as they may not behave as expected.
tls
TLS: disabled by default, set to “true” to enable
tls-only
disabled by default, when enabled prevents sofia from listening on the unencrypted port for this connection. This can stop many generic brute force scripts and if all your clients connect over TLS then can help decrease the exposure of your FreeSWITCH server to the world.
tls-bind-params
additional bind parameters for TLS
tls-sip-port
Port to listen on for TLS requests. (5061 will be used if unspecified)
tls-cert-dir
Location of the agent.pem and cafile.pem ssl certificates (needed for TLS server)
tls-version
TLS version (“sslv2”, “sslv3”, “sslv23”, “tlsv1”, “tlsv1.1”, “tlsv1.2”). NOTE: Phones may not work with TLSv1
When not set defaults to: “tlsv1,tlsv1.1,tlsv1.2”
tls-passphrase
If your agent.pem is protected by a passphrase stick the passphrase here to enable FreeSWITCH to decrypt the key.
tls-verify-date
If the client/server certificate should have the date on it validated to ensure it is not expired and is currently active.
tls-verify-policy
This controls what, if any security checks are done against server/client certificates. Verification is generally checking certificates are valid against the cafile.pem. Set to ‘in’ to only verify incoming connections, ‘out’ to only verify outgoing connections, ‘all’ to verify all connections, also ‘subjects_in’, ‘subjects_out’ and ‘subjects_all’ for subject validation (subject validation for outgoing connections is against the hostname/ip connecting to). Multiple policies can be split with a ‘|’ pipe, for example ‘subjects_in|subjects_out’. Defaults to none.
tls-verify-depth
When certificate validation is enabled (tls-verify-policy) how deep should we try to verify a certificate up the chain again the cafile.pem file. By default only depth of 2.
tls-verify-in-subjects
If subject validation is enabled for incoming connections (tls-verify-policy set to ‘subjects_in’ or ‘subjects_all’) this is the list of subjects that are allowed (delimit with a ‘|’ pipe), note this only effects incoming connections for outgoing connections subjects are always checked against hostnames/ips.
DTMF
rfc2833-pt
TODO RFC 2833 is obsoleted by RFC 4733.
dtmf-duration
dtmf-type
TODO RFC 2833 is obsoleted by RFC 4733. Set the parameter in the SIP profile:
or
or
OR set the variable in the SIP gateway or user profile (NOT in the channel, it must be before CS_INIT):
Note the “_” instead of “-” in profile param (this is var set in dialplan). (24.10.2010: “both” don’t seem to me work in my tests, “outbound” does) Note: for inband DTMF, Misc. Dialplan Tools start_dtmf must be used in the dialplan. Also, to change the outgoing routing from info or rfc2833 to inband, use Misc._Dialplan_Tools_start_dtmf_generate RFC 2833
pass-rfc2833
TODO RFC 2833 is obsoleted by RFC 4733. Default: false If true, it passes RFC 2833 DTMF’s from one side of a bridge to the other, untouched. Otherwise, it decodes and re-encodes them before passing them on.
liberal-dtmf
TODO RFC 2833 is obsoleted by RFC 4733. Default: false For DTMF negotiation, use this parameter to just always offer 2833 and accept both 2833 and INFO. Use of this parameter is not recommended since its purpose is to try to cope with buggy SIP implementations.
SIP Related options
enable-timer
This enables or disables support for RFC 4028 SIP Session Timers.
Note: If your switch requires the timer option; for instance, Huawei SoftX3000, it needs this optional field and drops the calls with “Session Timer Check Message Failed”, then you may be able to revert back the commit that took away the Require: timer option which is an optional field by: git log -1 -p 58c3c3a049991fedd39f62008f8eb8fca047e7c5 libs/sofia-sip/libsofia-sip-ua | patch -p1 -R touch libs/sofia-sip/.update
make mod_sofia-clean make mod_sofia-install
enable-100rel
This enable support for 100rel (100% reliability - PRACK message as defined in RFC3262) This fixes a problem with SIP where provisional messages like “180 Ringing” are not ACK’d and therefore could be dropped over a poor connection without retransmission. 2009-07-08: Enabling this may cause FreeSWITCH to crash, see FSCORE-392.
minimum-session-expires
This sets the “Min-SE” value (in seconds) from RFC 4028. This value must not be less than 90 seconds.
sip-options-respond-503-on-busy
When set to true, this param will make FreeSWITCH respond to incoming SIP OPTIONS with 503 “Maximum Calls In Progress” when FS is paused or maximum sessions has been exceeded. When set to false or when not set at all (default behavior), SIP OPTIONS are always responded with 200 “OK”.
Setting this param to true is especially useful if you’re using a proxy such as OpenSIPS or Kamailio with dispatcher module to probe your FreeSWITCH servers by sending SIP OPTIONS.
sip-force-expires
Setting this param overrides the expires value in the 200 OK in response to all inbound SIP REGISTERs towards this sip_profile. This param can be overridden per individual user by setting a sip-force-expires user directory variable.
sip-expires-max-deviation
Setting this param adds a random deviation to the expires value in the 200 OK in response to all inbound SIP REGISTERs towards this sip_profile. Result will be that clients will not re-register at the same time-interval thus spreading the load on your system. For example, if you set:
then the expires that is responded will be between 1800-600=1200 and 1800+600=2400 seconds. This param can be overridden per individual user by setting a sip-expires-max-deviation user directory variable.
outbound-proxy
Setting this param will send all outbound transactions to the value set by outbound-proxy.
send-display-update
Tells FreeSWITCH not to send display UPDATEs to the leg of the call.
RTP Related options
auto-jitterbuffer-msec
Set this to the size of the jitterbuffer you would like to have on all calls coming through this profile.
rtp-timer-name
rtp-rewrite-timestamps
If you don’t want to pass through timestamps from 1 RTP stream to another, rtp-rewrite-timestamps is a parameter you can set in a SIP Profile (on a per call basis with rtp_rewrite_timestamps chanvar in a dialplan). The result is that FreeSWITCH will regenerate and rewrite the timestamps in all the RTP streams going to an endpoint using this SIP Profile. This could be necessary to fix audio issues when sending calls to some paranoid and not RFC-compliant gateways (Cirpack is known to require this).
media_timeout
was: rtp-timeout-sec (deprecated) The number of seconds of RTP inactivity (media silence) before FreeSWITCH considers the call disconnected, and hangs up. It is recommended that you use session timers instead. If this setting is omitted, the default value is “0”, which disables the timeout.
media_hold_timeout
was: rtp-hold-timeout-sec (deprecated) The number of seconds of RTP inactivity (media silence) for a call placed on hold by an endpoint before FreeSWITCH considers the call disconnected, and hangs up. It is recommended that you use session timers instead. If this setting is omitted, the default value is “0”, which disables the timeout.
rtp-autoflush-during-bridge
Controls what happens if FreeSWITCH detects that it’s not keeping up with the RTP media (audio) stream on a bridged call. (This situation can happen if the FreeSWITCH server has insufficient CPU time available.) When set to “true” (the default), FreeSWITCH will notice when more than one RTP packet is waiting to be read in the incoming queue. If this condition persists for more than five seconds, RTP packets will be discarded to “catch up” with the audio stream. For example, if there are always five extra 20 ms packets in the queue, 100 ms of audio latency can be eliminated by discarding the packets. This will cause an audio glitch as some audio is discarded, but will improve the latency by 100 ms for the rest of the call. If rtp-autoflush-during-bridge is set to false, FreeSWITCH will instead preserve all RTP packets on bridged calls, even if it increases the latency or “lag” that callers hear.
rtp-autoflush
Has the same effect as “rtp-autoflush-during-bridge”, but affects NON-bridged calls (such as faxes, IVRs and the echo test). Unlike “rtp-autoflush-during-bridge”, the default is false, meaning that high-latency packets on non-bridged calls will not be discarded. This results in smoother audio at the possible expense of increasing audio latency (or “lag”). Setting “rtp-autoflush” to true will discard packets to minimize latency when possible. Doing so may cause errors in DTMF recognition, faxes, and other processes that rely on receiving all packets.
Auth
These settings deal with authentication: requirements for identifying SIP endpoints to FreeSWITCH.
challenge-realm
Choose the realm challenge key. Default is auto_to if not set. 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. If you want URL dialing to work you’ll want to set this to auto_from. If you use any other value besides auto_to or auto_from you’ll loose the ability to do multiple domains. Note: comment out to restore the behavior before 2008-09-29
accept-blind-auth
accept any authentication without actually checking (not a good feature for most people)
auth-calls
Users in the directory can have “auth-acl” parameters applied to them so as to restrict users access to a predefined ACL or a CIDR.
Value can be “false” to disable authentication on this profile, meaning that when calls come in the profile will not send an auth challenge to the caller.
log-auth-failures
Write log entries ( Warning ) on authentication failures ( Registration & Invite ). useful for users wishing to use fail2ban. note: Required SVN#15654 or higher
auth-all-packets
On authed calls, authenticate all the packets instead of only INVITE and REGISTER(Note: OPTIONS, SUBSCRIBE, INFO and MESSAGE are not authenticated even with this option set to true, see http://jira.freeswitch.org/browse/FS-2871)
Registration
disable-register
disable register which may be undesirable in a public switch
multiple-registrations
Valid values for this parameter are “contact”, “true”, “false”. value=“true” is the most common use. Setting this value to “contact” will remove the old registration based on sip_user, sip_host and contact field as opposed to the call_id.
max-registrations-per-extension
Defines the number of maximum registrations per extension. Valid value for this parameter is an integer greater than 0. Please note that setting this to 1 would counteract the usage of multiple-registrations. When an attempt to register an extension is made after the maximum value has been reached sofia will respond with 403. The following example will set maximum registrations to 2
inbound-reg-force-matching-username
Force the user and auth-user to match.
force-publish-expires
Force custom presence update expires delta (-1 means endless)
force-register-domain
all inbound registrations will look in this domain for the users. Comment out to use multiple domains
force-register-db-domain
all inbound reg will stored in the db using this domain. Comment out to use multiple domains
send-message-query-on-register
Can be set to ’true’, ‘false’ or ‘first-only’. If set to ’true’ (this is the default behavior), mod_sofia will send a message-query event upon registration. mod_voicemail uses this for counting messages.
If set to ‘first-only’, only the first REGISTER will trigger the message-query (it requires the UA to increment the NC on subsequent REGISTERs. Some phones, snom for instance, do not do this). The final effect of the message-query is to cause a NOTIFY MWI message to be sent to the registering UA (it is used to satisfy terminals that expect MWI without subscribing for it).
unregister-on-options-fail
If set to True with nat-options-ping the endpoint will be unregistered if no answer on OPTIONS packet.
nat-options-ping
With this option set FreeSWITCH will periodically send an OPTIONS packet to all NATed registered endpoints to keep alive connection. If set to True with unregister-on-options-fail the endpoint will be unregistered if no answer on OPTIONS packet.
all-reg-options-ping
With this option set FreeSWITCH will periodically send an OPTIONS packet to all registered endpoints to keep alive connection. If set to True with unregister-on-options-fail the endpoint will be unregistered if no answer on OPTIONS packet.
registration-thread-frequency
Controls how often registrations in the FreeSWITCH are checked for expiration.
ping-mean-interval
Controls the mean interval FreeSWITCH™ will send OPTIONS packet to registered user, by default 30 seconds.
Subscription
force-subscription-expires
force suscription expires to a lower value than requested
force-subscription-domain
all inbound subscription will look in this domain for the users. Comment out to use multiple domains
Presence
manage-presence
Enable presence. If you want to share your presence (see dbname and presence-hosts) set this to “true” on the first profile and enable the shared presence database. Then on subsequent profiles that share presence set this variable to “passive” and enable the shared presence database there as well.
dbname
Used to share presence info across sofia profiles Name of the db to use for this profile
presence-hold-state
By default when a call is placed on hold, monitoring extensions show that extension as ringing. You can change this behavior by specifying this parameter and one of the following values. Available as of commit 1145905 on April 13, 2012.
- confirmed - Extension appears busy.
- early (default) - Extension appears to be ringing.
- terminated - Extension appears idle.
presence-hosts
A list of domains that have a shared presence in the database specified in dbname. People who use multiple domains per profile can’t use this feature anyway, so you’ll want to set it to something like “DISABLED” in this case to avoid getting users from similar domains all mashed together. For multiple domains also known as multi-tenant calling 1001 would call all matching users in all domains. Don’t use presence-hosts with multi-tenant.
presence-privacy
Optionally globally hide the caller ID from presence notes in distributed NOTIFY messages. For example, “Talk 1002” would be the presence note for extension 1001 while it is on a call with extension 1002. If the presence privacy tag is set to true, then it would distribute the presence note as “On The Phone” (without the extension to which it is connected). So any subscriber’s to 1001’s presence would not be able to see who he/she is talking to. http://jira.freeswitch.org/browse/FS-849 This also hides the number in the status “hold”, “ring”, “call” and perhaps others. http://jira.freeswitch.org/browse/FS-4420
send-presence-on-register
Specify whether or not to send presence information when users register. Default is not to send presence information. Valid options:
- false
- true
- first-only
CallerID Related options
caller-id type
choose one, can be overridden by inbound call type and/or sip_cid_type channel variable Remote-Party-ID header:
P-*-Identity family of headers:
neither one:
pass-callee-id
(defaults to true) Disable by setting it to false if you encounter something that your gateway for some reason hates X-headers that it is supposed to ignore
Other (TO DO)
hold-music
disable-hold
This allows to disable Music On Hold (added in GIT commit e5cc0539ffcbf660637198c698e90c2e30b05c2f, from Fri Apr 30 19:14:39 2010 -0500). This can be useful when the calling device intends to send its own MOH, but nevertheless sends a REINVITE to FreeSWITCH triggering its MOH. This can be done from dialplan also with rtp_disable_hold channel variable.
apply-inbound-acl
set which access control lists, defined in acl.conf.xml, apply to this profile
apply-register-acl
apply-proxy-acl
This allows traffic to be sent to FreeSWITCH via one or more proxy servers. The proxy server should add a header named X-AUTH-IP containing the IP address of the client. FreeSWITCH trusts the proxy because its IP is listed in the proxy server ACL, and uses the value of the IP in this header as the client’s IP for ACL authentication (acl defined in apply-inbound-acl).
record-template
max-proceeding
max number of open dialogs in proceeding
bind-params
if you want to send any special bind params of your own
disable-transfer
disable transfer which may be undesirable in a public switch
manual-redirect
enable-3pcc
enable-3pcc determines if third party call control is allowed or not. Third party call control is useful in cases where the SIP invite doesn’t include a SDP (late media negotiation). enable-3pcc can be set to either ’true’ or ‘proxy’, true accepts the call right away, proxy waits until the call has been answered then sends accepts
nonce-ttl
TTL for nonce in sip auth
This parameter is set to 60 seconds if not set here. It’s used to determine how long to store the user registration record in the sip_authentication table. The expires field in the sip_authentication table is this value plus the expires set by the user agent.
sql-in-transactions
If set to true (default), it will instruct the profile to wait for 500 SQL statements to accumulate or 500ms to elapse and execute them in a transaction (to boost performance).
odbc-dsn
If you have ODBC support and a working dsn you can use it instead of SQLite
mwi-use-reg-callid
username
If you wish to hide the fact that you are using FreeSWITCH in the SDP message (Specifically the o= and and s= fields) , then set the username param under the profile. This has no relation whatsoever with the username parameter when we’re dealing with gateways. If this value is left unset the system defaults using FreeSWITCH as the username parameter with the o= and s= fields.
Example: . v=0. o=root 1346068950 1346068951 IN IP4 1.2.3.4. s=root. c=IN IP4 1.2.3.4. t=0 0. m=audio 26934 RTP/AVP 18 0 101 13. a=fmtp:18 annexb=no. a=rtpmap:101 telephone-event/8000. a=fmtp:101 0-16. a=ptime:20.
when you set
Directory of Users
To allow users to register with the server, the user information must be specified in the conf/directory/default/*xml file. To dynamically specify what users can register, use Mod xml curl
Default Configuration File
From the FreeSWITCH Github repository’s vanilla configurations ([conf/vanilla/autoload_configs/sofia.conf.xml](https://github.com/signalwire/freeswitch/blob/master/conf/vanilla/autoload_configs/sofia.conf.xml)):
conf/autoload_configs/sofia.conf.xml
<global_settings> <!– the new format for HEPv2/v3 and capture ID protocol:host:port;hep=2;capture_id=200;
–> </global_settings>
- shutdown and restart FreeSWITCH (or)
- unload and load mod_sofia
If you’ve only made changes to a particular profile, you may simply (WARNING: will drop all calls associated with this profile):
- sofia profile restart reloadxml
Security Features
- SIP TLS for secure signaling.
- SRTP for secure media delivery.
- The Auth section above for authentication settings.