Configuration and Adaptation of SIP Providers via Provider Profiles (kb3436)
The information in this article applies to:
- SwyxWare 22.214.171.124
- SwyxWare 11.00.1.0
- SwyxWare 11.00
- SwyxWare 11
- SwyxWare 2015 R40.3.0
- SwyxWare 2015 R40.2.0
- SwyxWare 2015 R40.1.0
- SwyxWare 2015 R40.0.0
- SwyxWare 2015 R30.5.0
- SwyxWare 2015 R30.4.0
- SwyxWare 2015 R3.2.2
- SwyxWare 2015 R3.2
- SwyxWare 2015 R3.1
- SwyxWare 2015 R3
- SwyxWare 2015 R2
- SwyxWare 2015
- SwyxWare 2013
- SwyxWare 2011 R2
This article describes how to add a profile for a new SIP provider to the SwyxWare, in order to add it to the list of available provider profiles when creating a new SIP trunk group.
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, usually C:\Program Files (x86)\SwyxWare. 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.
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||string without space||-|
|numberformats||Type (see below)||-|
|stun||string||"" (no STUN Server)|
|registrar||string||value from proxy|
|realm||domainname||value from registrar|
|DtmfMode||enum (see below)||"None"|
|CallingPartyNumberPosition||enum (see below)||"FromHeaderSIPURI"|
|IncomingFaxMethod||FaxMethods (see below)||"T38"|
|OutgoingFaxMethod||FaxMethods (see below)||"G711"|
|TransportType||enum (see below)||"NotSpecified"|
|RecvCalledPartyNumberPosition||enum CalledPartyNumberPositions (siehe unten)||"ToHeaderSIPURI"|
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
- 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:
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.
- 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)
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)
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:
- all "number formats" must be set to "CanonicalWithPlus".
- 'DtmfMode' must be set to "Rfc2833_Event".
- '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.
Since SwyxWare 11.00:
ReuseMediaPorts - determines if the RTP/RTCP media ports should be reused within a call.
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
This is an example for 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" />