Provisioning Settings
Provisioning (or phones auto-provisioning) allows you to quickly configure your SIP phones by allowing them to download firmware and MAC based provisioning files created with Configuration Manager.
Provisioning Settings screen allows system administrator to configure how configuration files are generated and delivered to phones. The system supports two provisioning modes: Local and External.
Provisioning Mode
The Provisioning Mode selector at the top of the settings form determines how device configuration files are delivered to phones.
Local Mode (Built-in)
In Local mode, this server generates and serves configuration files directly to phones via FTP and HTTP/HTTPS. This is the default mode and the traditional provisioning method.
Server address. This is the address that will be placed in the generated phone configuration files as server or proxy address.
Directory. This is an informational field that cannot be changed. It shows where the provisioning files will be placed on the server.
Default Protocol. Specifies the system-wide default provisioning protocol (HTTP, HTTPS, FTP, FTPS, or TFTP). This protocol is used when generating provisioning URLs for phones unless overridden at the model level. Defaults to HTTP. Individual phone models can specify a different protocol in their model definition using the protocol= key.
When configuring protocols for provisioning (FTP, FTPS, HTTP, HTTPS, TFTP), you should only enable the protocols you actually use, and for security reasons, avoid using TFTP on unprotected servers. The configuration settings allow you to enable these protocols and specify credentials where applicable.
The provisioning system automatically selects the correct credentials based on the active protocol: FTP and FTPS use the FTP username/password, while HTTP, HTTPS, and TFTP use the HTTP username/password configured on this screen.
External Mode (External DMS)
In External mode, configuration files are generated locally on this server but phones are directed to download them from an external Device Management System (DMS). This allows customers to use their own DMS with features like Mutual TLS, per-device credentials, or custom delivery pipelines.
External DMS Server. Hostname or IP address of the external DMS that phones will contact to download their configuration files.
External Protocol. Protocol used by the external DMS (HTTP or HTTPS). HTTPS is recommended.
Provisioning Path. URL path on the external DMS where configuration files are served. Defaults to /provisioning to match the path structure used by shipped templates.
External DMS Username / Password. HTTP credentials that phones will use to authenticate with the external DMS. These are injected into generated config files as the provisioning credentials. If the external DMS uses certificate-based authentication (e.g., mTLS) without HTTP Basic Auth, these can be left empty.
Firmware Server. (External mode only) Hostname where phones download firmware files. Leave empty to use the same DMS server configured above. This allows firmware to be hosted on a separate CDN or server.
SIP and Infrastructure
These settings apply to both local and external provisioning modes. They control how phones are configured for SIP registration, proxy, and time synchronization. Leave fields empty to use defaults (management server address).
Backup Registrar. Backup SIP registration server for phone failover. When configured, phones will attempt to register with this server if the primary registrar is unreachable. Available in templates as ${REG_SERVER_BACKUP}.
SIP Proxy. SIP proxy server address. Leave empty to use the registration server (management host). Available as ${PROXY_SERVER}.
Backup SIP Proxy. Backup SIP proxy for failover. Leave empty to use the backup registrar address. Available as ${PROXY_SERVER_BACKUP}.
NTP Server. NTP server for phone time synchronization. Leave empty to use the management server address. Available as ${NTP_SERVER}.
File Transport
When using External provisioning mode, the File Transport section allows you to automatically push generated configuration files to external storage after each device is provisioned. This automates the delivery pipeline between the config generation server and the external DMS.
Transport Method:
- None (default) - Files are generated on disk only. The customer is responsible for collecting them (e.g., via rsync, cron, or manual copy).
- S3-Compatible Storage - Push files to any S3-compatible object storage service (AWS S3, MinIO, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, etc.) after each device is provisioned.
- Custom Script - Run a custom executable after each device is provisioned. The script receives the list of generated file paths as arguments.
S3 Transport Settings
When S3 transport is selected:
- S3 Endpoint URL - The S3-compatible API endpoint (e.g.,
https://s3.amazonaws.comfor AWS, orhttp://127.0.0.1:9000for a local MinIO instance). - S3 Bucket - Name of the bucket where config files will be uploaded.
- Access Key / Secret Key - S3 credentials for authentication.
- Region - S3 region (e.g.,
us-east-1). Required for AWS S3, optional for MinIO and other S3-compatible services. - Key Prefix - Optional path prefix for uploaded files (e.g.,
configs/). Leave empty to upload to the bucket root.
S3 connectivity is validated when you save the settings. If the endpoint or bucket is unreachable, the save will fail with an error message.
Transport is best-effort: if a file upload fails during provisioning, the failure is logged but does not prevent the phone from being provisioned. Files remain on disk regardless of transport outcome.
Shared Asset Sync
When S3 transport is configured in External mode, the system automatically syncs shared provisioning assets to the same S3 bucket so that phones using the external DMS can access contact directories, firmware, and static configuration files.
Contact directories (CONTACTS/) are synced to S3 immediately after regeneration. When a company directory contact is added, edited, or deleted, the system marks the tenant as dirty and regenerates the XML files within 5 minutes. After regeneration, the updated files are pushed to S3 under the CONTACTS/{tenant}/ prefix.
Firmware and static assets (FIRMWARE-*, Config/, PROFILES/, etc.) are synced hourly. The system checks modification times and skips the sync if no source directories have changed since the last successful sync. This covers firmware files for all installed phone brands and static configuration assets like Polycom localization files, override directories, and license files.
Both sync operations use rclone sync, which only uploads files that have changed. This makes repeated syncs efficient even for large firmware directories.
Custom Script Transport
When Custom Script transport is selected:
- Script Path - Full path to the executable script (e.g.,
/usr/local/bin/push-configs.sh). The script must exist and be executable.
After each device is provisioned, the script is called with the generated file paths as arguments and the following environment variables:
PROV_MAC- Device MAC addressPROV_TENANT- Tenant namePROV_MODE- Provisioning mode (localorexternal)PROV_SERVER- Provisioning server addressPROV_MODEL_SEGMENT- In external mode, the per-model path segment (INI model id); empty in local mode
The script exit code is logged (0 = success, non-zero = failure) but does not block provisioning.
Template Variables
Server Variables
The provisioning system provides specialized server variables so that each function (SIP, provisioning, firmware, NTP) can be independently configured. In most single-server deployments, all server variables resolve to the management server address. In external or multi-server deployments, they diverge.
| Variable | Purpose | Default |
|---|---|---|
${REG_SERVER} | SIP registration server | Management server |
${REG_SERVER_BACKUP} | Backup SIP registrar | Empty |
${PROXY_SERVER} | SIP proxy | = REG_SERVER |
${PROXY_SERVER_BACKUP} | Backup SIP proxy | = REG_SERVER_BACKUP |
${PROV_SERVER} | Config download server | Management (local) or DMS (external) |
${PROV_PATH} | Provisioning URL base path | /provisioning (local); in external mode, external_path plus a per-model segment from the model INI id (see ${PROV_MODEL_SEGMENT}) |
${PROV_MODEL_SEGMENT} | Per-model path segment for external IAM / S3 layout | Empty in local mode; in external mode, the device model key (section name from models.txt / models.d/), with minimal sanitization |
${FIRMWARE_SERVER} | Firmware download server | = PROV_SERVER |
${FIRMWARE_PATH} | Full firmware directory path | PROV_PATH + firmware dir |
${NTP_SERVER} | Time sync server | Management server |
The legacy ${SERVER} variable remains available as an alias of ${REG_SERVER} for backward compatibility with existing templates.
Protocol and Credential Variables
| Variable | Purpose |
|---|---|
${PROTO} | Protocol scheme (http, https, ftp, etc.) |
${PROTO_URL} | Complete provisioning base URL (protocol + credentials + server + path) |
${FIRMWARE} | Firmware filename from model definition |
${FIRMWARE_URL} | Complete firmware download URL |
${PROV_USER} / ${PROV_PASSWORD} | Credentials auto-selected by protocol |
${HTTP_USER} / ${HTTP_PASSWORD} | HTTP provisioning credentials |
${FTP_USER} / ${FTP_PASSWORD} | FTP provisioning credentials |
Device and Tenant Variables
| Variable | Purpose |
|---|---|
${MAC} / ${mac} | Device MAC address (upper/lowercase) |
${TENANT} / ${TENANT_ID} | Current tenant name / ID |
${LABEL} | Device description |
${TL_TIMEZONE} / ${TL_TIMEZONE_NAME} | Phone timezone value / display name |
${DEFAULT_PARKEXT} | Default call park extension |
${OVERRIDE} | Per-device and template override content |
Per-Line Variables (set per SIP account in line templates)
| Variable | Purpose |
|---|---|
${LINE} / ${LINE_ZERO_BASED} | Line number (1-based / 0-based) |
${DISPLAY_NAME} | Caller ID display name |
${USERID} | SIP authentication username |
${PASSWORD} | SIP authentication password |
${EXTENSION} | User extension number |
${FIRST_NAME} / ${LAST_NAME} | User name fields |
${LABEL} / ${LINE_LABEL} | Line label for display |
Custom Variables
The Template Variables tab provides an editable grid where you can define global custom name-value pairs. Each custom variable becomes available as ${VARIABLE_NAME} in all provisioning template files.
- Enter only the variable name (e.g.,
SYSLOG_SERVER, not${SYSLOG_SERVER}) - Names must be uppercase letters, digits, and underscores only
- Names must not conflict with built-in variable names
- Custom variables have lower priority than built-in variables