Gateways Configuration

About

Small guide on how Gateways are configured in FreeSWITCH™.

Click here to expand Table of Contents

1 Introduction
- 1.1 conf/directory/default/brian.xml
2 Clarification
3 Gateway Options
- 3.1 Params
  - 3.1.1 Caller ID
    - 3.1.2 Inbound Destination
- 3.2 Variables
4 IRC Discussions
5 See Also

Introduction

This has been a source of confusion for some, but it's really rather simple.

A bare-bones gateway setup for outbound calls with no username/pass (because you have ACL permission):

 <include>
    <gateway name="provider">
      <param name="proxy" value="199.96.248.140"/>
      <param name="register" value="false"/>
      <param name="caller-id-in-from" value="true"/> <!--Most gateways seem to want this-->
      <param name="username" value="not-used"/>
      <param name="password" value="not-used"/>
    </gateway>
 </include>

SIP gateways can be defined in the directory section _or_ the configuration section. In the default config, there are example gateways defined under the

conf/sip_profiles/external/example.xml file, like so:

<include>
  <!--<gateway name="asterlink.com">-->
  <!--/// account username *required* ///-->
  <!--<param name="username" value="cluecon"/>-->
  <!--/// auth realm: *optional* same as gateway name, if blank ///-->
  <!--<param name="realm" value="asterlink.com"/>-->
  <!--/// username to use in from: *optional* same as  username, if blank ///-->
  <!--<param name="from-user" value="cluecon"/>-->
  <!--/// domain to use in from: *optional* same as  realm, if blank; can also be set to "auto-aleg-full" or "auto-aleg-domain" ///-->
  <!--<param name="from-domain" value="asterlink.com"/>-->
  <!--/// account password *required* ///-->
  <!--<param name="password" value="2007"/>--> 
  <!--/// extension for inbound calls: *optional* same as username, if blank. To use what's in ${sip_to_user}, set it to the value "auto_to_user" ///-->
  <!--<param name="extension" value="cluecon"/>-->
  <!--/// proxy host: *optional* same as realm, if blank ///-->
  <!--<param name="proxy" value="asterlink.com"/>-->
  <!--/// send calls via this proxy: *optional* ///-->
  <!-- <param name="outbound-proxy" value="your-proxy.com"/> -->
  <!--/// send register to this proxy: *optional* same as proxy, if blank ///-->
  <!--<param name="register-proxy" value="mysbc.com"/>-->
  <!--/// expire in seconds: *optional* 3600, if blank ///-->
  <!--<param name="expire-seconds" value="60"/>-->
  <!--/// do not register ///-->
  <!--<param name="register" value="false"/>-->
  <!-- which transport to use for register -->
  <!--<param name="register-transport" value="udp"/>-->
  <!--How many seconds before a retry when a failure or timeout occurs -->
  <!--<param name="retry-seconds" value="30"/>-->
  <!--Use the callerid of an inbound call in the from field on outbound calls via this gateway -->
  <!--<param name="caller-id-in-from" value="false"/>-->
  <!--extra sip params to send in the contact-->
  <!--<param name="contact-params" value="tport=tcp"/>-->
  <!--send an options ping every x seconds, failure will unregister and/or mark it down-->
  <!--<param name="ping" value="25"/>-->
  <!--</gateway>-->
</include>

and also in the user directory, conf/directory/default/example.com.xml as well as brian.xml

conf/directory/default/example.com.xml
<!--
    Shell provider account should work with most providers.
-->
<include>
  <user id="$${default_provider}">
    <gateways>
      <gateway name="$${default_provider}">
        <param name="username" value="$${default_provider_username}"/>
        <param name="password" value="$${default_provider_password}"/>
        <param name="from-user" value="$${default_provider_username}"/>
        <param name="from-domain" value="$${default_provider_from_domain}"/>
        <param name="expire-seconds" value="600"/>
        <param name="register" value="$${default_provider_register}"/>
        <param name="retry-seconds" value="30"/>
        <param name="extension" value="$${default_provider_contact}"/>
        <!--<param name="contact-params" value="domain_name=$${domain}"/>-->
        <param name="context" value="public"/>
      </gateway>
    </gateways>
    <params>
      <param name="password" value="$${default_provider_password}"/>
    </params>
  </user>
