Skip to content
Thirdlane

Managed Devices

Auto-provisioning lets IP phones configure themselves: instead of an administrator keying settings into each handset, Configuration Manager generates a config file per device that the phone downloads and applies on boot. This is what makes deploying dozens or hundreds of phones - and re-configuring them later - practical, and it keeps every device consistent with your PBX settings. This page covers how provisioning templates work, the variables you can use in them, the Phone Models catalog, and the Managed Devices list where each provisioned phone is tracked.

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:[email protected]/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:[email protected]/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.

This takes a phone from box to working handset without ever touching its web UI.

  1. Install the model and firmware. Under Template Bundles, install the Yealink bundle. This drops a yealink-t54w model definition into models.d/ and the firmware onto the provisioning server.
  2. Tell phones where to fetch config. In Provisioning Settings, set the Default Protocol (say https), the Server Address phones can reach, and provisioning credentials. Templates that use ${PROTO_URL} / ${PROV_USER} now resolve correctly.
  3. Set the default phone model. In Default Values (or on the Tenant in Multi Tenant), set Phone Model to Yealink T54W so bulk-created users pick it up automatically.
  4. Create the user with a MAC. On Jane’s User Extension (ext 101), enter the phone’s MAC Address on the Basic tab. Saving generates her config files (e.g. <mac>.cfg) in the provisioning directory - the MAC is what triggers this, and the phone now appears in Managed Devices.
  5. (Optional) Add buttons. Open the device in Managed Devices and use Assign to set a BLF for ext 102 and a Speed Dial to the main office number. This only works if the model has blf_template / speeddial_template files (the Yealink bundle includes them).
  6. Boot the phone. Plug in the T54W on the same network. On boot it downloads its config (and firmware if newer), registers as 101-acme, and shows Jane’s name - no manual entry.
  7. Re-provision later. Change something (new firmware, a button)? Select the device in Managed Devices and click Provision Selected, then reboot the phone or send it the check_sync NOTIFY.

To do a whole office at once, put the MACs in the spreadsheet and let the Bulk Generator run steps 4-6 for every row.

Best practices

  • Customize templates only under /etc/asterisk/user_provisioning (or the per-tenant subdirectory) - never under /etc/asterisk/provisioning, which is overwritten on every Configuration Manager update.
  • Prefer the protocol-aware variables (${PROTO_URL}, ${FIRMWARE_URL}, ${PROV_USER}, ${PROV_PASSWORD}) over hardcoded servers and credentials, so a change in Provisioning Settings propagates to every model automatically.
  • Clone a read-only System model rather than editing it when you need a variation; clones are saved as editable Custom or Tenant scope and leave the original intact.
  • Centralize site-specific values (NTP, VLAN, syslog) as custom variables instead of repeating them across templates.
  • Test with one device after any template change and verify the generated files contain the expected URLs before provisioning in bulk.