You can automatically provision a network device using ZTP from a removable storage device such as a USB flash drive. The following are the configuration types available in a removable storage device:

• Device-specific configuration: The device-specific configuration is available in the folder that has a name matching the chassis serial number of the device. The sample path for the device-specific configuration is /USB-path/xr-config/serial-number/router-cfg. For example, /USB-path/xr-config/FOC2102R1D0/router-cfg FOC2102R1D0 is the chassis serial number.

• Generic configuration: The generic configuration is available in the xr-config folder. The sample path for the generic configuration is./USB-path/xr-config/router-cfg

Here is the high-level work flow of the ZTP process using a USB flash drive:

1. When you boot the device, the device verifies if the USB is enabled in the ztp.ini file. By default, the USB fetcher is enabled and assigned the highest priority.

   Fetcher defines which port ZTP should use to get the provisioning details. By default, each port has a fetcher priority defined in the ztp.ini file.

2. ZTP checks for a USB flash drive on the device If the USB drive isn't available, the ZTP process moves to the next fetcher as defined in the fetcher priority of the ZTP.ini file.

3. If a USB flash drive is available, the device scans for the xr-config file in the root of the USB mount in the following sequence:

   1. The ZTP process first scans for the router-cfg file in the folder that is matching the chassis serial number of the device within the xr-config folder and applies the device-specific configuration.

      For example, /USB-path/xr-config/FOC2102R1D0/router-cfg

   2. If the device-specific configuration with a serial number isn't available, the ZTP process scans for the router-cfg file in the xr-config folder and applies a generic configuration.

   3. If the xr-config folder isn't available, the ZTP process moves to the next fetcher as defined in the fetcher priority of the ZTP.ini file.

4. The device applies the configuration.

5. The network device is now up and running.

When you boot the device, the ZTP process initiates automatically if the device does not have a prior configuration. During the process, the router receives the details of the configuration file from the DHCP server.

This image depicts the high-level work flow of the ZTP process:

The ZTP process initiates when you boot the network-device with an IOS-XR image. The process starts only on the device that doesn't have a prior configuration.

Here is the high-level work flow of the ZTP process for the Fresh boot:

1. ZTP sends DHCP request to fetch the ZTP configuration file or user script. To help the Bootstrap server uniquely identify the device, ZTP sends below DHCP option

   • DHCP(v4/v6) client-id=Serial Number

   • DHCPv4 option 124: Vendor, Platform, Serial-Number

   • DHCPv6 option 16: Vendor, Platform, Serial-Number

   The following is the default sequential flow of the ZTP process:

   • ZTP sends IPv4 DHCP request first on all the management port. In case there is a failure, then ZTP sends IPv6 DHCP request on all the management port.

   • ZTP sends IPv4 DHCP request first on all the data port. In case there is a failure, then ZTP sends IPv6 DHCP request on all the data port.

     The default sequential flow is defined in configuration file and you can modify the sequence using the configuration file.

2. DHCP server identifies the device and responds with DHCP response using one of the following options:

   DHCP server should be configured to respond with the DHCP options.

   • DHCPv4 using BOOTP filename to supply script/config location.

   • DHCPv4 using Option 67 (bootfile-name) to supply script/config location.

   • DHCPv6 using Option 59 (OPT_BOOTFILE_URL) to supply script/config location

3. The network device downloads the file from the web server using the URI location that is provided in the DHCP response.

4. The device receives a configuration file or script file from the HTTP server.

   Note	If the downloaded file content starts with !! IOS XR it is considered as a configuration file. If the downloaded file content starts with #! /bin/bash, #! /bin/sh or #!/usr/bin/python it is considered as a script file.

5. The device applies the configuration file or executes the script or binary in the default bash shell.

6. The Network device is now up and running.

This script or binary is executed in the IOS-XR Bash shell and can be used to interact with IOS-XR CLI to configure, verify the configured state and even run exec commands based on the workflow that the operator chooses.

Build your ZTP script with either shell and python. ZTP includes a set of CLI commands and a set of shell utilities that can be used within the user script.

Note

We recommend that you do not execute the APIs on a router that is already provisioned. ZTP Utility APIs are designed to be executed from the ZTP script when you boot the router for the first time. The APIs perform additional operations to run the requested actions during the boot process and bring changes in the existing configuration before executing any action. ZTP utility APIs have prerequisites which are executed in the ZTP workflow before running the ZTP utility APIs. These prerequisites help with running specific actions during the boot process and in making necessary configuration changes. We recommend that you do not use ZTP utilities outside the scope of ZTP script. The APIs in this script use username as ztp or ztp-user in every action. The ZTP utility executed outside the scope of the ZTP script may fail as it is not executed from the ZTP workflow. This may modify the configurations on the device and affect other related operations. If the ZTP utility is executed outside the scope ZTP script, the logs display that the script is executed using username ztp or ztp-user, misleading that the script is executed from the workflow.

ZTP includes a set of shell utilities that can be sourced within the user script. ztp_helper.sh is a shell script that can be sourced by the user script. ztp_helper.sh provides simple utilities to access some XR functionalities. Following are the bash functions that can be invoked:

• xrcmd—Used to run a single XR exec command:xrcmd “show running”

• xrapply—Applies the block of configuration, specified in a file:

  
  cat >/tmp/config <<%%
  !! XR config example
  hostname node1-mgmt-via-xrapply
  %%
  xrapply /tmp/config

