Automatic Provisioning

From Pbxnsip Wiki

Jump to: navigation, search

Many SIP devices support a way for automatic provisioning of configuration files. The PBX addresses this problem with a built-in tftp server that generates configuration data on the fly. Also, the other built-in servers for http and https can be used for provisioning.

Image:note.gif Most of the information in this page is not intended for the end user. For supported devices, you don't have to set up your own automatic provisioning files. This page is a reference for users who want to automatically provision a device that is not supported by the PBX yet. If you want to add a device to the list of supported devices, please let us know, so that we can include this device in the next build.

Contents

[edit]

Ways of Provisioning

The PBX supports the following ways of automatic provisioning:

  • The DHCP server provides the address of the PBX. This is typically done using option 66 of the DHCP protocol.
  • The administrator manually sets the address of the PBX on the phone. This requires some work; phones do not work right out of the box
  • The PBX also listens to multicast packets on the SIP port. For phones which support this mechanism, they will install automatically even if the DHCP server does not provide the address of the PBX. This is typically useful in environments where the administrator has no control over the DHCP server (e.g. DSL router with built-in DHCP server).
[edit]

Available Devices

Unfortunately, there is no standard for provisioning phones. Every phone vendor has another way for provisioning phones, sometimes even the same vendors has different methods for different models and firmware revisions.

pbxnsip tries to keep the provisioning files up-to-date. Currently, the following devices are supported:

  • Cisco 79xx (G models using 8.x firmware with XML-based provisioning)
  • Polycom 2.0 firmware revisions, models 30x, 430, 50x and 60x.
  • snom 3xx firmware revisions 6.x.

Those devices should be working more or less "out of the box". See the Interoperability Pages for more information on this topic.

If you are willing to contribute configuration files, you are more than welcome.

[edit]

Configuration Files

The configuration files can be dynamically changed. Those files must be placed in the html directory of the working directory of the PBX (if the directory does not exist, just create it).

When the PBX starts, it reads the file "pnp.xml". This file contains the information, which device needs which file. It looks like the following example: 

<?xml version="1.0"?>
<plug-and-play>
  <file name="sep_cnf.xml" encoding="xml">
    <pattern>!SEP([0-9A-F]{12})\.cnf\.xml!\1!</pattern>
    <vendor>Cisco 79x1</vendor>
  </file>
  <file name="polycom_master.xml" encoding="xml">
    <pattern>!^(0004f2[0-9a-f]{6})\.cfg!\1!</pattern>
    <vendor>Polycom, Inc.</vendor>
  </file>
  <file name="polycom_phone.xml" encoding="xml">
    <pattern>!polycom_phone_([0-9a-f]{12})\.cfg!\1!</pattern>
    <vendor>Polycom, Inc.</vendor>
  </file>
  <file name="snom320_6.txt" encoding="ascii">
    <pattern>!snom3[26]0-([0-9A-F]{12})\.htm!\1!</pattern>
    <vendor>snom</vendor>
    <model>snom320</model>
    <pnp-vendor>snom</pnp-vendor>
    <pnp-content-type>application/url</pnp-content-type>
    <pnp-url>https://{IP-Adr}:{HTTPS-Port}/{Model}.htm</pnp-url>
  </file>
</plug-and-play>

For every file that should be processed during the plug and play configuration, you need to add an entry. The name tag in the file entry indicates which file should be read from the html directory.

The encoding style indicates what encoding is being used. Currently, the encoding styles "xml" (for XML-files) and "ascii" (without any specific encoding) are available.

The "pattern" entry contains an extended regular expression, as it is being used in other places of the PBX (e.g. in the IVR Node). The PBX tries to match the file which is being requested from the phone with that pattern, and if the result is not empty, it will provision that file. For example, the file "polycom_phone_124354abdedc.cfg" will match "!polycom_phone_([0-9a-f]{12})\.cfg!\1!", while "phone_124354abdedc.cfg" will not match. The replacement is used as MAC address, if necessary during the processing of the file.

The "vendor" entry is used to identity the vendor. The "model" entry is used to identity the model. They are used in the multicast provisioning; otherwise they have just descriptive character.

The "pnp-vendor" entry is used for multicast provisioning. When a device is trying to get a configuration via the multicast interface, the PBX needs to match the vendor tag in the SUBSCRIBE message to this string. If it is found (and the MAC address can be provisioned), it response with a NOTIFY that contains the URL for automatic provisioning and the content-type. The content type is in the entry "pnp-content-type", the URL in the entry "pnp-url". The URL can contain the following placeholders:

  • {IP-Adr} is the IP address of the PBX
  • {TFTP-Port} contains the TFTP port of the PBX
  • {HTTP-Port} contains the HTTP port of the PBX
  • {HTTPS-Port} contains the HTTPS port of the PBX
  • {MAC} is the MAC address as the result of the pattern matching process
  • {Vendor} is the content of the vendor entry
  • {Model} is the content of the model entry
