Explanation#

Provisioning is a way of distributing settings to one or multiple devices/phones. Most often a http-server is involved where each phone can request it's settings from.

How the phone does try to acquire provisioned settings is itself a setting-section within the phone's configuration.

Manual Provisioning#

via Web-UI#

You have limited provisioning by simply uploading a provisioning-xml via restore backup in the phone's Web-UI. This method doesn't allow provisioning-xmls of the reference type.

You'll have to put a provisioning-xml on a http-server somewhere that the phone can reach. Enter that file-url (e.g. http://192.168.1.1/prov.xml) as Provisioning server URL (on phone: Settings -> Provisioning). The same phone-menu has an entry: Start provisioning. Press it and the phone will download the file and install it.

Automatic Provisioning#

Preconditions#

To achieve a successful Provisioning, the phone needs

a correctly configured and available Network
a valid time - It relies on NTP to acquire one

Process#

After activation, the provisioning-service checks the preconditions. Then it checks the following fixed sequence of sources:

via DHCP
concurrently:
- Redirect Service
- Multicast Subscribe
a configured Provisioning server URL

The service sends a request to the first found URL. After a successful download it checks, whether the file is of the Reference Type. This may lead to subsequent downloads. Every URL can contain special markers, that are replaced with device information.

The service uses the files in the specified sequence. The migration-machnism applies the files to the configuration. This process doesn't restart the device.

Triggers#

A provisioning can be initiated by various events.

manually: within the phones settings-menu under provisioning
at system boot: If configured, the provisioning service reacts on every system boot.
at a specific time: configured via the provisioning-settings.
via check sync: A SIP notify message can start a provisioning.

via DHCP#

A device uses the DHCP options 66, 67 and 43 to determine an URL. It combines the options 66 and 67. The following example configuration of an isc-dhcp-server:

host d200 {
   hardware ethernet 00:09:52:00:00:0E;
   filename "prov.py?mac=<MACADR>";
   option tftp-server-name "http://prov.server.com";
}

is combined to http://prov.server.com/prov.py?mac=. Missing / are inserted between the options.

    Option  Length  Text
    66  11  http://foo      block to transmit
    67  12  <HWTYP>.bak     block to transmit

The DHCP option 43 can contain the encoded information from option 66 and 67. The test is hexadecimal encoded and separated by :.

    Option  Length  Text
    42:     0b:     68:74:74:70:3a:2f:2f:66:6f:6f:00       encoded
    43:     0c:     3c:48:57:54:59:50:3e:2e:62:61:6b:00    encoded

Results in the complete option 43 content: 42:0b:68:74:74:70:3a:2f:2f:66:6f:6f:00:43:0c:3c:48:57:54:59:50:3e:2e:62:61:6b:00

Redirect Service#

The Redirect Service is an Auerswald/FonTevo Service, which assigns an URL to a device. It replies the assigned URL, when the configured device sends a request.

Registered partners can register their devices here.

The multicast subscribe mechanism sends a SIP multicast subscribe message and listens for sip notify responses. Contains on of the responses an URL, it is used by the provisioning service.

This mechanism should only be used in trustworthy networks. The device can't apply any security measures to ensure the authenticity and validity of the notify origin.

Provisioning-xml#

Provisioning-xml's come in different types.

Settings Patch Type#

When you create a backup of your settings you'll get an Provisioning-xml of this patch-type. It lists all settings within an encompassing configuration-element. When you re-upoload this xml it replaces all existing settings.

You may also reduce such a patch-type to only one settings-section and upload it. In this case only that section is replaced or merged.

If you want to alter just a couple or a single sub-element of a settings-section, reduce these settings and mark it with patch="true". Your uploaded sub-elements will alter their existing counter-parts but other settings will be left alone.

The settings evolve with each release. New ones are added, others might get renamed. We list the configuration XSD definitions so you can check which settings structure is expected:

You may even provision settings-sections of an elder version, the telephone uses a migration-machnism to change an outdated settings-version into the current one.

Reference Type#

A reference file allows the user to provide more than one configuration file.

The schema for this XML document is the provisioning_references.xsd.

Example schema
    <?xml version="1.0" encoding="UTF-8" ?>
    <referencedSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="provisioning_references.xsd">
      <URL>first_file.xml</URL>
      <URL>/second_file.xml</URL>
      <URL>http://another.server.com/third_file.xml</URL>
      <URL>prov.py?mac=&lt;MACADR&gt;</URL>
    </referencedSettings>

Each URL-element is loaded one-by-one. They can point to provisioning-xml's of any type so chaining is possible.

When interpreting the content of an URL-element, the phone takes into account from which server the reference file was acquired. Lets say the above reference-file was fetched from http://prov.server.com/prov/references.xml, the phone will subsequently load these 4 files:

http://prov.server.com/prov/first_file.xml - URL-element is a simple file -> that file will be acquired from the same directory on the server as the reference file was.
http://prov.server.com/second_file.xml - URL-element is a file-path (starts with '/') -> file-path is appended to the host of the reference file.
http://another.server.com/third_file.xml - URL-element is a complete URL and gets used as is.
http://prov.server.com/prov.py?mac=00095200000E - URL-element contains Marker replacements which allow to insert phone-details into the query of the resulting http-requests.

Operations Type#

The operations-type is new in version 1.6 and allows to specify delete-operations on the basis of XPaths. The Schema for this provisioning-file-type is included in the patch type xsd's.

<operations>
    <delete path="/templates/template[@name='Test']" />
    <replace path="/keys/phoneXtensions/key[@keyNumber='3']/parameters/parameter[@name='@string/identity']">
             <parameter name="@string/identity" value="3"/>
    </replace>
    <add path="/keys/phoneXtensions/key[@keyNumber='3']/parameters/">
             <parameter name="@string/foo" value="bar"/>
    </add>
</operations>

All operations are applied to the current settings (no migration but only after all operations are applied do we check each setting-section. If it is still a valid configuration it is stored, if not all operations on that setting-section are discarded.

The path-parameter of our operations must point to an existing sub-tree. I.e. letting it point to an individual attribute to change it will not work.

Marker replacement#

The provisioning service replaces the following markers in URL's (e.g. in the reference file or the Provisiong-Server-URL-setting):

<SERIAL> or {serial} to the devices serial number.
<HWTYP> or {type} to D100, D110,D200, D210, D400 or D600.
<MACADR> or {mac} to the devices MAC address ( uppercase, without ":" )

Given the following URL:

http://prov.server.com/prov.py?mac=<MACADR>&sn=<SERIAL>&hw=<HWTYP>

the phone will fetch:

http://prov.server.com/prov.py?mac=00095200000E&sn=123412341234&hw=D100