• xrapply_with_reason—Used to apply a block of XR configuration along with a reason for logging purpose:

  
  cat >/tmp/config <<%%
  !! XR config example
  hostname node1-mgmt-via-xrapply
  %%
  xrapply_with_reason "this is a system upgrade" /tmp/config

• xrapply_string—Used to apply a block of XR configuration in one line:

  
  xrapply_string "hostname foo\interface HundredGigE0/0/0/24\nipv4 address 1.2.3.44 255.255.255.0\n"

• xrapply_string_with_reason—Used to apply a block of XR configuration in one line along with a reason for logging purposes:

  
  xrapply_string_with_reason ”system renamed again" "hostname venus\n interface HundredGigE0/0/0/24\n ipv4 address 172.30.0.144/24\n”

• xrreplace—Used to apply XR configuration replace in XR namespace via a file.

  
  cat rtr.cfg <<%%
  !! XR config example
  hostname node1-mgmt-via-xrreplace
  %%
  xrreplace rtr.cfg

• xrapply_with_extra_auth—Used to apply XR configuration that requires authentication, in XR namespace via a file. The xrapply_with_extra_auth API is used when configurations that require additional authentication to be applied such as alias, flex groups.

  
  cat >/tmp/config <<%%
  !! XR config example
  alias exec alarms show alarms brief system active
  alias exec version run cat /etc/show_version.txt
  %%
  xrapply_with_extra_auth >/tmp/config 
  
  

• xrreplace_with_extra_auth—Used to apply XR configuration replace in XR namespace via a file The xrreplace_with_extra_auth API is used when configurations that require additional authentication to be applied such as alias, flex groups

  
  cat >/tmp/config <<%%
  !! XR config example
  alias exec alarms show alarms brief system active
  alias exec version run cat /etc/show_version.txt
  %%
  xrreplace_with_extra_auth >/tmp/config 

The ZTP python library defines a single Python class called ZtpHelpers. The helper script is located at /pkg/bin/ztp_helper.sh

[apple2:~]$ python sample_ztp_script.py 

###### Debugs enabled ######


###### Change context to user specified VRF ######


###### Using Child class method, setting the root user ######

2016-12-17 04:23:24,091 - DebugZTPLogger - DEBUG - Config File content to be applied  !
                     username netops
                     group root-lr
                     group cisco-support
                     secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1
                     !
                     end
2016-12-17 04:23:28,546 - DebugZTPLogger - DEBUG - Received exec command request: "show configuration commit changes last 1"
2016-12-17 04:23:28,546 - DebugZTPLogger - DEBUG - Response to any expected prompt ""
Building configuration...
2016-12-17 04:23:29,329 - DebugZTPLogger - DEBUG - Exec command output is ['!! IOS XR Configuration version = 6.2.1.21I', 'username netops', 'group root-lr', 'group cisco-support', 'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1', '!', 'end']
2016-12-17 04:23:29,330 - DebugZTPLogger - DEBUG - Config apply through file successful, last change = ['!! IOS XR Configuration version = 6.2.1.21I', 'username netops', 'group root-lr', 'group cisco-support', 'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1', '!', 'end']


###### Debugs Disabled ######


###### Executing a show command ######

Building configuration...
{'output': ['!! IOS XR Configuration version = 6.2.1.21I',
            '!! Last configuration change at Sat Dec 17 04:23:25 2016 by UNKNOWN',
            '!',
            'hostname customer2',
            'username root',
            'group root-lr',
            'group cisco-support',
            'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1',
            '!',
            'username noc',
            'group root-lr',
            'group cisco-support',
            'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1',
            '!',
            'username netops',
            'group root-lr',
            'group cisco-support',
            'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1',
            '!',
            'username netops2',
            'group root-lr',
            'group cisco-support',
            'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1',
            '!',
            'username netops3',
            'group root-lr',
            'group cisco-support',
            'secret 5 $1$7kTu$zjrgqbgW08vEXsYzUycXw1',
            '!',
            'cdp',
            'service cli interactive disable',
            'interface MgmtEth0/RP0/CPU0/0',
            'ipv4 address 11.11.11.59 255.255.255.0',
            '!',
            'interface TenGigE0/0/0/0/24',
            'shutdown',
            '!',
            'interface TenGigE0/0/0/0/25',
            'shutdown',
            '!',
             
            'router static',
            'address-family ipv4 unicast',
            '0.0.0.0/0 11.11.11.2',
            '!',
            '!',
            'end'],
 'status': 'success'}

###### Apply valid configuration using a file ######

Building configuration...
{'status': 'success', 'output': ['!! IOS XR Configuration version = 6.2.1.21I', 'hostname customer', 'cdp', 'end']}

###### Apply valid configuration using a string ######

Building configuration...
{'output': ['!! IOS XR Configuration version = 6.2.1.21I',
            'hostname customer2',
            'end'],
 'status': 'success'}

###### Apply invalid configuration using a string ######

{'output': ['!! SYNTAX/AUTHORIZATION ERRORS: This configuration failed due to',
            '!! one or more of the following reasons:',
            '!!  - the entered commands do not exist,',
            '!!  - the entered commands have errors in their syntax,',
            '!!  - the software packages containing the commands are not active,',