Auto-provision (Auto-Tuning) Polycom Phones Using Asterisk

Task: Set up phones (or any other subscriber device) automatically based on the MAC address, preferably without taking the device out of the box.

The idea of ​​centralized configuration of subscriber devices has long been with me and, finally, found its implementation in one of the projects. Video at the end of the post.
Almost all (Cisco, Polycom, D-Link, Escene) IP phones that I have met with, in one form or another, support centralized configuration from the server, i.e. Auto-provisioning by our auto-provision. In this case, the example with Polycom phones is considered, but in essence, a similar approach will allow you to configure any phone with certain adjustments.

How does it work (about Polycom)?

The phone is configured by default to obtain an IP address via DHCP, in addition to the address itself, the phone receives a number of options from DHCP , among which the gateway, netmask and DNS server are usually indicated, in addition, you can specify the SNTP server and much more. Polycoms look by default at options 66 and 160, there they try to find the address / name of the auto-provision server. If the phone detects the server address, it tries to connect to it by default via FTP (it also supports HTTP, HTTPS, TFTP), using as login and password:

The phone asks the server for the version (sip.ver file) and the firmware files themselves and configuration files. The phone downloads new firmware, updates, then after a reboot, it contacts the server again, sees that the software does not require updating, downloads and applies configuration files in XML format. In general, the machine requests the following files.

File name
General configuration file (says what and where to download)
* .sip.ld (for split)
sip.ld (for combined) *
Phone firmware of the corresponding model (set from 0000000000.cfg),
Software version
Phone Configuration with MAC Address 1234123adba

* - Polycom has two versions of combined software (it weighs a lot) - suitable for everyone, split - for each line of phones there is a separate small * sip.ld file (reduces the load on the network).
It would seem that's all, the phone is ready to go! In fact, for small systems the way it is, i.e. enough:
  1. Download firmware from the manufacturer’s website for their phones
  2. In 0000000000.cfg specify which configuration files the phone should download from the server (CONFIG_FILES = "custom.cfg"), this is enough, because default.
  3. Create custom.cfg containing settings common to all devices.
  4. Create several conf files for each of the devices <MAS-address> .cfg which will contain information unique to each subscriber i.e. in general, only his SIP login and password.

This solution will allow you to quickly deploy a small VoIP infrastructure, however, on large systems, you will have to create many files of the same type and is convenient and does not have much flexibility. It’s also boring.

So I went a more sophisticated way:
  1. Via FTP we configure the phone so that it receives files via HTTP: 8088
  2. On Asterisk, using phoneprov, we dynamically generate a configuration file for each phone based on the users.conf file.

With this method of configuration, it will be enough to add its MAC in users.conf to add a new device and set the username and password there, the rest of the configuration is automatic.
Now in more detail we will consider what needs to be done:

DHCP setup

In this case, I set the static addresses for each device through the config, i.e. The device needs a dynamic address only in the first and second boot, after the third it is already fully configured and has a static IP. Therefore, I set the rental time - 5 minutes, so as not to occupy the address pool in the empty. In the general case, addresses can also be distributed dynamically by making a reservation for each MAC. In addition, you need to add option 66 or 160 - to your taste, containing the address of the provisioning server. In Windows, this is done like this:

In my case, Mikrotik:

So, it is necessary that the addresses and options 66 with the address of the provisioning server are dynamically distributed. In my case, the range of dynamic addresses is from 20 to 99, and the 101-199 range for static addresses is to make the internal number of the subscriber match his IP.

Phone setup via FTP

To configure via FTP, you need FTP, set (CentOS):
yum install -y vsftpd
chkconfig vsftpd on
service vsftpd start

You can configure via /etc/vsftpd/vsftpd.conf.
Create a user under which polycom will try to connect:
useradd PlcmSpIp
passwd PlcmSpIp

Given the complexity of the password, it will be worthwhile to make sure that this user is as powerless as possible.
Now download the archive with the firmware and unpack it in / home / PlcmSpIp.

When you download the firmware, read the warnings carefully, most likely you will have to download the bootloader updates as well, we also unpack them in the / home / PlcmSpIp directory.

At the moment, the phone connected to the network should, when turned on, pump out a new bootloader and firmware and update the software.

Work with configuration files

