Universal Provisioning thru TFTP and DHCP

Overview

SARK UCS/MVP has an extensible provisioning system. This provides two benefits. Firstly, it allows the user to edit and add their own provisioning parameters to configuration files. Secondly, it allows the user to create configuration files for any unsupported phone provided the configuration files are in plain text.

SIP provisioning

In general, most of the popular SIP phone types can be automatically provisioned (configured) using either TFTP ot HTTP (most support both). Actual provisioning is usually achieved by providing each phone with some sort of script file, often in XML, which describes the phone's attributes; for example, extension number, address of the SIP server and so on. These script files are almost always saved with a common naming protocol (chosen by the manufacturer) which contains the MAC address of the phone. As an example, Aastra use {MAC Address}.cfg, Snom use snom{model Number}-{MAC Address}.htm. In this way, it is quite straightforward for a phone to issue a TFTP read or HTTP GET to retrieve its provisioning information from the provisioning server.

In addition, many manufacturers also use additional script files. Most have the notion of a "common" script file. Since much of the information required by each phone in a given installation is always the same, the programmer can create a single common file which all phones will retrieve in addition to the MAC specific file. This can save a lot of time in intial coding and ongoing maintenance. For example, Aastra have a common script file called aastra.cfg. Snom allow a common script file for each of their phone types; snom300.htm, snom320.htm, snom360.htm and so on, while Cisco use a file called SIPDefault.cnf.

Some manufacturers use still more script files to hold other types of common information such as logfiles, image files and so on.

SARK can map and maintain most of these filetypes for you using its two provisioning file types (Templates and Descriptors) and its substitutional variables...

Templates and Descriptors

Templates are used to define the MAC address based script files that a particular phone requires while Descriptors are used to create the common and ancillary files which a particular manufacturer requires. They are both defined in the IP Devices panel. Templates are defined as part of the individual phone definitions while descriptors are defined using their own file type.

Each time a new phone extension is created in the extensions panel, the template data is copied from the IP Device definition in the SARK database and made available in the provisioning window of the extension edit panel. Here is a diagram of the process using a Cisco 7960 as an example...

During the copy operation, the copy routine will substitute real values into the SARK templating variables (those which begin with a $ symbol) in all but one specific case -$localip (see below).

Descriptor files are created/recreated on the TFTP server and HTTP server each time you issue a COMMIT.

Template File Rules

A templating mechanism is used to generate the configuration files. The IP Devices panel in the server manager contains templates for each supported device. When a device is edited or a new device is created, a freeform text area is created for provisioning. It is into this text area that the provisioning template details are entered.

Currently, provisioning file templates have been set up for Grandstream, Linksys Sipura, Aastra, Cisco and Snom IP phones. You can set up provisioning templates of your own for new phone types by following the guidelines below.

1. '[' and ']' are the file delimiters. '[' starts a script file, and ']' ends it. In this way, you can specify more than one script file per device if necessary. We've never had to do this in practice but the capability is there if needed.
2. The filename directly follows the start file delimiter, and must be in double quotes. It is usually made up of the special variable $MAC or $MAU combined with the fixed elements which the vendor requires.

• If the filename contains the variable $MAC, replace this with the lowercase MAC Address.
• If the filename contains the variable $MAU, replace this with the uppercase MAC Address.

3 Freeform text - usually as specified in the phone manuufacturer's provisioning guide. You can freely add substitutional variables as follows...

• $MAC will be replaced by the device MAC address using lower case
• $MAU will be replaced by the device MAC address using upper case
• $ext will be replaced by the extension number
• $desc will be replaced by the extension SIP/IAX name
• $password will be replaced by the generated password (secret).
• $localip. In releases prior to 2.2.1-650, $localip will be replaced by the local IP address. This changed in release -650 such that the variable is not replaced until file generation time (i.e. the COMMIT).

Template example for an Aastra phone.

["$MAC.cfg"
sip screen name: $desc
sip user name: $ext
sip display name: $ext
sip auth name: $ext
sip password: $ext
sip proxy ip: $localip
]

This example shows a name of "$MAC.cfg". The MAC variable will be replaced by the lower-case MAC address. The example has a mixture of constant and variable provisioning parameters.

Descriptor file rules.

Descriptor files are created in the IP Devices panel. They are used to build the "common-data" files required by many vendors. The name you give to a descriptor will be the name which it is stored as on the TFTP and HTTP servers. So, for example, Aastra phones look for a common file called aastra.cfg. So we can create a descriptor file called "aastra.cfg" and populate it according to the manufacturers guidelines...

example aastra.cfg:-

download protocol: TFTP
sip proxy ip: $localip
sip proxy port: 5060
sip outbound proxy: $localip
sip outbound proxy port: 5060
sip registrar ip: $localip
sip registrar port: 5060
sip registration period: 0
time server1: pool.ntp.org
time zone name: GB-London
sip vmail: *50*
sip mode: 0

Here is another example, this time for Cisco 79XX phones. Cisco phones look for common files called SIPDefault.cnf and RINGLIST.DAT...

Example SIPDefault.cnf:-

; sip default configuration file

# Image Version
image_version: P0S3? -08-7-00 ;
# Proxy Server
proxy1_address: $localip;
proxy_register: 1 ;
logo_url: "http://sarkpbx.com/sail/Cisco_79XX_logos/logoSARKPBX.bmp" ;

Example RINGLIST.DAT:-

Piano 1 Piano1.raw
Piano 2 Piano2.raw
Pop Pop.raw
Pulse Pulse1.raw
Old Style ringer1.pcm
Synth Low ringer2.pcm

It should be noted that you can also use $ variables inside descriptor files; in the above SIPDefault.cnf example, you can see that we use $localip.

Descriptors are very flexible because you can pretty much model any kind of plain text file and give it any name you wish. This allows us to model a large number of different manufacturer provisioning models.