</include>

conf/directory/default/brian.xml

<include>
  <!--
      ipauth if you have an cidr= in the user attributes ie cidr="1.2.3.4/32"  
      see <node type="allow" domain="$${domain}"/> in default acl.conf.xml 
  -->
  <user id="brian" cidr="192.0.2.0/24">
    <!-- Outbound Registrations Related to this user -->
    <gateways>
      <!--<gateway name="asterlink.com">-->
      <!--/// account username *required* ///-->
      <!--<param name="username" value="cluecon"/>-->
      <!--/// auth realm: *optional* same as gateway name, if blank ///-->
      <!--<param name="realm" value="asterlink.com"/>-->
      <!--/// username to use in from: *optional* same as  username, if blank ///-->
      <!--<param name="from-user" value="cluecon"/>-->
      <!--/// domain to use in from: *optional* same as  realm, if blank ///-->
      <!--<param name="from-domain" value="asterlink.com"/>-->
      <!--/// account password *required* ///-->
      <!--<param name="password" value="2007"/>--> 
      <!--/// replace the INVITE from user with the channel's caller-id ///-->
      <!--<param name="caller-id-in-from" value="false"/>-->
      <!--/// extension for inbound calls: *optional* same as username, if blank ///-->
      <!--<param name="extension" value="cluecon"/>-->
      <!--/// proxy host: *optional* same as realm, if blank ///-->
      <!--<param name="proxy" value="asterlink.com"/>-->
      <!--/// send register to this proxy: *optional* same as proxy, if blank ///-->
      <!--<param name="register-proxy" value="mysbc.com"/>-->
      <!--/// expire in seconds: *optional* 3600, if blank ///-->
      <!--<param name="expire-seconds" value="60"/>-->
      <!--/// do not register ///-->
      <!--<param name="register" value="false"/>-->
      <!-- which transport to use for register -->
      <!--<param name="register-transport" value="udp"/>-->
      <!--How many seconds before a retry when a failure or timeout occurs -->
      <!--<param name="retry-seconds" value="30"/>-->
      <!--Use the callerid of an inbound call in the from field on outbound calls via this gateway -->
      <!--<param name="caller-id-in-from" value="false"/>-->
      <!--extra sip params to send in the contact-->
      <!--<param name="contact-params" value="tport=tcp"/>-->
      <!--send an options ping every x seconds, failure will unregister and/or mark it down-->
      <!--<param name="ping" value="25"/>-->
      <!--</gateway>-->
    </gateways>
    <params>
      <!-- omit password for authless registration -->
      <param name="password" value="$${default_password}"/>
      <param name="vm-password" value="9999"/><!--if vm-password is omitted password param is used-->
      <!--<param name="email-addr" value="me@mydomain.com"/>-->
      <!--<param name="vm-delete-file" value="true"/>-->
      <!--<param name="vm-attach-file" value="true"/>-->
      <!--<param name="vm-mailto" value="me@mydomain.com"/>-->
      <!--<param name="vm-email-all-messages" value="true"/>-->
      <!-- optionally use this instead if you want to store the hash of user:domain:pass-->
      <!--<param name="a1-hash" value="c6440e5de50b403206989679159de89a"/>-->
      <!-- What this user is allowed to acces --> 
      <!--<param name="http-allowed-api" value="jsapi,voicemail,status"/> -->
    </params>
    <variables>
      <!--all variables here will be set on all inbound calls that originate from this user -->
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="Brian West"/>
      <variable name="effective_caller_id_number" value="1000"/>
      <!-- Don't write a CDR if this is false valid values are: true, false, a_leg and b_leg -->
      <variable name="process_cdr" value="true"/>
      <!-- sip_secure_media will offer mandatory SRTP on invite AES_CM_128_HMAC_SHA1_32, AES_CM_128_HMAC_SHA1_80 or true-->
      <variable name="rtp_secure_media" value="true"/>
      <!-- limit the max number of outgoing calls for this user -->
      <!--<variable name="max_calls" value="2"/>-->

      <!-- send presence information if FS is configured to do so -->
      <!--<variable name="presence_id" value="1000@$${domain}"/>-->

      <!-- set these to take advantage of a dialplan localized to this user -->
      <!--<variable name="numbering_plan" value="US"/>-->
      <!--<variable name="default_area_code" value="434"/>-->
      <!--<variable name="default_gateway" value="asterlink.com"/>-->
      <!--  
	   NDLB-connectile-dysfunction - Rewrite contact ip and port
	   NDLB-tls-connectile-dysfunction - Rewrite contact port only.
      -->
      <!--<variable name="sip-force-contact" value="NDLB-connectile-dysfunction"/>-->
      <!--<variable name="sip-force-expires" value="10"/>-->
      <!--<variable name="sip-register-gateway" value="cluecon.com"/>-->
      <!-- Set the file format for a specific user -->
      <!--<variable name="vm_message_ext" value="mp3"/> -->
    </variables>

    <vcard>
      <!-- insert optional compliant vcard xml here-->
    </vcard>
  </user>
