Views

Difference between revisions of "Zero Touch Deployment"

The Wiki of Unify contains information on clients and devices, communications systems and unified communications. - Unify GmbH & Co. KG is a Trademark Licensee of Siemens AG.

Jump to: navigation, search
(Created page with "= Zero Touch Deployment =")
 
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Zero Touch Deployment =
+
== Introduction ==
 +
Zero Touch Deployment describes a method of deploying a Desk Phone CP SIP device, without user interaction, via the Unify redirect server. For this to work, a service provider needs access to the redirect server API, in order to prepare the deployment of the device. On initial startup or after a factory reset, the device will contact the redirect server and will receive information about the service providers deployment system.
 +
 
 +
== Provisioning details ==
 +
The Desk Phone CP SIP device will only contact the redirect server for zero touch deployment under certain circumstances. It must be running with factory default settings (out of the box or after a factory reset), it must not be configured with a SIP, DLS, DMS or ACS server address via DHCP and it must be able to resolve and access cloud-setup.com on port 18443
 +
 
 +
The phone will connect to the address of cloud-setup.com and check for a zero touch deployment profile being available. If it is not available (e.g. because the service provider has added the profile after the initial start of the device), the device needs to be restarted in order to restart the zero touch deployment process.
 +
 
 +
In the process of connecting to cloud-setup.com, the phone will validate the connection to the server via a hard coded root certificate that comes with every phone software version.
 +
 
 +
== API ==
 +
The redirect server API is available at https://cloud-setup.com/api/devices and supports the following methods
 +
 
 +
* POST
 +
* PUT
 +
* DELETE
 +
 
 +
==== Authentication ====
 +
Access to the API is authenticated via certificate based mutual authentication. Every service provider will get an individual certificate.
 +
 
 +
==== POST ====
 +
The POST method is used to retrieve information about devices prepared for zero touch deployment. The data sent in the POST request must contain the mac address of up to 100 devices per request.
 +
 
 +
  [{"mac":"01:23:45:67:89:ab"},...]
 +
 
 +
the mac address can be provided in the following format
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="200" | Value
 +
|-
 +
| mac<br>'''required'''
 +
| 01:23:45:67:89:AB<br>01-23-45-67-89-AB<br>01:23:45:67:89:ab<br>01-23-45-67-89-ab
 +
|}
 +
 
 +
The data received on a successful request.
 +
 
 +
  [{"mac":"01:23:45:67:89:ab","result":"OK","data":"'<Item name="bw-dms-addr">https://192.168.0.100/home</Item>\r\n<Item name="language-iso">de</Item>'"},...]
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="500" | Value
 +
|-
 +
| mac
 +
| The MAC address sent in the request or ERROR if no MAC given
 +
|-
 +
| result
 +
| The result of the request. Can be OK or ERROR
 +
|-
 +
| data<br>''optional''
 +
| If the result is OK, value will contain the data prepared for the given MAC address
 +
|-
 +
| reason<br>''optional''
 +
| If the result is ERROR, will contain the reason for the ERROR response
 +
|}
 +
 
 +
==== PUT ====
 +
The PUT method is used to prepare information about devices for zero touch deployment. The data sent in the PUT request must contain the mac address and deployment data of up to 100 devices per request.
 +
 
 +
  [{"mac":"01:23:45:67:89:ab","data":[Data-Object]},...]
 +
 
 +
the mac address can be provided in the following format
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="400" | Value
 +
|-
 +
| mac<br>'''required'''
 +
| 01:23:45:67:89:AB<br>01-23-45-67-89-AB<br>01:23:45:67:89:ab<br>01-23-45-67-89-ab
 +
|-
 +
| data<br>'''required'''
 +
| The data provided as another Array of supported item objects
 +
|}
 +
 
 +
The Data-Object
 +
 
 +
  [{"name":"acs-server-address","value":"https://acs.cloud-provider.com","index":"0"},...]
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="500" | Value
 +
|-
 +
| name<br>'''required'''
 +
| The name of the item
 +
