4PSA Knowledge Base

Space shortcuts

Page tree

Applies to VoipNow 3 and higher!

This article describes the steps to take when you want to create a Service Provider template, which you will need for setting up a new SIP channel in VoipNow.

Overview

VoipNow lets you simplify the SIP channel configuration with the help of a SIP Provider Template. These templates are XML files that encapsulate specific settings required to easily set up the channel connection with a particular service provider, desired by the customer. The system administrators can upload to the interface the XML files for the desired providers. This way administrators do not have to manually fill in all the details or to update them in time, as VoipNow  periodically runs a cron script that checks the vendor's website (4psa.com) for the latest versions of the configuration files for the certified providers.

4PSA verifies and certifies the providers in order to offer you secure and reliable communication options for your company. The providers are grouped based on the certification level (Platinum, Gold, Silver, None) and the list is continuously updated.

Requirements

Before you start, you need to make sure you have the following:

  • VoipNow
  • Good XML knowledge
  • Awareness of the provider's specific settings

Provider templates usage

The provider template is basically a XML file that contains configuration information about a specific provider and the way the SIP channel set up based on this template will behave.

VoipNow offers you two ways to define and use the provider templates:

  1. First, you can download from the VoipNow interface one of the available predefined templates, modify its content according to your requirements and upload it in the system as a new provider template using the controls available in the Unified Communications → SIP Provider Templates page.
  2. Second, you can access the special customization form available on the website, fill in the desired parameters, save the automatically generated XML file to your machine and upload it from the VoipNow interface.

How to create a Service Provider template

All the provider templates must respect the default file structure, as explained in this example and in VoipNow User's Guide.

Here are the steps to take:

  1. Open your favorite text editor (e.g. Notepad++, jEdit).
  2. All the data must be grouped within the <provider-template> </provider-template> tags.

    First, set the UUID that identifies the template, for example 0062001:

    <provider-template uuid="0062001">
  .
  .
  .
</provider-template>


    When a user uploads a certificate, the system checks two things:

    1. First, it verifies if there is a certificate in the database with the same UUID. If not, then the new template is added. Else, the existing provider template is updated.
    2. Then the system checks if the template signature is valid. If so, then the Certification level is set to the specified value, Silver or Gold. Else, it is set to None.

    When the cron script updates the entries, the Certification level will be changed as required (e.g. to Silver or to Gold).

  3. Then all the relevant information about the provider must be included within the <provider> </provider> tags, as shown below.


    <provider>

	<!-- Name of the provider (as it appears in the VoipNow interface) -->
	<name>Foo Telecom</name>

	<!-- Certification level, requires signing by 4PSA -->
	<certification>Silver</certification>

	<!-- Provider's website -->	
	<website>http://www.foo.com</website>

	<!-- List of countries where the provider is active - at least one is
	required. -->	
	<active-countries>

		<!-- List countries, code ISO 3166 - for this example, two countries
		are considered, UK and NL -->

		<country>UK</country>		
		<country>NL</country>

	</active-countries>

	<!-- A short description about the provider -->		
	<description>Test provider for UK and NL</description>

