Skip to content
Platform Documentation

Device Provisioning

Device Provisioning using Templates

While configuration can be performed by entering data into each phone, it is more efficient to use Configuration Manager’s auto-provisioning feature which creates the configuration files a phone can download together with the required firmware.

To create these files for each phone, Configuration Manager uses Provisioning Templates which are combined with each phone’s specific information. You can install the templates for the phone models you use, together with the manufacturer’s firmware as Template Bundles.

During provisioning, Configuration Manager processes all the templates defined for the specified phone model, replaces variables it finds, and places the resulting files in the provisioning directory. Phones can download these files and firmware based on the options defined in Provisioning Settings.

Creating and Customizing Provisioning Templates

If you wish to customize existing provisioning templates or create new templates, you can place them in the directory /etc/asterisk/user_provisioning. You can further customize templates for each Tenant by placing the templates in /etc/asterisk/user_provisioning/tenantname.

Do not place your templates in /etc/asterisk/provisioning directory as they will be overwritten whenever Configuration Manager is updated.

Templates locations have the following precedence:

  1. /etc/asterisk/user_provisioning/tenantname
  2. /etc/asterisk/user_provisioning
  3. /etc/asterisk/provisioning.

In earlier versions of Configuration Manager, file models.txt described the composition of templates for all the supported phones. In most recent versions, Template Bundles installation creates a separate directory under /etc/asterisk/provisioning/models.d where it places a file with model description settings for each phone supported by the bundle.

Here is what model description settings look like for Ploycom VVX 350:

[polycom-vvx350]
label=Polycom VVX 350
lines=1
check_sync=polycom-check-cfg
translationmap=polycom
phone_template=polycom_phone.cfg
line_template=polycom_line.cfg
blf_template=polycom_blf.cfg
speeddial_template=polycom_speeddial.cfg
output=${mac}-registration.cfg
input_1=polycom_mac.cfg
output_1=${mac}.cfg
input_2=polycom_local_uc.cfg
output_2=${TENANT}-settings-uc.cfg
command_1=/usr/local/sbin/generate_compdir_polycom.py ${TENANT}

Fields in the model description settings are as follows:

label. Phone model used to select this device model in Configuration Manager when setting defaults or when creating User Extensions.

lines. Number of lines this device supports.

check_sync. Command that will be sent to the phone after the provisioning files are generated.

translationmap. Translation Map used by this phone.

phone_template. Contains all the general phone information, i.e. other than the line or button specific entries.

line_template. The name of the file containing a template processed for each line. For example, if 3 lines are defined, then 3 copies of the entries in the line_template will be included in the final output file.

blf_template. The name of the file containing a template processed for each button designated as a BLF (Busy Lamp Field).

speeddial_template. The name of the file containing a template processed for each button designated as a Speed Dial.

output. The name of the generated configuration file for each provisioned device. Note that variables can be used as part of the file name.

The following entries can be specified more than once:

input_x. Any additional files that need to be processed.

output_x. The name of the file resulting from processing input_x. Note that variables can be used as part of the file name.

required_x. Specifies any files that Configuration Manager will simply move in the output directory without any substitutions. Typically, contains system wide configuration settings.

command_x. Command to be executed at the end of the provisioning for each device. This can be used to run special applications required by some phone manufacturers to load the configuration files. Note that variables can be used as part of the command.

protocol. (Optional) The provisioning protocol this model should use (http, https, ftp, ftps, or tftp). If not specified, the global Default Protocol from Provisioning Settings is used. This allows different phone models to use different protocols — for example, Yealink phones via FTP while Fanvil phones use HTTPS.

firmware. (Optional) The firmware version string for this model (e.g., 96.86.0.30). When specified, the ${FIRMWARE} and ${FIRMWARE_URL} template variables become available during provisioning, allowing templates to reference the correct firmware download URL dynamically.

firmware_dir. (Optional) The firmware subdirectory name on the provisioning server (e.g., FIRMWARE-YEALINK). If not specified, it is automatically derived from the model name prefix (e.g., model yealink-t54w produces FIRMWARE-YEALINK).

How Provisioning Works

