Phone Provisioning Variables
Vodia PBX uses a template-based provisioning system. Config files are scanned for tags in {curly braces} and each tag is replaced with the appropriate value for the device and user being provisioned. Tags are case-insensitive.
| Tag | Description |
|---|
{ip-adr} | The IP address of the PBX as seen by the requesting device. May be a domain name if the system is configured to use domain names for provisioning. |
{sip-port} | The SIP port determined by the active transport layer (UDP, TCP, or TLS). |
{sip-udp-port} | The SIP port for UDP transport. |
{sip-tcp-port} | The SIP port for TCP transport. |
{sip-tls-port} | The SIP port for TLS transport. |
{rtp-port-begin} | The first port of the RTP port range configured on the PBX. |
{rtp-port-end} | The last port of the RTP port range configured on the PBX. |
{http-port} | The HTTP port (TCP). |
{https-port} | The HTTPS port (TCP). |
{http-url} | The full HTTP provisioning base URL (e.g., http://pbx.domain.com/). Automatically computes scheme, host, and port based on how the provisioning request arrived (HTTP, HTTPS, or TFTP). |
{https-url} | The full HTTPS provisioning base URL (e.g., https://pbx.domain.com/). Upgrades to HTTPS even when the original request arrived over HTTP or TFTP. |
{ldap-port} | The LDAP port (TCP). |
{ldaps-port} | The LDAPS (LDAP over TLS) port. |
{syslog-port} | The syslog port. |
These tags are used to populate SIP registration and outbound proxy settings. The PBX resolves the correct transport and address based on domain-level, extension-level, and MAC-level overrides, falling back to the system default.
| Tag | Description |
|---|
{outbound-proxy <transport>} | The full SIP outbound proxy URI, e.g., sip:pbx.domain.com:5061;transport=tls. The transport argument specifies preferred transport (e.g., tls, udp:udp/tcp/tls). |
{outbound-ip} | The IP address or hostname of the outbound SIP proxy. Respects domain/extension/MAC-level overrides. Supports mode nsni to force the system address when a TLS certificate is available. |
{outbound-port <transport>} | The port of the outbound SIP proxy for the given transport. |
{outbound-layer <transport> [udp=val] [tcp=val] [tls=val]} | The transport layer string for the outbound proxy. Use key=value pairs to map internal transport names to device-specific values, e.g., {outbound-layer tls tls=TLS tcp=TCPOnly udp=UDPOnly}. |
{outbound-secure <transport> <tls_val> <other_val>} | Returns tls_val if transport is TLS, otherwise other_val. Useful for toggling TLS-specific settings. |
{backup-ip} | The IP address of the configured backup SIP server. |
{backup-port <transport> [udp=val] [tls=val]} | The port for the backup SIP server, with optional per-transport mapping. |
| Tag | Description |
|---|
{account} | The extension number (e.g., 404). |
{account display} | The display-formatted extension number as shown in the domain dial plan. |
{account local} | The local (short) version of the extension number. |
{domain} | The SIP domain name of the extension (e.g., company.com). |
{domain-alias} | The first configured alias for the domain that differs from the primary domain name. Falls back to the primary domain name if no alias is defined. |
{display-name} | The full display name of the user (e.g., Jane Smith). Resolves hot-seat origin when applicable. |
{display-name short} | The short display name if one is configured; otherwise falls back to the full display name. |
{display-number} | The display number of the user. Resolves hot-seat origin when applicable. |
{id} | The internal integer ID of the user account. Typically not shown to end users. |
{mwicallback} | The voicemail callback number: the domain's voicemail prefix prepended to the extension number (e.g., 8404). |
{lines} | The count of private SIP lines (buttons) configured for this extension. |
{parameter1} | Custom user parameter 1, configured in the extension settings. |
{parameter2} | Custom user parameter 2, configured in the extension settings. |
{parameter3} | Custom user parameter 3, configured in the extension settings. |
{language} | The language code assigned to the extension (e.g., en, de, fr). |
All password tags are tracked internally as sensitive fields. When provisioning logging is enabled, password values are masked with asterisks in stored files.
| Tag | Description |
|---|
{password} | The SIP registration password for the extension. Alias: {sip-pass}. |
{sip-pass} | Alias for {password}. The SIP registration password for the extension. |
{web-pass} | The web interface password for the extension. |
{ldap-pass} | The LDAP password for the extension. If none is set, a random 16-character password is auto-generated and stored. |
{pin} | The voicemail/user PIN for the extension. |
{admin-user} | The provisioning admin username configured at the domain level. |
{admin-pass} | The provisioning admin password configured at the domain level. |
{admin-pin} | The provisioning admin PIN configured at the domain level. |
{password-start} / {password-end} | Deprecated. Previously used to mark a password region for masking. Now ignored. |
{webhash} | Deprecated. Do not use. Previously generated an MD5 hash of user:web-password. |
| Tag | Description |
|---|
{tz <name>} | Returns a specific parameter from the extension's (or domain's) timezone definition. For example, {tz utcoffset}, {tz dst-start-dayp}. See the timezone database for available parameter names. |
{timezone} | Outputs a vendor-formatted timezone block for the extension's configured timezone. The format argument selects the output style (e.g., {timezone yealink}). Used for phones that require a structured timezone format rather than individual parameters. |
{ddmmyyhhmm} | Outputs the current system time as a compact Gigaset-style timestamp in the format DDMMYYHHММ (day, month, year, hour, minutes-always-zero). |
Dial Plan & Star Codes
| Tag | Description |
|---|
{dialplan <format>} | The dial plan for the user agent in the requested format. The format argument is vendor-specific (e.g., yealink, snom, xml). |
{starcode <field>} | The value of a domain-level star code field. The field name corresponds to the internal domain setting key (e.g., domains_vm_access). |
| Tag | Description |
|---|
{mac} | The MAC address of the requesting device (lowercase, no separators, e.g., aabbccddeeff). |
{mac-hash} | A cryptographic hash of the MAC address. Useful for generating stable but non-reversible device identifiers in config files. |
Conditionals can be nested. All conditional blocks must be closed with their corresponding terminator tag.
General Conditionals
| Tag | Description |
|---|
{if <expression>} | Opens a conditional block. The expression supports ==, !=, <, >, <=, >=, &&, and || operators. Operands can be attribute names, quoted strings, numbers, or the special variables listed below. |
{else} | Else branch for {if}. |
{elif <expression>} | Else-if branch for {if}. |
{fi} | Closes an {if} / {else} / {elif} block. |
Attribute-Based Conditionals
| Tag | Description |
|---|
{if_attr <attribute> <pattern>} | Opens a conditional block that renders if the given request attribute matches the ERE pattern. |
{fi_attr} | Closes an {if_attr} block. |
Model-Based Conditionals
| Tag | Description |
|---|
{if_model <model1> [model2] ...} | Opens a conditional block that renders if the model attribute (from the provisioning request) matches any of the listed model strings (case-insensitive). |
{ei_model <model1> [model2] ...} | Else-if branch for {if_model}. |
{el_model} | Else branch for {if_model}. |
{fi_model} | Closes an {if_model} block. |
Parameter-Based Conditionals
| Tag | Description |
|---|
{if_parm <parm> <value>} | Opens a conditional block that renders if the PnP parameter parm equals value (case-insensitive). |
{fi_parm} | Closes an {if_parm} block. |
{ifn_parm <parm> <value>} | Opens a conditional block that renders if the PnP parameter parm does NOT equal value. |
{fin_parm} | Closes an {ifn_parm} block. |
{if_gt <parm> <value>} | Opens a conditional block that renders if the PnP parameter parm is numerically greater than value. |
{fi_gt} | Closes an {if_gt} block. |
Multicast Conditionals
| Tag | Description |
|---|
{if_multicast [n]} | Opens a conditional block that renders if multicast group n (0-based) is configured and includes this extension. If n is omitted, checks for any multicast membership. |
{fi_multicast} | Closes an {if_multicast} block. |
Loops iterate over the accounts (extensions) associated with a device MAC. Loops can be given an explicit start/end range.
| Tag | Description |
|---|
{loop-start [start] [end]} | Begins a loop block. Optional start and end arguments control the range of accounts to iterate. Without arguments, iterates once per account assigned to the MAC. |
{loop-end} | Ends a {loop-start} block. |
{loop-count [offset]} | The current 1-based iteration counter within a loop. An optional numeric offset is added to the counter value, e.g., {loop-count 0} gives a 0-based index. Alias: {lc [offset]}. |
{lc [offset]} | Short alias for {loop-count [offset]}. |
{use-account <n>} | Selects account number n (1-based) from the MAC's account list as the current user context for subsequent tags, without starting a loop. Also updates the next-account, prev-account, count-account, sequence-account, and first-account attributes. |
Address book tags are used inside an {adrbook-start} ... {adrbook-end} loop block.
| Tag | Description |
|---|
{adrbook-start [start] [end]} | Begins an address book loop. Iterates over personal and/or domain address book entries for the extension, according to the extension's address book preference setting (personal, domain, or both). Optional start and end limit the range. |
{adrbook-end} | Closes an {adrbook-start} block. |
{adrbook-name} | The full display name of the current address book entry (first + last name combined). |
{adrbook-first-name} | The first name of the current address book entry. |
{adrbook-last-name} | The last name of the current address book entry. |
{adrbook-number} | The phone number of the current address book entry. |
{adrbook-speed} | The speed dial index of the current address book entry (the leading * from the speed dial code is stripped). |
These tags expose PBX multicast paging group settings. The optional n argument is the 0-based group index (default: 0). The default argument is the value returned if no multicast group is found.
| Tag | Description |
|---|
{multicast-adr [n] [default]} | The IP address of multicast group n. |
{multicast-port [n] [default]} | The UDP port of multicast group n. |
{multicast-adrport [n] [default]} | The address:port of multicast group n combined. |
{multicast-size [n] [default]} | The RTP packet duration (in ms) for multicast group n (10, 20, or 30). |
{multicast-name [n] [default]} | The display name of multicast group n. |
{multicast-number [n] [default]} | The extension number of multicast group n. |
{multicast-codec [n] [default] [codec=value] ...} | The codec payload type of multicast group n. Use codec=value pairs to map internal values to device-specific strings (e.g., 0=PCMU 8=PCMA 18=G729). |
{multicast-enable [n] <true_val> <false_val>} | Returns true_val if multicast group n is enabled for this extension, otherwise false_val. |
| Tag | Description |
|---|
{parameter <name>} | The value of the named PnP parameter. Parameters are looked up first at the user level, then at the domain level, then at the system level. The parameter value itself may contain provisioning tags and will be recursively expanded. |
{global <setting>} | The value of a system-wide (global) PBX configuration setting by its internal name. For tos_rtp and tos_sip, appending int as a second argument returns the numeric DSCP value (e.g., {global tos_rtp int}). |
{set <parm> <value>} | Sets the named extension parameter to value. Both parm and value are evaluated against the current context. Used to update a setting as a side effect of provisioning. |
{get <name>} | Retrieves and outputs the value of any named attribute, PnP parameter, or extension/domain setting. More general than {parameter} in that it resolves from the full attribute and settings hierarchy. |
{set-attribute <name> <value>} | Explicitly sets a provisioning request attribute to the resolved value of value. The new attribute value is available to subsequent tags in the same template. |
These tags access the HTTP request attributes that were sent with the provisioning request (e.g., from the phone's User-Agent header, URL parameters, or the PnP database).
| Tag | Description |
|---|
{attribute <name>} | The value of the provisioning request attribute name. Common attributes include mac, ip, model, user-agent, firmware, host. |
{attribute-partial <name> <n>} | The value of attribute name with the last n characters removed. Useful for stripping version suffixes. |
{attribute-match <name> <pattern>} | The substring of attribute name that matches the ERE pattern pattern. Returns empty string if no match. |
{ere <dest> <source> <pattern>} | Evaluates the ERE/NAPTR pattern pattern against the value of attribute source and stores the result in attribute dest. Used for number transformations and ENUM lookups. |
| Tag | Description |
|---|
{certificate [line_length]} | The base64-encoded root CA certificate for the provisioning host. If the domain has a certificate chain ending in a self-signed root, that root is returned. Otherwise, the chain's issuer certificate is returned. Optional line_length controls base64 line wrapping (default: 65536). |
{image <name> <encoding>} | The image from the PBX image library. Set name to own to return the user's profile photo (falling back to a placeholder). Other names load from the img/ directory. Set encoding to base64 to return base64-encoded data. |
| Tag | Description |
|---|
{open-curly} | Outputs a literal { character. Use this when a config file needs a literal curly brace that should not be treated as a tag. |
{close-curly} | Outputs a literal } character. |
{filehash <filename>} | Generates the provisioned content of filename for the current user and returns its MD5 hash. Used to provide phones with a version token for a config file without transferring the file itself. |
{emergency-numbers [sep]} | The list of emergency numbers configured for the domain, joined by sep. The default separator is a space. |
{lng <file>#<key>} | A translated UI string from the web interface language files. file is the language file name (without suffix), key is the item key. The language used is the extension's configured language. |
{enum extension <setting> <default> [value=output] ...} | Maps an extension setting value to a device-specific output string using value=output pairs. Falls back to default if the value is not in the map. Also works with domain instead of extension. |
{codec-priority [codec=value] ...} | The codec priority list for the extension (or system default), mapped through the provided codec name pairs. Supports `separator=comma |
{timeformat <24h_val> <12h_val>} | Returns 24h_val or 12h_val based on the system time format setting. If no setting is configured, the country code is used to guess (country code 1 = 12-hour). |
{dateformat <row_val> <us_val> [uk_val]} | Returns the date format value appropriate for the configured locale. |
{version} | The Vodia PBX software version string. |
{log <level> <arg1> [arg2] ...} | Writes a message to the provisioning log at the given level (1–9). Arguments are resolved as PnP values. Does not produce output in the config file. |
These tags generate vendor-specific BLF and function key configuration XML or parameter blocks from the PBX button assignments for the extension.
| Tag | Description |
|---|
{snom-buttons} | BLF/function key configuration for Snom desk phones. |
{snom-m500-buttons} | Button configuration for Snom M500/M700 DECT handsets. Iteration offset starts at 1. |
{snom-hd-buttons} | Button configuration for Snom HD series handsets. |
{yealink-buttons} | DSS key configuration for Yealink desk phones. Includes the phone model in key-type resolution. |
{avaya-buttons} | Button configuration for Avaya J-series IP phones. |
{aastra-buttons} | Button configuration for Aastra/Mitel IP phones. |
{htek-buttons} | Button configuration for Htek IP phones. |
{grandstream-buttons} | BLF key configuration for Grandstream GXP series phones. |
{grandstream2-buttons} | BLF key configuration for Grandstream phones (alternate model variant). |
{grandstream-hp-buttons} | BLF key configuration for Grandstream GRP high-performance series. |
{fanvil1-buttons} | Button configuration for Fanvil phones (type 1 format). |
{fanvil2-buttons} | Button configuration for Fanvil phones (type 2 format). Includes the provisioning URL for action URLs. |
{vtech-buttons} | Button configuration for VTech IP phones. |
{vtech-buttons2} | Speed dial configuration for VTech hotel phones (type 2). |
{vtech-buttons3} | Speed dial configuration for VTech hotel phones (type 3, alternate models). |
{spa-buttons} | Button/line key configuration for Cisco SPA and 78xx/88xx series phones. |
{polycom-buttons} | Speed dial and BLF configuration for Polycom VVX phones. |
{polycom-adrbook} | Address book XML configuration for Polycom VVX phones. |
{poly-edge-buttons} | Button configuration for Poly Edge E-series phones. Generated for all accounts on the MAC, not just the current user. |
{panasonic-buttons [arg]} | Button/label configuration for Panasonic IP phones. |
{shandong-buttons} | Button configuration for Shandong/generic SIP phones. |
{ale-buttons} | Button configuration for Alcatel-Lucent Enterprise (ALE) IP phones. |
{auerswald-buttons} | Button configuration for Auerswald IP phones. |
{behnke-buttons} | Button configuration for Behnke IP phones. |
{unify-buttons} | Button configuration for Unify/OpenScape IP phones. |
{aei-buttons} | Button configuration for AEI IP phones. |
{maxwell-buttons} | Button configuration for Gigaset Maxwell series phones. |
| Tag | Description |
|---|
{require-credentials} | If the current provisioning request is unauthenticated, challenges the device with HTTP Basic authentication using the MAC address. If credentials are valid or the device is in PnP pairing mode, provisioning continues. |
{post-process-yealink} | Instructs the provisioning engine to apply Yealink-specific post-processing to the generated config file (deduplication of duplicate parameter lines). Can be placed anywhere in the template. |
{sni-sip-ldap} | Stores the device's IP address in the MAC record so that the PBX can present the correct domain certificate when the device subsequently connects for SIP or LDAP over TLS (SNI). |
{presence} | Presence subscription URI for the extension (sip:ext@domain). Used in templates that configure BLF subscriptions. |
Variables Available in {if} Expressions
In addition to named PnP parameters and extension/domain settings, the following special variable names can be used in {if} conditions and {get} tags:
| Variable | Description |
|---|
version | The PBX software version string. |
provisional | true if the requesting MAC address is not yet registered to any user; false otherwise. |
pairing | true if the device is currently in PnP pairing mode (open for auto-provisioning). |
has_multicast | true if at least one multicast paging group is configured that includes this extension. |
has_multicast(n) | true if multicast group n (0-based) includes this extension. |
valid_certificate | true if the domain has a valid TLS certificate (domain-specific cert or matching system cert). |
system_certificate | true if the system address has a valid TLS certificate. |
provision_has_cert | true if the TLS certificate on the provisioning hostname matches that hostname. Useful for deciding whether to provision a phone with TLS-based SIP. |
bgimage:<category>:<resolution> | The version string of the background image stored for the given category and resolution (e.g., bgimage:picture:fanvil1). Returns empty string if no image exists. Use to trigger re-provisioning of background images when they change. |
tz:<name> | Returns the named parameter from the extension's timezone definition (e.g., tz:utcoffset, tz:dst-start-dayp). Same as the {tz} tag but usable inside expressions. |
ipei:<field> | DECT handset IPEI record field. Available fields: ipei:name, ipei:serial, ipei:vendor, ipei:model, ipei:version. Returns empty string if no IPEI record is found. |
max_ring_duration | Maximum ring duration in seconds (domain value + 1 second grace period). |
max_call_duration | Maximum call duration in seconds. |
prov_t38 | T.38 fax provisioning setting, resolved from MAC → domain → system level. |
Loop-Internal Attributes
Within {loop-start} and {use-account} contexts, the following attributes are automatically set and can be read with {attribute} or used in {if} expressions:
| Attribute | Description |
|---|
next-account | The 1-based index of the next account in the list, or empty if this is the last. |
prev-account | The 1-based index of the previous account in the list, or empty if this is the first. |
count-account | The total number of accounts associated with this MAC. |
sequence-account | The 1-based position of the current account within the loop. |
first-account | true if this is the first account in the list. |
Notes
- Tags are case-insensitive:
{MAC}, {Mac}, and {mac} are all equivalent.
- Use
\{ and \} in template content to output literal curly braces. Alternatively, use {open-curly} and {close-curly}.
- Most tags that output user data respect the encoding of the provisioning file (plain text or XML). Characters are escaped appropriately for the file type.
- Password tags are automatically masked in provisioning logs and stored provisioning snapshots when the Provisioning Log setting is enabled.
- Tags that reference user data (e.g.,
{account}, {password}) produce no output if no authenticated user is associated with the provisioning request.