Then I lost a lot of time trying to edit XML with my hands, and I conjure you, oh reader, do not edit configs with a text editor if you are not Obi-Wan-Kenobi in the XML world. To work with configs, I used XML Notepad 2007. If you downloaded the combined version firmware, then in the config folder there will be several configuration files with the * .cfg extension and the polycomConfig.xsd XML schema. 
* .cfg - examples of configuration files are thematically grouped
 Setting up video integration
 Set up video calls
 There are a lot of things, maybe even all the settings
 Settings for sip, calls, tones
 Sip settings
 Regional settings
 SIP registrations - basic
 SIP Registration - Extended
 H323 Settings
 Transfer Hold Forwarding Settings
 Device Settings, Network System
 Application settings

Each file has a line like this:

This means that if you open the configuration file with an XML editor, it will look for the polycomConfig.xsd schema file in the same folder, it contains all the possible fields of the configuration file and a list of available values ​​or a short comment. At this stage, we need to show the device that the download should be via HTTP and specify the http path to the configuration files.
In the folder with polycomConfig.xsd, create the text file custom.cfg with the following contents.

Open it with an XML editor. What fields that contain need to be searched by Google or use the 600-page instruction for the administrator to configure the phones of the manufacturer.
But for the most part, everything is intuitive. First, create an element (probably you should say a section or something else, but I don’t know and therefore I will name it as they are called an XML editor, i.e. an element) using the polycomConfig context menu or simply ctrl + insert while standing on polycomConfig.

In the drop-down list, select device because we are interested in the device settings, in the same way we create the device.dhcp element in the device element.

Now in it we create the Alt + Insert attribute or from the context menu on device.dhcp, a drop-down list of available attributes opens, when you hover a tooltip with available values ​​pops up.

We set Static - in our case this means that DHCP options 160 and 66 should be ignored. Similarly, we set other parameters, as a result, we have the following file:

Set device preferences
device.dhcp.bootSrvUseOpt = "Static"
Ignore DHCP Options 66 and 160
device.dhcp.enabled = "1"

Set value dhcp.enabled

Set bootSrvUseOpt value
device.prov.serverName = "http: // 8088 / phoneprov /"
File path
device.prov.serverType = "HTTP"
Provisioning Server Type

Set serverName

Set serverType

Particular attention should be paid to the attributes in bold, this is something like a switch, i.e. it’s not enough just to enter the value of some parameter and you need to say specifically “Yes”, this parameter must be applied. Especially importantbecause if this parameter is 0, then all settings of the device element will be ignored.

Asterisk Settings

That's it, now our phones will ask for files when downloading from : 8088 / phoneprov /. It is necessary to sublimate them there from nothingness. For this value, Asterisk has a special module, it allows you to automatically generate files based on templates and send them through the built-in HTTP server of the asterisk. More information can be found here and in particular it says:
Make sure that /etc/asterisk/manager.conf contains:
enabled = yes; - probably this is necessary, although it is not clear to me why
webenabled = yes; - probably it’s necessary, although it’s not clear to me why it is necessary to make

sure that /etc/asterisk/http.conf contains:
enabled = yes; includes an embedded HTTP server
bindaddr =; IP - on which the
bindport = 8088 server will be available ; - because The port 80 is occupied by Apache, we use 8088

When requesting a file from the http server, phoneprov takes the file template and substitutes the variables that it takes from users.conf and, which is especially nice, you can use the text functions of the dial plan. For example, $ {TOLOWER ($ {MAC})} in the template will be replaced when the configuration file is formed on the user's MAC address in lower case.
The following variables can be used in the template:
fullname = User Two ; ${DISPLAY_NAME}
secret = test ; ${SECRET}
username = 6001 ; ${USERNAME}
macaddress = deadbeef4dad ; ${MAC}
label = 6001 ; ${LABEL}
cid_number = 6001 ; ${CALLERID}
кроме того можно использовать:
${SERVER} – берется из phoneprov.conf если там не задана, то берет значение bindaddr из http.conf
${SERVER_PORT}  - берет значение bindport  из sip.conf, если оно не задано, то 5060

