Zero-Touch Provisioning

Zero-touch Provisioning (ZTP) automates the initial configuration of switch systems at boot time. It helps minimize manual operation and reduce customer initial deployment costs. ZTP allows for automatic upgrade of the switch with a specified OS image, setting up a switch configuration, and checking connectivity to external resources.

A switch configuration is applied by using either of the following two formats: YAML format file configuration or CLI commands in the regular text file.

The user can create a YAML configuration file by saving the running configuration by “nv config save” and later uploading that file to an external provisioning server.

The textual configuration file can be created by running “nv config show -o commands” and pasting the output to the text file. That text file can be edited later to add more commands or replace the ones in the list.

There is no explicit command to enable ZTP. It is enabled by default. Disabling it is performed by a user-initiated configuration save (using the command “nv config save”). There are two ways to re-enable ZTP. The first one is to run a “reset factory” command, clearing the configuration of the switch and rebooting the system. The second one is to run “nv action run system ztp” which will just remove the startup configuration and restart ZTP. It is encouraged to run the “reset factory” command.

ZTP is based on DHCP. For ZTP to work, the software enables DHCP by default on all its management interfaces. The switch OS requests option 66 (tftp-server-name) and/or 67 (bootfile-name) from the DHCPv4 server or option 59 (bootfile-url) from the DHCPv6 server and waits for the DHCP responses containing the ZTP JSON configuration file URL. See ZTP Configuration File section for more information.

The DHCP server must be configured to send back the URL to the ZTP configuration file. For DHCPv4 there are two options supported: Option 66 and Option 67. Providing both options by DHCP server will result in combining them to build TFTP ULR to ZTP configuration file. When using Option 66 the TFTP protocol prefix is omitted. Providing only Option 67 will be considered as URL to the location of the ZTP configuration file.

For DHCPv6, the only option supported is Option 67. It will contain the complete URL to the ZTP JSON configuration file. The format of all the options is a string. Below is a summary table:

Examples of Options for DHCPv4:

            

            
option tftp-server-name "198.51.100.8"; 
option bootfile-name "ztp.json"; 
        

Example of only Option 67 for DHCPv4:

            

            
option bootfile-name "scp://<user>:<pass>@198.51.100.8/ztp.json"; 
        

Example of only Option 67 for DHCPv6:

            

            
option dhcp6.bootfile-url "http://[2001:db8::8]/ztp.json"; 
        

When a switch requests a file specified by a URL, it is expected that the server which is handling the request knows which file to be returned. For example, when a switch requests for configuration file, the server needs to be able to give out a configuration file for the requesting switch. This selection of the file can be done in two ways:

• Provisioning Server side: DHCP Options, HTTP Headers

• ZTP Client side: Dynamic URL (see ZTP Configuration File Section)

DHCP Options

To have the DHCP server discern the proper files based on switch-specific information, the NOS must provide identifying information for the server to classify the switches. NOS provides the following identifying information:

• Product Name—Option 61

• Serial Number—Option 61

• Vendor Class Identifier—Option 77 (Option 15 for DHCPv6)

Upon receiving such DHCP requests from a client, the server should be able to map the switch-specific information to the target file URLs according to predefined rules.

The following are the DHCP options sent by the NVOS switch in the DHCP request:

HTTP Headers

For a server to make the decision on which file to serve out, it requires uniquely identifiable information about the requesting switch. Then, appropriate logic can be implemented on the server side to process the provided information, and identify and give out the requested file.

All HTTP/HTTPS requests made during ZTP contain switch identification information as part of HTTP headers. Below is the information that is included.

For ZTP to automate the provisioning process a user needs to provide a JSON configuration file. The ZTP JSON configuration file consists of configuration sections (objects). Each section has its own options. In other words, ZTP JSON configuration file is an instruction on how to perform provisioning and from where to get provisioning data. Here is an example of the ZTP JSON configuration file:

            

            
{ 
  "ztp": { 
    "01-image": { 
      "install": { 
        "url": "http://198.51.100.2/images/nvos.bin" 
      }, 
      "uninstall": true 
    }, 
    "02-commands-list": { 
      "url": "sftp://user:password@198.51.100.3/configs/commands.txt", 
      "clear-config": "true" 
    }, 
    "03-startup-file": { 
      "url": "scp://user:password@198.51.100.4/configs/config.yaml", 
      "clear-config": false 
    }, 
    "04-connectivity-check": { 
      "ping-hosts": [ "198.51.100.5", "localhost" ]
      "ping-count": 10, 
      "ignore-result": true 
    } 
  } 
} 
        

The main section is “ztp” and it must always be present in the ZTP JSON configuration file. Inside the main section may have the following configuration sections:

• image—to manage system images on the switch

• commands-list—to apply CLI commands in textual form

• startup-file—to apply YAML formatted configuration

