IP Phone Mass Deployment

Regardless if your AstLinux system supports only a few SIP phones or 50 or more, the process of coordinating the provisioning of SIP phones and the Asterisk configuration can be a tedious and time consuming process.

Described below are tools to assist in the task of mass deployment of SIP phones. The provided templates will most likely require some customization for your installation, but once you have your custom template defined, adding, deleting, and changing phones is a straightforward process.

First time users may find this quick overview helpful: IP Phone Provisioning Getting Started

If you have not already, create the /mnt/kd/phoneprov/ directory. See Below: IP Phone Provisioning

Warning -> When the /mnt/kd/phoneprov/ directory exists, HTTP/HTTPS is served with URL paths beginning with /phoneprov/ . Be sure to consider restricting /phoneprov/ access. See Below: Restricting Provisioning Access

Note: AstLinux 1.1.6 or later is required

Regardless if the web interface (GUI) or command-line interface (CLI) is used for the configuration, the core set of files are the template files that contain Asterisk dialplan and SIP configurations, as well as phone specific provisioning data.

Example template files are located at /stat/etc/phoneprov/templates/*.conf. The actual template files must be located at /mnt/kd/phoneprov/templates/*.conf (unless with an alternate path using the PHONEPROV_BASE_DIR system variable).

For the template syntax, see below: Phone Template Syntax

For the sake of this GUI discussion, it is assumed the template files have been customized as required for your installation.

Select the PhoneProv Tab in the web interface.

Define your phones starting with it's MAC address in the form: ff:ff:ff:ff:ff:ff

The Template menu has an entry for every *.conf file in the /mnt/kd/phoneprov/templates/ directory. The entries and “menu_name” can all be customized. An example Template menu is below:

Use the “Gateway Interface:” option to specify which interface the phones are connected to. (This defines the PHONEPROV_GW_IF system variable.)

After all your phones have been defined, or after any changes, you can generate all the related output files via the template(s) and phone configuration data by clicking Generate Files:

Additionally, if you want to also reload the Asterisk dialplan and SIP configurations, check the “Reload Dialplan/SIP” option:

Note -> Generate Files may take a few, to many seconds to complete, so be patient.

Tip -> A text file backup of the most recent Generate Files configuration file is saved at /mnt/kd/webgui-massdeployment.conf .

The Prefs Tab has an option to control how many Extension / CID Name(s) are displayed, a value of 1 to 6, the default is 2:

Note: AstLinux 1.1.6 or later is required

For reference the files in the /stat/etc/phoneprov/ directory can be used as examples. If you wish you can copy all these files into the /mnt/kd/phoneprov/ directory with the command:

cp -a /stat/etc/phoneprov/* /mnt/kd/phoneprov/

Of course only do this once, as you will be customizing the /mnt/kd/phoneprov/massdeployment.conf and /mnt/kd/phoneprov/templates/*.conf files (unless with an alternate path using the PHONEPROV_BASE_DIR system variable).

The massdeployment.conf file is where your phones will be defined, one per line as per the comments in that file. As usual, comments are lines beginning with the “#” character.

Tip -> The massdeployment.conf file is not required to be located at any specific location. You may want to use /mnt/kd/massdeployment.conf so a basic backup and restore would apply. Additionally, using /mnt/kd/massdeployment.conf will keep the file from being accessed via HTTP/HTTPS in the /phoneprov/ directory.

Example massdeployment.conf file entries are:

## Format:
## template mac_addr extension[/CID_Name][;ext2[/cid2];...] password [ account ]
##
snom320 00:04:13:11:33:21 201 secret
yealink 00:15:65:22:44:12 301/Front_Desk supersecret yealink_4412_301
yealink-2line 00:15:65:22:44:23 210/Office;310/Help_Line superdupersecret

The /mnt/kd/phoneprov/templates/*.conf files are used to generate the output files. Note that the left-most entries of the massdeployment.conf file define the “template” which then refers to which “template.conf” file in the templates directory that is used to generate files for that phone and extension.

For the template syntax, see below: Phone Template Syntax

The CLI phoneprov-massdeployment command:

Usage: phoneprov-massdeployment [options...] in_file

Options:
  -a, --auto-pass         Automatically generate missing password(s)
  -A, --only-pass         Same as "-a, --auto-pass" without further processing
  -f, --force-overwrite   Overwrite existing files
  -h, --help              Show this help text
  -i, --if-name           Interface Name: INTIF, INT2IF, INT3IF, EXTIF, ethN, brN
                                          Defaults to config variable PHONEPROV_GW_IF
  -p, --partial           Partial input, append "dialplan" and "sip" entries to existing
  -r, --auto-reload       Automatically reload Asterisk "dialplan" and "sip" on success
  -R, --only-reload       Same as "-r, --auto-reload" without further processing

Example massdeployment.conf, using snom320.conf and yealink.conf templates:

## Format:
## template mac_addr extension[/CID_Name][;ext2[/cid2];...] password [ account ]
##
snom320 00:04:13:11:33:21 201
yealink 00:15:65:22:44:12 301/Front_Desk

Note the required SIP passwords are missing, the -A option will automatically add them:

# phoneprov-massdeployment -A massdeployment.conf
Auto-generating password(s):
Missing password(s) were added to input file.

Now massdeployment.conf contains all the required passwords:

## Format:
## template mac_addr extension[/CID_Name][;ext2[/cid2];...] password [ account ]
##
snom320 00:04:13:11:33:21 201 2uAHicirH0avgJAA
yealink 00:15:65:22:44:12 301/Front_Desk nxQWqPrRf2vRFIIy

Of course you can also manually define your own SIP passwords.

Finally, generate the output provisioning files:

# phoneprov-massdeployment -i INT2IF massdeployment.conf
Generating Phone Provisioning files:
..Done

Note -> If any of the output files exist, the -f option will be required to overwrite any files.

The INT2IF interface name represents the 2nd LAN Interface, the network the phones are connected to, adjust for your configuration. Alternatively, setting the config variable,

PHONEPROV_GW_IF="INT2IF"

will define the default phoneprov gateway interface to INT2IF.

The phone template is a single file per phone type that contains Asterisk dialplan and SIP configurations, as well as phone specific provisioning data.

The /mnt/kd/phoneprov/templates/*.conf files are used to generate the output files. Note that the left-most entries of the massdeployment.conf file define the “template” which then refers to which “template.conf” file in the templates directory that is used to generate files for that phone and extension.

A template definition must contain a [general] context and optionally any or all of [dialplan], [sip], [phoneprov] contexts.

The template context's can use the following special variables that get merged for each phone definition.

Note -> The optional CID_Name in massdeployment.conf must NOT contain quotes or spaces, use underscores “_”, they will be mapped to spaces.

Note -> For the optional CID_NUM variable(s) AstLinux 1.4.3 or later is required. It let's you override the CALLERID(num) independant from the extension with a <nnn> suffix in CID_NAME and it stored in the SQL database as cid_num.

Note -> Auto-generated account names, with optional auto_account_case case, result in the format:

auto_account_prefix + extension(1-6) + auto_account_suffix

The concept of defining the [dialplan], [sip] and [phoneprov] contexts is quite simple. The simplest example is for the dialplan:

# Dialplan File entries
[dialplan]
exten => @EXT@,1,Dial(SIP/@ACCOUNT@)

As each phone definition is processed the above template has @EXT@ and @ACCOUNT@ merged and appended to your chosen dialplan_file setting. The same idea applies to the [sip] and [phoneprov] contexts.

Note that the [dialplan] and [sip] contexts are sequentially appended to their respective files, while the [phoneprov] context creates a standalone file.

So basically, you probably already have the data sitting around to define a custom template, simply replace some of the key data fields with the special merge variables above.

Tip -> Many phone models support provisioning both via a global phoneprov file (ex. MAC is 000000000000) and a MAC specific phoneprov file. Generally in that situation the [phoneprov] context would only generate an extension specific, partial configuration counting on the manually generated global phoneprov file for the remainder. Of course the MAC specific phoneprov file could contain the global and extension specific configuration all in the [phoneprov] context if desired.

Advanced -> The use of the additional [dialplan2-6] contexts can be useful to auto-generate BLF hints, FOP2 buttons.cfg, etc. . Following is a simple example of an Asterisk context provisioned-blf in a separate file containing 'hints':

[general]
...
dialplan2_file=astlinux-phoneprov-exten-hints.conf
dialplan2_context=provisioned-blf
...

[dialplan2]
exten => @EXT@,hint,SIP/@ACCOUNT@

Note: AstLinux 1.2.2 or later is required

The optional “/mnt/kd/phoneprov-reload.script” action script will be called when “Reload Dialplan/SIP” is checked.

By default, when “/mnt/kd/phoneprov-reload.script” does not exist, and when “Reload Dialplan/SIP” is checked, the following commands are executed:

asterisk -rx "dialplan reload" >/dev/null
asterisk -rx "sip reload" >/dev/null

You can customize these actions by creating a “/mnt/kd/phoneprov-reload.script” script. For example the following script will replicate the default action:

#!/bin/sh

asterisk -rx "dialplan reload" >/dev/null
asterisk -rx "sip reload" >/dev/null

If you require reloading fop2 or pjsip related asterisk modules, you can do that with this custom script.

Note -> Be sure to make your “/mnt/kd/phoneprov-reload.script” executable using the chmod command via the CLI.

Note: AstLinux 1.0.3 or later is required

Most modern IP Phones allow automatic provisioning from a central location. Described here are AstLinux features and configuration tips to provision phones.

Create the /mnt/kd/phoneprov/ directory. After a reboot, both HTTP and HTTPS will be served from that directory provided the URL directory path begins with /phoneprov/. This directory is not effected by the root directory of the general HTTP/HTTPS server configuration, which is independent, though the listing and logging options also apply to /phoneprov/.

Next, edit the /mnt/kd/dnsmasq.static file to utilize DHCP to instruct the phone where the provisioning files are located. The following examples show how the vendor ID from the MAC address can be matched to locate provisioning files organized by vendor.
(Change pbx in the examples to your AstLinux hostname or IP address.)

# SNOM https provisioning
dhcp-mac=set:snom,00:04:13:*:*:*
#dhcp-option=tag:snom,option:tftp-server,"https://pbx/phoneprov/snom/snom-{mac}.xml"
dhcp-option=tag:snom,option:tftp-server,"https://pbx/phoneprov/snom/"

Note -> Above, in the first (commented - https) snom example the phones look only for “snom-{mac}.xml” files, in the next (uncommented - https) example for a global “snom320.htm” and a MAC-specific “snom320-{mac}.htm” file.

# Yealink https provisioning
dhcp-mac=set:yealink,00:15:65:*:*:*
dhcp-option=tag:yealink,option:tftp-server,"https://pbx/phoneprov/yealink/"

Restart DNS & DHCP (dnsmasq) and reboot the IP Phone to apply any /mnt/kd/dnsmasq.static file changes.

Tip -> If your IP Phone does not support the DHCP “option-66” (tftp-server) feature, you must manually define the provisioning URL in the phone's web interface. Some vendors like Cisco are using additional custom DHCP options like 159 + 160.

Tip -> If you need to use a different DHCP server (tested with a Windows Server 2008R2), you could also try to test DHCP option 60 (Vendor Class Identifier - sent by the phone (e.g. snom300 or yealink)) and option 43 (sent by the server) which can encapsulate the option 66 setting. The phones must be able to send option 60 and understand option 43 though (tested with Snom 300 phones with newer firmware and Yealink phones!).
Link ¹⁾, e.g. Snom options

Tip -> If your IP Phone does not support HTTP/HTTPS provisioning, TFTP may be used by placing the provisioning files in the /mnt/kd/tftpboot/ directory. In this case sub-directories within tftpboot like with HTTP mostly don't work!.

Note: AstLinux 1.0.6 or later is required

The IP Phone provisioning data can contain access credentials, such that the average user on the LAN should not have access to. Using the firewall to restrict this access is not practical since both HTTP and HTTPS is supported for /phoneprov/ and access to parts of the web interface by LAN users using the same services is often desired.

The solution is to restrict access via the web server itself for only the /phoneprov/ access. Using the Network tab in the web interface…

Network → Network Services:

In the above example only the IP addresses that begin with 10.10.50. with a wildcard * match for the remainder, will have access to /phoneprov/ . Note the matching is performed via a regular expression, not CIDR syntax, so 10.10.50.0/24 will not work in this case. The default is to allow all IP's with no Allowed IP's specified.

Another Example: 10.1.2.* 2001:db8:1:* 192.168.101.20

Showing both IPv4 and IPv6 address are supported, as well as single IP addresses, each separated by a space character.