[edit]

Configuration File Tags

Inside the configuration file, you can use other tags. Those tags are replaced with information about the PBX and information about the extension that is being provisioned.

[edit]

Tags with Global Scope

  • "MAC" is the MAC address of the currently provisioned extension.
  • "IP-Adr" is the IP address of the PBX. If several IP addresses are available, the PBX will choose the one which is used to communicate with the extension.
  • "SIP-UDP-Port" is the first UDP port of the PBX.
  • "SIP-TCP-Port" is the first TCP port of the PBX.
  • "SIP-TLS-Port" is the first TLS port of the PBX.
  • "SIP-Port" inserts the port according to the transport layer. The transport layer is stored in a parameter. The name of the parameter is stated behind the tag (e.g. "{SIP-Port trans}").
  • "Starcode" inserts a star code of the pbx. The tag has a parameter which indicates which code should be inserted. The name of the code is the name as it appears in the database of the PBX. For examples see the domain configuration file in the domains directory.
[edit]

Extension Parameters

The PBX can loop through the available extensions for device that is being configured. The following tags are available:

  • "Loop-Start" indicates the beginning of the list of extensions per device. You may provide two optional parameters for this tag. The first parameter indicates the number for the first entry (typically, "0" or "1"). The second parameter indicates the maximum number for the loop. This way, you can avoid providing too many extensions for the phone. For example, if you want to have only two extensions with the index 1 and 2, you would use the tag "{Loop-Start 1 3}".
  • "Loop-End" indicates the end of the loop.
  • "Loop-Count" or "LC" is being replaced with the current loop counter. For example, if you are looping from 1 to 2, the values would be "1" and "2". If you add a parameter, the PBX will add the value of that parameter to the loop count. This way, you can specify an offset (e.g. "{LC 1}" will generate a counter with an offset of 1).
  • "Account" is the name if the extension, for example "123".
  • "Domain" is the domain name for the extension, for example "domain.com".
  • "Password" or "SIP-Password" is the SIP password for the extension. If the password may not be provisioned (see Port Setup), this setting will stay empty.
  • "Web-Pass" is the Web password for the extension. If the password may not be provisioned (see Port Setup), this setting will stay empty.
  • "PIN" is the PIN code for the extension. If the password may not be provisioned (see Port Setup), this setting will stay empty.
  • "Password-Start" marks the start of the password-area. If the password should not be provisioned, this area is not sent to the user-agent (e.g. if it has already been sent).
  • "Password-End" marks the end of the password-area. A Typical usage of "Password-Start" and "Password-End" looks like this: '{Password-Start}reg.{Loop-Count}.auth.password="{Password}" {Password-End}'.
  • "Display-Name" will be the first ands the last name of the extension, separated by a space (if necessary).
  • "Parameter1" is the first general-purpose parameter for the extension.
  • "Parameter2" is the second general-purpose parameter for the extension.
  • "Lines" is the number of lines for the extension.
  • "Buddy" is the buddy list for the extension (monitoring calls). It has a parameter, which is the index into the buddy list. The PBX will append the domain name to the buddy name and make it a SIP URI. For example "{Buddy 3}" on the list "123 456 789" will return something like "sip:789@domain.com".
  • "Presence" is like the buddy list, but for presence information published by the end points.
  • "Parameter" will insert a parameter value specified in the pnp.xml file for that provisioning file. This is useful to keep the provisioning more generic, e.g. specify the transport layer only once in the pnp.xml file.
  • "Multicast-Adr", "Multicast-Port", "Multicast-Size" will insert the IP address and port for the first found paging group that does multicast paging. The Multicast-Size will insert the packet size for the RTP packets sent by the PBX.
  • "ENUM" is used to enumerate a setting. This is for example useful to list existing languages. The first parameter is the location, this is currently limited to "extension" (which means that only extension parameters can currently be enumerated). The second parameter is the setting name, as it appears in the PBX database. The default value is the value of the third parameter. The other parameters list pairs for the enumeration, seperated with the equal symbol. The values are URL-encoded. For example, "{ENUM extension lang_web English de=Deutsch fr=French}" would result in either "English", "Deutsch" or "French".
  • "Global" returns a global setting of the PBX. For example "{Global packet_size}" would return the packet size used on the PBX.
[edit]

Time Zone Provisioning