|-
 +
| value<br>'''required'''
 +
| The value of the item with a maximum of 255 characters
 +
|-
 +
| index<br>''optional''
 +
| Contains the index value of the item
 +
|}
 +
 
 +
The data received on a successful request.
 +
 
 +
  [{"mac":"01:23:45:67:89:ab","result":"OK","data":"[Data-Object]"},...]
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="500" | Value
 +
|-
 +
| mac
 +
| The MAC address sent in the request or ERROR if no MAC given
 +
|-
 +
| result
 +
| The result of the request. Can be OK or ERROR
 +
|-
 +
| data<br>''optional''
 +
| If the result is OK, value will contain the data prepared for the given MAC address
 +
|-
 +
| reason<br>''optional''
 +
| If the result is ERROR, will contain the reason for the ERROR response
 +
|}
 +
 
 +
Result for Data-Oject
 +
 
 +
  [{"name":"acs-server-address","result":"OK"},...]
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="500" | Value
 +
|-
 +
| name
 +
| The name of the item
 +
|-
 +
| result
 +
| The result of the request. Can be OK or ERROR
 +
|-
 +
| reason<br>''optional''
 +
| If the result is ERROR, will contain the reason for the ERROR response
 +
|}
 +
 
 +
==== DELETE ====
 +
The DELETE method is used to delete information about devices prepared for zero touch deployment. The data sent in the DELETE request must contain the mac address of up to 100 devices per request.
 +
 
 +
  [{"mac":"01:23:45:67:89:ab"},...]
 +
 
 +
the mac address can be provided in the following format
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="200" | Value
 +
|-
 +
| mac<br>'''required'''
 +
| 01:23:45:67:89:AB<br>01-23-45-67-89-AB<br>01:23:45:67:89:ab<br>01-23-45-67-89-ab
 +
|}
 +
 
 +
The data received on a successful request.
 +
 
 +
  [{"mac":"01:23:45:67:89:ab","result":"OK"},...]
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="100" | Key
 +
! width="500" | Value
 +
|-
 +
| mac
 +
| The MAC address sent in the request or ERROR if no MAC given
 +
|-
 +
| result
 +
| The result of the request. Can be OK or ERROR
 +
|-
 +
| reason<br>''optional''
 +
| If the result is ERROR, will contain the reason for the ERROR response
 +
|}
 +
 
 +
== Items ==
 +
The following items can be prepared to be deployed to the device during the zero touch deployment process.
 +
 
 +
{| {{DefaultTable}}
 +
|-
 +
! width="150" | Item name
 +
! width="100" | Index
 +
! width="400" | Description
 +
|-
 +
| dls-addr
 +
| false
 +
| The address of a DLS server
 +
|-
 +
| dls-port
 +
| false
 +
| The port of a DLS server
 +
|-
 +
| bw-dms-addr
 +
| false
 +
| The address of a Broadworks DMS server
 +
|-
 +
| language-iso
 +
| false
 +
| The language setting of a device
 +
|-
 +
| sntp-addr
 +
| false
 +
| The address of an NTP server
 +
|-
 +
| acs-server-address
 +
| false
 +
| The address of an ACS server
 +
|-
 +
| acs-username
 +
| false
 +
| The username for accessing an ACS server
 +
|-
 +
| acs-password
 +
| false
 +
| The password for accessing an ACS server
 +
|}

Latest revision as of 20:33, 4 December 2019

Introduction

Zero Touch Deployment describes a method of deploying a Desk Phone CP SIP device, without user interaction, via the Unify redirect server. For this to work, a service provider needs access to the redirect server API, in order to prepare the deployment of the device. On initial startup or after a factory reset, the device will contact the redirect server and will receive information about the service providers deployment system.

Provisioning details

The Desk Phone CP SIP device will only contact the redirect server for zero touch deployment under certain circumstances. It must be running with factory default settings (out of the box or after a factory reset), it must not be configured with a SIP, DLS, DMS or ACS server address via DHCP and it must be able to resolve and access cloud-setup.com on port 18443