The configuration file of res_phoneprov itself is /etc/asterisk/phoneprov.conf, in it you need to specify the directory of static files relative to the path / var / lib / asterisk / phoneprov /, a list of static files, a list of templates and name templates for dynamically generated files. Here is an example:
serveraddr=192.168.ххх.ххх ; задается переменная ${SERVER}.
serverport=5060        ; задается переменная ${SERVER_PORT}.
default_profile=polycom ; профиль по умолчанию если не задан в users.conf
staticdir => configs/ ; Сюда кладете статические файлы, прошивку, фоновые картинки, телефонный справочник и т.п., путь относительно /var/lib/asterisk/phoneprov/
mime_type => text/xml
static_file => 2345-12345-001.bootrom.ld
static_file => 2345-12360-001.bootrom.ld
static_file => 2345-12365-001.bootrom.ld
static_file => 2345-12365-002.bootrom.ld
static_file => 2345-12375-001.bootrom.ld
static_file => 2345-12375-002.bootrom.ld
static_file => 2345-12450-001.bootrom.ld
static_file => 2345-12450-002.bootrom.ld
static_file => 2345-12500-001.bootrom.ld
static_file => 2345-12560-001.bootrom.ld
static_file => 2345-12600-001.bootrom.ld
static_file => 2345-12600-002.bootrom.ld
static_file => 2345-12670-001.bootrom.ld
static_file => 2345-12670-002.bootrom.ld
static_file => 3111-15600-001.bootrom.ld
static_file => 3111-30900-001.bootrom.ld
static_file => 3111-40000-001.bootrom.ld
static_file => bootrom.ld
static_file => sip.ver
static_file => sip.ld
static_file => 000000000000-directory.xml ;- это телефонный справочник
static_file => languages/Website_dictionary_language_ru-ru.xml
static_file => SoundPointIPLocalization/Russian_Russia/SoundPointIP-dictionary.xml
${TOLOWER(${MAC})}.cfg => 000000000000.cfg ;Это значит, что при запросе http://192.168.ххх.ххх:8088/phoneprov/111111111111.cfg будет сформирован файл из шаблона 000000000000.cfg с именем 111111111111.cfg,  при этом значения переменных будут взяты из файла users.conf из того юзера у которого macaddress=111111111111
${TOLOWER(${MAC})}-custom.cfg => 000000000000-phone.cfg ;При запросе файла http://192.168.ххх.ххх:8088/phoneprov/111111111111-custom.cfg будет сформирован файл 111111111111-custom.cfg при этом значения переменных будут взяты из файла users.conf из того юзера у которого macaddress=111111111111

With static files, everything is simple, if the file is registered in phoneprov.conf and is located at the appropriate address, then it will be available from the web server.
With dynamic, it seems a little more complicated, but now everything will become clear. Here is an example of patterns:

By default, all phones request the file 1234123adba.cfg, where 1234123adba is the MAC address of the phone, i.e. the phone will send a request http: // 8088 / phoneprov / 1234123adba.cfg . There is only one variable in this template, and the CONFIG_FILES = "$ {TOLOWER ($ {MAC})} - custom.cfg" directive turns into CONFIG_FILES = "1234123adba-custom.cfg", which tells the phone that it should download the configuration file 1234123adba -custom.cfg. The phone will send a request http: // 8088 / phoneprov / 1234123adba.cfg-custom.cfg in response to this request, the server will generate another dynamic file based on the second template 000000000000-phone.cfg:

Several variables are used here:
$ {SECRET} will substitute the secret value from the description of the user with the poppy 1234123adba from users.conf
$ {USERNAME} will substitute the username value from the description of the user with the poppy 1234123adba from users.conf.
$ {SERVER} will substitute the value from phoneprov.conf
Note! After changing phoneprov.conf, reload is needed so that the settings are tightened.
After everything is ready, check through the console:
phoneprov show routes
Static routes should be displayed, dynamic ones will be only if there are users in users.conf that have autoprov = yes and a mas address

Configuring users.conf

Almost everything remains to create /etc/asterisk/users.conf. Here, too, there was an opportunity for optimization. With the zxing application for android, I scanned all the MAC addresses of the phones, right from the boxes, and from the same application I sent them to my mail. It remains a matter of small to associate with each poppy some kind of account. Hands to write for each macaddress = ......., somehow I did not want to. I made a file for automatically generating Asterisk configs based on tabular data , it also has a password generator.

It remains only to copy the column and paste into users.conf. The phones in this project are all the same because it makes sense to create a template for everyone, and add only the MAC and password in the user’s description.
[def](!) ;- умолчательный шаблон
hasvoicemail = no
hassip = yes
hasiax = no
hash323 = no
hasmanager = no
autoprov = yes ;- включить для этого юзера автопровизию

Everything is ready to check through the console: phoneprov show routes
Both static routes and dynamic routes should be displayed. It remains to check the browser : 8088 / phoneprov / 1234123adba.cfg for example, and you can turn on the phones, then everything happens by itself.

Do not forget about security, after deploying the infrastructure, it is better to disable the ftp server and on the asterisk the built-in web server, until you need to update configs or software. If suddenly the configuration needs to be changed often, use HTTPS.

Also popular now: