A software image is a file containing the installable network operating system software (such as Cisco IOS-XR or, for PnP ZTP, Cisco IOS-XE) that enables a network device to function.

Software image loading is optional for all ZTP modes, although it is required if the device you are onboarding has no software image installed. You are not required to apply a software image to a device that is already imaged. You can also apply configuration files to a device without loading an image. Loading images is required only when the device you want to onboard does not have an image installed on it, or when you want to upgrade the network OS at the same time you onboard the device.

Cisco distributes IOS-XR images as TAR, ISO, BIN, or RPM files. Cisco distributes IOS-XE images as BIN files only. Each Cisco image file represents a single release of the given network OS for a given device platform or family.

Download software image files from the Cisco Support & Downloads page. During the download, record the image's MD5 checksum. You can also generate your own MD5 checksum for an image you want to upload. Cisco Crosswork uses the MD5 checksum to validate the integrity of the software image file.

Load software image files to Cisco Crosswork one at a time, and enter the MD5 checksum for each software image file during the load.

To load software images to Cisco Crosswork:

1. Launch Cisco Crosswork.

2. From the main menu, select Device Management > Software Images

3. Click the

4. Enter, or click Browse and select, the software image file you want to upload. When prompted, enter the MD5 checksum for the file.

5. Click Add to finish adding the software image file.

6. Repeat as needed until you have loaded all the software image files to be used in the planned ZTP run.

Configuration files are script files that configure the features of the installed software image on a given device. They are required for all ZTP modes.

Configuration files used with Classic and Secure ZTP modes can be Linux shell scripts (SH), Python scripts (PY), or device operating system CLI commands stored in an ASCII text file (TXT). For Cisco IOS-XR devices and with Classic or Secure ZTP only, you can also use configuration files to upgrade an installed network OS software version using an SMU (see Find and Load SMUs).

Classic ZTP supports only one day-zero configuration file per device. Secure ZTP allows you to apply up to three configuration files during onboarding: one for pre-configuration preparation, a second that is the day-zero or main configuration, and a third post-configuration file to be applied after the day-zero configuration is complete. Only the day-zero configuration is required. The order of application is fixed.

Cisco PnP ZTP supports only day-zero configuration TXT files on Cisco ASR 900 and Cisco NCS 520 devices. Your PnP ZTP configuration files must use IOS-XE CLI commands. PnP ZTP does not support Linux shell (SH) or Python (PY) script files.

Upload configuration files to Cisco Crosswork one at a time.

Your organization or consultants create configuration files. The following sections provide guidelines for preparing configuration files for use when onboarding devices using any of the ZTP modes, as well as how to load these files into Cisco Crosswork.

Download the Sample Configuration File

The contents of your configuration script file will vary greatly, depending on the devices you use and how your organization uses them. A complete description of all the options available to you is therefore beyond the scope of this document.

The main guidelines to remember are:

1. Your custom configuration code can use both default and custom replaceable (or "placeholder") parameters. This allows you to insert values at runtime using the Configuration Attributes field when importing device entries in bulk or creating them one at a time.

2. You can create new, custom replaceable parameters as needed. You can name them anything you like, as long as they do not use the same names as the default parameters and follow the variable naming conventions discussed in this topic. If you do use the default replaceable parameters, their runtime values will be inserted from the sources described in the the "Use Default Replaceable Parameters in Configuration Files" section of this topic, instead of the values you set in the device entry's Configuration Attributes field.

3. Replaceable parameter names are case-sensitive, and must include the braces and dollar sign. They must not include spaces (use underscores instead).

4. Be sure all of your custom replaceable parameters have a runtime value specified in the Configuration Attributes field. If you fail to specify a runtime value for even one of your custom replaceable parameters, the device configuration process will fail.

5. If you’re using Secure ZTP, you can use custom replaceable parameters for the day-zero configuration only. Custom replaceable parameters are not supported for pre-configuration and post-configuration files.

6. Your configurations must use Cisco Crosswork API calls to complete some tasks. In particular, the code must use API calls to notify the Cisco Crosswork server when the device transitions from one ZTP state to another. .

7. While any configuration file can call another configuration file and run it (if it can be successfully downloaded to the device), only Secure ZTP lets you specify separate pre-configuration, post-configuration, and day-zero configuration files as part of the initial, secure download.

8. Configuration file names cannot contain more than one period, and must use underscores in place of spaces. Additional file restrictions are noted in the sample configuration file discussed below.