The time zone information is an important part of the phone's configuration. The PBX provides several useful tags for providing the time zone that has been selected for the user. If there are several user extensions for the device, the PBX will choose the first profile for the time zone provisioning. For more information about time zones, please check for example http://en.wikipedia.org/wiki/Time_Zone.

  • TZ ntp-adr: A useful address for the NTP server. There is a setting called "ntp_host" in the Global Configuration File, which is by default set to "pool.ntp.org".
  • TZ gmt-offset: The offset from GMT for this time zone in seconds.
  • TZ gmt-hourminute: The offset from GMT for this time zone in HH:MM format.
  • TZ gmt-string: The offset from GMT in "GMT-xx:xx" format.
  • TZ dst-enable: If the DST offset is set, this tag will be replaced with "1", otherwise with "0".
  • TZ dst-fixed: If the DST starts on a fixed day (e.g. April, 28th) this setting will be set to "1", otherwise set to "0".
  • TZ dst-start-month: The month in which the DST will start
  • TZ dst-start-day: If the DST starts on a fixed date, then this setting will contain the day of the month.
  • TZ dst-start-hour: This will contain the hour when DST will start.
  • TZ dst-start-wday: Indicates the day of the week when DST starts (1 = Sunday, 7 = Saturday).
  • TZ dst-start-last: If the DST should start at the last week of a month, then this setting will be "1", else "0".
  • TZ dst-stop-month: See start-month, but for the end of the DST.
  • TZ dst-stop-day: See start-day, but for the end of the DST.
  • TZ dst-stop-hour: See start-hour, but for the end of the DST.
  • TZ dst-stop-wday: See start-wday, but for the end of the DST.
  • TZ dst-stop-last: See start-last, but for the end of the DST.
  • TZ dst-snom: This is the snom-specific time zone string (e.g. "3600 22.03 03:00:00 22.09 04:00:00")
  • TZ dst-spa: This is the Sipura-specific time zone string (e.g. "start=4/2/7/2:0:0;end=10/-2/7/2:0:0;save=1")

Other parameters may be provided in the "timezone.xml" file with the time zones. Those parameters are transparently passed through the configuration process.

[edit]

Dialplan Provisoning

As with the time zone, the provisioning of a dial plan for an extension makes the administrators life much easier.

The "Dialplan" tag has one parameter, which identifies the vendor. This identification is used as index into the "dialplans.xml" file, which lists the available dial plans by vendor. An example file looks like this: 

<?xml version="1.0"?> 
<dialplans default="enter">
  <plan name="enter">
    <global>!^011([0-9]*)!+\1!</global>
    <global>!^00([0-9]*)!+\1!</global>
    <vendor pattern="Polycom"></vendor>
    <vendor pattern="snom"></vendor>
  </plan>
  <plan name="usa3">
    <global>!^011([0-9]*)!+\1!</global>
    <global>!^1([0-9]{10})!+1\1!</global>
    <global>!^([0-9]{10})!+1\1!</global>
    <vendor pattern="Polycom">[5-7]xx|8[5-7]xx|[1-9]11|9,x11|9,011xxx.T|9,[0-1][2-9]xxxxxxxxx|9,[2-9]xxxxxxxxx</vendor>
    <vendor pattern="snom">!([5-7][0-9]{2})!\1!d</vendor>
  </plan>
  <plan name="europe3">
    <global>!^00([0-9]*)!+\1!</global>
    <global>!^0([0-9]*)!+\c\1!</global>
    <vendor pattern="Polycom">[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT</vendor>
    <vendor pattern="snom">!([5-7][0-9]{2})!\1!d</vendor>
  </plan>
</dialplans>

The available dial plans for every vendors an entry. The "pattern" attribute is compared with the parameter for the "Dialplan" tag. If there is a match, the PBX will replace the content of the entry into the file.

The "global" entries are for future use. Their purpose will be to get a canonical number representation.

[edit]

Address Book Provisioning

The PBX is able to provision the address book for a specific user. The following tags are available:

  • Adrbook-Start: Indicates the beginning of the loop. You may provide two optional parameters for this tag. The first parameter indicates the number for the first entry (typically, "0" or "1"). The second parameter indicates the maximum number for the loop. This way, you can avoid providing too many address book entries for the phone.
  • Adrbook-End: Indicates the end of the loop.
  • Adrbook-Name: The first name and the last name of the contact, if necessary separated by a space character.
  • Adrbook-First-Name: The first name

Adrbook-Last-Name: The last name.

  • Adrbook-Number: The number associated with the address book entry.
  • Adrbook-Speed: The speed dial number for the address book entry.

The following example shows the Polycom address book provisioning. You can see that for every address book item the PBX generates a line which contains the other parameters like the first name and the last name. 

<?xml version="1.0" standalone="yes"?>
<directory><item_list>
{Adrbook-Start}<item><fn>{Adrbook-First-Name}</fn><ln>{Adrbook-Last-Name}</ln><ct>{Adrbook-Number}</ct><sd>{Adrbook-Speed}</sd></item>
{Adrbook-End}</item_list></directory>
Retrieved from "http://wiki.pbxnsip.com/index.php/Automatic_Provisioning"
Personal tools
Getting Help