How To: Configuration and Adaptation of SIP Providers via Provider Profiles

To create a SIP trunk group within the SwyxWare, a number of predefined profiles for a large number of different SIP providers exist. In these profiles, the parameters a configured to assure a flawless interoperability between the SwyxWare and the chosen provider. These profiles are stored in the XML file called ProviderProfiles.config, which exists in the SwyxWare installation directory. Most of these parameters can be changed if necessary through the AdminTool, other can only be changed within the ProviderProfiles.config. Since this file will be replaced by an update, it is strongly advised against modifying this file.

If a new profile has to be created for a provider that is not yet being supported, it could be realised through the CustomProvider wizard. But since not all parameters can be configured this way, it is also advised against. Instead, a second XML file called CustomProviderProfiles.config should be created in the installation directory of the SwyxWare.

Important:

Prior to creating or modifying the CustomProviderProfiles.config, the SwyxWare Administration must be closed. Otherwise, the new entries won't become available.

The XML structure in this file is identical to the ProviderProfiles.config and must also be saved as UTF8-coded since otherwise special characters won't be added correctly.

If you change the XML file, the LinkManager needs to apply these changes. Therefore, it is necessary to restart the LinkManager.

To add a new provider to the XML file a new XML element "SIPProviderProfile" with the attributes listed in the table below needs to be added. The bold entries are mandatory, the other ones are optional. The default values of the optional attributes are listed in case that a attribute is not explicitly set.

id - identifier that distinguishes all provider profiles. Each profile in the ProviderProfiles.config and CustomProviderProfiles.config must have a unique id.

name - name of the provider, as it appears in the provider list when creating a new SIP trunk group.

