npm

Need private packages and team management tools?Check out npm Orgs. »

@itentialopensource/file-transfer

0.2.0 • Public • Published

Table of Contents

Intro

This folder contains the file-download workflows for Cisco devices (IOS / XR / NX).
This workflow iterates through a list of device(s) and issue the copy command to download a file (for example: a bin firmware image) from a remote file server using scp.
This solution consist of:

  • main workflow (IAP Artifacts Image Download) that is responsible for:
    1. collecting all job variables
    2. testing device availability and type
    3. calling the appropriate child-workflow (per device)
    4. displaying full summary of devices and their file copy/verification outcome.
  • child workflows (per device type):
    1. issuing the copy command
    2. performing file integrity using md5
    3. error handling missing folder structure on device
    4. error handling file existing prior to download
    5. error handling md5 verification failure
    6. generic error handling

Features:

  • auto-check for device compatibility and type
  • iterating through list of devices and download specified file from remote server using selected protocol
  • supports secured protocols for file transfer
  • md5 file verification to confirm integrity of the downloaded file
  • skips download process if file already exist, and will perform integrity check
  • offers to copy-overwrite files that failed integrity test, and will try to download again
  • shows a conclusive report with a summary report of all devices, and their download status (or error)
  • verbose mode allows enhanced log messages
  • creates folder structure recursively on device if it doesn't exist

Known limitations:

  • tested using scp protocol
  • creation folder structure for NX devices only
  • tested 3 device types manged by NSO
  • tested IOS managed by Ansible

The following job variables are required to start the workflow:

  • fileName - file name of the downloaded file
  • md5 - md5 signature of the downloaded file
  • host - hostname or IP address of file server
  • protocol - protocol to be used for downloading
  • hostPath - the host's path for the downloaded file
  • destinationDrive - the destination drive for the file to be downloaded onto
  • destinationPath - the destination path for the file to be downloaded onto
  • hostUsername - the username for the file server
  • hostPassword - the password for the file server
  • devicesNames - a string (of one device hostname) or array (of many device hostnames)
  • verbose - a boolean to enable or disable verbose mode during workflow
  • vrf - select a vrf to be used in copy command (for NX devices)

Supported device types

Cisco IOS Cisco IOS-XR Cisco NX

Test environment:

  • NSO Ver: 4.7.1
  • NEDs Ver:
    • cisco-ios: 5.8.3
    • cisco-xr: 7.0.10
    • cisco-nx: 5.7.5
    • itential-tools: 1.14.2
  • Devices Ver:
    • ios: 16.03.07
    • xr: 6.3.3
    • nx: 9.2(2)
  • IAP version 2019.01

Running

Running the file download artifact requires an API POST call to http://<IAP-HOST>:<IAP-PORT>/workflow_engine/startJob/IAP Artifacts Image Download where IAP-HOST is an ip address and IAP-PORT is the port.
If using Postman to make the call, you may use the example JSON objects as reference to the post call body:

  • Example payload for ios device
        "description":"ios device file download workflow from postMan",
        "variables":{
          "md5":"c9c4419a70c685a52fcsb85620420f09",
          "fileName": "file.name",
          "protocol": "scp",
          "host":"192.168.1.211",
          "hostPath":"~/",
          "destinationDrive":"flash",
          "destinationPath":"",
          "hostUsername":"user1",
          "hostPassword":"user1.Password",
          "devicesNames":["csr1kv1-ESXi","csr1kv2-ESXi"],
          "verbose": true
        }
      }
  • Example payload for xr device
        "description":"xr device file download workflow from postMan",
        "variables":{
          "md5":"c9c4419a70c685a52fcsb85620420f09",
          "fileName": "file.name",
          "protocol": "scp",
          "host":"192.168.1.211",
          "hostPath":"/root/",
          "destinationDrive":"harddisk",
          "destinationPath":"",
          "hostUsername":"user1",
          "hostPassword":"user1.Password",
          "devicesNames":["ESXi-IOS-XRv9k"],
          "verbose": true
        }
      }
  • Example payload for nx device
      "description":"nx device file download workflow from postMan",
      "variables":{
        "md5":"c9c4419a70c685a52fcsb85620420f09",
        "fileName": "file.name",
        "protocol": "scp",
        "host":"192.168.1.211",
        "hostPath":"/root/",
        "destinationDrive":"bootflash",
        "destinationPath":"/new/folder/path/",
        "hostUsername":"user1",
        "hostPassword":"user1.Password",
        "devicesNames":["cisco-nx"],
        "verbose": true,
        "vrf":"management"
      }
    }
     

Test cases:

# name ios xr nx
1. device name is string
2. device names are strings within array
3. device name does not exist
4. no available space on device
5. target folder does not exist on device
6. multiple target folders do not exist on device:
7. file already exist
8. file failed md5 checksum (corrupted file)
9. copy command timeout
10. md5 checksum timeout
11. download protocol: scp
12. download protocol: ftp
13. wrong file server ip / hostname
14. file server is ip address / hostname
15. wrong file server credentials
16. file does not exist on file server
17. wrong vrf name
18. Devices managed by Cisco NSO
19. Devices managed by Ansible manager

install

npm i @itentialopensource/file-transfer

Downloadsweekly downloads

63

version

0.2.0

license

Apache-2.0

homepage

gitlab.com

repository

Gitgitlab

last publish

collaborators

  • avatar
  • avatar
  • avatar
Report a vulnerability