Zero Touch Previsioning (ZTP), automating configuration and firmware DHCP
Zero Touch Provisioning (ZTP) allows WTI devices to be provisioned with configuration and/or firmware during their initial boot, from a DHCP and file server.
Preparation
These are typical steps for configuration over a network:
Create an .xml configuration file.
Obtain the latest flash firmware upgrade file from: https://ftp.wti.com/firmware/.
Publish these files on a fileserver that understands one of the HTTPS, HTTP, FTP or TFTP protocols.
Configure your DHCP server to include "vendor specific" sub-options for WTI devices.
The "vendor specific" option is option 43.
Option 43 sub-option 1 is the URL of the configuration file, the config URL must end in .xml
Option 43 sub-option 2 is the URL of the firmware file, the firmware URL must end in .md5.
The sub-option strings combined should not exceed 250 characters in length.
This configuration will be DHCP server-specific, a sample ISC DHCP server config snippet is included later in this document
Connect a new WTI device (either at defaults from the factory, or config erased) to the network and apply power.
It may take 5 - 10 minutes for the entire process to complete.
Create the configuration file
Note: When creating backups to apply WTI products of a different model, it is recommended to run "make-template" to scrub any model-specific configuration, which may cause compatibility issues.
To get this template file, login to a WTI device, issue the command:
/DF ZTP
Since this template is going to be used across multiple devices, you can exclude certain parameters like Port Parameters, Plug Parameters and certain System Parameters (for a complete list see Appendix B)
From this menu, INCLUDE any items you want to be included in the download and select "Download Template."
This is will be the universal .xml configuration file that you can put on your DHCP server.
Example ISC DHCP server configuration
The following is an example of an ISC DHCP server configuration fragment for serving an .xml configuration image and a firmware upgrade file for both console and powers units from WTI:
option space wtinetwork code width 1 length width 1;
option wtinetwork.config-url code 1 = text;
option wtinetwork.firmware-url code 2 = text;
class "wticonsole-ztp" {
match if option vendor-class-identifier ~~ "^WTI-CONSOLE";
vendor-option-space wtinetwork;
option wtinetwork.config-url "http://example.com/config/console.xml";
option wtinetwork.firmware-url "http://example.com/firmware/uimage_3352_tsm_arm.md5";
}
class "wtipower-ztp" {
match if option vendor-class-identifier ~~ "^WTI-POWER";
vendor-option-space wtinetwork;
option wtinetwork.config-url "http://example.com/config/power.xml";
option wtinetwork.firmware-url "http://example.com/firmware/uimage_3352_vmr_arm.md5";
}
For other DHCP servers, please consult their documentation on specifying "Vendor Specific" option fields.
How it works
This section explains in detail how the WTI device uses DHCP to obtain initial setup.
The unit you are using ZTP for needs it to be in an un-configured state, which is only obtained in the following ways:
Firmware programming at factory (no IP addresses, Subnet masks, Gateways, DHCP and no Cellular APN defined). To defalult a WTI unit issue the following command:
/I , (3 option)
Creating the file /flash/.ztpyes, removing /flash/.ztpnever and then rebooting
When an un-configured WTI boots, it performs these steps to find a configuration:
The WTI device transmits a DHCP DISCOVER request onto its primary Network Interface (eth0). This DHCP request will carry a Vendor Class Identifier of the form WTI-modeltype-model-name (for example, “WTI-CONSOLE-CPM-800-1-EA-PT9-PL8") and its parameter request list will include option 43 (Vendor-Specific Information).
On receipt of a DHCP OFFER, the device will use the information in the offer to assign an IPv4 address to its primary Network Interface, add a default route, and prepare its DNS resolver.
If the offer also contained an option 43 with sub-option 1, the device interprets the sub-option as a URL to configuration files to try to restore.
If a configuration file URL was provided (sub-option 1), the configuration file is downloaded; a quick syntax check is performed, then set into place as the current configuration. The configuration URL must end in .xml or it is skipped.
Next, If a firmware image URL was provided (sub-option 2) the system now runs the upgrade process for the URL until one of the URLs succeeds (the image was flashed or matched to existing flash). The firmware URL must end in .md5 or it is skipped.
The firmware image is downloaded, WTI will checksum and flash the firmware image. If the Check fails, the downloaded file is abandoned and operation continues.
The curl program is used to download the URL.
If all goes well the system will reboot with the new firmware and configuration file activated.
Note: If a URL failed, the system will wait for 30 seconds before retrying again. It will retry the URLs up to 10 times. After the 10th retry, the system reboots. If the system has been manually configured in the meantime, the retries stop and ZTP is disabled.
Note: If no option 43 is received over DHCP, no URLs are downloaded and no reboots occur: the system must be manually configured. Once configured (manually or by ZTP), a WTI device will no longer request option 43 from the DHCP server, and it will ignore any option 43 configuration URLs presented to it.
Technical Details
On the WTI unit a /etc/dhclient-eth0.conf file will be created:
timeout 30;
send dhcp-client-identifier 1:02:ed:45:32:67:65;
send dhcp-lease-time 15;
send fqdn.server-update off;
send vendor-class-identifier "WTI-CONSOLE-PRODUCTNAME-PT8-PL0";
option wtinetwork.config-url code 1 = string;
option wtinetwork.firmware-url code 2 = string;
option local-encapsulation code 43 = encapsulate wtinetwork;
request wtinetwork.config-url, wtinetwork.firmware-url;
On the ISC DHCP server add these lines of code (for Console Units)
option space wtinetwork code width 1 length width 1;
option wtinetwork.config-url code 1 = text;
option wtinetwork.firmware-url code 2 = text;
class "wticonsole-ztp" {
match if option vendor-class-identifier ~~ "^WTI-CONSOLE*";
vendor-option-space wtinetwork;
option wtinetwork.config-url "http://example.com/config/console.xml";
option wtinetwork.firmware-url "http://example.com/firmware/uimage_3352_tsm_arm.md5";
}
When the WTI unit boots, it sends the Option 43 bits. If the vendor-class-identifier matches close enough the return will be the Option 43 answers in hex encoded bits.
WTI DHCP REQUEST:
10:40:57.087417 IP (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 1c:ba:8c:e0:cf:b2, length 300, xid 0x6c43784d, secs 8, Flags [none] (0x0000)
Client-Ethernet-Address 1c:ba:8c:e0:cf:b2
Vendor-rfc1048 Extensions
Magic Cookie 0x63825363
DHCP-Message Option 53, length 1: Discover
Lease-Time Option 51, length 4: 15
FQDN Option 81, length 3: ""
Vendor-Class Option 60, length 32: "WTI-CONSOLE-CPM-800-1-EA-PT9-PL8"
Client-ID Option 61, length 7: ether 1c:ba:8c:e0:cf:b2
ISC DHCP SERVER RESPONSE:
10:40:58.089319 IP (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 401)
192.168.0.159.67 > 192.168.0.33.68: [udp sum ok] BOOTP/DHCP, Reply, length 373, xid 0x6c43784d, secs 8, Flags [none] (0x0000)
Your-IP 192.168.0.33
Server-IP 192.168.0.159
Client-Ethernet-Address 1c:ba:8c:e0:cf:b2
Vendor-rfc1048 Extensions
Magic Cookie 0x63825363
DHCP-Message Option 53, length 1: Offer
Server-ID Option 54, length 4: 192.168.0.159
Lease-Time Option 51, length 4: 3343
Subnet-Mask Option 1, length 4: 255.255.255.0
Domain-Name Option 15, length 11: "example.org"
Vendor-Option Option 43, length 6:
1.39.104.116.116.112.58.47.47.49.57.50.46.49.54.56.46.48.46.49.53.57.47.99.111.110.102.105.103.47.99.111.110.115.111.108.101.46.120.109.108.2.53.104.116.116.112.58.47.47.49.57.50.46.49.54.56.46.48.46.49.53.57.47.102.105.114.109.119.97.114.101.47.117.105.109.97.103.101.95.51.51.53.50.95.116.115.109.95.97.114.109.46.109.100.53
For a Detailed Explanation of the hex output see Appendix A.
The Vendor-Option Option 43 gets translated and stored on the WTI here:
/var/db/dhclient.leases
As follows:
lease {
interface "eth0";
fixed-address 192.168.0.33;
option subnet-mask 255.255.255.0;
option dhcp-lease-time 3342;
option dhcp-message-type 5;
option dhcp-server-identifier 192.168.0.159;
option domain-name "example.org";
option wtinetwork.config-url "http://192.168.0.159/config/console.xml";
option wtinetwork.firmware-url "http://192.168.0.159/firmware/uimage_3352_tsm_arm.md5";
renew 4 2018/02/22 19:07:37;
rebind 4 2018/02/22 19:28:56;
expire 4 2018/02/22 19:35:54;
}
The WTI unit then tries to use the Linux curl program to first grab the configuration file then the firmware image. If either one is present, they are copied, and the unit will reboot.
If the ZTP DHCP call does not contain the Option 43 parameter, the WTI unit will stop the DHCP client and continue booting and never try the ZTP sequence again.
Reset back into ZTP mode
After an IP address of some kind has been defined in the WTI device, ZTP will not be attempted on boot up. To re-enable ZTP on boot up, from any WTI device CLI prompt enter the command:
/ZTPFORCE
This will reset the ZTP flag and reboot the WTI device.
APPENDIX A
In this listing:
Vendor-Option Option 43, length 96:
1.39.104.116.116.112.58.47.47.49.57.50.46.49.54.56.46.48.46.49.53.57.47.99.111.110.102.105.103.47.99.111.110.115.111.108.101.46.120.109.108.2.53.104.116.116.112.58.47.47.49.57.50.46.49.54.56.46.48.46.49.53.57.47.102.105.114.109.119.97.114.101.47.117.105.109.97.103.101.95.51.51.53.50.95.116.115.109.95.97.114.109.46.109.100.53
The total length of the block is 96 bytes.
The first byte (1) is telling that this is option one. The next byte (39) is telling you that option one is 39 bytes long.
Taking the next 39 bytes as decimal:
104.116.116.112.58.47.47.49.57.50.46.49.54.56.46.48.46.49.53.57.47.99.111.110.102.105.103.47.99.111.110.115.111.108.101.46.120.109.108
And translating them from ASCII, you get:
http://example.com/config/console.xml
The next byte (2) is telling you that option two is next and is 53 bytes long.
Taking the next 53 bytes as decimal:
104.116.116.112.58.47.47.49.57.50.46.49.54.56.46.48.46.49.53.57.47.102.105.114.109.119.97.114.101.47.117.105.109.97.103.101.95.51.51.53.50.95.116.115.109.95.97.114.109.46.109.100.53
And translating them from ASCII, you get: http://example.com/firmware/uimage_3352_tsm_arm.md5
APPENDIX B
These System Parameters are not included by default:
Site ID
Modem Phone Number
Real Time Clock Parameters
IP Address/Gateway/Mask Addresses
DHCP
IP Security
Static Routes