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.

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