Explanation [DokuWiki extern]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{indexmenu_n>1}}

======= 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 [[en:products:comfortel-d-series:developer:provisioning:settings:provisioning|setting-section]] within the phone's configuration.

====== Manual Provisioning ======
===== via Web-UI =====
You have limited provisioning by simply uploading a [[en:products:comfortel-d-series:developer:provisioning:explanation#provisioning-xml]] via `restore backup` in the phone's Web-UI. This method doesn't allow [[#provisioning-xml|provisioning-xmls]] of the [[#reference_type|reference type]].

===== via Settings-Menu =====
You'll have to put a [[#provisioning-xml]] on a http-server somewhere that the phone can reach. Enter that file-url (e.g. <nowiki>http://192.168.1.1/prov.xml</nowiki>) 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|preconditions]].
Then it checks the following fixed sequence of sources:
  - [[#via DHCP]]
  - concurrently:
    * [[#Redirect Service]]
    * [[#Multicast Subscribe]]
  - a configured [[en:products:comfortel-d-series:developer:provisioning:settings:provisioning|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 [[#Marker Replacement|device information]].

The service uses the files in the specified sequence.
The [[en:products:comfortel-d-series:developer:provisioning:migrationindetail|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 [[en:products:comfortel-d-series:developer:provisioning:settings:provisioning|provisioning-settings]].
  * via check sync: A SIP [[en:products:comfortel-d-series:developer:provisioning:unsolicited_notify|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 <nowiki>http://prov.server.com/prov.py?mac=<MACADR></nowiki>.
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 [[https://provisioning.auerswald.de/|here]]. 

===== Multicast Subscribe =====
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 [[en:products:comfortel-d-series:developer:provisioning:explanation:patchindetail:replacevsmergeexample|replaces]] all existing settings.

You may also reduce such a patch-type to only one [[en:products:comfortel-d-series:developer:provisioning:explanation:patchindetail:singlesettingsexamples|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 [[en:products:comfortel-d-series:developer:provisioning:explanation:patchindetail|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:

[[en:products:comfortel-d-series:firmware|(release history)]]

[[en:products:comfortel-d-series:firmware:release1.10]] 

[[en:products:comfortel-d-series:firmware:release2.0c]] 

[[en:products:comfortel-d-series:firmware:release2.2a]] 

You may even provision settings-sections of an elder version, the telephone uses a [[en:products:comfortel-d-series:developer:provisioning:migrationindetail|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 [[en:products:comfortel-d-series:developer:provisioning:provisioning_references|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 <nowiki>http://prov.server.com/prov/references.xml</nowiki>, the phone will subsequently load these 4 files:

  - ''<nowiki>http://prov.server.com/prov/first_file.xml</nowiki>'' - URL-element is a simple file -> that file will be acquired from the same directory on the server as the reference file was.
  - ''<nowiki>http://prov.server.com/second_file.xml</nowiki>'' - URL-element is a file-path (starts with '/') -> file-path is appended to the host of the reference file.
  - ''<nowiki>http://another.server.com/third_file.xml</nowiki>'' - URL-element is a complete URL and gets used as is.
  - ''<nowiki>http://prov.server.com/prov.py?mac=00095200000E</nowiki>'' - URL-element contains [[#Marker Replacement|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 [[#settings_patch_type|patch type]] xsd's.

<code xml>
<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>
</code>

All operations are applied to the current settings (no [[en:products:comfortel-d-series:developer:provisioning:migrationindetail|migration]]) but only after all operations are applied do we check each [[en:products:comfortel-d-series:developer:provisioning:settings|setting-section]]. If it is still a valid configuration it is stored, if not all operations on that [[en:products:comfortel-d-series:developer:provisioning:settings|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_type|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