numberformats - the number format of the destination number (called party) and the originator number (calling party). This format is used in SIP messages (e.g. INVITE's) going to/from the SIP provider. You need to assign values to the following attributes:

• inbound_called:  Called party for inbound calls
• inbound_calling:  Calling party for inbound calls
• outbound_called:  Called party for outbound calls
• outbound_calling:  Calling party for outbound calls

Possible values:

• CanonicalWithPlus:  use canonical numbers with leading "+" (e.g. +4923147770)
• CanonicalWithoutPlus:  use canonical numbers without leading "+" (e.g. 4923147770)
• National:  use the national number format. This conversion is based on information configured in SwyxServer, such as country code and local area code (e.g. 023147770)

proxy - the SIP proxy for outgoing calls.

stun - the STUN server to be used. If this is left empty, STUN is deactivated for all SIP trunk with this provider. If STUN has to be used, but the provider itself does not run a STUN server, a list of of public STUN servers can be found at http://www.voip-info.org/wiki/view/STUN. In case that the default STUN port 3478 cannot be used, it can be specified after the STUN server separated by a colon (e.g. stun.example.org.12345).

registrar - name or IP address of the SIP registrar, where REGISTER requests are being sent to. In case that the default SIP port 5060 cannot be used, it can be specified after the server separated by a colon.

realm - defines the SIP realm. This item will be used as host part in the SIP URIs of the relevant headers. The SIP URI is written as follows: <12345>@>realm>.

reRegistrationTimeout - defines registration interval. A smaller value will allow you to quickly recognize the loss of the SIP connection to the provider. A higher value results in lower network load. The SIP provider can define another value for registration interval by using the "expires" header of the SIP OK answer. The SwyxWare adapts to that value.

DtmfMode - the mode of the DTMF signalization with this provider. Possible values:

• None:  No DTMF signalization
• Rfc2833_Event:  DTMF signalization based on the event mechanism described in RFC2833
• InfoMethod_DtmfRelay:  DTMF signaling via SIP INFO requests as recommended by Cisco (applicationtype DtmfRelay)

UseDisplayInfo - defines whether the URI in the From header of outgoing calls has to contain a display field. The display field contains the alphanumeric user name, i.e. "John Miller"

CallingPartyNumberPosition - defines for outgoing calls the type of signalization of the calling party number. Possible values:

• None:  signalization is deactivated
• FromHeaderSIPURI:  in the user field of the URI in the From header
• FromHeaderDisplayName:  in the display info field of the From header
• RFC3325:  use the procedure as described in RFC3325 ("P-Preferred-Identity" and "Privacy" header field)

Note: Since SwyxWare 2013 R3 the SwyxWare always sends the P-Asserted-Identity header, independent of the configured value. This header usually contains the public number of the caller, if the user has one. Otherwise it contains the first public number that is assigned to that trunk.

CalledPartyNumberPosition - defines the position of called party number for inincoming calls. Possible values:

• ToHeaderSIPURI:  in the user field of the To header URI
• RequestURI:  in the user field of the Request URI

FaxMethods - defines the preferred Fax method. Possible values:

• T38:  use fax method T.38 for incoming or outgoing calls (IncomingFaxMethod, OutgoingFaxMethod).
• G711:  use fax method G.711 for incoming or outgoing calls (IncomingFaxMethod, OutgoingFaxMethod).
• G711+T38:  use fax methods G.711 and T.38 for outgoing calls (OutgoingFaxMethod only).

TransportType - defines the preferred transport protocol. Possible values:

• NotSpecified  (usually UDP will be taken)
• UDP
• TCP
• TLS

UseRegistration - defines whether the SIP trunk registers actively at the provider with a SIP REGISTER.

UseOverlapDialing - here, you can activate "overlapped dialing", as known from the PSTN. This allows a dialed target number to be signaled digit per digit to the provider, i.e. several invites with one digit each are sent to the provider for one call. The provider needs to answer each invite with a SIP 484 message, if the call cannot be delivered. The advantage is that the call can be signaled directly and there is no need to wait for a timeout for collecting the digits.

Since SwyxWare 2013 R3:
UseSIPConnectV1_1 - enables support of all practice-relevant parts of the technical recommendation "SIPconnectVer 1.1". For more information, please refer to the website: http://www.sipforum.org/sipconnect

Please note that:

1. all "number formats" must be set to "CanonicalWithPlus".
2. 'DtmfMode' must be set to "Rfc2833_Event".
3. 'CallingPartyNumberPosition' is automatically set to "FromHeaderSIPURI", regardless of the configured value.

Since SwyxWare 2013 R4:

• UsePAssertedIdentity - defines if P-Asserted-Identity header is used on outgoing calls.
  Note: Cannot be disabled, if "UseSIPConnectV1_1" is True.
• UseInviteAuth - determines whether to authenticate SIP INVITE requests for incoming calls.

Since SwyxWare 2015 R40.0.0:

• FilterSipMessages - determines if SIP messages should be filtered by the remote source IP address of the SIP provider trunk.
• UseSipInstanceId - determines if SIP REGISTER requests should use a SIP instance UUID (RFC 5626).
• UseSipRfc3262 - use SIP reliability of provisional responses (RFC 3262) / PRACK message if set to true.
• RecvCalledPartyNumberPosition - determines the way to handle the received called party number via SIP.
• outboundProxy - the SIP outbound proxy for outgoing calls.
• MediaEncryption - Possible values:
  • No  - media encryption disabled
  • Mandatory - media encryption mandatory

Since SwyxWare 11.00:
ReuseMediaPorts - determines if the RTP/RTCP media ports should be reused within a call.

Since SwyxWare 11.25:
ReuseSipConnection - reuse SIP transport connection to avoid further DNS resolutions on SIP requests.

Since SwyxWare 11.40:
PEarlyMedia - determines whether the early media handling using SIP P-Early-Media header (RFC 5009) should be applied.

Since SwyxWare 12.00:

• CompletenessTimeout - timeout (in seconds) for completeness of the dialed number.
• DtmfRfc2833PayloadType - DTMF RFC 2833 payload type default for negotiation (e.g. in SIP INVITE).
• DtmfGapDuration - DTMF gap duration between tones (in milliseconds).
• DtmfVolume - DTMF tone volume.
• DtmfToneDuration - DTMF tone duration (in milliseconds).
• IgnoreSIPDiversionHeader - ignore SIP Diversion Header.
• MediaSec - use media security handling (RFC 3329) (defined by MediaSecTypes, see below).
• MediaSecTypes - Possible values:
  • off  - media security handling disabled
  • on - media security handling (RFC 3329) enabled
  • sec_agree - media security handling (RFC 3329) enabled, using SIP option tag sec-agree
• MinSessionTimer - Minimum value of the SIP session timer interval in seconds according to RFC 4028.
• SessionTimer - SIP session timer interval in seconds according to RFC 4028. If value is zero the session timer handling is disabled.
• UseNaptrForDns - use NAPTR for DNS resolution.
• UseNextNonce - use SIP authentication with nextnonce handling (RFC 2617).
• UsePPreferredIdentity - use SIP P-Preferred-Identity header field if set to true.
• UseRecvDisplayInfo - use display info fields of received INVITE messages if set to true.
• UseRegUserIdInContact - use SIP registration user id in Contact header field for outgoing calls.

The most frequent problems that may occur when connecting a SIP trunk to a SIP provider can arise in the following areas. These are described each in a separate knowledge base article.

• DDI - Signalling of extensions and delivery errors for incoming calls: http://www.swyx.com/partnernet/ssdb.html?kbid=kb3312
• Fax using T.38 and the related media negotiation: http://www.swyx.com/partnernet/ssdb.html?kbid=kb3409

Example:
A CustomProviderProfiles.config file where a SIP provider named "Sample Provider" was configured. This will be available in the trunk group configuration after the file is copied to the SwyxWare installation directory.

<?xml version="1.0" encoding="utf-8"?>
<sp:ProviderProfiles xmlns:sp="http://www.lanphone.de/ProviderProfiles" allowcustom="false">
  <sp:SIPProviderProfile id="smplprv" name="Sample Provider" stun="stun.example.org" proxy="proxy.example.org" DtmfMode="Rfc2833_Event" >
    <sp:NumberFormats outbound_called="CanonicalWithPlus" outbound_calling="CanonicalWithPlus" inbound_called="CanonicalWithPlus" inbound_calling="CanonicalWithPlus" />
  </sp:SIPProviderProfile>
</sp:ProviderProfiles>