How does Phone provisioning work?

Introduction

HTTP provisioning of phone sets is useful for an administrator as it helps to automate the process of configuring the phone set for a particular extension. The administrator creates the extension as usual, and in addition specifies the MAC address of the phone. Once the extension is created, a configuration for the specified phone set is created using the MAC address as the file name in the directory [pbx install dir]\Data\Http\provisioning\. The phone is then configured to download the configuration from this directory via the 3CX http server on next startup. During startup no user action is required.

The Process:

  1. When a new extension is created, the below list of details are mandatory for phone provisioning configuration generation:

      a. Extension Number (e.g. 100)
      b. First Name (e.g. John)
      c. Last Name (e.g. Doe)
      d. Authentication ID (e.g. 100)
      e. Authentication Password (e.g. 100)
      f. Phone MAC Address (e.g. 000413246672)
      g. Phone model (e.g. Snom320)
      h. PBX interface IP (e.g. 10.172.0.2)

  2. Once user confirms the details and clicks on “OK”, the details are passed to an XML template configuration where:

      a. Extension Number = %%extension_number%%
      b. First Name = %%extension_first_name%%
      c. Last Name = %%extension_last_name%%
      d. Authentication ID = %%extension_auth_id%%
      e. Authentication Password = %%extension_auth_pw%%
      f. Phone MAC Address = %%mac_address%%
      g. Phone model = <description> Snom 320 SIP Phone </description>
      h. PBX interface IP = %%pbx_ip%%

    Sample configuration template file for a SNOM phone, which can be found in [pbx install dir]\Data\Http\templates\phones.
    Note: Real configuration templates are longer, the configuration shown below is shortened for documentation purposes and it shows only values which are changed from the http provisioning module:

    <?xml version="1.0"?>
    <doc xmlns:tcx="http://www.3cx.com">
      <header>
        <type>phone-template</type>
        <version>3802</version>
        <time>2007-11-08 09:30:00</time>
        <name>Snom 320</name>
        <url>http://www.snom.com</url>
        <image>snom.png</image>
        <description>Snom 320 SIP Phone</description>
      </header>
      <data>
        <device>
          <type>phone</type>

              <!-- Friendly Name -->
          <field name="Name">Snom 320</field>

        <deviceconfig filename="cfg%%mac_address%%">
     <![CDATA[

      # First account

      user_pname1$: %%extension_auth_id%%
      user_pass1$: %%extension_auth_pw%%
      user_name1$: %%extension_number%%
      user_realname1$: %%extension_first_name%% %%extension_last_name%%
      user_host1$: %%pbx_ip%%

      ]]>
         </deviceconfig>

       </device>
     </data>
    </doc>

  3. The details in the extension properties page will be added to configuration where specified from the variables (e.g. %%extension_auth_id%%), and the configuration is generated in [pbx install dir]\Data\Http\provisioning\. Below is a sample configuration:

      # First account

      user_pname1$: 100
      user_pass1$: 100
      user_name1$: 100
      user_realname1$: John Doe
      user_host1$: 10.172.0.2

  4. The filename of the generated configuration is generated from this line:
    <deviceconfig filename="cfg%%mac_address%%">
    Therefore configuration filename would be cfg000413246672.

  5. The phone should be set to retrieve the configuration from the web server on booting up. The settings which should be set on the phone are the protocol used for retrieval of configuration, which in our case is HTTP (usually this can be TFTP, FTP or HTTP) and the URL where the telephone should retrieve the configuration
    (.e.g. http://10.172.0.2:5481/provisioning/).

  6. On rebooting, the telephone will send an http GET request to the web server to retrieve the configuration.
    E.g. http://10.172.0.2:5481/provisioning/cfg000413246672

  7. Once the phone downloads the configuration, it loads the configuration and the phone is ready to be used with the configured extension.

Conclusion

As discussed in this document, the concept of HTTP provisioning is to automatically configure the phone set without the need to input user and extension details.

Note: Not all phone sets request the same configuration file name, but usually this can be changed from the phone. Usually all phones include their MAC address in the filename so configuration is unique. Filename of generated configuration files can also be changed from the template by changing this field:
<deviceconfig filename="cfg%%mac_address%%">.

Current limitations are that we cannot set more than 1 account on each phone and that we cannot include them in the bulk import of extensions.

General 3CX Phone System FAQs