• connectivity-check—to check a connectivity to predefined location

The configuration sections are processed by ZTP software in lexical order so to control the order of execution, a “xx-“ prefix to the section names is allowed (e.g., 02-commands-list).

Each configuration section of ZTP JSON includes some common parameters that can be used to influence its execution. The default value for a parameter is assumed when the parameter is not specified in the configuration section:

• description: Optional free-form text string used to describe a configuration section defined in the ZTP JSON configuration file.

• ignore-result (default: false):

  • true—ZTP service marks status as SUCCESS even if an error is encountered while processing this individual section.

  • false—ZTP service marks status as FAILED if an error is encountered while processing this individual section.

• halt-on-failure (default: false):

  • true—If configuration section result is FAILED, ZTP service stops and exits immediately marking ZTP status as FAILED. No other configuration sections are processed. User intervention is needed to restart ZTP.

  • false—ZTP service moves on to next configuration section.

• restart-ztp-on-failure (default: true):

  • true—ZTP procedure is restarted if the result of ZTP is FAILED after processing all of the configuration sections defined in the ZTP JSON configuration file. This happens up to 10 times.

  • false—ZTP service exits after processing all of the configuration sections defined in the ZTP JSON configuration file.

And the main “ztp” section has its own parameter:

• restart-ztp-no-config (default: false):

  • true—ZTP procedure is restarted if switch startup configuration file is not present after the completion of processing the configuration sections defined in the ZTP JSON configuration file. This happens up to 10 times.

  • false—ZTP service exits after processing all of the configuration sections defined in the ZTP JSON configuration file even if the Switch startup configuration file is not present.

ZTP service exits and marks the status as FAILED if any errors are encountered while parsing the ZTP JSON configuration file. It is encouraged to check for any JSON format correctness before rolling out the ZTP JSON configuration file for use. When processing a configuration section and provided data is found to be insufficient, it is marked as failed and ZTP moves on to the next section.

ZTP Configuration Section: image

The image configuration section is used for image management on a switch. It can be used to install and uninstall system images.

Example config section to install a new image and boot into it:

            

            
"image": { 
    "install": { 
        "url": "http://198.51.100.2/images/nvos.bin", 
        "skip-reboot ": false 
    } 
} 
Example config section to uninstall a NVOS image from the Switch: 
"image": { 
    "uninstall": true 
} 
        

Following is the list of parameters supported in image configuration section and their brief description with a default values. The default value for a parameter is assumed when the parameter is not used:

• install—Used to install an image using URL.

  • url/dynamic-url—Specifies the URL string from where the system image file has to be downloaded in the form of url or dynamic-url object.

  • skip-reboot (default: false)—Specifies if a switch reboot operation is performed immediately after installing a new switch image. Reboot is skipped when set to true.

• uninstall (default: false)—Used to uninstall an existing image on the disk.

  • true—Uninstall the image from the second partition.

  • false—Do nothing.

ZTP Configuration Section: startup-file

The startup-file configuration section is used to apply the switch configuration in form of YAML file and apply the configuration. The YAML file format of the configuration is the same as switch startup configuration file. Here is an example of startup-file configuration section:

            

            
"startup-file": { 
    "url": "http://198.51.100.3/startup.yaml", 
    "clear-config": true, 
    "save-config": true 
} 
        

Following is the list of parameters supported by the startup-file configuration section:

• url/dynamic-url—Define the URL string from where the startup.yaml file has to be downloaded in the form of url or dynamic-url object.

• clear-config (default: true)—Use this to specify if the existing configuration has to be cleared before loading the download startup.yaml file content . When set to true, ZTP replaces all current configuration with startup.yaml file content. When set to false it merges the configurations.

• save-config (default: false)—Use this to perform config save command after loading the downloaded startup.yaml file.

ZTP Config Section: commands-list

The commands-list configuration section is used to apply switch configuration in form of CLI text commands. The list of commands is provided in text file which should be downloaded and applied. Commands' file must contain only non-interactive commands, otherwise it will fail entire commands-list section. It is user responsibility to make sure commands are non-interactive, for example user should provide “force / -y / -n” or similar flags to the interactive CLI to prevent AYS (Are You Sure?) questions.

Example of commands-list configuration section:

            

            
"commands-list": { 
    "url": "http://198.51.100.4/commands.txt", 
    "clear-config": true, 
    "save-config": true 
} 
        

Following is the list of parameters supported by the commands-list configuration section:

• url/dynamic-url—Define the URL string from where the commands-list file has to be downloaded in the form of url object or dynamic-url object.

• clear-config (default: true)—Use this to specify if the existing configuration has to be cleared before applying file content. If true, it applies empty (default) configuration prior executing commands.

• save-config (default: false)—Use this to perform a config save command after applying downloaded commands list.

ZTP Config Section: connectivity-check