</include>

Clarification

So, why is it presented 3 different ways?

In a nutshell, the sip_profile declaration puts the gateway in the context of that sip_profile, insofar as when you stop/start/restart that sofia profile the gateway will stop/start/restart with it. In the second case, the default_provider example, the gateway comes up with the default directory (always). And in the final example, the gateway can be made to come up and down only when the user brian is registered.

Gateway Options

Params

Caller ID

If you want the caller ID to be in the "From:", which is CID type=none

<param name="caller-id-in-from" value="true"/>

Inbound Destination

By default, incoming calls on this gateway will go to the username.

If you want FreeSWITCH to respect the ${sip\_to\_user}, set the value to "auto\_to\_user". Be sure you have the context

<param name="extension" value="auto_to_user"/>

Registration

If this gateway is ONLY for outbound calling, then there's rarely a need to maintain a registration ahead of time.

<param name="register" value="false"/>

Variables

In addition to the parameters you can optionally set variables to set on either incoming or outgoing calls through this gateway. You set a direction, which sets it on both incoming and outgoing calls if omitted.

<gateway>
 ...params...
 <variables>
   <variable name="inbound_var_name"  value="this is inbound"  direction="inbound"/>
   <variable name="outbound_var_name" value="this is outbound" direction="outbound"/>
   <variable name="both_var_name"     value="this on any direction"/>
 </variables>
</gateway>

IRC Discussions

So should gateways go in configuration or in directory?

This question was answered by anthm a while back on IRC, here is what he said:

<branchcut> me too ...
<rpm> my gateway is defined in sofia.conf.xml not in directory.xml
<branchcut> I'm kinda confused by the fact it can be defined in both places .. whats the difference?
<anthm> enterprise vs shuttlecraft
<[intra]lanman> lol
<branchcut> heh
<anthm> if you put them in a user tag in your directory you can then tell sofia to manage the whole
        domain and it will iterate all the users in that domain and reg the gateways
<anthm> if you don't need that you can just put them in the sofia conf

What I gather from this is that if you only want certain extensions to be registered with your voip provider when a specific user registers with freeswitch you should define gateways in the directory section rather than in the sofia configuration. Conversely, if you always want an extension registered with a provider you would define the gateway as part of the sip profile.

Gateways Configuration

About​

Introduction​

conf/directory/default/brian.xml​

Clarification​

Gateway Options​

Params​

Caller ID​

Inbound Destination​

Variables​

IRC Discussions​

See Also​

Comments:​