For examples of how to use the replaceable parameters and API calls, see the sample ZTP configuration file for Cisco IOS-XR devices supplied with the Cisco Crosswork ZTP application. To download the sample ZTP configuration file from Cisco Crosswork, select Device Management > ZTP Configuration Files, then click Download Sample Script (XR). The sample configuration script is commented and provides examples of the more commonly used API calls and replaceable parameters.

For more details on replaceable parameters, see the following sections, "Use Default Replaceable Parameters in Configuration Files", and "Use Custom Replaceable Parameters in Configuration Files".

For more details on Crosswork API calls, see the section on ZTP device and configuration APIs in the "Crosswork API References" menu, available on the Cisco Developer Network (DevNet) site for Cisco Crosswork.

The following section "Sample ZTP Configuration Scripts" provides examples of how to use replaceable parameters and APIs.

Preview Configuration Files

To preview the contents of any configuration file previously uploaded to Cisco Crosswork, select Device Management > ZTP Configuration Files, then click the configuration file name. The pop-up preview includes code syntax styling for important code features, as shown in the following table.

Use Default Replaceable Parameters in Configuration Files

The following table lists the default replaceable parameters you can use in your custom configuration files. At runtime, for each of these placeholders, Cisco Crosswork substitutes the appropriate values for each device. For an example of the use of these placeholders, download the sample configuration script from Cisco Crosswork: Device Management > ZTP Configuration Files > Download Sample Script (XR). For examples showing how to use these default replaceable parameters, see the section later in this topic, "Sample ZTP Configuration Scripts".

Use Custom Replaceable Parameters in Configuration Files

You can create your own custom replaceable parameters in configuration files, as shown in the following sample. You can use custom and default replaceable parameters in the same configuration file, as shown in the sample.

You can assign any name you want to a custom replaceable parameter, so long as you:

• Follow the given variable definition format (for example, {$MyParm})

• Substitute an underline character in place of spaces in the parameter name.

• Don't re-use the same names and capitalization as any of the default replaceable parameters.

• Supply values for each of your custom parameters in the Configuration Attributes field in the device entry file. To use the following sample CLI configuration file and its custom parameters with a ZTP device entry file, you would need to specify a value for the {$LOOPBACK0_IP} custom parameter in each device's Configuration Attributes field in the ZTP device entry file. If you forget to specify values for any custom parameter, the configuration will fail.

If you’re using Secure ZTP, custom replaceable parameters are supported for the day-zero configuration file only.

The first line in this sample script is required in CLI scripts for IOS-XR devices. It allows ZTP to verify whether the file is a CLI script or bash/Python script. Be sure to update the version number as appropriate. No such line is required for IOS-XE devices.

!! IOS XR Configuration 7.3.1
!
hostname {$HOSTNAME}
username {$SSH_USERNAME}
 group root-lr
 group cisco-support
 password 0 {$SSH_PASSWORD}
!
cdp
!
line console
exec-timeout 0 0
!
line default
exec-timeout 0 0
session-timeout 120
!

call-home
 service active
 contact smart-licensing
 profile CiscoTAC-1
  active
  destination transport-method http
 !
!
interface Loopback0
 ipv4 address {$LOOPBACK0_IP} 255.255.255.255
!
interface MgmtEth0/RP0/CPU0/0
 description OOB Management ZTP
 ipv4 address {$IP_ADDRESS}
!     
end

Sample ZTP Configuration Scripts

This section provides examples of configuration scripts for ZTP.

#!/bin/bash

#################################################################################
#
# ztpSampleScriptFile.sh
#
# Purpose: This sample script is required to notify Crosswork of the status of
# ZTP processing on an IOS XR device, and to update the device's IP address and
# hostname in Crosswork. It is also used to download a day0 config file from
# Crosswork config repository and apply this initial configuration to the device.
#
# To use: Modify the sample script as needed, following the comment guidance.
# Then upload the modified script to the Crosswork config repository.
# Next, copy the URL of this file from the repository and set that
# value in the DHCP server boot filename for ZTP config download. When ZTP is
# triggered on the device, it will download and run the script, then notify
# Crosswork.
#
# Replace the following variables with valid values & upload to Crosswork config
# repository. Sample values are provided for reference.
# - XRZTP_INTERFACE_NAME: e.g., MgmtEth0/RP0/CPU0/0 interface where ZTP triggered
# - CW_HOST_IP: Crosswork VM management or data network IP address
# - CW_PORT: 30604 for HTTP & 30603 only for HTTPS download of config file
# - CW_CONFIG_UUID: Replace with UUID of day0 config file from Crosswork repo,
#   assuming user has already uploaded device day-0 config file.
#
# This script has been tested and is known to work on Cisco NCS5501, NCS540l,
# ASR9901, and 8800 routers.
#
#################################################################################


export LOGFILE=/disk0:/ztp/customer/user-script.log

XRZTP_INTERFACE_NAME="MgmtEth0/RP0/CPU0/0"
# ZTP helper library is assumed to be installed in IOS-XR linux shell
source /pkg/bin/ztp_helper.sh
interfacedata=$(xrcmd "show interface ${XRZTP_INTERFACE_NAME}")

CW_HOST_IP="<EnterIPv4AddressHere>"
CW_PORT="30604"
CW_CONFIG_UUID="e04661f8-0169-4ad3-82b8-a7c26c4f2565"

# Send logging information to log file on device disk0:/ztp/user-script.log
function ztp_log() {

    echo "$(date +"%b %d %H:%M:%S") "$1 >> $LOGFILE
}

#
# Get chassis serial number of the device, required by ZTP process.
# This works on Cisco NCS5501, NCS540l, 8800 series routers.
#
function get_serialkey(){

    local sn=$(dmidecode | grep -m 1 "Serial Number:" | awk '{print $NF}');
    if [ "$sn" != "Not found" ]; then
           ztp_log "Serial $sn found.";
           # The value of $sn from dmidecode should be same as serial number
           # of XR device chassis.
           DEVNAME=$sn;
           return 0
    else
        ztp_log "Serial $sn not found.";
        return 1
    fi
}

#
# Get chassis serial number of the device, required by ZTP process.
# This is tested and works on Cisco ASR 9901, but not other devices.
#
function get_serialkey_asr9901(){

     udi=$(xrcmd "show license udi")
     sn="$(cut -d':' -f4 <<<"$udi")"
     pid="$(cut -d':' -f3 <<<"$udi")"
     pid="$(cut -d',' -f1 <<<"$pid")"
     echo "Serial Number $sn"
     echo "product id $pid"
}

#
# Get IP address and subnet mask from device. IP address is assigned from DHCP
# server on interface where ZTP was triggered.
#
function get_ipaddress(){

    local ipvar=($(echo $interfacedata | awk -F "Internet address is " '{sub(/ .*/,"",$2);print $2}'));
    local ipv4addr=$(xrcmd "sh run interface ${XRZTP_INTERFACE_NAME} | i ipv4 address" | awk '{print $3}')
    local ipv6addr=$(xrcmd "sh run interface ${XRZTP_INTERFACE_NAME} | i ipv6 address" | awk '{print $3}')
    local ipaddress=($(echo $ipvar | awk -F "/" '{sub(/ .*/,"",$1);print $1}'));
    local mask=($(echo $ipvar | awk -F "/" '{sub(/ .*/,"",$2);print $2}'));
    local maskv6=($(echo $ipv6addr | awk -F "/" '{sub(/ .*/,"",$2);print $2}'));

    ztp_log "### Value of interfacedata => $interfacedata ###"
    ztp_log "### Value of ipvar => $ipvar ###"
    ztp_log "#####IPv4 address $ipaddress and mask $mask found. #####";

    IPADDR=$ipaddress
    MASK=$mask
    MASKV6=$maskv6

    return 0
}

#
# Fetch hostname from device configuration.
#
function get_hostname(){

    hostnamedata=$(xrcmd "show running-config hostname")
    local hostname=($(echo $hostnamedata | awk -F "hostname " '{sub(/ .*/,"",$2);print $2}'));

    ztp_log "#####hostname $hostname found.";
    HOSTNAME=$hostname;
    return 0;
}

#
# Download day-0 config file from Crosswork config repository using values
# set for CW_HOST_IP, CW_PORT and CW_CONFIG_UUID.
# The MESSAGE variable is optional, can be used to display a suitable message
# based on the ZTP success/failure log.
#
function download_config(){

    ztp_log "### Downloading system configuration ::: ${DEVNAME} ###";
    ztp_log "### ip address passed value ::: ${IPADDR} ###";
    ip netns exec global-vrf /usr/bin/curl -k --connect-timeout 60 -L -v --max-filesize 104857600 http://${CW_HOST_IP}:${CW_PORT}/crosswork/configsvc/v1/configs/device/files/${CW_CONFIG_UUID} -H X-cisco-serial*:${DEVNAME} -H X-cisco-arch*:x86_64 -H X-cisco-uuid*: -H X-cisco-oper*:exr-config -o /disk0:/ztp/customer/downloaded-config 2>&1

    if [[ "$?" != 0 ]]; then
        STATUS="ProvisioningError"
        ztp_log "### status::: ${STATUS} ###"
        ztp_log "### Error downloading system configuration, please review the log ###"
        MESSAGE="Error downloading system configuration"
    else
        STATUS="Provisioned"
        ztp_log "### status::: ${STATUS} ###"
        ztp_log "### Downloading system configuration complete ###"
        MESSAGE="Downloading system configuration complete"
    fi
}

#
# Apply downloaded configuration to the device and derive ZTP status based on
# success/failure of ZTP process. The MESSAGE variable is optional, can be used
# to display a suitable message based on the ZTP success/failure log.
#
function apply_config(){
    ztp_log "### Applying initial system configuration ###";
    xrapply_with_reason "Initial ZTP configuration" /disk0:/ztp/customer/downloaded-config 2>&1 >> $LOGFILE;
    ztp_log "### Checking for errors ###";
    local config_status=$(xrcmd "show configuration failed");
    if [[ $config_status ]]; then
        echo $config_status  >> $LOGFILE
        STATUS="ProvisioningError"
        ztp_log "### status::: ${STATUS} ###"
        ztp_log "!!! Error encountered applying configuration file, please review the log !!!!";
        MESSAGE="Error encountered applying configuration file, ZTP process failed"
    else
       STATUS="Provisioned"
       ztp_log "### status::: ${STATUS} ###"
       ztp_log "### Applying system configuration complete ###";
       MESSAGE="Applying system configuration complete, ZTP process completed"
   fi
}

#
# Call Crosswork ZTP API to update device ZTP status, IP address, hostname.
# Without this function, device status will remain in "In Progress" and not
# be updated in Crosswork.
#
# Using this API, device SSH/SNMP connectivity details can also be updated.
# Values for connectivity details values can be added as part of
# "connectivityDetails" array in below curl command. Sample snippet provided:
#
#   "connectivityDetails": [{
#     "protocol": "SSH",
#     "inetAddr": [{
#       "inetAddressFamily": "IPV4/IPV6",
#       "ipaddrs": "<ssh/snmp ipaddress>",
#       "mask": <ipaddress mask(Integer).>,
#       "type": "CONNECTIVITYINFO"
#     }],
#     "port": <ssh/snmp port(Integer)>,
#     "timeout": <ssh/snmp timeout(Integer). default to 60sec>
#   }]
#
function update_device_status() {

     echo "'"$IPADDR"'"
     echo "'"$MASK"'"
     echo "'"$DEVNAME"'"
     echo "'"$STATUS"'"
     echo "'"$HOSTNAME"'"
     echo "'"$MESSAGE"'"


    curl -d '{
       "ipAddress":{
            "inetAddressFamily": "IPV4",
            "ipaddrs": "'"$IPADDR"'",
            "mask":  '$MASK'
        },
       "serialNumber":"'"$DEVNAME"'",
       "status":"'"$STATUS"'",
       "hostName":"'"$HOSTNAME"'",
       "message":"'"$MESSAGE"'"
   }' -H "Content-Type: application/json" -X PATCH http://${CW_HOST_IP}:${CW_PORT}/crosswork/ztp/v1/deviceinfo/status
}


# ==== Script entry point ====
STATUS="InProgress"
get_serialkey;
#get_serialkey_asr9901; // For Cisco ASR9901, replace get_serialkey with get_serialkey_asr9901.
ztp_log "Hello from ${DEVNAME} !!!";
get_ipaddress;
ztp_log "Starting autoprovision process...";
download_config;
apply_config;
get_hostname;
update_device_status;

ztp_log "Autoprovision complete...";
exit 0

!! IOS XR
!
hostname ztpdevice1
!
interface MgmtEth0/RP0/CPU0/0
 ipv4 address dhcp
!

!! IOS XR
!
hostname {$hname}
!
interface MgmtEth0/RP0/CPU0/0
 ipv4 address {$mgmt_ipaddr} {$mgmt_subnet_mask}
!

#!/bin/bash

#################################################################################
#
#SZTP post script to update hostname and ipaddress for the device
# input -  serial key and crosswork host and port
# 
#################################################################################


export LOGFILE=/disk0:/ztp/customer/user-script.log

XRZTP_INTERFACE_NAME="MgmtEth0/RP0/CPU0/0"
# ZTP helper library is assumed to be installed in IOS-XR linux shell
source /pkg/bin/ztp_helper.sh
interfacedata=$(xrcmd "show interface ${XRZTP_INTERFACE_NAME}")

CW_HOST_IP="<EnterIPv4AddressHere>"   #update from the post script prepare code
CW_PORT="30603"           #update from the post script prepare code


# Send logging information to log file on device disk0:/ztp/user-script.log
function ztp_log() {

    echo "$(date +"%b %d %H:%M:%S") "$1 >> $LOGFILE
}


# 
# Get IP address and subnet mask from device. IP address is assigned from DHCP 
# server on interface where ZTP was triggered.
#
function get_ipaddress(){

    local ipvar=($(echo $interfacedata | awk -F "Internet address is " '{sub(/ .*/,"",$2);print $2}'));
    local ipv4addr=$(xrcmd "sh run interface ${XRZTP_INTERFACE_NAME} | i ipv4 address" | awk '{print $3}')
    local ipv6addr=$(xrcmd "sh run interface ${XRZTP_INTERFACE_NAME} | i ipv6 address" | awk '{print $3}')
    local ipaddress=($(echo $ipvar | awk -F "/" '{sub(/ .*/,"",$1);print $1}'));
    local mask=($(echo $ipvar | awk -F "/" '{sub(/ .*/,"",$2);print $2}'));
    local maskv6=($(echo $ipv6addr | awk -F "/" '{sub(/ .*/,"",$2);print $2}'));

    ztp_log "### Value of interfacedata => $interfacedata ###"
    ztp_log "### Value of ipvar => $ipvar ###"
    ztp_log "#####IPv4 address $ipaddress and mask $mask found. #####";

    IPADDR=$ipaddress
    MASK=$mask
    MASKV6=$maskv6

    return 0
}

#
# Fetch hostname from device configuration.
#
function get_hostname(){

    hostnamedata=$(xrcmd "show running-config hostname")
    local hostname=($(echo $hostnamedata | awk -F "hostname " '{sub(/ .*/,"",$2);print $2}'));

    ztp_log "#####hostname $hostname found.";
    HOSTNAME=$hostname;
    return 0;
}



# 
# Call Crosswork ZTP API to update device ZTP status, IP address, hostname.
# Without this function, device status will remain in "In Progress" and not 
# be updated in Crosswork.
#
# Using this API, device SSH/SNMP connectivity details can also be updated.
# Values for connectivity details values can be added as part of 
# "connectivityDetails" array in below curl command. Sample snippet provided:
#
#   "connectivityDetails": [{
#     "protocol": "SSH",
#     "inetAddr": [{
#       "inetAddressFamily": "IPV4/IPV6",
#       "ipaddrs": "<ssh/snmp ipaddress>",
#       "mask": <ipaddress mask(Integer).>,
#       "type": "CONNECTIVITYINFO"
#     }],
#     "port": <ssh/snmp port(Integer)>,
#     "timeout": <ssh/snmp timeout(Integer). default to 60sec>
#   }]
#
function update_device_status() {

     echo "'"$IPADDR"'"
     echo "'"$MASK"'"
     echo "'"$SERIAL_KEY"'"
     echo "'"$HOSTNAME"'"


    curl -d '{
       "ipAddress":{
            "inetAddressFamily": "IPV4",
            "ipaddrs": "'"$IPADDR"'",
            "mask":  '$MASK'
        },
       "serialNumber":"'"$SERIAL_KEY"'", 
       "hostName":"'"$HOSTNAME"'",
       "message":"Post config script updated succssfully"
   }' -H "Content-Type: application/json" -X PATCH http://${CW_HOST_IP}:${CW_PORT}/crosswork/ztp/v1/deviceinfo/status
}

function get_sudi_serial() {
   local rp_card_num=`ip netns exec xrnns /pkg/bin/show_platform_sysdb | grep Active  | cut -d ' ' -f 1`
   echo $rp_card_num
   xrcmd "show platform security tam all location $rp_card_num" > tamfile.txt
   local sudi_serial=$(sed -n -e '/Device Serial Number/ s/.*\- *//p' tamfile.txt)
   echo $sudi_serial
   SERIAL_KEY=$sudi_serial
   return 0
}

function ztp_disable()
{
	xrcmd "ztp disable noprompt"
}

function ztp_enable()
{
	xrcmd "ztp enable noprompt"
}

# ==== Script entry point ====
get_sudi_serial;
ztp_log "Hello from ${SERIAL_KEY} !!!";
get_ipaddress;
get_hostname;
update_device_status;

ztp_log "Autoprovision complete...";
ztp_log "Disabling secure mod"
ztp_disable;
exit 0

Load Configuration Files

To load configuration files to Cisco Crosswork:

1. Launch Cisco Crosswork.

2. From the main menu, select Device Management > ZTP Configuration Files.

3. Click the

4. Click Browse to select a configuration file.

5. Enter the required configuration information:

   If you’re using Secure ZTP, use the Type dropdown to specify whether the configuration file you are adding is a Pre-config, Day0-config, or Post-config.

   For Classic and PnP ZTP, always select Day0-config he Type dropdown.

6. Click Add to finish adding the configuration file.

7. Repeat as needed until you have loaded all the configuration files to be used in the planned ZTP run.

A Software Maintenance Update (SMU) is a Cisco software package file that provides point fixes for critical issues in a given release of a Cisco network operating system software image. Cisco distributes SMUs in nonbootable format with a readme.txt file explaining the issues associated with the SMU. Cisco rolls SMU contents into the next maintenance release of a software image.

Applying an SMU to a device during ZTP onboarding is supported for Classic and Secure ZTP only, and then only during application of a configuration file (see Prepare and Load Configuration Files). SMUs are not supported for Cisco IOS-XE devices or for PnP ZTP.

As with software images, download SMU files from the Cisco Support & Downloads page. During the download, record the SMU file's MD5 checksum. Cisco Crosswork uses the MD5 checksum to validate the integrity of the SMU file. Load SMUs to Cisco Crosswork one at a time, and enter the MD5 checksum for each SMU file during the load.

To load SMUs to Cisco Crosswork:

1. Launch Cisco Crosswork.

2. From the main menu, select Device Management > Software Images

3. Click the

4. Enter, or click Browse and select, the SMU file you want to upload. When prompted, enter the MD5 checksum for the file.

5. Click Add to finish adding the SMU.

6. Repeat as needed until you have loaded all the SMU files to be used in the planned ZTP run.

Device serial numbers are required for all ZTP modes.

Most organizations maintain a database of network device serial numbers as part of their non-sales inventory records. When adding new devices to the network, they will typically add the new device serial numbers to the same database at the time of purchase. This is the first place to look for serial numbers for devices you plan to onboard using ZTP.

You can also contact Cisco Support for help getting the serial numbers for newly purchased devices.

As a last resort, and for a Cisco IOS device that is already imaged, log in to the device console and run the show inventory CLI command. In the command output, look for a device name and description section like the one shown in the following illustration. In the case of devices with line cards or other options (as shown in this example), you will want to load both the chassis and card serial numbers.

RP/0/RP0/CPU0:ios#sh inv
Wed May 18 13:33:53.674 UTC
NAME: "0/RP0", DESCR: "NC5501 w/o TCAM Route Processor Card"
PID: NCS-5501          , VID: V01, SN: FOC23297HGS

NAME: "Rack 0", DESCR: "NCS5501 w/o TCAM 1RU Chassis"
PID: NCS-5501          , VID: V01, SN: FOC2332R014
...

To load device serial numbers to Cisco Crosswork:

1. Launch Cisco Crosswork.

2. From the main menu, select Device Management > Serial Number and Voucher.

3. Click Add Serial Number.

4. Click Upload CSV, then click the serialnumber.csv link to download the sampleSerialnumber.csv template file.

5. Using your choice of CSV file editor, enter into the template the serial numbers for all the devices you plan to onboard using ZTP. Save the updated CSV file template under a new name.

6. Select Add Serial Number again.

7. Click Browse to select the updated CSV file

8. Click Add Serial Number to import the serial numbers.

The Pinned Domain Certificate, Owner Certificate, and Owner Key are required only for Secure ZTP. They are not used with Classic ZTP and PnP ZTP.

In a test environment, you can use the default Pinned Domain Certificate (PDC), Owner Certificates (OCs) and Owner Key that Cisco Crosswork generates when ZTP is first installed. These credentials rely on Cisco as the Certificate Authority (CA) and are offered solely for the convenience of product testing. Cisco assumes that when you are using these default credentials, you are testing Cisco Crosswork in a protected "sandbox" environment that does not expose your network to security risks.

For production use, you must pin the Domain Certificate, generate intermediate OCs, and sign the Owner Key. You can then update the default versions of these credentials using the steps in the following section, "Update the Default PDC, OCs and Owner Key".

Organizations with their own certificate management staff and procedures will be familiar with how to generate a PDC, OCs and Owner Key using their chosen CA. Organizations that need more assistance with these tasks should see the examples and advice in the later section of this topic, "Pin the Domain Certificate, Generate Owner Certificates and Sign the Owner Key".

Update the Default PDC, OCs and Owner Key

To update the default Pinned Domain Certificate (PDC), Owner Certificate (OCs), and Owner Key:

1. Launch Crosswork.

2. From the main menu, select Administration > Certificate Management.

3. Under Certificates, click the next to Crosswork-ZTP-Owner, then click Update Certificate.

4. Click Browse to select your Pinned Domain Certificate (PEM or CRT file). With the file selected, click Save.

5. Click Browse to select the Owner Certificate (PEM or CRT file). With the file selected, click Save.

6. Click Browse to select the Owner Key (PEM, KEY, CRT file). With the file selected, click Save.

7. Click Save to update the default certificates and key.

Pin the Domain Certificate, Generate Owner Certificates and Sign the Owner Key

The following steps provide a series of examples showing how to use OpenSSL and the Linux Bash shell to generate a PDC, OCs and a signed Owner Key using your own Certificate Authority. You can find additional explanations and examples of this process at the following public resource: OpenSSL Certificate Authority. Once you've generated these credentials, follow the procedure in the preceding section, "Update the Default PDC, OCs and Owner Key".

1. Create a set of directories to manage the certificate and other files you will use or generate. For example:

   #!/bin/sh
   mkdir ./ca
   mkdir ./ca/certs
   mkdir ./ca/crl
   mkdir ./ca/newcerts
   mkdir ./ca/private
   chmod 700 ./ca/private
   touch ./ca/index.txt
   echo 1000 > ./ca/serial
   mkdir ./ca/intermediate
   mkdir ./ca/intermediate/certs
   mkdir ./ca/intermediate/crl
   mkdir ./ca/intermediate/csr
   mkdir ./ca/intermediate/newcerts
   mkdir ./ca/intermediate/private
   chmod 700 ./ca/intermediate/private
   touch ./ca/intermediate/index.txt
   echo 1000 > ./ca/intermediate/serial
   echo 1000 > ./ca/intermediate/crlnumber

2. Generate the root key. For example:

   #!/bin/bash
   cd ca
   openssl genrsa -aes256 -out private/ca.key.pem 4096
   chmod 400 ./private/ca.key.pem

3. Create the root certificate. For example:

   #!/bin/bash
   cd ca
   ##-subj "/C=us/ST=nc/L=rtp/O=cisco/OU=cx/CN=cisco.com" \
   openssl req -config openssl.cnf -key ./private/ca.key.pem -new -x509 -days 7300 -sha256 -subj "/C=us/ST=nc/L=rtp/O=cisco/OU=cx/CN=cisco.com" -extensions v3_ca -out certs/ca.cert.pem
   chmod 444 ./certs/ca.cert.pem

4. Verify the root certificate. For example:

   #!/bin/bash
   cd ca
   openssl x509 -noout -text -in certs/ca.cert.pem

5. Generate the intermediate key. For example:

   #!/bin/bash
   cd ca
   openssl genrsa -aes256 -out intermediate/private/intermediate.key.pem 4096
   chmod 400 ./intermediate/private/intermediate.key.pem

6. Create the intermediate certificate. For example:

   #!/bin/bash
   cd ca
   ##-subj "/C=us/ST=nc/L=rtp/O=cisco/OU=cx/CN=cisco.com" \
   openssl req -config intermediate/openssl.cnf -new -sha256 \
         -key intermediate/private/intermediate.key.pem \
         -out intermediate/csr/intermediate.csr.pem \
         -subj "/C=us/ST=nc/L=rtp/O=cisco/OU=cx/CN=intermediate.cisco.com"
   chmod 444 ./certs/ca.cert.pem
   © 2022 GitHub, Inc.
   

7. Sign the intermediate key. For example:

   #!/bin/bash
   cd ca
   openssl ca -config openssl.cnf -extensions v3_intermediate_ca \
         -days 3650 -notext -md sha256 \
         -in intermediate/csr/intermediate.csr.pem \
         -out intermediate/certs/intermediate.cert.pem
   chmod 444 ./intermediate/certs/intermediate.cert.pem

8. Verify the intermediate certificate. For example:

   #!/bin/bash
   cd ca
   openssl x509 -noout -text -in intermediate/certs/intermediate.cert.pem

9. Create the certificate chain. For example:

   #!/bin/bash
   cd ca
   cat intermediate/certs/intermediate.cert.pem \
         certs/ca.cert.pem > intermediate/certs/ca-chain.cert.pem
   chmod 444 intermediate/certs/ca-chain.cert.pem

10. Sign the Certificate Revocation List (CRL). For example:

    #!/bin/bash
    mycsr=$1
    myip=$2
    export SAN="IP:${myip}"
    echo $SAN
    cd ca
    openssl ca -config intermediate/openssl.cnf \
          -extensions usrSrv_cert -days 750 -notext -md sha256 \
          -in intermediate/csr/${mycsr}.csr.pem \
          -out intermediate/certs/${mycsr}.cert.pem
    chmod 444 intermediate/certs/${mycsr}.cert.pem

Ownership Vouchers (OVs) are required for Secure ZTP only. Depending on how they are supplied to you, you can load them one at a time or in bulk.

Cisco supplies OVs on request in the form of VCJ or TAR files.

