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

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

To achieve a successful Provisioning, the phone needs

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

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

  1. concurrently:

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.

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.

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=<MACADR>. 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

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.

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:

Release 1.0B

Release 1.2A

Release 1.4 A / 1.4B

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.

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

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

<?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:

  1. 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.
  2. 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.
  3. http://another.server.com/third_file.xml - URL-element is a complete URL and gets used as is.
  4. 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.

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']" />
    <delete path="/templates/template[@name='Test2']" />
</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.

We plan to add further operations like replace and add but there is always so much to do. If you need more control, let us know.

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, D200.
  • <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 applies its data

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