1. General
1.1 Extract the NED package
1.2 Install the NED package
1.2.1 Local install
1.2.2 System install
1.3 Configure the NED in NSO
2. Optional debug and trace setup
3. Dependencies
4. Sample device configuration
5. Built in RPC actions
5.1. rpc clean-package
5.2. rpc compile-modules
5.3. rpc export-package
5.4. rpc get-modules
5.5. rpc list-modules
5.6. rpc list-profiles
5.7. rpc patch-modules
5.8. rpc rebuild-package
5.9. rpc show-default-local-dir
5.10. rpc show-loaded-schema
6. Built in live-status show
7. Limitations
8. How to report NED issues and feature requests
9. How to rebuild a NED
10. Using NETSIM for testing
1. General
This document describes the cisco-cnc_rc NED.
This is a RESTCONF NED to be used together with the Cisco CNC platform
The NED has been successfully tested with the following CNC versions:
- 6.1.4
IMPORTANT:
This NED is delivered without any of the device YANG models bundled to the NED package.
It is required to download the YANG files separately and rebuild the NED package before the NED is
fully operational. See the README-rebuild.md for further information.
The recommended way to do this is by following the steps below:
Install and setup the NED. See chapter 1.1 to 1.3
Download the YANG models. See chapter 1.1 in README-rebuild.md for the recommended method (alternatives are described in
README-rebuild.md chapter 2 and 3).
Rebuild the NED. See chapter 1.3 in README-rebuild.md (an alternative with a custom NED-ID is described in README-rebuild.md chapter 4).
Reload the NED in NSO. See chapter 1.4 in README-rebuild.md
Additional README files bundled with this NED package
+---------------------------+------------------------------------------------------------------------------+
| Name | Info |
+---------------------------+------------------------------------------------------------------------------+
| README-ned-settings.md | Information about all run time settings supported by this NED. |
| | |
| README-rebuild.md | Detailed instructions on how to download the device YANG models and |
| | rebuilding the NED with them. |
+---------------------------+------------------------------------------------------------------------------+
Common NED Features
+---------------------------+-----------+------------------------------------------------------------------+
| Feature | Supported | Info |
+---------------------------+-----------+------------------------------------------------------------------+
| netsim | yes | See README.md for further info on how to configure the NED to |
| | | use netsim as a RESTCONF target. |
| | | |
| check-sync | yes | Is by default using the last-modified-timestamp headers attached |
| | | to GET response messages sent from the CNC internal NSO |
| | | |
| partial-sync-from | yes | |
| | | |
| live-status actions | yes | The standard action get-any is supported |
| | | |
| live-status show | yes | |
| | | |
| load-native-config | no | |
+---------------------------+-----------+------------------------------------------------------------------+
Verified target systems
+---------------------------+-----------------+--------+---------------------------------------------------+
| Model | Version | OS | Info |
+---------------------------+-----------------+--------+---------------------------------------------------+
| Cicsco CNC | 7.1 | NSO | |
+---------------------------+-----------------+--------+---------------------------------------------------+
1.1 Extract the NED package
It is assumed the NED package ncs-<NSO version>-cisco-cnc_rc-<NED version>.signed.bin has already
been downloaded from software.cisco.com.
In this instruction the following example settings will be used:
NSO version: 6.0
NED version: 1.0.1
NED package downloaded to: /tmp/ned-package-store
Extract the NED package and verify its signature:
> cd /tmp/ned-package-store
> chmod u+x ncs-6.0-cisco-cnc_rc-1.0.1.signed.bin
> ./ncs-6.0-cisco-cnc_rc-1.0.1.signed.bin
In case the signature can not be verified (for instance if no internet connection),
do as below instead:
The result of the extraction shall be a tar.gz file with the same name as the .bin file:
> ls *.tar.gz
ncs-6.0-cisco-cnc_rc-1.0.1.tar.gz
1.2 Install the NED package
There are two alternative ways to install this NED package.
Which one to use depends on how NSO itself is setup.
In the instructions below the following example settings will be used:
NSO version: 6.0
NED version: 1.0.1
NED download directory: /tmp/ned-package-store
NSO run time directory: ~/nso-lab-rundir
A prerequisite is to set the environment variable NSO_RUNDIR to point at the NSO run time directory:
> export NSO_RUNDIR=~/nso-lab-rundir
IMPORTANT:
This NED is delivered as an “empty” package, i.e without any device YANG models bundled.
It must be rebuilt with the device YANG models to become operational.
The procedure to rebuild the empty NED (described in the README-rebuild.md) shall typically
be done in a lab environment. For this step a “local install” of the NED shall be used.
It is not suitable to use “system install” here since it is intended for production systems only.
Once this NED has been rebuilt with the device YANG and exported to one or many
separate tar.gz customized NED packages, a “system installation” can be used on them.
1.2.1 Local install
This section describes how to install a NED package on a locally installed NSO
(see "NSO Local Install" in the NSO Installation guide).
It is assumed the NED package has been been unpacked to a tar.gz file as described in 1.1.
Untar the tar.gz file. This creates a new sub-directory named:cisco-cnc_rc-<NED major digit>.<NED minor digit>:
> tar xfz ncs-6.0-cisco-cnc_rc-1.0.1.tar.gz
> ls -d */
cisco-cnc_rc-gen-1.0
Install the NED into NSO, using the ncs-setup tool:
Configure a TLS/SSL certificate. Either a host certificate identifying the device or
a self signed root CA. The certificate shall be entered in DER Base64 format, which
is the same as the PEM format but without the banners "----- BEGIN CERTIFICATE-----"
etc.
Use the Unix tool 'openssl' to fetch the PEM certificate from a device:
Configure cerificate, private key and possibly key passphrase to be used by the NED
to identify itself for the device.
The certificate and private key shall be entered in DER Base64 format. I.e same as PEM
format but without the banners is the same as the PEM format but without the banners
like "----- BEGIN|END CERTIFICATE-----", "----- BEGIN|END PRIVATE KEY-----" etc
YANG-PATCH
The NED is by default configured to use the YANG-PATCH protocol when deploying config on the Cisco CNC.
YANG-PATCH is a recent addition to the RESTCONF protocol, which is supported by the Cisco CNC. The
biggest benefit with YANG-PATCH is that it makes the deployment atomical and reduces the number of
required round trips towards the device.
The NED can easily be re-configured to use the standard RESTCONF protocol instead. See the
README-ned-settings.md for further details.
CHECK-SYNC
The NED is by default configured to support the NSO check-sync feature. This is done by doing a hash
of the config received from the Cisco CNC.
The NED can easily be re-configured to disable the check-sync feature completely.
See the README-ned-settings.md for further details.
Finally commit the configuration
admin@ncs(config)# commit
Verify configuration, using a sync-from.
admin@ncs(config)# devices device dev-1 sync-from
result true
If the sync-from was not successful, check the NED configuration again.
2. Optional debug and trace setup
It is often desirable to see details from when and how the NED interacts with the device(Example: troubleshooting)
This can be achieved by configuring NSO to generate a trace file for the NED. A trace file
contains information about all interactions with the device. Messages sent and received as well
as debug printouts, depending on the log level configured.
NSO creates one separate trace file for each device instance with tracing enabled.
Stored in the following location:
The log level 'info' is used by default and the 'debug' level is the most verbose.
IMPORTANT:
Tracing shall be used with caution. This feature does increase the number of IPC messages sent
between the NED and NSO. In some cases this can affect the performance in NSO. Hence, tracing should
normally be disabled in production systems.
An alternative method for generating printouts from the NED is to enable the Java logging mechanism.
This makes the NED print log messages to common NSO Java log file.
IMPORTANT:
Java logging does not use any IPC messages sent to NSO. Consequently, NSO performance is not
affected. However, all log printouts from all log enabled devices are saved in one single file.
This means that the usability is limited. Typically single device use cases etc.
3. Dependencies
This NED has the following host environment dependencies:
Java 1.8 (NSO version < 6.2)
Java 17 (NSO version >= 6.2)
Gnu Sed
Dependencies for NED recompile:
Apache Ant
Bash
Gnu Sort
Gnu awk
Grep
Python3 (with packages: re, sys, getopt, subprocess, argparse, os, glob)
4. Sample device configuration
devices device cnc-1
address port <port, usually 30603>
authgroup cnc-1
device-type generic ned-id cisco-cnc_rc-gen-1.0
ned-settings cisco-cnc_rc connection ssl accept-any true
state admin-state unlocked
!
In many cases it is beneficial to let the NED cache the bearer token as well as the probed
list of YANG modules and capabilities. This will reduce the number of required round trips to the device and increase the NED performance.
Cleans the NED package from all downloaded third party YANG files.
Input arguments:
- verbose <empty>
Print the full clean output also for successful executions (otherwise only printed on errors).
5.2. rpc compile-modules
Compile YANG modules, showing all non-fatal warnings found.
Input arguments:
- local-dir <string>
Path to the directory where the YANG files are found (defaults to src/yang in package).
- no-deviations <empty>
Set to disable deviations.
5.3. rpc export-package
Export the customized and rebuilt NED. The exported archive file can then be used to install the
NED package in other NSO instances. The name of the file will have the following format ncs-<NSO
version>-<NED name>-<NED-version>-customized.tgz.
Input arguments:
- destination <string> (default /tmp)
Set destination directory for the exported archive file.
- suffix <string> (default -customized)
Configure a customized suffix to the name of the archive file.
5.4. rpc get-modules
Fetch the YANG modules advertised by the device, from device or given source.
Input arguments:
- module-include-regex <string>
Regular expression matching all YANG models to be included in the download. Example:
'openconfig-.*'.
- module-exclude-regex <string>
Regular expression matching all YANG models to be excluded from the download. Example:
'tailf-.*'.
- namespace-include-regex <string>
Regular expression matching all namespaces to be included in the download. Example:
'tailf-.*'.
- namespace-exclude-regex <string>
Regular expression matching all namespaces to be excluded from the download. Example:
'tailf-.*'.
- module-additional-include-regex <string>
Regular expression matching additional YANG models that are not advertised by the device. For
instance vendor specific deviation models. Example: cisco-nx-openconfig-deviations.*.
- module-additional-exclude-regex <string>
Regular expression matching exceptions from the additional-include-regex.
- profile <union>
Use a download profile to match a predefined subset of matching YANG files.
- local-dir <string>
Path to the directory where the YANG files are to be copied (defaults to src/yang in package).
- ignore-errors <empty>
Ignore errors during download. For example missing files of failed revision checks.
Either of:
- remote device <empty>
The device itself.
OR:
- remote dir <string>
A directory on the local host holding all YANG files. For instance a local clone of a git
repository.
OR:
- remote archive <string>
A path to a zip/tgz archive file containing the YANG files.
OR:
- remote git repository <string>
The URL to the git repository. Example: https://github.com/YangModels/yang.git.
- remote git dir <string>
Path to a sub directory inside the git repo where the YANG files can be found. Example:
vendor/cisco/nx/10.1-2.
- remote git checkout <string>
Optionally, a name of a branch/tag in the git repo where the YANG files can be found.
Example: master.
- remote git include-dir <string>
Optional extra include paths to be used when searching for YANG files. Each include path
is relative to the git root directory.
5.5. rpc list-modules
Use this command to list the YANG modules advertised by the device. Returns a list with module
names, including revision tag if available.
Input arguments:
- module-include-regex <string>
Regular expression matching all YANG models to be included in the download. Example:
'openconfig-.*'.
- module-exclude-regex <string>
Regular expression matching all YANG models to be excluded from the download. Example:
'tailf-.*'.
- namespace-include-regex <string>
Regular expression matching all namespaces to be included in the download. Example:
'tailf-.*'.
- namespace-exclude-regex <string>
Regular expression matching all namespaces to be excluded from the download. Example:
'tailf-.*'.
- module-additional-include-regex <string>
Regular expression matching additional YANG models that are not advertised by the device. For
instance vendor specific deviation models. Example: cisco-nx-openconfig-deviations.*.
- module-additional-exclude-regex <string>
Regular expression matching exceptions from the additional-include-regex.
- profile <union>
Use a download profile to match a predefined subset of matching YANG files.
5.6. rpc list-profiles
List all predefined download profiles bundled with the NED. Including a short description of each.
No input arguments
5.7. rpc patch-modules
Patch YANG modules, to remove non-fatal warnings found.
Input arguments:
- local-dir <string>
Path to the directory where the YANG files are found (defaults to src/yang in package).
- no-deviations <empty>
Set to disable deviations.
- output-dir <string>
Path to the directory where the patched YANG files are written (defaults to src/yang in
package), existing files will be renamed to <name>.yang.orig.
5.8. rpc rebuild-package
Rebuild the NED package directly from within NSO. This invokes the gnu make internally.
Input arguments:
- verbose <empty>
Print the full build output also for successful builds (otherwise only printed on errors).
- profile <union>
Apply a certain build profile.
- filter scope dir <string>
Directory containing one or many xml file representing the wanted scope.
- filter trim-schema nodes <string>
List of nodes to trim. Use one of the pre-defined top node names. Alternatively, specify a
custom xpath to trim (prefix is mandatory on each element in the path).
- filter trim-schema file <string> (default /tmp/nedcom-trim-deviations.yang)
Name of auto generated deviation file with nodes to trim.
- filter auto-config dir <string>
Directory containing the files used for auto-config filtering. The following files must be
present: before.xml and after.xml.
- filter auto-config file <string> (default /tmp/nedcom-auto-deviations.yang)
Name of auto generated deviation file.
- ned-id major <string>
Set a custom major number in the generated ned-id.
- ned-id minor <string>
Set a custom minor number in the generated ned-id.
- ned-id suffix <string>
Set a custom suffix in the generated ned-id.
5.9. rpc show-default-local-dir
Show the path to the default directory where the YANG files are to be copied. I.e <path to current
NED package>/src/yang.
No input arguments
5.10. rpc show-loaded-schema
Display the schema currently built into the NED package. Each node will by default be listed with
a schema path.
Input arguments:
- scope <enum> (default all)
Select the scope for the nodes that will be listed.
all - Display all nodes in the schema. This is the default.
used - Display only the config nodes in use, i.e currently populated in CDB.
unused - Display only the config nodes that are not in use.
- count <empty>
Count the nodes and return the sum instead of the full list of nodes.
- root-paths <string>
Specify root paths for which nodes shall be listed or counted. Only nodes with a schema path
starting any of the specified roots will then be processed.
- config <true|false> (default true)
Set to false to display non config nodes in the schema. Note: scope will in this case be
'all'.
6. Built in live-status show
This NED has full support for fetching operational data via the NSO live-status API.
7. Limitations
NONE
8. How to report NED issues and feature requests
Issues like bugs and errors shall always be reported to the Cisco NSO NED team through
the Cisco Support channel:
The following information is required for the Cisco NSO NED team to be able
to investigate an issue:
- A detailed recipe with steps to reproduce the issue.
- A raw trace file generated when the issue is reproduced.
- Access to a device where the issue can be reproduced by the Cisco NSO NED team.
This typically means both read and write permissions are required.
Pseudo access via tools like Webex, Zoom etc is not acceptable.
However, it is ok with device access through VPNs, jump servers etc though.
Do as follows to gather the necessary information needed for your device, here named 'dev-1':
Reproduce the found issue using ncs_cli or your NSO service.
Write down each necessary step in a reproduction report.
Gather the reproduction report and a copy of the raw trace file
containing data recorded when the issue happened.
Contact the Cisco support and request to open a case. Provide the gathered files
together with access details for a device that can be used by the
Cisco NSO NED when investigating the issue.
Requests for new features and extensions of the NED are handled by the Cisco NSO NED team when
applicable. Such requests shall also go through the Cisco support channel.
The following information is required for feature requests and extensions:
A detailed use case description, with details like:
Data of interest
The kind of operations to be used on the data. Like: 'read', 'create', 'update', 'delete'
and the order of the operation
Device APIs involved in the operations (For example: REST URLs and payloads)
Device documentation describing the operations involved
Run sync-from # devices device dev-1 sync-from (if relevant)
Attach the raw trace to the ticket (if relevant)
Access to a device that can be used by the Cisco NSO NED team for testing and verification
of the new feature. This usually means that both read and write permissions are required.
Pseudo access via tools like Webex, Zoom etc is not acceptable. However, it is ok with access
through VPNs, jump servers etc.
9. How to rebuild a NED
Check the README-rebuild.md file, chapter 1.3, for more information.
10. Using NETSIM for testing
NETSIM (ConfD) has a built in RESTCONF server and can easily be configured as a test device.
Configure a NETSIM device instance in NSO like below:
devices authgroups group netsim-0
default-map remote-name admin
default-map remote-password admin
!
devices device netsim-0
address 127.0.0.1
port 7080
authgroup netsim-0
device-type generic ned-id cisco-cnc_rc-gen-2.0
trace raw
state admin-state unlocked
ned-settings cisco-cnc_rc restconf profile netsim
!
