Getting Started

This guide provides an example usage of the API based on user scenarios. The examples provided in the guide are for demonstration purpose which can be used as a reference for external systems' integration with CNC. The scenarios and examples in this guide demonstrate workflow and sequence API execution for creating backups of device configurations and restoring them when needed. These backups are stored as archives in the database, enabling network administrators to maintain a record of device configurations and quickly restore them in case of issues.

Prerequisites

Before using the examples in this guide, ensure that:

  1. CNC is installed and configured with the corresponding release version.
  2. Required applications and NSO are properly set up and integrated with CNC.
  3. Devices are onboarded to CNC. Refer to the CNC Installation and Administration guides for detailed setup instructions.

Download and set up example scripts

Follow these instructions to set up the scripts to execute against the target CNC setup.

  1. Download cnc-device-config_backup_restore-api-examples.tar.gz and unzip in user home directory for the example scripts used in this guide.
  2. After unzipping cnc-device-config_backup_restore-api-examples.tar.gz, you should see a folder containing example script "device-config-backup.sh", environment variables file "env", JWT token authentication scripts "get-cnc-jwt.sh" and "cnc-api-common.sh", input directory for input request payload and output directory for output response.
  3. Edit the cnc-device-config-backup-restore-api-examples/env file to update the CNC server host, port, and user credentials.
  4. Invoke the get-cnc-jwt.sh to obtain the JWT for authenticating the api calls
  5. Invoke each use-case script after optionally updating the input files according to the CNC environment.

Authentication and Authorization

Accessing the CNC Device Config 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.

Script Details

get_jwt() {
    # The get_jwt.sh script retrieves a JWT token for authenticating API calls. This process involves two steps:
    # Obtaining a Ticket Granting Ticket (TGT) using CNC server credentials.
    # Exchanging the TGT for a JWT token, which is stored in a file for later use."
 
    # 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"
    response=$(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 the purpose of this example. Store it in ~/.cnc-jwt file
    echo $response > $CNC_JWT_FILE
 
}
get_jwt

Example Script Environment Variables

The example script defined set of environment variables which are required to run the usecase scripts.

  1. To learn the CNC Server host, port and user credentials - in cnc-device-config-backup-restore-api-examples/env
  2. To reuse the API endpoints root contexts - in cnc-device-config-backup-restore-api-examples/cnc-api-commons.sh
# Standard CNC URL ROOT CONTEXTS
# Alarms and Events API Endpoint Root Context
# CNC_DEVICE_CONFIG_API_CTX: Base URL for the CNC Device Configuration Backup and Restore API.
export CNC_DEVICE_CONFIG_API_CTX="https://$CNC_HOST:$CNC_PORT/crosswork/config"