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.
(→DELETE) |
Hans.zeiner (talk | contribs) (→Firewall Rules) |
||
| (4 intermediate revisions by 2 users not shown) | |||
| Line 8: | Line 8: | ||
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. | 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. | ||
| + | |||
| + | ==== '''Firewall Rules''' ==== | ||
| + | |||
| + | Host address and port numbers for ZTP | ||
| + | |||
| + | {| | ||
| + | |- | ||
| + | | align=center style="background-color:#0066a1;border-top:0.05pt solid #000000;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.097cm;" |<div style="color:white"> '''Trusted Host'''</div> | ||
| + | | align=center style="background-color:#0066a1;border-top:0.05pt solid #000000;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.097cm;" |<div style="color:white"> '''Protocol'''</div> | ||
| + | | align=center style="background-color:#0066a1;border-top:0.05pt solid #000000;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.097cm;" |<div style="color:white"> '''Port'''</div> | ||
| + | |- | ||
| + | | align=left style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.097cm;" | '''cloud-setup.com''' | ||
| + | | align=left style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.097cm;" | TLS | ||
| + | |||
| + | | align=center style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.097cm;" | 18443 | ||
| + | |} | ||
== API == | == API == | ||
| Line 35: | Line 51: | ||
|} | |} | ||
| − | The data received on a successful request | + | The data received on a successful request with HTTP response code 200 |
| − | {"mac":"01:23:45:67:89:ab | + | {"mac":"01:23:45:67:89:ab","data":"'<Item name="bw-dms-addr">https://192.168.0.100/home</Item>\r\n<Item name="language-iso">de</Item>'"} |
{| {{DefaultTable}} | {| {{DefaultTable}} | ||
| Line 45: | Line 61: | ||
|- | |- | ||
| mac | | mac | ||
| − | | The MAC address sent in the request or ERROR if no MAC given | + | | The MAC address sent in the request or ERROR if no MAC given. |
|- | |- | ||
| − | | | + | | certificate<br>''optional'' |
| − | | | + | | If a certificate is prepared for the provided MAC address, will contain the lifetime. |
|- | |- | ||
| data<br>''optional'' | | data<br>''optional'' | ||
| − | | If the | + | | If the response code is 200, value will contain the data prepared for the given MAC address. |
|- | |- | ||
| reason<br>''optional'' | | reason<br>''optional'' | ||
| − | | If the | + | | If the response code is not 200, will contain the reason for the response. |
|} | |} | ||
| Line 209: | Line 225: | ||
| false | | false | ||
| The port of a DLS server | | The port of a DLS server | ||
| + | |- | ||
| + | | e164 | ||
| + | | false | ||
| + | | The terminal number of a device | ||
|- | |- | ||
| bw-dms-addr | | bw-dms-addr | ||
Latest revision as of 16:02, 7 November 2024
Contents
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.
Firewall Rules
Host address and port numbers for ZTP
Trusted Host
|
Protocol
|
Port
|
| cloud-setup.com | TLS | 18443 |
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 the device.
{"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 with HTTP response code 200
{"mac":"01:23:45:67:89:ab","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. |
| certificate optional |
If a certificate is prepared for the provided MAC address, will contain the lifetime. |
| data optional |
If the response code is 200, value will contain the data prepared for the given MAC address. |
| reason optional |
If the response code is not 200, will contain the reason for the 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 either the deployment data of the device or the certificate request.
{"mac":"01:23:45:67:89:ab","certificate":"true","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 |
| certificate optional |
"true" or "false" |
| data optional |
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 with HTTP response code 200
{"mac":"01:23:45:67:89:ab","certificate":"{Certificate-Object}","data":"[Data-Object]"}
| Key | Value |
|---|---|
| mac | The MAC address sent in the request or ERROR if no MAC given. |
| certificate optional |
If a device certificate certificate was requested, will contain the result of the request. |
| data optional |
Will contain the result of the data prepared for the given MAC address. |
| reason optional |
If the HTTP response code is not 200, will contain the reason for the response. |
Result for Certificate-Object
{"code":201,"serial":"..."}
| Key | Value |
|---|---|
| code | The response code of the request. 201 on successful creation. |
| serial optional |
If the response code is 201, will contain the serial number of the certificate created. |
| lifetime optional |
If the response code is 200 because a certificate already exists, will contain the lifetime of the current certificate. |
| reason optional |
If the response code is not 201, will contain the reason for the response |
Result for Data-Oject
[{"name":"acs-server-address","code":200},...]
| Key | Value |
|---|---|
| name | The name of the item. |
| code | The response code of the request. 200 on success. |
| reason optional |
If the response code is not 200, will contain the reason for the 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 the device.
{"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 with an HTTP response code of 200
{"mac":"01:23:45:67:89:ab"}
| Key | Value |
|---|---|
| mac | The MAC address sent in the request or ERROR if no MAC given |
| reason optional |
If the response code is not 200, will contain the reason for the 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 |
| e164 | false | The terminal number of a device |
| 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 |
| bw-dms-authentication-policy | false | The authentication policy for the DMS provisioning server. |
HTTP responses
The following HTTP responses are possible when sending requests to the API
| HTTP code | Description |
|---|---|
| 200 | response code for successful requests |
| 400 | response code for invalid data |
| 404 | response code for unsupported path |
| 405 | response code for not allowed method |
| 406 | response code for unsupported method |
| 415 | response code for parsing error of JSON data |