The provisioning process has two stages:

  1. Model definitions (models.txt or models.d/*.txt) specify plain configuration values for each phone model — template filenames, protocol, firmware version, output filename patterns, etc. Some model values like output can use ${...} variables (e.g., output=${mac}.cfg) because the output filename needs to vary per device.

  2. Template files (.cfg files referenced by the model) contain the actual phone configuration with ${...} variable placeholders. During provisioning, the system reads the model definition, combines it with device-specific data (MAC address, extension, line settings, etc.), and replaces all ${...} variables in the template files to produce the final configuration files for each phone.

In other words: model keys like protocol=https and firmware=96.86.0.30 are data inputs — the provisioning code reads them and makes them available as template variables (${PROTO}, ${FIRMWARE}, ${FIRMWARE_URL}, etc.) for use in the .cfg template files.

Variables are specified as ${VARIABLE_NAME} and are case sensitive.

The ${MAC} variable will be substituted by the MAC address in uppercase, while ${mac} will be in lowercase.

Here is the polycom_phone.cfg template referenced in the model description settings for Polycom VVX 350 above:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <!-- $Polycom Revision: 1.67 $  $Date: 2005/03/11 17:05:46 $ -->
<PHONE_OVERRIDES>
  <OVERRIDES
${LINES}
${BLFS}
${SPEEDDIALS}
  />
</PHONE_OVERRIDES>

Note the ${LINES}, ${BLFS} and ${SPEEDIALS} variables. These will be replaced by the combined content of processed templates - line_template (polycom_line.cfg), blf_template (polycom_blf.cfg), and speeddial_template (polycom_speeddial.cfg) for each button configured.

You can add support for any phones not currently supported by Thirdlane or customize the templates as follows:

  1. If adding a new model create a models.txt file in /etc/asterisk/user_provisioning directory and add an entry for the device model you want to add.

  2. Create the templates (or change the existing templates) and place them in the same directory. Note that you are not required to create blf_template and speeddial_template files unless you use them.

Here is a list of variables that can be specified in model descriptions and the provisioning templates, and how they will be substituted:

${MAC}. Device MAC address in uppercase.

${mac}. Device MAC address in lowercase.

${SERVER}. Server address.

${TENANT}. Tenant name (Multi-Tenant only).

${TENANT_ID}. Internal tenant id (Multi-Tenant only).

${LABEL}. Usually first name and the last name from the User Extension screen.

${COMPANY_NAME}. Name on the license (Licensed to).

${LINE_KEYS}. Number of lines specified in model description.

${LINES}. Content of processed line_templates.

${BLFS}. Content of processed blf_templates.

${SPEEDDIALS}. Content of processed speeddial templates.

${STATION_NAME}. Caller id name.

${VOICEMAIL_NUMBER}. Extension.

${USERID}. Line name as specified in User Extensions.

${PASSWORD}. Phone password as specified in User Extensions.

${DISPLAY_NAME}. Caller id name.

${EXTENSION}. Extension.

${NAT_MAPPING}. Yes’/‘No” depending on NAT setting in User Extensions.

${NAT_KEEPALIVE} ‘Yes’/‘No’ depending on NAT setting in User Extensions.

${BUTTON}. Button number as specified in Tools -> Auto-Provisioning.

${LINE}. Button number as specified in Tools -> Auto-Provisioning (it is the same as $ {BUTTON} and is kept for backward compatibility. You should use $ {BUTTON} for new templates.

${BUTTON_ZERO_BASED}. Button number - 1. This is useful when buttons are zero based as in snom phones.

${DISPLAY_NAME}. Caller id name.

${LINE_LABEL}. Line label as per Managed Device screen below.

${LABEL}. Line label if non blank (if specified on the Managed Device screen below ) or caller id number.

${BLF_LABEL}. Label for a BLF button as per Managed Device screen below.

${BLF_TARGET}. BLF target as per Managed Device screen below.

${SPEEDDIAL_LABEL}. Label for a Speed Dial button as per Managed Device screen below.

${SPEEDDIAL_TARGET}. Speed Dial target as per Managed Device screen below.

${PROTO}. The resolved provisioning protocol for this device’s model (e.g., http, https, ftp). Determined by the model’s protocol= key, falling back to the global Default Protocol in Provisioning Settings, and then to http.

${PROTO_URL}. The full provisioning base URL including protocol, credentials (if configured), and server address. For example: https://admin:secret@pbx.example.com/provisioning. Use this variable in templates instead of hardcoding the protocol and server address.

${FIRMWARE}. The firmware version string from the model’s firmware= key. Empty if not specified.

${FIRMWARE_URL}. The full firmware download URL including protocol, credentials, server address, firmware directory, and firmware version. For example: https://admin:secret@pbx.example.com/provisioning/FIRMWARE-YEALINK/96.86.0.30. Empty if the model has no firmware= key.

${PROV_USER}. The provisioning username, selected based on the active protocol (FTP credentials for FTP/FTPS, HTTP credentials for HTTP/HTTPS/TFTP).

${PROV_PASSWORD}. The provisioning password, selected based on the active protocol.

Custom Variables

In addition to the built-in variables above, administrators can define global custom variables in Provisioning Settings → Template Variables tab. Each custom variable becomes available as ${VARIABLE_NAME} in all templates. Custom variables have lower priority than built-in variables — if there is a name conflict, the built-in value is used.

Common use cases include ${NTP_SERVER}, ${VLAN_ID}, ${SYSLOG_SERVER}, or any site-specific value you want to centralize rather than hardcode in each template.

See Provisioning Settings — Custom Variables for configuration details.

Template Conversion Examples

Older provisioning templates may have hardcoded protocol and server addresses. With the new protocol-aware variables, you can make templates dynamic so they automatically use the correct protocol, credentials, and firmware URLs based on the model and system configuration.

Before (hardcoded):

#!version:1.0.0.1
auto_provision.server.url = http://192.168.1.100/provisioning
auto_provision.server.username = admin
firmware.url = http://192.168.1.100/provisioning/FIRMWARE-YEALINK/96.86.0.30

After (using variables):

#!version:1.0.0.1
auto_provision.server.url = ${PROTO_URL}
auto_provision.server.username = ${PROV_USER}
firmware.url = ${FIRMWARE_URL}

The model definition in models.txt or models.d/ provides the data:

[yealink-t54w]
protocol=http
firmware=T5XW-96.86.0.70.rom
firmware_dir=FIRMWARE-YEALINK

Fanvil Example

Before (hardcoded):

<FirmwareUrl>https://pbx.example.com/provisioning/FIRMWARE-FANVIL/v65.z</FirmwareUrl>

After (using variables):

<FirmwareUrl>${FIRMWARE_URL}</FirmwareUrl>

With the model definition:

[fanvil-v65]
protocol=https
firmware=v65.z
firmware_dir=FIRMWARE-FANVIL

Conversion Steps

  1. Identify hardcoded protocol/server URLs in your .cfg templates
  2. Replace them with ${PROTO_URL} (for provisioning base URL) or ${FIRMWARE_URL} (for firmware download URL)
  3. Replace hardcoded usernames/passwords with ${PROV_USER} and ${PROV_PASSWORD}
  4. Add protocol=, firmware=, and optionally firmware_dir= keys to the model definition
  5. Test by provisioning a device and verifying the generated files contain the correct URLs

Sample converted templates are also available on the server in /etc/asterisk/provisioning/samples/.

Phone Models

The Phone Models screen (under Provisioning in the navigation tree) allows you to view all installed device models and manage custom models.

System models (installed by Template Bundles) are shown with scope “System” and are read-only. You can clone a system model to create an editable custom or tenant copy.

Custom models (scope “Custom”) are stored in /etc/asterisk/user_provisioning/models.txt and are available to all tenants.

Tenant models (scope “Tenant”) are stored in /etc/asterisk/user_provisioning/{tenant}/models.txt and are available only to the specific tenant.

Filtering

The filter bar at the top allows you to search models by scope, name, or label. Enter your filter criteria and click Select to apply, or Clear to reset.

Adding a Custom Phone Model

Click “Add” to create a new custom model. The form has the following tabs:

General — Set the model name (must be unique, alphanumeric characters, hyphens, and underscores only), display label, number of lines, phone template, protocol override, firmware version, and other basic properties.

Templates — View and edit template file references for this model (phone_template, line_template, blf_template, speeddial_template, linekey_template, and n_a_template).

I/O Files — Manage numbered input/output file pairs and post-provisioning commands.

Template Content — View and edit the content of any template file referenced by this model. Select a file from the dropdown to load its content. For system models, template content is displayed read-only. For user/tenant models, you can edit the content and save — changes are written to user_provisioning/ as an override, keeping the original system template intact. If you have unsaved changes when switching files, you will be prompted to confirm before the new file is loaded.

Cloning Models

You can clone any model (including system models) using the Clone button. The cloned model opens in a new form with an editable name field. Clones are always saved as user or tenant scope, even when the source was a system model. Template content becomes editable in the cloned copy.

Managed Devices

If MAC address is specified when User Extensions are created either in Bulk Generator or individually, the configuration files are generated automatically, and MAC is added to the Managed Devices.

If you use Bulk Generator, you must specify the default Phone Model in Default Values or in Tenants if using Multi Tenant.

To generate configuration files and provision devices in bulk, select them using the check box on the left and click on “Provision Selected”.

Create/Edit Managed Device

The screen allow you to further refine auto-provisioning information and assign behavior to phones’ buttons as needed.

MAC Address. Phone’ s MAC address.

Description. Short description.

Phone Model or Extended Phone Template. Select Phone Model from the list of supported models or Extended Phone Templates.

Time Zone. Time zone for this phone. Time zone will be translated based on the Translation Map for this Phone Model.

Template Variables. Allows you to specify values for the variables defined in the Translation Map for this Phone Model. These variables will be converted to internal values based on Translation Map for selected Phone Model

Add Account. Add a line to this phone.

Assign. Assign functionality to a phone button. Note that in order to assign various button types such as BLF, Speedial, etc you must have corresponding template files (blf_template, speeddial_template, etc) for the selected Phone Model.