The phone will connect to the address of cloud-setup.com and check for a zero touch deployment profile being available. If it is not available (e.g. because the service provider has added the profile after the initial start of the device), the device needs to be restarted in order to restart the zero touch deployment process.

In the process of connecting to cloud-setup.com, the phone will validate the connection to the server via a hard coded root certificate that comes with every phone software version.

API

The redirect server API is available at https://cloud-setup.com/api/devices and supports the following methods

  • POST
  • PUT
  • DELETE

Authentication

Access to the API is authenticated via certificate based mutual authentication. Every service provider will get an individual certificate.

POST

The POST method is used to retrieve information about devices prepared for zero touch deployment. The data sent in the POST request must contain the mac address of up to 100 devices per request.

 [{"mac":"01:23:45:67:89:ab"},...]

the mac address can be provided in the following format

Key Value
mac
required
01:23:45:67:89:AB
01-23-45-67-89-AB
01:23:45:67:89:ab
01-23-45-67-89-ab

The data received on a successful request.

 [{"mac":"01:23:45:67:89:ab","result":"OK","data":"'<Item name="bw-dms-addr">https://192.168.0.100/home</Item>\r\n<Item name="language-iso">de</Item>'"},...]
Key Value
mac The MAC address sent in the request or ERROR if no MAC given
result The result of the request. Can be OK or ERROR
data
optional
If the result is OK, value will contain the data prepared for the given MAC address
reason
optional
If the result is ERROR, will contain the reason for the ERROR response

PUT

The PUT method is used to prepare information about devices for zero touch deployment. The data sent in the PUT request must contain the mac address and deployment data of up to 100 devices per request.

 [{"mac":"01:23:45:67:89:ab","data":[Data-Object]},...]

the mac address can be provided in the following format

Key Value
mac
required
01:23:45:67:89:AB
01-23-45-67-89-AB
01:23:45:67:89:ab
01-23-45-67-89-ab
data
required
The data provided as another Array of supported item objects

The Data-Object

 [{"name":"acs-server-address","value":"https://acs.cloud-provider.com","index":"0"},...]
Key Value
name
required
The name of the item
value
required
The value of the item with a maximum of 255 characters
index
optional
Contains the index value of the item

The data received on a successful request.

 [{"mac":"01:23:45:67:89:ab","result":"OK","data":"[Data-Object]"},...]
Key Value
mac The MAC address sent in the request or ERROR if no MAC given
result The result of the request. Can be OK or ERROR
data
optional
If the result is OK, value will contain the data prepared for the given MAC address
reason
optional
If the result is ERROR, will contain the reason for the ERROR response

Result for Data-Oject

 [{"name":"acs-server-address","result":"OK"},...]
Key Value
name The name of the item
result The result of the request. Can be OK or ERROR
reason
optional
If the result is ERROR, will contain the reason for the ERROR response

DELETE

The DELETE method is used to delete information about devices prepared for zero touch deployment. The data sent in the DELETE request must contain the mac address of up to 100 devices per request.

 [{"mac":"01:23:45:67:89:ab"},...]

the mac address can be provided in the following format

Key Value
mac
required
01:23:45:67:89:AB
01-23-45-67-89-AB
01:23:45:67:89:ab
01-23-45-67-89-ab

The data received on a successful request.

 [{"mac":"01:23:45:67:89:ab","result":"OK"},...]
Key Value
mac The MAC address sent in the request or ERROR if no MAC given
result The result of the request. Can be OK or ERROR
reason
optional
If the result is ERROR, will contain the reason for the ERROR response

Items

The following items can be prepared to be deployed to the device during the zero touch deployment process.

Item name Index Description
dls-addr false The address of a DLS server
dls-port false The port of a DLS server
bw-dms-addr false The address of a Broadworks DMS server
language-iso false The language setting of a device
sntp-addr false The address of an NTP server
acs-server-address false The address of an ACS server
acs-username false The username for accessing an ACS server
acs-password false The password for accessing an ACS server