</provider>


  4. The channel technical information is listed in the structure presented below. When a channel is created based on a template (in this case, Foo Telecom), this information will be used for setup. All the options available between the <channel> </channel> tags are the ones specific to a SIP channel and can also be manually configured from the interface. Not all the tags presented below are mandatory.


    <channel>
    
	<!-- VoipNow send calls to Hostname/IP -->
	<hostname visible="1">168.14.14.99</hostname>
	
	<!-- VoipNow send calls to Port -->
	<port visible="1">693</port>
	
	<!-- VoipNow accepts calls from IPs/network  -->	
	<acceptips visible="1">
		
		<ip>169.20.11.11</ip>
		<ip>192.166.66.66</ip>
		
	</acceptips>
	
	<!-- Username to connect to provider -->	
	<username visible="1">username</username>
	
	<!-- Password to connect to provider -->
	<password visible="1">password</password>
	
	<!-- Do not register with provider, the VoipNow IP is authenticated instead -->
	<donotregister visible="1">1</donotregister>
	
	<!-- Authorization username  -->
	<authorization-username visible="1">authusername</authorization-username>
	
	<!-- Concurrent calls (outgoing + incoming), usually should not be
	included in template -->
	<concurrent-calls visible="1">35</concurrent-calls>
	
	<!-- Charging plan, usually should not be included in template -->
	<charging-plan visible="1">free</charging-plan>
	
	<!-- Channel capabilities, usually should not be included in
	template -->
	<flow-capable visible="1">1</flow-capable>
	
	<!-- DTMF mode -->
	<dtmf visible="1">rfc2833</dtmf>
	
	<!-- Behind NAT -->
	<nat visible="1">0</nat>
	
	<!-- CallerID -->
	<callerid visible="1">0422</callerid>
	
	<!-- From user -->
	<from-user visible="0"></from-user>
	
	<!-- From domain -->
	<from-domain visible="1">144.369.21.44</from-domain>
	
	<!-- Authorization extension -->
	<auth-extension visible="0"></auth-extension>
	
	<!-- Get DID from custom header -->
	<did-header visible="0"></did-header>	
	
	<!-- Qualify, send SIP:Options to provider periodically -->
	<qualify visible="1">100</qualify>
	
	<!-- Prefix all calls with -->
	<prefix visible="0"></prefix>
	
	<!-- Trusted channel -->
	<trust visible="0"></trust>		
	
	<!-- Trust Remote-Party-ID SIP header -->
	<trust-rpid visible="0"></trust-rpid>
	
	<!-- Send Remote-Party-ID SIP header -->
	<send-rpid visible="0"></send-rpid>
	
	<!-- Session timers -->
	<session-timers visible="1">Accept</session-timers>
	
	<!-- Session refresh interval -->
	<session-refresh visible="1">180</session-refresh>
	
	<!-- Minimum session refresh interval -->
	<min-session-refresh visible="1">60</min-session-refresh>
	
	<!-- Session refresh source -->
	<refresh-source visible="1">UAS</refresh-source>
	
	<!-- Codecs: g723, ulaw, alaw, gsm, g726, slin, g729, speex,
	ilbc, lpc10, h261, h263, h263p, g726aal2, h264, g722  -->
	<permit-codecs visible="1">
	
		<!-- Codecs list -->
			<codec>gsm</codec>
			<codec>g726</codec>
			<codec>slin</codec>
		</permit-codecs>
	
	<!-- Use MD5 -->
	<md5 visible="1">1</md5>
</channel>

    The visibility variable specifies if the field will be displayed in the interface or not. When the value is set to 0, the option can still be managed, but only after clicking the Channel Preferences - Reveal All Fields link available in the Channels >> Add SIP channel page.

  5. An optional section that allows the labels displayed in the interface to be overridden without being modified can be present. The default labels will be used when the labels for the language used by the VoipNow interface are not available. This information can be found between the <label> </label> tags:


    <label>
	<!-- Code of the channel parameter, as defined above -->

	<trust>
		<locale code="en_US">
			<pre-label>PRE EN</pre-label>
			<post-label>POST EN</post-label>
		</locale>

		<locale code="ro_RO">
			<pre-label>PRE RO</pre-label>
			<post-label>POST RO</post-label>
		</locale>
	</trust>

	<min-session-refresh>
		<!-- What is displayed before the field value, if empty, the
		VoipNow Professional default value is used -->
	<pre value="IETF language tag">Hello</pre>

	<!-- What is displayed after the field value, has precedence over 
	the VoipNow Professional values even if it is empty -->
		<post value="IETF language tag">world</post>
	</min-session-refresh>
	.
	.
	.
