Create NETCONF NEDs.
Creating and installing a NETCONF NED consists of the following steps:
Make the device YANG data models available to NSO
Build the NED package from the YANG data models using NSO tools
Install the NED with NSO
Configure the device connection and notification events in NSO
Creating a NETCONF NED that uses the built-in NSO NETCONF client can be a pleasant experience with devices and nodes that strictly follow the specification for the NETCONF protocol and YANG mappings to NETCONF. If the device does not, the smooth sailing will quickly come to a halt, and you are recommended to visit the NED Administration in Administration and get help from the Cisco NSO NED team who can diagnose, develop and maintain NEDs that bypass misbehaving devices special quirks.
Before NSO can manage a NETCONF-capable device, a corresponding NETCONF NED needs to be loaded. While no code needs to be written for such NED, it must contain YANG data models for this kind of device. While in some cases, the YANG models may be provided by the device's vendor, devices that implement RFC 6022 YANG Module for NETCONF Monitoring can provide their YANG models using the functionality described in this RFC.
The NSO example under $NCS_DIR/examples.ncs/development-guide/ned-development/netconf-ned implements two shell scripts that use different tools to build a NETCONF NED from a simulated hardware chassis system controller device.
netconf-console and ncs-make-package ToolsThe netconf-console NETCONF client tool is a Python script that can be used for testing, debugging, and simple client duties. For example, making the device YANG models available to NSO using the NETCONF IETF RFC 6022 get-schema operation to download YANG modules and the RFC 6241get operation, where the device implements the RFC 7895 YANG module library to provide information about all the YANG modules used by the NETCONF server. Type netconf-console -h for documentation.
Once the required YANG models are downloaded or copied from the device, the ncs-make-package bash script tool can be used to create and build, for example, the NETCONF NED package. See ncs-make-package(1) in Manual Pages and ncs-make-package -h for documentation.
The demo.sh script in the netconf-ned example uses the netconf-console and ncs-make-package combination to create, build, and install the NETCONF NED. When you know beforehand which models you need from the device, you often begin with this approach when encountering a new NETCONF device.
The NETCONF NED builder uses the functionality of the two previous tools to assist the NSO developer onboard NETCONF devices by fetching the YANG models from a device and building a NETCONF NED using CLI commands as a frontend.
The demo_nb.sh script in the netconf-ned example uses the NSO CLI NETCONF NED builder commands to create, build, and install the NETCONF NED. This tool can be beneficial for a device where the YANG models are required to cover the dependencies of the must-have models. Also, devices known to have behaved well with previous versions can benefit from using this tool and its selection profile and production packaging features.
netconf-console and ncs-make-package CombinationFor a demo of the steps below, see README in the $NCS_DIR/examples.ncs/development-guide/ned-development/netconf-ned example and run the demo.sh script.
List the YANG version 1.0 models the device supports using NETCONF hello message.
List the YANG version 1.1 models supported by the device from the device yang-library.
The ietf-hardware.yang model is of interest to manage the device hardware. Use the netconf-console NETCONF get-schema operation to get the ietf-hardware.yang model.
The ietf-hardware.yang import a few YANG models.
Two of the imported YANG models are shipped with NSO.
Use the netconf-console NETCONF get-schema operation to get the iana-hardware.yang module.
The timestamp-hardware.yang module augments a node onto the ietf-hardware.yang model. This is not visible in the YANG library. Therefore, information on the augment dependency must be available, or all YANG models must be downloaded and checked for imports and augments of the ietf-hardware.yang model to make use of the augmented node(s).
Create and build the NETCONF NED package from the device YANG models using the ncs-make-package script.
If you make any changes to, for example, the YANG models after creating the package above, you can rebuild the package using make -C nso-rundir/packages/devsim all.
Start NSO. NSO will load the new package. If the package was loaded previously, use the --with-package-reload option. See ncs(1) in Manual Pages for details. If NSO is already running, use the packages reload CLI command.
As communication with the devices being managed by NSO requires authentication, a custom authentication group will likely need to be created with mapping between the NSO user and the remote device username and password, SSH public-key authentication, or external authentication. The example used here has a 1-1 mapping between the NSO admin user and the ConfD-enabled simulated device admin user for both username and password.
In the example below, the device name is set to hw0, and as the device here runs on the same host as NSO, the NETCONF interface IP address is 127.0.0.1 while the port is set to 12022 to not collide with the NSO northbound NETCONF port. The standard NETCONF port, 830, is used for production.
The default authentication group, as shown above, is used.
Fetch the public SSH host key from the device and sync the configuration covered by the ietf-hardware.yang from the device.
NSO can now configure the device, state data can be read, actions can be executed, and notifications can be received. See the $NCS_DIR/examples.ncs/development-guide/ned-development/netconf-ned/demo.sh example script for a demo.
For a demo of the steps below, see README in the $NCS_DIR/examples.ncs/development-guide/ned-development/netconf-ned example and run the demo_nb.sh script.
As communication with the devices being managed by NSO requires authentication, a custom authentication group will likely need to be created with mapping between the NSO user and the remote device username and password, SSH public-key authentication, or external authentication.
The example used here has a 1-1 mapping between the NSO admin user and the ConfD-enabled simulated device admin user for both username and password.
In the example below, the device name is set to hw0, and as the device here runs on the same host as NSO, the NETCONF interface IP address is 127.0.0.1 while the port is set to 12022 to not collide with the NSO northbound NETCONF port. The standard NETCONF port, 830, is used for production.
The default authentication group, as shown above, is used.
A temporary NED identity is configured to netconf as the NED package has not yet been built. It will be changed to match the NETCONF NED package NED ID once the package is installed. The generic netconf ned-id allows NSO to connect to the device for basic NETCONF operations, such as get and get-schema for listing and downloading YANG models from the device.
Create a NETCONF NED Builder project called hardware for the device, here named hw0.
The NETCONF NED Builder is a developer tool that must be enabled first through the devtools true command. The NETCONF NED Builder feature is not expected to be used by the end users of NSO.
The cache directory above is where additional YANG and YANG annotation files can be added in addition to the ones downloaded from the device. Files added need to be configured with the NED builder to be included with the project, as described below.
The project argument for the netconf-ned-builder command requires both the project name and a version number for the NED being built. A version number often picked is the version number of the device software version to match the NED to the device software it is tested with. NSO uses the project name and version number to create the NED name, here hardware-nc-1.0. The device's name is linked to the device name configured for the device connection.
This step is not required if the device supports the NETCONF get-schema operation and all YANG modules can be retrieved from the device. Otherwise, you copy the YANG models to the state/netconf-ned-builder/cache/hardware-nc-1.0 directory for use with the device.
After downloading the YANG data models and before building the NED with the NED builder, you need to register the YANG module with the NSO NED builder. For example, if you want to include a dummy.yang module with the NED, you first copy it to the cache directory and then, for example, create an XML file for use with the ncs_load command to update the NSO CDB operational datastore:
In some situations, you want to annotate the YANG data models that were downloaded from the device. For example, when an encrypted string is stored on the device, the encrypted value that is stored on the device will differ from the value stored in NSO if the two initialization vectors differ.
Say you have a YANG data model:
And create a YANG annotation module:
After downloading the YANG data models and before building the NED with the NED builder, you need to register the dummy-ann.yang annotation module, as was done above with the XML file for the dummy.yang module.
get-schema with the NED BuilderIf the device supports get-schema requests, the device can be contacted directly to download the YANG data models. The hardware system example returns the below YANG source files when the NETCONF get-schema operation is issued to the device from NSO. Only a subset of the list is shown.
The fetch-ssh-host-key command fetches the public SSH host key from the device to set up NETCONF over SSH. The fetch-module-list command will look for existing YANG modules in the download-cache-path folder, YANG version 1.0 models in the device NETCONF hello message, and issue a get operation to look for YANG version 1.1 models in the device yang-library. The get-schema operation fetches the YANG modules over NETCONF and puts them in the download-cache-path folder.
After the list of YANG modules is fetched, the retrieved list of modules can be shown. Select the ones you want to download and include in the NETCONF NED.
When you select a module with dependencies on other modules, the modules dependent on are automatically selected, such as those listed below for the ietf-hardware module including iana-hardware ietf-inet-types and ietf-yang-types. To select all available modules, use the wild card for both fields. Use the deselect command to exclude modules previously included from the build.
Before diving into more details, the principles of selecting the modules for inclusion in the NED are crucial steps in building the NED and deserve to be highlighted.
The best practice recommendation is to select only the modules necessary to perform the tasks for the given NSO deployment to reduce memory consumption, for example, for the sync-from command, and improve upgrade wall-clock performance.
For example, suppose the aim of the NSO installation is exclusively to manage BGP on the device, and the necessary configuration is defined in a separate module. In that case, only this module and its dependencies need to be selected. If several services are running within the NSO deployment, it will be necessary to include more data models in the single NED that may serve one or many devices. However, if the NSO installation is used to, for example, take a full backup of the device's configuration, all device modules need to be included with the NED.
Selecting a module will also require selecting the module's dependencies, namely, modules imported by the selected modules, modules that augment the selected modules with the required functionality, and modules known to deviate from the selected module in the device's implementation.
Avoid selecting YANG modules that overlap where, for example, configuring one leaf will update another. Including both will cause NSO to get out of sync with the device after a NETCONF edit-config operation, forcing time-consuming sync operations.
An NSO NED is a package containing the device YANG data models. The NED package must first be built, then installed with NSO, and finally, the package must be loaded for NSO to communicate with the device via NETCONF using the device YANG data models as the schema for what to configure, state to read, etc.
After the files have been downloaded from the device, they must be built before being used. The following example shows how to build a NED for the hw0 device.
Build errors can be found in the build-error leaf under the module list entry. If there are errors in the build, resolve the issues in the YANG models, update them and their revision on the device, and download them from the device or place the YANG models in the cache as described earlier.
Warnings after building the NED can be found in the build-warning leaf under the module list entry. It is good practice to clean up build warnings in your YANG models.
A build error example:
The full compiler output for debugging purposes can be found in the compiler-output leaf under the project list entry. The compiler-output leaf is hidden by hide-group debug and may be accessed in the CLI using the unhide debug command if the hide-group is configured in ncs.conf. Example ncs.conf config:
For the ncs.conf configuration change to take effect, it must be either reloaded or NSO restarted. A reload using the ncs_cmd tool:
As the compilation will halt if an error is found in a YANG data model, it can be helpful to first check all YANG data models at once using a shell script plus the NSO yanger tool.
As an alternative to debugging the NED building issues inside an NSO CLI session, the make-development-ned action creates a development version of NED, which can be used to debug and fix the issue in the YANG module.
YANG data models that do not compile due to YANG RFC compliance issues can either be updated in the cache folder directly or in the device and re-uploaded again through get-schema operation by removing them from the cache folder and repeating the previous process to rebuild the NED. The YANG modules can be deselected from the build if they are not needed for your use case.
Having device vendors update their YANG models to comply with the NETCONF and YANG standards can be time-consuming. Visit the NED Administration and get help from the Cisco NSO NED team, who can diagnose, develop and maintain NEDs that bypass misbehaving device's special quirks.
A successfully built NED may be exported as a .tar file using the export-ned action. The tar file name is constructed according to the naming convention below.
The user chooses the directory the file needs to be created in. The user must have write access to the directory. I.e., configure the NSO user with the same uid (id -u) as the non-root user:
When the NED package has been copied to the NSO run-time packages directory, the NED package can be loaded by NSO.
ned-id for the hw0 DeviceWhen the NETCONF NED has been built for the hw0 device, the ned-id for hw0 needs to be updated before the NED can be used to manage the device.
NSO can now configure the device, state data can be read, actions can be executed, and notifications can be received. See the $NCS_DIR/examples.ncs/development-guide/ned-development/netconf-ned/demo-nb.sh example script for a demo.
Installed NED packages can be removed from NSO by deleting them from the NSO project's packages folder and then deleting the device and the NETCONF NED project through the NSO CLI. To uninstall a NED built for the device hw0: