Getting Started

This guide provides an example usage of ZTP (Zero Touch Provisioning) APIs based on user scenarios. The examples provided in the guide are for demonstration purpose and can be used as a reference for external systems integration with CNC.

The scenarios and examples in this guide demonstrate a typical ZTP workflow and sequence of API execution for ZTP use cases.

ZTP Overview

ZTP can be classified into two types.

  1. Classic
  2. Secure ZTP (SZTP)

Classic ZTP is insecure and is meant to be used in a secure network environment. SZTP is recommended to be used in an insecure network. For Classic ZTP, a Serial Number needs to be added and associated to a device for onboarding it to DLM (Device Lifecycle Management). For SZTP, an ownership voucher (OV) needs to be added and associated to the device in order to onboard it. The OV is in the form of a .vcj file. It ensures that the device being onboarded onto the network is a genuine Cisco device and it is safe to onboard this device onto the network.

A typical ZTP flow to onboard a device to DLM via ZTP is explained below.

  1. Add serial numbers & Ownership Vouchers (OV). OV is required only for secure ZTP.
  2. Upload software images (optional)
  3. Upload ZTP configuration files
  4. Create ZTP profile
  5. Add a device
    • Choose device type (XR, XE & Others)
    • Select a secure connection type (Depends on device support)
    • Provide device details
    • Assign Profile
  6. Initiate ZTP from device (Device dependent)

The subsequent guide pages will explain how to carry out steps 1-5 mentioned above using APIs

Prerequisites

Before using any examples provided in this guide, it is expected that the user has set up CNC with a release corresponding to API version, required applications and NSO together.

Environment Setup to Make API Calls

Follow the below instructions to set up the environment to execute the sample curl commands to call ZTP APIs against the target CNC setup. Note that the below mentioned steps are for Unix/Linux environment.

1. Setup required environment variables

Copy the below content in a file named 'env' to any folder. It is recommended to create this file in a new folder.

#!/bin/bash
# update the host, port, user, password according to the target CNC
x=${CNC_HOST:=0.0.0.0}
x=${CNC_PORT:=30603}
x=${CNC_USER:=testuser}
x=${CNC_PASSWORD:=testpassword}
x=${CNC_JWT_FILE:=./cnc_jwt_file.txt}

export CNC_HOST
export CNC_PORT
export CNC_USER
export CNC_PASSWORD
export CNC_JWT_FILE

x=${CURL_OPTS:="-k -s"}
export CURL_OPTS

ZTP_URL=https://$CNC_HOST:$CNC_PORT/crosswork/ztp/v1
export ZTP_URL

Set execute permissions for 'env' file using the below command.

chmod 755 env

2. Setup JWT based authentication

Accessing the CNC ZTP API requires Authentication and Authorization. CNC uses a JWT based authentication which can be obtained using two-step process. Authorization of each API is controlled by API level access control as well as Role Based Access Control (RBAC) defined and configured in CNC.

Copy the below content in a file named 'setup.sh' in the same folder as the 'env' file.

#!/bin/bash

. ./env

get_jwt() {
    # getting jwt to use in cnc api authentication is a two step process
    # Step 1. get the Ticket Granting Ticket (TGT)
    # Step 2. use the TGT to get the JWT

    # Step 1. invoke this url with the username,password in the post payload
    export CNC_API_TGT_URL="https://$CNC_HOST:$CNC_PORT/crosswork/sso/v1/tickets"
    response=$(curl $CURL_OPTS -X POST $CNC_API_TGT_URL \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Accept: text/plain' \
    -d "username=${CNC_USER}&password=${CNC_PASSWORD}" \
    )

    # Step 2: invoke the jwt url with the jwt and forwarding service url in the post payload
    export CNC_API_JWT_URL="https://$CNC_HOST:$CNC_PORT/crosswork/sso/v2/tickets/jwt"
    BEARER_TOKEN=$(curl $CURL_OPTS -X POST $CNC_API_JWT_URL \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "tgt=$response&service=https://$CNC_HOST:$CNC_PORT/app-dashboard" \
    )

    # Step 3. only for example purpose. store it in ~/.cnc-jwt file
    echo $BEARER_TOKEN > $CNC_JWT_FILE
}

get_jwt

Set execute permissions for 'setup.sh' file using the below command.

chmod 755 setup.sh

At this stage the environment setup required to execute sample ZTP API curl commands is complete.