</label>
  6. Optionally, you can include the certificate's signature. If it's missing or the information it contains is invalid, the template will not be certified. Else, the template will be added as Silver or as Gold. The signature content must be included between the <signature> </signature> tags:


    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
	<ds:SignedInfo>
		<ds:CanonicalizationMethod 
		Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
		<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
		
		<ds:Reference>
			<ds:Transforms>
				<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#
				enveloped-signature"/>
			</ds:Transforms>
	
			<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#
			sha1"/>
			<ds:DigestValue>2ofDWFo5K24zTp8fs0b4Fzl+X/4=</ds:DigestValue>
		</ds:Reference>
	</ds:SignedInfo>
	
	<ds:SignatureValue>nUcF/6qtlpDk4TFEl79kF2aASZSJQtqrGF1UcqR5UM+aCMcc
	Ve8Vdjc6kb3ClGwDB40f6c5Gci1Mb8auOKfGIpFW2x6M6DwKaGQCrsK2GSdigR2rtcn5Bdo72
	QhD2T4FpRyoOPZ7yXrv0fC5udFT+02TQmDXxRMqUIX+uFzRNX8=</ds:SignatureValue>
	
	<ds:KeyInfo>
		<ds:X509Data>
			<ds:X509Certificate>MIICaTCCAdICCQCzngU1YWDilTANBgkqhkiG9w
			0BAQUFADB5MQswCQYDVQQGEwJybzENMAsGA1UECBMEYWxiYTEOMAwGA1UEBxMFY3
			VnaXIxDTALBgNVBAoTBGxpYXMxDTALBgNVBAsTBGxpYXMxEDAOBgNVBAMTB2xpYX
			Mucm8xGzAZBgkqhkiG9w0BCQEWDGxpYXNAbGlhcy5ybzAeFw0xMTAxMDUxMjMxMj
			RaFw0xMjAxMDUxMjMxMjRaMHkxCzAJBgNVBAYTAnJvMQ0wCwYDVQQIEwRhbGJhMQ
			4wDAYDVQQHEwVjdWdpcjENMAsGA1UEChMEbGlhczENMAsGA1UECxMEbGlhczEQMA
			4GA1UEAxMHbGlhcy5ybzEbMBkGCSqGSIb3DQEJARYMbGlhc0BsaWFzLnJvMIGfMA
			0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDYxCgqKvQxQDeIVm0ghzTTLxC2BnqlUd
			5N5phYzlsGAPpwwavzP2INaHGSVqzSadNwEqTvBOrh4Q0mvAimy3gJCCKxVlIAG
			GaFHaVmUW7FuSMV/E0ZFcL1gtxPkMExykt9zed4q+JhtWAjQiBRHo5NcGK/QvX4B
			hzL96abaayRsQIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAD5YBI0Hr0CGIbajU4bmt
			c8xObmOZ2SM2OF/llHRvyPk2w9AeM9g3e95sAExnSZWg2vviEKOHm2N0Y0FV4VuR
			X3q1iEq87YJ7G8XYLbT5dlebi2B0kiPgSSZkPwsJlNLfsAwUR/H63bPGKHSL5ye+
			jZeivXgpErhKWEP95Do4l/Y</ds:X509Certificate>
		</ds:X509Data>
	</ds:KeyInfo>
</ds:Signature>


    The XML template should be signed according to the XML Signature Syntax and Processing standard.

  7. After you have defined all the required parameters, you can save the data as a .xml file (e.g. foo_telecom.xml).

How to upload the Provider template

Now that you have defined the preferences for your desired provider, in our example Foo Telecom, and the behavior of the SIP channel that will used to communicate with this provider, you can upload the template from the VoipNow web interface:

  1. Log in to your administrator account.
  2. Go to the Unified Communications → SIP Provider Templates page and click the Add provider template icon.
  3. Use the Browse icon to locate the recently created provider template.
  4. Then press OK to upload the file to the system.

If the file you are trying to upload does not match the default provider template structure, then it will not be saved to the database. A warning message like the one below will be displayed:

Failed to upload the new template.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.