Build your Configuration File
Based on the business need, you can use a configuration or script file to initiate the ZTP process.
 Note |
When you use a USB flash drive as a source for ZTP, you cannot use the script file for provisioning. The script file is not
supported in the USB fetcher. Fetcher defines which port the ZTP process should use to get the provisioning details as defined
in the |
The configuration file content starts with !! IOS XR and the script file content starts with #! /bin/bash, #! /bin/sh or #!/usr/bin/python.
Once you create the configuration file, apply it to the device using the ztp_helper function xrapply.
The following is the sample configuration file:
!! IOS XR
username root
group root-lr
password 0 lablab
!
hostname ios
alias exec al show alarms brief system active
interface HundredGigE 0/0/0/24
ipv4 address 10.10.10.55 255.255.255.0
no shutdown
!
Create User Script
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 that 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 Shell Utilities
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. You can invoke the following bash functions:
-
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. This api internally performs authentication and authorization to gain additional privilege.
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. This api internally performs authentication and authorization to gain additional privilege.
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
API Implementation Behavior
Note |
The xrcmd ,xrapply , and xrreplace APIs or utilities carry out a series of internal operations to execute specific actions. These operations, which are performed sequentially, include:
In addition to these internal operations, the xrapply_with_extra_auth and xrreplace_with_extra_auth APIs performs an authentication process before applying configurations. |
ZTP Helper Python Library
The ZTP python library defines a single Python class called ZtpHelpers. The helper script is located at /pkg/bin/ztp_helper.sh
ZtpHelpers Class Methods
Following are utility methods of the ZtpHelpers class:
-
init(self, syslog_server=None, syslog_port=None, syslog_file=None):__init__ constructor :param syslog_server: IP address of reachable Syslog Server :param syslog_port: Port for the reachable syslog server :param syslog_file: Alternative or addon file for syslog :type syslog_server: str :type syslog_port: int :type syslog_file:str All parameters are optional. When nothing is specified during object creation, then all logs are sent to a log rotated file /tmp/ztp_python.log (max size of 1MB). -
setns(cls, fd, nstype):Class Method for setting the network namespace :param cls: Reference to the class ZtpHelpers :param fd: incoming file descriptor :param nstype: namespace type for the sentns call :type nstype: int 0 Allow any type of namespace to be joined. CLONE_NEWNET = 0x40000000 (since Linux 3.0) fd must refer to a network namespace -
get_netns_path(cls, nspath=None, nsname=None, nspid=None):Class Method to fetch the network namespace filepath associated with a PID or name :param cls: Reference to the class ZtpHelpers :param nspath: optional network namespace associated name :param nspid: optional network namespace associate PID :type nspath: str :type nspid: int :return: Return the complete file path :rtype: str -
toggle_debug(self, enable):Enable/disable debug logging :param enable: Enable/Disable flag :type enable: int -
set_vrf(self, vrfname=None):Set the VRF (network namespace) :param vrfname: Network namespace name corresponding to XR VRF -
download_file(self, file_url, destination_folder):Download a file from the specified URL :param file_url: Complete URL to download file :param destination_folder: Folder to store the downloaded file :type file_url: str :type destination_folder: str :return: Dictionary specifying download success/failure Failure => { 'status' : 'error' } Success => { 'status' : 'success', 'filename' : 'Name of downloaded file', 'folder' : 'Directory location of downloaded file'} :rtype: dict -
setup_syslog(self):Method to Correctly set sysloghandler in the correct VRF (network namespace) and point to a remote syslog Server or local file or default log-rotated log file.
-
xrcmd(self, cmd=None):Issue an IOS-XR exec command and obtain the output :param cmd: Dictionary representing the XR exec cmd and response to potential prompts { 'exec_cmd': '', 'prompt_response': '' } :type cmd: dict :return: Return a dictionary with status and output { 'status': 'error/success', 'output': '' } :rtype: dict -
xrapply(self, filename=None, reason=None):Apply Configuration to XR using a file :param file: Filepath for a config file with the following structure: ! XR config command ! end :param reason: Reason for the config commit. Will show up in the output of: "show configuration commit list detail" :type filename: str :type reason: str :return: Dictionary specifying the effect of the config change { 'status' : 'error/success', 'output': 'exec command based on status'} In case of Error: 'output' = 'show configuration failed' In case of Success: 'output' = 'show configuration commit changes last 1' :rtype: dict -
xrapply_string(self, cmd=None, reason=None):Apply Configuration to XR using a single line string :param cmd: Single line string representing an XR config command :param reason: Reason for the config commit. Will show up in the output of: "show configuration commit list detail" :type cmd: str :type reason: str :return: Dictionary specifying the effect of the config change { 'status' : 'error/success', 'output': 'exec command based on status'} In case of Error: 'output' = 'show configuration failed' In case of Success: 'output' = 'show configuration commit changes last 1' :rtype: dict -
xrreplace(self, filename=None):Replace XR Configuration using a file :param file: Filepath for a config file with the following structure: ! XR config commands ! end :type filename: str :return: Dictionary specifying the effect of the config change { 'status' : 'error/success', 'output': 'exec command based on status'} In case of Error: 'output' = 'show configuration failed' In case of Success: 'output' = 'show configuration commit changes last 1' :rtype: dict
API Implementation Behavior
Note |
The xrcmd ,xrapply , and xrreplace APIs or utilities carry out a series of internal operations to execute specific actions. These operations, which are performed sequentially, include:
|
Example
The following shows the sample script in phyton
[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,',
For information on helper APIs, see https://github.com/ios-xr/iosxr-ztp-python#iosxr-ztp-python.
Feedback