If you want to use Secure ZTP to onboard third party devices, you will need to request VCJ files from the third-party manufacturer. VCJ files the manufacturer supplies must follow the naming convention serial.vcj, where serial is the serial number of the corresponding device. Cisco Crosswork requires this file naming convention in order to map the Ownership Voucher to the device. For background about restrictions on vouchers from third-party manufacturers, see #reference_qhs_1cm_3vb__SecureZTPGuidelinesThird.

Request Ownership Vouchers From Cisco

Contact Cisco Support to request OVs for the Cisco devices you plan to onboard using Secure ZTP. When requesting OVs, you must provide the following:

• Pinned Domain Certificate (PDC): A trusted digital certificate issued by a Certificate Authority (CA) and pinned by you. For details on pinning the PDC, see Update the PDC, Owner Certificates, and Owner Key.

• The serial number of each of the devices you plan to onboard using Secure ZTP (see Find and Load Device Serial Numbers).

Here is an example request for a single device:

{
    "expires-on": "2016-10-21T19:31:42Z",
    "assertion": "verified",
    "serial-number": "JADA123456789",
    "idevid-issuer": "base64encodedvalue==",
    "pinned-domain-cert": "base64endvalue==",
    "last-renewal-date": "2017-10-07T19:31:42Z"
 ​}

Cisco Support will respond to your OV request by sending you a VCJ file. If you requested OVs for more than one device, you will receive multiple VCJs in a TAR file instead of a single VCJ file. We recommend that you perform the VCJ or TAR file exchange using a secure method that you have agreed upon with Cisco Support.

Remember that individual VCJ files, whatever the source, must have the device serial number as the file name. Following the example request given in Step 1, Cisco would return a file with this name: JADA123456789.VCJ.

Load Ownership Vouchers

To load Ownership Vouchers:

1. Launch Cisco Crosswork.

2. From the main menu, select Device Management > Serial Number & Voucher.

3. Click Add Voucher.

4. Enter the name of or browse to the VCJ or TAR file you want to upload.

5. Click Upload to finish uploading the OVs.

Update the Default Ownership Voucher Certificate

To update the default ownership voucher certificate:

1. From the main menu, select Administration > Certificate Management

2. Click Update Certificate.

3. Click Browse to select the TAR or VCJ file you want to use to update the default ownership voucher.

4. Click Update Certificate.

5. Click Save.

The SUDI Root Certificate is required for Secure ZTP, and for PnP ZTP when onboarding IOS-XE devices. It is not used for Classic ZTP.

There are two types of "SUDI certificates":

• The device SUDI Certificate (also known as the Trust Anchor Certificate). Every Cisco IOS-XR and IOS-XE device has a SUDI Certificate stored on the device. The device SUDI certificate cannot be modified.

• The SUDI Root Certificate. This is the root Certificate Authority that enables the SUDI Certificate on each device.

Uploading the SUDI Root Certificate to Crosswork enables the Secure ZTP process (and, for IOS-XE devices, the PnP ZTP process) to authenticate each device by comparing the SUDI Root Certificate with the device's stored SUDI Certificate. This is required before PnP ZTP or Secure ZTP processes can provide bootstrap information to the device.

To prepare the SUDI Root Certificate and upload it to Cisco Crosswork:

1. Download the "Cisco Root CA 2048" and "Cisco Root CA 2099" files, in PEM format, from Cisco PKI: Policies, Certificates, and Documents (https://www.cisco.com/security/pki/policies/index.html).

2. Use an ASCII text editor to combine the two downloaded PEM files into a single PEM file, as in the example below:

   -----BEGIN CERTIFICATE-----
   MIIDQzCCAiugAwIBAgIQX/h7KCtU3I1CoxW1aMmt/zANBgkqhkiG9w0BAQUFADA1
   ....
   kxpUnwVwwEpxYB5DC2Ae/qPOgRnhCzU=
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   MIIDITCCAgmgAwIBAgIJAZozWHjOFsHBMA0GCSqGSIb3DQEBCwUAMC0xDjAMBgNV
   ...
   PKkmBlNQ9hQcNM3CSzVvEAK0CCEo/NJ/xzZ6WX1/f8Df1eXbFg==
   -----END CERTIFICATE-----

3. Launch Cisco Crosswork.

4. From the main menu, select Administration > Certificate Administration.

5. Click the and complete the fields as follows:

   Certificate Name: Crosswork-ZTP-Device-SUDI

   Certificate Role: ZTP SUDI

   Cisco M2 CA Certificate: Enter the name of or browse to the PEM file you want to upload.

6. Click Save. Crosswork stores the SUDI Root Certificate.