Using TFTP to provision Tesira VoIP cards
This article describes how to configure a TFTP file for provisioning VoIP card properties in Tesira Server and Server-IO with SVC-2 card, TesiraFORTÉ VT and VI. Beginning with software and firmware version 3.15, Tesira VoIP card attributes can be provisioned using a JSON file delivered via TFTP (Trivial File Transfer Protocol).
Many proprietary VoIP systems support TFTP for their devices, it allows the devices to automatically pull their configuration information from a host database. Since the Biamp devices are not part of that proprietary system the user will need to manually populate and upload a JSON configuration file with the correct settings to their database.
To configure the VoIP endpoint via TFTP, Tesira’s VoIP card must be pointed to a TFTP server to download a VoIP attributes file with the correct VoIP account details.
Many users may still choose to manually configure the Tesira VoIP settings via the Tesira configuration file or VoIP web interface rather than create the TFTP file. Options for manual configuration can be found on our VoIP webpages.
Note that TFTP is not an encrypted data transfer protocol so any VoIP account authentication passwords will potentially be exposed using this method.
If additional certificates and authentication are required for TLS or 802.1x then these attributes will need to be configured properly at this time as well. Please review our documentation specific to those topics as needed.
Preparing the Tesira configuration file
Tesira’s VoIP card must be configured to use TFTP by the Tesira programmer. This is done as part of the Tesira system configuration file.
Note that certain network details must be populated on the VoIP card to allow TFTP provisioning. VoIP network details will need to be provided by the customer’s VoIP administrator.
- The Tesira system must be configured (programmed) before a TFTP transfer can occur.
- If a static IP address is to be used by the VoIP port it must be defined along with subnet and gateway in the Tesira file.
- If a VoIP VLAN is used, VLANs must be enabled and the correct VLAN defined in the Tesira file.
- The TFTP network provisioning server address options must be defined in the Tesira file.
- If Tesira VoIP webpage access is desired, or if VoIP Telnet is desired, then these should be enabled in the Tesira file.
- The Tesira programmer must make note of the MAC address of the VoIP (SVC-2) card for correct naming of the JSON file for TFTP transfer.
TFTP Network Provisioning Server address
The network location of the TFTP server must be specified in the Tesira configuration, the VoIP administrator should be able to provide the correct information for discovery.
The location of the TFTP server can be specified as a static IP address or hostname, or the location can be communicated to the Tesira device from a DHCP server using the DHCP configuration options.
The settings can be defined either:
- in the Properties sheet for the VoIP Control/Status block under Network Provisioning Server or
- within the VoIP Control/Status block’s Network tab (while in the Advanced view) under Provisioning Server.
Any single TFTP configuration method described below can be used to point a Tesira VoIP endpoint to a valid TFTP location. A correctly named and formatted JSON attribute file must be loaded to the data folder of the TFTP server for delivery to Tesira VoIP. TFTP file requests are sent by the Tesira VoIP card on boot, power cycling the host Tesira device is the recommended manner of manually rebooting the VoIP card.
To disable TFTP in the VoIP card set the TFTP Server Mode to None.
Tesira VoIP supports TFTP Server discovery using static addressing or DHCP methods.
The next steps will detail setting up a TFTP Server connection within Tesira software. This process must be followed if TFTP is to be used.
Static IP address configuration
The Tesira VoIP card may be configured to use static IP addressing.
If the Tesira VoIP card's IP address is set to static (DHCP is disabled) and TFTP provisioning is desired, then the TFTP Server Address field must be populated with a static IP address or hostname. The TFTP Server Mode DHCP options are not available and are hidden while the card's DHCP is disabled.
Static
- Disable the DHCP option in the VoIP Control-Status block, set an IP address, subnet mask, and gateway in the popup window and click OK.
- Change the TFTP Server Mode to Static.
- Enter the static IP or hostname in the popup window and click OK. The TFTP Server Address field should reflect the changes made.
DHCP configuration options
The Tesira VoIP card may be configured to use DHCP addressing.
The Tesira VoIP card IP address must first be set to DHCP ‘Enabled’ for the TFTP DHCP options to be exposed in the TFTP Server Mode menu. Users can choose the default DHCP option 66, or provide a custom option number using string or binary notation.
The use of a static IP address or hostname for the TFTP Server Address is also supported while the VoIP card is DHCP enabled.
Static
- Change the TFTP Server Mode to Static.
- Enter the static IP or hostname in the popup window and click OK. The TFTP Server Address field should reflect the changes made.
TFTP Server locations can be provided via a DHCP exchange. If the network supports this method and the Tesira endpoint is configured to use DHCP, a DHCP option can be used to tell Tesira the IP address of the TFTP server. The default DHCP option number for TFTP is 66.
It is possible to use a custom DHCP Option number for TFTP location services. However, the method that the DHCP server uses to deliver the address must also be considered in this case. The DHCP server may send the information using a string value or by providing a binary value. Tesira offers support for both methods.
DHCP Option 66
- To obtain the TFTP Server Address using DHCP option 66 set the TFTP Server Mode to DHCP 66.
DHCP Custom (string or binary)
- Set the TFTP Server Mode to either DHCP Custom (String) or DHCP Custom (Binary)
- In the DHCP Custom Option enter the DHCP option number to be used, the default value is 150. This value can only be edited while DHCP Custom is selected.
Find the MAC Address of the VoIP card
The MAC address of the VoIP port is used as the unique filename for the JSON attribute file to be uploaded over TFTP. The correct format is bsipXXXXXXXXXXXX.json, where all letters in the MAC address are lower case.
- The VoIP card (SVC-2) MAC address can be found while on- or offline in Tesira software’s Equipment Table > Device Information tab for a previously discovered and compiled device.
- The VoIP card (SVC-2) MAC address is also available while online in Tesira software’s Device Maintenance > Network Settings on the MAC Addresses tab.
JSON file
Click here to jump ahead to the TFTP JSON file templates section.
The template can be sent to the VoIP system administrator to add the details specific to the VoIP endpoint. They can then save and rename the file to match the VoIP card’s MAC address, or you may wish to create properly named blank template files for them for each MAC address being provisioned.
The VoIP admin will need to update the file with the account settings and information for each VoIP endpoint. The Tesira SVC-2 VoIP card supports 2 unique VoIP endpoints (line 1 and line 2) and one or both may be provisioned using the JSON file.
The VoIP admin will then need to upload the file to their TFTP database.
The expected file name is bsipXXXXXXXXXXXX.json where the X's are replaced by the 12-character MAC address of the Biamp VoIP card. (E.g. bsip00905e12b4e3.json)
Please refer to the parameter matrix at the end of this article for correct formatting of parameters. JSON formatting does not support commenting out lines to disable or hide unused parameters, so only required parameters should be included in the final file. The formatting of the final JSON file should be validated using a JSON file editor such as https://jsonformatter.org/json-editor.
The matrix of parameters defines the correct syntax for each field. In general:
- Integer and Enum values do not need quotes.
- String values need quotes.
- If a parameter isn’t the only one in a section, it must be ended with a comma.
- Only required and defined parameters should be included in the file.
- Parameters manually entered on the VoIP card will be overwritten with new values when present in the JSON file.
- If parameters are not provided in the file, they are left as is and not changed.
- If invalid parameters are provided, existing parameter values are left in place.
When imported, the JSON file will only overwrite those fields in the Biamp VoIP configuration for which it has parameters defined. Invalid formatting will result in the existing parameters being left in place for any affected parameters.
Note: If Authentication Passwords are required they should be set either in the Tesira configuration software or via secure VoIP webpage interface (HTTPS), if they are set via the TFTP file they will be sent as plain text during the TFTP transfer.
Once it is online, the Biamp VoIP card will attempt to connect to the TFTP Server at the address defined earlier, where it will request the .json file corresponding to its MAC address. It will import the information from that file to populate its VoIP configuration settings and then attempt to register with the defined proxy server. No further configuration should be required.
Troubleshooting
Note that certain requirements must be met to allow TFTP provisioning of the VoIP card.
- The Tesira system must be configured (programmed) before a TFTP transfer can occur.
- The Tesira programmer must note the MAC address of the VoIP (SVC-2) card for correct naming of the JSON attribute file.
- A correctly named and formatted VoIP parameter .json file must be loaded to the TFTP server database.
- The TFTP server address options must be defined by the Tesira programmer in the Tesira file.
- If a VoIP VLAN is used, the Tesira programmer must enable VLANs and define the correct VLAN in the Tesira file.
- If a static IP address is to be used by the VoIP port the Tesira programmer must define it, along with subnet and gateway, in the Tesira file. If the JSON file defines DHCP as true or undefined then DHCP will be enabled on the card when the file loads.
- If 802.1x port authentication is used the Tesira programmer must correctly provision the authentication method. 802.1x attributes are not defined via the JSON file.
- If Tesira VoIP webpage access is desired, or if VoIP Telnet is desired, then these should be enabled by the Tesira programmer in the Tesira file to assist debugging if the file transfer fails.
- Wireshark will show file requests from Tesira VoIP to the IP address of the TFTP server using port 69. Return traffic is not on port 69 but will indicate if the expected file is not found or if it data is transferred. If no response is seen the TFTP server may not be active, the network address may be incorrect, or firewalls may be blocking access to the TFTP server.
- The TFTP server interface should indicate file requests from the Tesira VoIP and show failed or completed transfers.
TFTP file discovery will be initiated on a reboot of the VoIP card. The preferred method of manually rebooting the VoIP card is to power cycle the Tesira.
For TFTP servers hosted on a PC a custom firewall rule for inbound traffic on port 69 with private/domain/public allowed may be required.
JSON Templates
Below are examples of the JSON file template.
Parameters are categorized into different sections based upon functionalities.
Tesira VoIP supports two VoIP profiles or channels. In thechannelAttrssection, the square bracket denotes an array which includes 2 curly brace framed sections, each is an independent channel definition for Line 1 and Line 2.
If a parameter isn’t the only one in a section, it must be ended with a comma.
If users don’t need to change a parameter, they must not put the parameter in the file.
Cisco Call Manager
Click to download file CCM-template-bsipXXXXXXXXXXXX.json
{
"NOTE - template for Cisco Call Manager": "",
"NOTE - card attributes are network port settings shared by both Line 1 and Line 2": "",
"cardAttrs": {
"sipConfig": {
"NOTE – transport type 1=UDP, 2=TCP, 3=TLS.": "",
"transport": 1
}
},
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"channelAttrs": [
{
"NOTE - Line 1": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line1",
"sipDisplayName": "Line 1",
"proxy": {
"proxyAddr": "192.168.1.100",
"proxyPort": 5060
},
"auth": {
"authUser": "Line1",
"authPasswd": "1234"
},
"miscInfo": {},
"NOTE - vendor defines the VoIP provider": "",
"vendor": 6
}
},
{
"NOTE - Line 2": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"NOTE – Delete this entire section if Line 2 is not being used": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line2",
"sipDisplayName": "Line 2",
"proxy": {
"proxyAddr": "192.168.1.100",
"proxyPort": 5060
},
"auth": {
"authUser": "Line2",
"authPasswd": "1234"
},
"miscInfo": {},
"vendor": 6
}
}
]
}
Microsoft Skype for Business
Click to download file Skype-template-bsipXXXXXXXXXXXX.json
{
"NOTE - template for Microsoft Skype for Business": "",
"NOTE - card attributes are network port settings shared by both Line 1 and Line 2": "",
"cardAttrs": {
"sipConfig": {
"NOTE – transport type 1=UDP, 2=TCP, 3=TLS.": "",
"transport": 3
}
},
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"channelAttrs": [
{
"NOTE - Line 1": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line1",
"sipDisplayName": "Line 1",
"sipDomain": "dev.biamp-SfB.com",
"proxy": {
"NOTE - proxyAdddr can be static IP or FQDN, if FQDN is used proxyPort must be 0": "",
"proxyAddr": "dev.biamp-SfB.com",
"proxyPort": 0
},
"auth": {
"authUser": "Line1",
"authPasswd": "1234",
"NOTE - authNetBiosName is only used for Skype-for-Business": "",
"authNetBiosName": "Skypetest"
},
"miscInfo": {},
"NOTE - vendor defines the VoIP provider": "",
"vendor": 8
}
},
{
"NOTE - Line 2": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"NOTE – Delete this entire section if Line 2 is not being used": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line2",
"sipDisplayName": "Line 2",
"sipDomain": "dev.biamp-SfB.com",
"proxy": {
"NOTE - proxyAdddr can be static IP or FQDN, if FQDN is used proxyPort must be 0": "",
"proxyAddr": "10.10.10.26",
"proxyPort": 5061
},
"auth": {
"authUser": "Line2",
"authPasswd": "1234",
"NOTE - authNetBiosName is only used for Skype-for-Business": "",
"authNetBiosName": "Skypetest"
},
"miscInfo": {},
"vendor": 8
}
}
]
}
Shoretel Director
Click to download file Shoretel-template-bsipXXXXXXXXXXXX.json
{
"NOTE - template for Shoretel Director": "",
"NOTE - card attributes are network port settings shared by both Line 1 and Line 2": "",
"cardAttrs": {
"sipConfig": {
"NOTE – transport type 1=UDP, 2=TCP, 3=TLS.": "",
"transport": 1
}
},
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"channelAttrs": [
{
"NOTE - Line 1": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line1",
"proxy": {
"proxyAddr": "192.168.1.100",
"proxyPort": 5060
},
"auth": {
"authUser": "Line1",
"authPasswd": "1234"
},
"miscInfo": {
"sessionTimer": {
"sessionTimerEnable": "true",
"refresher": 2
}
}
},
"NOTE - vendor defines the VoIP provider": "",
"vendor": 7
},
{
"NOTE - Line 2": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"NOTE – Delete this entire section if Line 2 is not being used": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line2",
"proxy": {
"proxyAddr": "192.168.1.100",
"proxyPort": 5060
},
"auth": {
"authUser": "Line2",
"authPasswd": "1234"
},
"miscInfo": {
"sessionTimer": {
"sessionTimerEnable": "true",
"refresher": 2
}
}
},
"vendor": 7
}
]
}
Avaya Session Manager
Click to download file Avaya-SM-template-bsipXXXXXXXXXXXX.json
{
"NOTE - template for Avaya SM": "",
"NOTE - card attributes are network port settings shared by both Line 1 and Line 2": "",
"cardAttrs": {
"sipConfig": {
"NOTE – transport type 1=UDP, 2=TCP, 3=TLS.": "",
"NOTE - proxyPort should be 5060 if UDP or TCP are used, or 5061 if TLS is used.": "",
"transport": 1
}
},
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"channelAttrs": [
{
"NOTE - Line 1": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line1",
"sipDisplayName": "Line 1",
"proxy": {
"NOTE - proxyAdddr should be static IP for Avaya SM.": "",
"NOTE - proxyPort should be 5060 if UDP or TCP are used, or 5061 if TLS is used.": "",
"proxyAddr": "10.10.10.26",
"proxyPort": 5060
},
"auth": {
"authUser": "Line1",
"authPasswd": "1234"
},
"miscInfo": {},
"NOTE - vendor defines the VoIP provider": "",
"vendor": 3
}
},
{
"NOTE - Line 2": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"NOTE – Delete this entire section if Line 2 is not being used": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line2",
"sipDisplayName": "Line 2",
"proxy": {
"NOTE - proxyAdddr should be static IP for Avaya SM": "",
"NOTE - proxyPort should be 5060 if UDP or TCP are used, or 5061 if TLS is used.": "",
"proxyAddr": "10.10.10.26",
"proxyPort": 5060
},
"auth": {
"authUser": "Line2",
"authPasswd": "1234"
},
"miscInfo": {},
"vendor": 3
}
}
]
}
Mitel ICP
Click to download file Mitel-ICP-template-bsipXXXXXXXXXXXX.json
{
"NOTE - template for Mitel ICP": "",
"NOTE - card attributes are network port settings shared by both Line 1 and Line 2": "",
"cardAttrs": {
"sipConfig": {
"NOTE – transport type 1=UDP, 2=TCP, 3=TLS.": "",
"NOTE - proxyPort should be 5060 if UDP or TCP are used, or 5061 if TLS is used.": "",
"transport": 1
}
},
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"channelAttrs": [
{
"NOTE - Line 1": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line1",
"sipDisplayName": "Line 1",
"proxy": {
"NOTE - proxyAdddr should be the static IP of the Mitel server.": "",
"NOTE - proxyPort should be 5060 if UDP or TCP are used, or 5061 if TLS is used.": "",
"proxyAddr": "10.10.10.26",
"proxyPort": 5060
},
"auth": {
"authUser": "Line1",
"authPasswd": "1234"
},
"miscInfo": {},
"NOTE - vendor defines the VoIP provider": "",
"vendor": 9
}
},
{
"NOTE - Line 2": "",
"NOTE - channel attributes are unique for Line 1 and Line 2": "",
"NOTE – Delete this entire section if Line 2 is not being used": "",
"dialPlan": {
"dialingTimeOut": 3,
"dialPlan": "[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT"
},
"sipInfo": {
"sipUser": "Line2",
"sipDisplayName": "Line 2",
"proxy": {
"NOTE - proxyAdddr should be the static IP of the Mitel server": "",
"NOTE - proxyPort should be 5060 if UDP or TCP are used, or 5061 if TLS is used.": "",
"proxyAddr": "10.10.10.26",
"proxyPort": 5060
},
"auth": {
"authUser": "Line2",
"authPasswd": "1234"
},
"miscInfo": {},
"vendor": 9
}
}
]
}
Configurable parameters for Tesira VoIP JSON file
|
Parameter or Section Header |
Values (Blank if section header) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|