The connectivity-check section is used to ping a remote host and verify if the switch is able to reach the remote host. It is possible to ping multiple hosts and the plugin result is marked as failed even if ping to one of the specified host fails.

            

            
"connectivity-check": { 
    "ping-hosts": [ "198.51.100.5", "localhost" ] 
} 
        

Following is the list of objects supported by the connectivity-check section:

• ping-hosts—List of IPv4 hosts to ping.

• ping6-hosts—List of IPv6 hosts to ping.

• retry-interval (default: 5)—Specify a timeout, in seconds, before retrying ping to a host.

• retry-count (default: 12)—Stop ping to a host and move on to the next host specified in the list after retrying specified count of times.

• ping-count (default: 3)—Stop after sending count ECHO_REQUEST packets. With deadline option, ping waits for count ECHO_REPLY packets, until the timeout expires.

• deadline (default: N/A)—Specify a timeout, in seconds, before ping exits regardless of how many packets have been sent or received. In this case ping does not stop after count packet are sent, it waits either for deadline expire or until count probes are answered or for some error notification from network.

• timeout (default: N/A)—Time to wait for a response, in seconds. The option affects only timeout in absence of any responses, otherwise ping waits for two RTTs (Round Trip Time).

Software upgrade from non-ZTP versions to ZTP versions and vice versa is supported. When upgrading from a non-ZTP version, ZTP is disabled because ZTP is always assumed to start with an empty configuration.

DHCPv4 Configuration

The following is a configuration example for ISC DHCPv4 server:

            

            
host master { 
    hardware ethernet 12:34:56:AB:CD:EF; 
    fixed-address 192.51.100.201; 
    option bootfile-name "scp://<user>:<password>@192.51.100.8/ztp.json"; 
} 
        

DHCPv6 Configuration

The following is a DHCPv6 configuration example:

            

            
host master { 
    ........ 
    option dhcp6.bootfile-url "http://[2001:db8::8]/ztp.json"; 
} 
        

ZTP Configuration File Example

            

            
{ 
  "ztp": { 
    "01-image": { 
      "uninstall": true 
    }, 
    "02-commands-list": { 
      "url": "sftp://user:password@198.51.100.3/configs/commands.txt", 
      "clear-config": "true" 
    }, 
    "03-startup-file": { 
      "url": "scp://user:password@198.51.100.4/configs/config.yaml" 
    }, 
    "04-connectivity-check": { 
      "ping-hosts": [ "198.51.100.5", "localhost" ], 
    } 
  } 
} 
        

Commands List Example

            

            
# Disable password hardening 
nv set system security password-hardening state disabled 
 
# Configure log rotation rules 
nv set system log rotation frequency weekly 
 
# Configure system message 
nv set system message pre-login Hello 
 
# Applying config 
nv config apply -y 
        

YAML Formatted File Configuration

            

            
- set: 
    system: 
      log: 
        rotation: 
          size: 30.0 
      ntp: 
        dhcp: disabled 
        server: 
          localntpserver: {} 
          ua.pool.ntp.org: 
            association-type: pool 
      security: 
        password-hardening: 
          state: disabled 
        

nv show system ztp

            

            
admin@nvos:~$ nv show system ztp 
             operational        applied 
-----------  -----------------  -------- 
runtime      31s 
service      inactive 
source       dhcp-opt67 (eth0) 
state        enabled 
status       success 
config-save  disabled           disabled 
 
 
ZTP stages 
============= 
    Stage             Exit Status  Ignore Result  Runtime  Status 
    ----------------  -----------  -------------  -------  ------- 
    02-startup-file   success      no             09s      success 
    03-commands-list  success      no             18s      success
 
 
 
 
admin@nvos:~$ nv show system ztp 
             operational       applied 
-----------  ----------------  -------- 
runtime      05m 08s 
service      active-discovery 
state        enabled 
status       not-started 
config-save  disabled          disabled 
 
 
ZTP stages 
============= 
No Data
        

nv set system ztp config-save

            

            
admin@nvos:~$ nv set system ztp config-save enabled 
admin@nvos:~$ nv config apply 
admin@nvos:~$ nv config save 
        

nv action system ztp

            

            
admin@nvos:~$ nv action abort system ztp 
The operation will perform abort of the ZTP. 
Type [y] to perform abort of the ZTP. 
Type [N] to cancel an action. 
 
Do you want to continue? [y/N] y 
Action executing ... 
Aborting ZTP session 
Action executing ... 
Action succeeded
 
admin@nvos:~$ nv action run system ztp 
The operation will perform rerun of the ZTP. 
Type [y] to perform rerun of the ZTP. 
Type [N] to cancel an action. 
 
Do you want to continue? [y/N] y 
Action executing ... 
Rerunning ZTP session 
Action executing ... 
Action succeeded