Release Announcement: NSO 6.6 is here!
Check out the release highlights to see what's new
NSO DevCenterTry NSO

README-rebuild

Table of contents

  1. General
    1.1 Overview
    1.2 Using the Built-in Tool For YANG Download
    1.3 Rebuild the NED With the Downloaded YANG Models
    1.4 Reload the NED Package in NSO
  2. Cleaning And Resetting the NED Package
    2.1 Removing All Downloaded YANG Models
    2.2 Resetting NED Package To Its Original Initial State
  3. Using the Built-in Downloader Tool For a Custom Download
    3.1 Creating a Custom Download
  4. Alternative Download Methods
    4.1 Copy the Files Into the NED Source Directory
  5. Rebuilding the NED Using a Custom NED-ID
    5.1 Rebuild With a Custom NED-ID
    5.2 Exporting the Rebuilt NED Package
  6. YANG Fixes Applied When Rebuilding the NED
    6.1 General
    6.2 Fixes Listed by Schema Paths
    6.3 Fixes Listed by YANG File Paths
    6.4 Other Fixes
  7. Advanced: Repairing Third-Party YANG Modules
    7.1 Types of YANG Related Issues
    7.2 Compile-time Issues
    7.3 Run-time Issues
  8. Advanced: Customizing Third-Party YANG Schemas
    8.1 Scope Filtering
    8.2 Trim Filtering
    8.3 Auto-config Filtering
  9. Advanced: Issues Solvable with Schema Customization
    9.1 Excessive RPCs Leading to Unresponsive NSO CLI
    9.2 Removing Deprecated Nodes from the Schema
    9.3 Identifying Problematic XPath Expressions Causing Performance Degradation in NSO
    9.4 Solving Issues Related to the NSO Brownfield Feature
  10. Migrating From the Legacy IOSXR NETCONF NED

1. General

1.1 Overview

The cisco-iosxr_nc NED is delivered without any YANG models included in the package.

To make the NED fully operational, you must first download the required models, then rebuild and reload the package.

This NED provides an optional built-in tool to simplify the download of device models.

Alternatively, you can download the models manually, as described in chapter 4.

Before using the downloader tool, ensure that the NED package (without device models) is properly configured in a running NSO environment. Complete the steps outlined in Chapters 1.1 through 1.3 of the README.md before proceeding.

1.2 Using the Built-in Tool for Simple YANG Download

The downloader tool is implemented as an NSO RPC, which can be invoked, for example, from the NSO CLI.

When executed, the tool causes the NED to automatically connect to the target device to download the necessary YANG models. During this process, the NED requests the device to provide a list of supported models by probing its capabilities.

This list serves as the basis for downloading the models. Additionally, the tool scans each downloaded YANG file for further dependencies specified by import or include statements and attempts to download all such dependent YANG files as well.

When using the NETCONF protocol the YANG models can normally be downloaded directly from the device.

Simple Usage

The downloader tool is pre-configured with five different profiles:

Do as follows in the NSO CLI to download the native yang files using the profile 'native':

Do as follows in the NSO CLI to download the openconfig yang files using the profile 'openconfig':

Note: If a built-in profile is selected and the user specifies additional module-include-regex and/or module-exclude-regex options on the command line, the tool will merge the profile's regex patterns with those provided by the user.

For more advanced options when using the downloader tool, see Chapter 3.

Chapter 5 ("rpc get-modules") of the README.md provides more details about the downloader tool, including a complete list of available command line arguments.

1.3 Rebuild the NED With the Downloaded YANG Models

The NED must be rebuilt after the device models have been successfully downloaded and stored.

It is common to encounter issues when building device YANG models. Such issues can result in compiler errors or unexpected runtime behaviors in NSO.

To address this, the NED is configured to handle all currently known build and runtime issues. It automatically patches problematic files to ensure they build correctly for NSO, using a set of YANG build recipes included with the NED package.

Please note that adapting the YANG build recipes is an ongoing process. If new issues are discovered, the Cisco NSO NED team will update the recipes and release a new version of the NED as needed.

End users are strongly encouraged to report any new YANG build issues to the Cisco NSO NED team through a support request.

The NED offers two options for rebuilding: you can either use the built-in tool within NSO, or run gnu make in an external shell.

Rebuild Using the Built-in Tool

The built-in RPC command rebuild-package rebuilds the NED package by automatically invoking gnu make in the source directory of the package installation root.

Example usage:

Note: This RPC may take a significant amount of time to complete, as compiling YANG models is a time-consuming process.

Additional Arguments:

  • verbose: Prints the full output returned from gnu make. By default, output is shown only if errors occur.

  • profile: Applies a specified build profile during the rebuild process.

  • ned-id: Parameters for customizing the NED ID. For more information, see Chapter 5.

  • create-namespace-files: Builds Python and Java namespace files representing the nodes in the rebuilt schema.

Rebuild Using a Separate Shell

The NED must be rebuilt from within the NED package installation root (i.e., $NED_ROOT_DIR as configured in Chapter 1.1 of the README.md).

To rebuild the NED, follow these steps:

1.4 Reload the NED Package In NSO

After the NED has been successfully rebuilt with the device models, it is necessary to reload the package in NSO.

To reload, use the following NSO CLI command:

Note: If the NED package has been rebuilt with a new NED-ID (as described in Chapter 5), you must add the force option to the reload command:

2. Cleaning And Resetting the NED Package

2.1 Removing All Downloaded YANG Models

If you plan to download a new set of YANG models for an already installed and reloaded NED, it is mandatory to first remove all old device YANG models from the previous download. Failing to do so may result in unintended mixing of different YANG models.

Clean Using the Built-in Tool

Clean Using a Separate Shell

2.2 Resetting NED Package to Its Original Initial State

If you have rebuilt the NED with downloaded YANG files and a custom ned-id, the original default ned-id is no longer available. To reset the NED package to its original state, follow the steps below.

Reset Using the Built-in Tool

  1. Remove the downloaded YANG files:

  2. Rebuild NED package without any additional arguments. This will reset the NED-ID to its original initial state:

Reset Using a Separate Shell

3. Using the Built-in Downloader Tool For a Custom Download

Using a pre-configured download profile is the easiest way to download device YANG models.

If this approach is not suitable, the downloader tool offers several additional arguments for customizing the download-for example, by limiting the scope of the YANG models to be downloaded.

3.1 Creating a Custom Download

To customize the download scope, use the module-include-regex and module-exclude-regex arguments. Both should be specified as regular expressions.

The easiest way to determine the correct arguments is by using the RPC command list-modules.

Example:

Start with fetching a full list of the YANG models supported by the device:

Limit the scope to only include some models, by specifying a simply regular expression for the argument 'module-include-regex':

Now use the argument 'module-exclude-regex' to exclude some of the files matching the 'module-include-regex':

When the 'list-modules' rpc returns only the models of interest you can use the same arguments for the 'get-modules' rpc.

For more details about the get-modules and list-modules RPC commands, see Chapter 5 in the README.md.

4. Alternative Download Methods

Device models can also be downloaded manually. To use this option, the NED package must first be unpacked. Complete the steps described in Chapter 1.1 of the README.md beforehand. It is also recommended to follow the steps in Chapters 1.2 and 1.3 for best results.

4.1 Copy the Files Into the NED Source Directory

When YANG models have been downloaded manually, all files must be copied into the source directory of the NED installation:

Note:

YANG files named in the format <module name>@<date revision>.yang must be renamed to <module name>.yang. This is due to a limitation in the current NED make system.

This manual procedure is equivalent to using the downloader tool with a path to a local directory as the remote source. For more information, see Chapter 5 ("rpc get-modules") in the README.md.

Important:

Do not remove any of the YANG files used internally by the NED in $NED_ROOT_DIR/src/yang.

This includes the following files:

The recommended way to clean the source directory is to follow the steps described in Chapter 5.

5. Rebuilding the NED Using a Custom NED-ID

A common use case is managing multiple versions of the same device in a network controlled by NSO. Each device may require its own unique set of YANG files, which means the NED must be rebuilt for each version.

To support this scenario, each built variant of the NED must have a unique NED-ID. This allows NSO to support multiple versions of the same NED package simultaneously.

There are two ways to rebuild the NED with a custom NED-ID:

1. Using the built-in RPC:

Specify the following additional arguments:

  • suffix

  • major

  • minor

2. Using gmake in a separate shell:

Set the following make variables:

  • NED_ID_SUFFIX

  • NED_ID_MAJOR

  • NED_ID_MINOR

The default NED-ID is: cisco-iosxr_nc-gen-1.1

5.1 Rebuild With a Custom NED-ID

Do as follows to build each flavour of the cisco-iosxr_nc NED. Do it in iterations, one at the time:

  1. Follow the instructions in chapter 1.1 to 1.3 in README.md to unpack the NED and install a device instance

    using it. Make sure a unique location is selected and update the environment variable $NED_ROOT_DIR

    accordingly and configure a device instance.

  2. Follow the instructions in chapter 1.2 to download the YANG models matching the configured device.

  3. Follow the instructions in chapter 1.3 to rebuild the NED:

    Alternative 1: Use the built-in rpc to rebuild with custom NED-ID

    Use any combination of the additional ned-id arguments major, minor and suffix.

    Two examples showing NED-ID adapted for "device version" 21.6:

    This will generate a NED-ID like: cisco-iosxr_nc-r21.6-gen-1.'

    This will generate a NED-ID like: cisco-iosxr_nc-gen-21.6

    Alternative 2: Rebuild the NED using gnu make from a shell

    Add any combination of the additional make variables NED_ID_SUFFIX, NED_ID_MAJOR and NED_ID_MINOR to the command line.

    Two examples showing NED-ID adapted for "device version" 21.6:

    This will generate a NED-ID like: cisco-iosxr_nc-r21.6-gen-1.0

    This will generate a NED-ID like: cisco-iosxr_nc-gen-21.6

  4. Follow the instructions in chapter 1.4 to reload the NED package. The rebuilt NED package will now have the NED-ID: cisco-iosxr_nc<NED_ID_SUFFIX>-gen-<NED_ID_MAJOR>.<NED_ID_MINOR>

    This is detected by NSO and will have the following side effects:

    • The default NED-ID will no longer exist after the packages has been reloaded in NSO. Hence, any devices configured with the default NED-ID can no longer exist either.

    • It is recommended to delete all device instances using the default NED-ID before reloading the packages in NSO.

    • It is necessary to use packages reload force when reloading the packages in NSO.

  5. Reconfigure the device instance from step #1 in this list. Now use the new NED-ID

  6. Verify functionality by executing a sync-from on the configured device instance.

5.2 Exporting the Rebuilt NED Package

After rebuilding the NED with a new NED-ID, it is often necessary to export it as a separate NED package. This new package will include both the raw and the customized, compiled versions of the third-party YANG models. The exported package can then be loaded into a new NSO instance or used like any other NED package.

The NED provides a built-in tool to simplify the export process. This tool is implemented as an additional RPC that can be invoked through the NSO CLI or any other northbound NSO interface.

The export tool copies all relevant files from the "source" directory of the rebuilt NED into a .tar.gz archive. The top-level directory of the archive will be named according to the generated NED-ID, for example: cisco-iosxr_nc<NED_ID_SUFFIX>-gen-<NED_ID_MAJOR>.<NED_ID_MINOR>.

Usage Example:

Additional arguments:

  • destination: Destination directory for the exported .tar.gz archive. Default is /tmp.

  • suffix: Suffix to append to the archive file name. Default is -customized.

6. YANG Fixes Applied When Rebuilding the NED

Third-party YANG files often contain errors that can cause issues during compilation or at runtime. In addition to standard YANG bugs, there may be constructs that are incompatible with NSO, or cases where the device does not fully adhere to the models.

The NED build system includes a set of tools that can automatically apply various fixes to third-party YANG files. These fixes, known as YANG recipes, ensure that the YANG files compile correctly when the NED package is rebuilt. Note that these recipes only cover YANG file versions that have been verified by the Cisco NED team. New build-time issues may still occur if the NED is rebuilt with unverified YANG file versions.

If you encounter any such issues, it is recommended to contact the Cisco NED team by opening a support ticket. See Chapter 8 in the README.md for more information.

Below is a description of the YANG recipes currently used by the cisco-iosxr_nc NED.

6.1 General

YANG recipe contains varies yang fixes by schema and YANG file paths.

6.2 Fixes listed by schema paths

6.3 Fixes listed by YANG file paths

Cisco-IOS-XR-ipv4-acl-datatypes.yang

6.4 Other fixes

Not applicable.

7. Advanced: Repairing Third-Party YANG Modules

Many third-party YANG models have issues that prevent them from being compiled or used with NSO - they often require repairs.

This NED package has been verified to work with the device models and YANG model revisions listed in the README.md. Any issues found in these verified revisions have already been addressed, and the necessary fixes are included in the package.

However, new issues with YANG models may still arise. This can happen if the NED is used with YANG models that have not been verified by the Cisco NED team, or if the NED is used in a new scenario that has not previously been tested.

In such cases, additional YANG repairs may be required.

It is strongly encouraged to contact the Cisco NED team for assistance with these issues.

Create a support case with a detailed description of the problem and the use case, following the instructions in the README.md.

There is also a do-it-yourself option for advanced users who have a strong understanding of the YANG modeling language. The NED package includes tools to help automate YANG repairs. This chapter provides an overview of how to use these tools.

7.1 Types of YANG Related Issues

When preparing YANG modules for use with NSO, issues can generally be classified as either compile-time or run-time.

  • Compile-time issues are problems that must be resolved before the YANG modules can be successfully compiled and loaded into NSO.

  • Run-time issues are problems that arise after the YANG has been compiled and loaded, such as invalid constraints that are not met by the actual device.

7.2 Compile-time Issues

Before using YANG modules in NSO, the first step is to ensure they can be compiled successfully. For convenience, most standard issues found in YANG files are automatically patched during the build process. The patched files are placed in src/tmp-yang (note: the original YANG files in src/yang are not modified).

This behavior is controlled by the make variable AUTOPATCH_YANG_NED. It is usually enabled by default in the NED makefile $NED_ROOT_DIR/src/Makefile, as shown below:

The auto-patcher feature only fixes the most common, standard issues.

If YANG compilation still fails (for example, as shown below), additional steps are required:

Always avoid modifying the original YANG files in src/yang. Instead, use the provided tools to patch the YANG files at compile time. The patched files will be placed in src/tmp-yang, which is where the make process looks for the active files.

The NED package includes three different YANG pre-processor tools for compile-time patching:

  • schypp

  • jypp

  • ypp

7.2.1 The schypp Tool

schypp is the schema-aware YANG pre-processor tool. It is automatically invoked at compile time and reads directives from the file $NED_ROOT_DIR/src/customize-schema.schypp.

Each line in this file contains a single pragma, starting with one of the keywords: add, remove, replace, or inline-type. This keyword is followed by the globally unique schema-path for the node to operate on. No line breaks are allowed.

If a prefix is needed for a non-unique name in the path, it must match the prefix declared in the module. Depending on the operation type, the schema-path is followed by :: (two colons) and additional arguments as needed. The details for each directive are described below.

Supported Pragmas

  • inline-type

  • add

  • remove

  • replace

The schypp tool operates by first building an in-memory schema tree from all available YANG files. It then applies each defined pragma to the corresponding nodes in this schema. Once all pragmas have been applied, schypp automatically generates patched versions of the YANG files and stores them in src/tmp-yang.

By inspecting the patched YANG files in src/tmp-yang, you can see exactly what changes have been made. For example:

This approach allows you to track and verify all changes made to the YANG files during the patching process.

inline-type

Applicable for leafs of type leafref. The tool looks up the type of the referred leaf and inlines the same type on the referee. This is especially useful for resolving issues related to leafrefs.

Syntax:

inline-type <schema-path>

Example:

inline-type /oc-netinst:network-instances/network-instance/protocols/protocol/name

add

Adds YANG statements to the schema.

Syntax:

Example:

remove

Removes a YANG statement from the schema.

Syntax:

Example:

replace

Replaces a YANG statement in the schema. The matching statement (must be a unique match) is replaced by the provided statement(s). The rules for stmt-match and YANG-stmt(s) are the same as for add and remove.

Syntax:

Example:

7.2.2 The jypp Tool

jypp is a YANG pre-processor tool implemented in Java (hence the name). It provides similar functionality to the schypp tool, but operates in a YANG model-aware manner rather than schema-aware.

The jypp tool requires a "path" within the YANG model file to identify the node or area to operate on.

Finding the YANG Path

To determine the path to a node:

  1. Identify the file containing the declaration of the node you wish to modify.

  2. Open the file and locate the node.

  3. Run jypp from a shell to print the path:

Example:

Suppose you need to modify the range for MPLS label values in openconfig-mpls-types.yang at line 278:

To find the path:

The path is: /#mpls-label/type/#uint32/range

Supported Operations

  • --add-stmt:

    Add a statement to the node identified by the YANG path.

    Syntax:

    ./tools/jypp --add-stmt=<YANG path>::<statement to add> <file to modify>

    Example:

    ./tools/jypp --add-stmt=/#mpls-label/type/#uint32::description "This is an addition"; tmp-yang/openconfig-mpls-types.yang

  • --remove-stmt:

    Remove a statement identified by the YANG path

    Syntax:

    ./tools/jypp --remove-stmt=<YANG path> <file to modify>

    Example:

    ./tools/jypp --remove-stmt=/#mpls-label/type/#uint32 tmp-yang/openconfig-mpls-types.yang

  • --replace-stmt:

    Replace a statement at the node identified by the YANG path

    Syntax:

    ./tools/jypp --replace-stmt=<YANG path>::<statement to replace> <file to modify>

    Example:

    ./tools/jypp --replace-stmt=/#mpls-label/type/#uint32/range::"range 13..1048575;" tmp-yang/openconfig-mpls-types.yang

Applying jypp Rules Automatically

After testing your jypp rules in a shell and confirming that the corresponding files in tmp-yang are updated as expected, you can add these rules to the build process so they're applied automatically each time the NED package is rebuilt.

  1. Open $NED_ROOT_DIR/src/ned-custom.mk.

  2. Locate the do-profile-default make target.

  3. Add your jypp rules to this section.

Example:

7.2.3 The ypp Tool

ypp is the oldest of the three YANG pre-processor tools. It is a pattern-matching, text-processing utility that operates using regular expressions - essentially an advanced version of sed. While most tasks can be accomplished more easily with schypp or jypp, there are situations where ypp is the only workable option.

Syntax:

Examples:

After testing your ypp rules in a shell and verifying that the files in tmp-yang are updated as expected, you should add these rules to the build process so they are applied automatically each time the NED package is rebuilt:

  1. Open $NED_ROOT_DIR/src/ned-custom.mk.

  2. Locate the do-profile-default make target.

  3. Add your ypp rules to this section.

Example:

7.2.4 Verify the YANG Repair

There is a dedicated make target for running only the "pre-processing" of the YANG modules, which includes automatic patching and application of local schema customizations. You can run it as follows:

After running this command, you can immediately review the resulting YANG modules in the src/tmp-yang directory. These are the files that will be used by the NED at runtime.

7.3 Run-time Issues

After all YANG modules have been successfully compiled and loaded into NSO, there may still be issues that only appear at run time. These are typically related to constraints defined in the YANG modules but not strictly followed by the device, such as integer value ranges or missing leafref targets. These issues can only be identified using actual device configurations, so a NED instance must be able to connect to the device and perform a full sync-from.

Example:

If the device returns configuration containing a leaf of type leafref whose target is missing, running a full sync-from might produce output like:

This indicates that the device is not fully compliant with the YANG models it uses, and further YANG repair is needed.

You can use the same toolkit described in section 7.2 to fix run-time issues.

For the example above, you could repair the issue with an additional schypp statement:

8. Advanced: Customizing Third-Party YANG Schemas

YANG models provided by many third-party vendors are often very large. When compiled, these schemas may contain tens of thousands of nodes, and in some cases, even exceed one million. Such large schemas can negatively impact NSO in several ways:

  • Runtime memory footprint: A single NED package that includes a large third-party YANG schema can easily consume several hundred megabytes to up to a gigabyte of memory. In an NSO environment with many such NED packages installed, the overall memory usage can become significantly high.

  • Persistent footprint: Large YANG files also result in large compiled schema files being installed in NSO, requiring more disk space on the host.

  • Runtime performance: Large schemas can degrade NSO's performance, affecting everything from CLI responsiveness to diff calculations during commit operations as well as sync-from operations.

In many cases, it may not be necessary or even beneficial to include the entire third-party YANG schema when building the NED package. Often, the use cases deployed through NSO only require a fraction of the full schema. In such cases, it is recommended to consider schema customization when rebuilding the NED package.

All third-party YANG NED packages include filtering tools that allow you to customize the schema during the package rebuild process. This chapter provides a detailed description of these tools, including how to use them, their benefits, and limitations.

This chapter applies generally to all third-party YANG NEDs and includes examples from various device types and vendors.

8.1 Scope Filtering

Scope filtering is typically the first method to try when aiming to reduce the size of the schema during the rebuilding of a NED package. It works by automatically limiting the number of YANG models included to only those required for your specific use cases. This means that only the necessary YANG models are incorporated, which helps in minimizing the overall schema size and improving performance and resource usage during NSO operations.

This approach is straightforward and effective because it excludes unnecessary parts of large third-party YANG schemas that are not relevant to your deployment.

This method is recommended as the initial step in schema customization when building or rebuilding NED packages to optimize NSO resource consumption and responsiveness.

8.1.1 How it Works

YANG models that define the schema are typically organized into functional groups. For example, one module might cover interface configuration, another system settings, and a third router settings. Each group is usually defined in a separate YANG module with its own XML namespace, as illustrated below:

These namespaces appear in the device's running configuration and in the configuration snippets sent when deploying new settings. This is evident when displaying the configuration in XML format. The example below shows a simple commit dry-run involving the description leaf on an interface:

To apply the configuration in this example, the NED only needs built-in support for the namespace http://openconfig.net/yang/interfaces. This means that only the YANG module openconfig-interfaces.yang and its dependencies (as indicated by the import statements above) must be compiled into the NED package. Other YANG modules, such as those defining system settings, are not required and can be excluded.

The scope filtering feature is an automatic pre-processing step invoked when rebuilding the NED package. It analyzes the use cases and the XML namespaces they require, then generates a list of YANG modules necessary to support all use cases. This list is provided to the YANG compiler, which compiles only the specified modules instead of all third-party YANG files currently downloaded.

What is a Use Case?

Before using scope filtering, you need to gather relevant use cases.

From the NED perspective, a use case is a configuration snippet that will be deployed to the device, typically generated by one or more service packages.

When collecting use cases, you must execute your services so they produce the configuration intended for the device. It is important to exercise all service options thoroughly, as certain service package options may trigger configuration nodes belonging to different XML namespaces, which must be included as separate use cases.

However, it is not necessary to deploy all use cases on the device physically. You can use NSO's commit dry-run outformat xml feature to collect use cases without actual deployment.

Example:

Another important use case to consider is the device's day-0 configuration. Your services might depend on existing device configuration, which should also be included as a use case.

All collected use cases need to be saved as XML files in an appropriate directory for use during NED package rebuilding.

8.1.2 Usage

To rebuild the NED package using the scope filtering feature with collected use cases stored in the directory /tmp/use-cases, you have two main options:

Using the NED Built-in Rebuild Tool (RPC)

This is the recommended method. Invoke the rebuild tool via the NSO CLI with the following command:

After the rebuild completes, reload the NED package:

If the reload fails because NSO detects that some XML namespaces have disappeared (which is expected when scope filtering removes unused modules), retry with the force flag:

Using a Unix Shell

Alternatively, you can rebuild the NED package directly from a Unix shell. Run the following command, specifying the scope filter directory:

8.1.3 Examples

This simple example shows how to use the scope filter to adapt the NED to only include the YANG modules covering the running config on the device together with the configuration that will be deployed through a simple service package named my-service.

  1. Make the NED fully operational with the full schema by following the initial setup steps (chapters 1.2 - 1.4).

  2. Connect to the device:

  3. Optionally, list the modules currently supported by the NED:

    This lists all YANG modules with revisions built into the NED package.

  4. Perform a sync-from operation from the device:

  5. Save the running configuration into an XML file:

  6. Execute a dry-run commit using the installed service package configuration (stored in /tmp/my-service-test-config.xml):

  7. Now you have two XML files representing the running config and the service package config, each specifying the namespaces needed for their configurations. This information is sufficient to create a scope filter.

    Rebuild the NED package again, using the scope filter pointing to the directory with the XML files:

  8. Reload the NED package:

  9. Optionally, list the modules supported again:

    The list should now be shorter than before. If not, it may indicate that scope filtering is not effective with the YANG models in use. In that case, refer to chapter 8.1.4 about limitations.

8.1.4 Limitations

The scope filtering feature depends on YANG models being properly partitioned into distinct XML namespaces, which is true for most third-party YANG models. However, there are notable limitations:

  • Namespace Partitioning Exception: Some models, such as the Nokia SROS YANG distribution, have the majority of their nodes within a single namespace. In these cases, scope filtering is ineffective.

    It is worth mentioning that all standard NEDs developed by the Cisco NSO NED team also utilize single-namespaced YANG models.

  • Granularity Limitation: Scope filtering can only remove complete YANG modules representing entire namespaces. It cannot remove individual nodes or subsets within a module.

To address these limitations, the trim filter feature shall be used instead. The trim filter allows more granular customization by removing specific nodes within a YANG model rather than entire modules, thus overcoming the constraints of scope filtering.

8.2 Trim Filtering

Trim filtering customizes third-party YANG schemas by patching the YANG files during the NED package rebuild process. This is done through a pre-processing step handled by the tool named schypp, which reads all installed YANG files into an in-memory schema representation. The schypp tool then applies modifications based on pragma directives, as described in the relevant documentation section 7.1. After applying these modifications, schypp automatically generates new patched versions of the YANG files.

Specifically for trimming, schypp can also remove any node from the schema, ranging from a single leaf to an entire subtree. It also intelligently resolves dependencies related to the trimmed nodes. For example, if there are references such as leafrefs, deviations, augments, or refines that point to the node or any of its subnodes being trimmed, schypp will automatically handle and resolve these references to maintain schema consistency.

This approach allows for much finer granularity in schema customization compared to scope filtering, which only removes entire modules based on XML namespaces. Trim filtering with schypp enables precise removal of unwanted parts of the schema while ensuring that all dependent references are correctly managed during the rebuild process.

8.2.1 How it Works

When trimming nodes using the schypp based trimmer tool, the process works as follows:

  • It removes the specified nodes from the schema, and generates new patched versions of the YANG files.

  • The trimmer tool automatically generates additional comments in the patched YANG files indicating which nodes have been trimmed and the reasons for their removal.

  • This helps maintain clarity and traceability in the modified YANG files.

Trimming Normal Nodes

Normal nodes refer to nodes that are directly modeled in YANG modules or nodes modeled within groupings that are not shared with other parts of the schema. These nodes are generally straightforward to trim.

Below is a simple YANG module that will be used for illustrating how the trimming works.

Assume the nodes identified with the schema paths /conf:top/a and /conf:top/c shall be trimmed.

Then the resulting patched YANG file will look like below:

Trimming Nodes Defined in Shared Groupings

When nodes to be trimmed are defined within groupings shared across multiple parts of the schema, the trimming process becomes more complex than trimming normal nodes. This is because directly trimming nodes from a shared grouping would affect all instances where that grouping is used, which is usually undesirable.

Trimmer Approach for Shared Groupings

  • The trimmer tool first expands the shared groupings at each location where they are used. This means it replaces the uses statement with the actual content of the grouping in that specific location.

  • After expansion, the nodes to be trimmed can be removed locally at each instance without affecting other parts of the schema.

  • The tool adds new auto-patch comments in the YANG files to document these changes, showing where groupings were expanded and which nodes were trimmed.

Example:

Given the YANG module below:

If the nodes /conf:top/a and /conf:top/subtree1/b need to be trimmed:

  • The grouping ab is used in three places (top, subtree1, and subtree2), so it is a shared grouping.

  • The trimmer tool will expand the grouping ab at top and subtree1 (where trimming is needed).

  • Then it trims the specified nodes locally.

The resulting patched YANG module will look like:

Additional Notes

  • If nodes to be trimmed are defined through multiple nested groupings, the trimmer tool will locate the top-most shared grouping and expand it recursively, including any sub-groupings as long as they represent the same XML namespace.

  • This approach ensures that trimming is precise and localized, avoiding unintended removal of nodes in other parts of the schema.

Trimming Augmented Nodes in YANG Schemas

Augmented nodes in YANG schemas are nodes added to existing schema trees via the augment statement, often representing a different XML namespace than their siblings. Trimming these nodes requires special handling to maintain the correct namespace and schema integrity.

Key Points on Trimming Augmented Nodes

  • Trimming must be done in the same YANG module where the augment is defined to preserve the XML namespace.

  • The trimming process is similar to trimming normal nodes but localized within the augmenting module.

  • The trimmer tool inserts comments indicating which nodes have been trimmed.

Example 1: Simple Augmented Node Trimming

Given a YANG module augmenting /conf:top/conf:subtree1 with a container extra having leaves x and y:

If the node /conf:top/subtree1/conf-aug:extra/y is to be trimmed, the patched module will look like:

Example 2: Trimming Augmented Nodes Defined Through Shared Groupings

When augmented nodes are defined via shared groupings used in multiple augmentations, trimming requires a more complex approach:

​ • The trimmer tool clones the shared grouping for the specific augmentation where trimming is needed.

​ • The cloned grouping is patched with the trimmed nodes.

​ • The augmentation is updated to use the cloned grouping instead of the original.

Given a YANG module below:

If /conf:top/subtree1/conf-aug:extra/y is to be trimmed, the patched module will be:

Summary

  • Trimming augmented nodes preserves the XML namespace by modifying the augmenting module.

  • For augmented nodes defined via shared groupings, the trimmer clones the grouping, applies trimming to the clone, and updates the augmentation to use the clone.

  • This approach ensures precise, localized trimming without affecting other schema parts.

Resolving Dependencies

When trimming YANG schemas, resolving dependencies is crucial to maintain schema integrity and ensure successful compilation of the patched modules. The trimmer tool automatically handles these dependencies using the following approaches:

1. Leafrefs

  • If a node to be trimmed is referenced by other nodes as a leafref, the tool automatically inlines the node type into all such references. This means the leafref is replaced by the actual type of the referenced node, removing the dependency on the trimmed node.

2. Augments, Deviations, and Refines

  • YANG statements such as augment, deviation, and refine that refer to a trimmed node are themselves automatically trimmed.

  • This ensures no dangling references remain in the schema.

Example Scenario

Consider three YANG modules:

  • Base module (trim-schema) defines a grouping ab with leaves a and b, a container top using ab, and a list sublist also using ab. It has a leaf active of type leafref pointing to ../sublist/a.

  • Augment module (trim-schema-test-aug) augments /conf:top/conf:sublist with a grouping extra containing leaves x and y.

  • Deviation module (trim-schema-test-dev) deviates leaf b in /conf:top/conf:sublist to replace its type.

If the node /conf:top/sublist is trimmed, the trimmer tool patches the modules as follows:

  • In the base module, the sublist list is removed (trimmed), and the leafref type for active is replaced by the inlined type (string) from the original leaf it referenced.

  • In the augment module, the augment statement for /conf:top/conf:sublist is removed.

  • In the deviation module, the deviation for /conf:top/conf:sublist/conf:b is removed.

This automatic resolution ensures the patched YANG modules remain consistent and compilable as shown below.

8.2.2 Usage

This is a detailed guide on using the NED built-in rebuild tool with the trim-schema filter for trimming YANG schema nodes:

Using the NED Built-in Rebuild Tool (RPC)

This is the recommended method to trim schema nodes. You invoke the rebuild tool via any NSO northbound interface and specify the trim-schema filter.

Basic Command Structure:

Options for the trim-schema Filter:

  • all-unused: Trim all currently unused nodes in the schema.

  • all-with-status: Trim all nodes annotated with specific 'status' statements (e.g., deprecated, obsolete).

  • method: Select the trimming method.

  • nodes: List specific nodes to trim by their full schema paths.

  • nodes-from-file: Specify a file containing a list of schema paths to trim.

Trimming Specific Nodes from the Command Line

Use the nodes option to specify one or more nodes by their full schema paths.

Example:

See chapter 8.2.3 on how to find out the full schema path for a any node in the schema.

Trimming Nodes from a File

If you have many nodes to trim, list them in a file (one schema path per line). Lines not starting with / are treated as comments.

Example file content:

Invoke the rebuild tool with:

Trimming All Deprecated and/or Obsolete Nodes

Third-party YANG models often contain many deprecated or obsolete nodes. Trimming these is usually safe and is a straightforward way to reduce schema size.

Trimming All Unused Nodes

This option trims all nodes not currently used in the NSO CDB database. Use with caution as it can be drastic.

Customized Trimming Using show-loaded-schema Tool

To create a customized list of nodes to trim, use the show-loaded-schema tool to extract schema paths based on filters.

Example:

  • To list all currently used nodes (populated in CDB):

    An alternative is to use the standard show running-config command like below:

    The output of this command displays instance xpaths, which differ from schema paths. To obtain the schema paths, you must perform the following extractions:

    • Remove the preceding path /ncs:devices/device['dev-1']/config from each xpath of interest.

    • Eliminate all xpath predicates, meaning everything enclosed within and including the square brackets []To list all unused nodes:

  • To list unused nodes under a specific subtree:

  • To list all deprecated nodes:

  • To list all RPCs in the schema:

You can then concatenate and edit these files to create a final list of nodes to trim.

Note:

  • Keep in mind, that nodes removed or commented out from the file are the ones that will not be trimmed.

  • The list includes nodes and their subnodes; including subnodes is optional but harmless.

After preparing the file with nodes to trim, rebuild the NED package:

Using a Unix Shell

Alternatively, rebuild the NED package directly from a Unix shell by specifying the trim filter file:

8.2.3 Schema Path Formats

When specifying schema paths for the trimmer tool, it is essential to use the full raw schema path, including prefixes whenever there is a namespace change. This is generally straightforward except for YANG choice statements. In the case of choice statements, both the choice node and the relevant case node must be included in the path.

For example, consider the following YANG module snippet:

In this example, the leaves x and z are defined within a YANG choice construct. To trim these leaves, the following full schema paths must be specified:

  • /conf:top/sublist/my-choice/first/x

  • /conf:top/sublist/my-choice/z/z

Note the extra z in the second path. This is because the leaf z is defined without an explicit surrounding case statement in the YANG. In such cases, the schypp tool adds an implicit case node to the schema when building the in-memory representation, which must be reflected in the path.

Thus, when trimming nodes under choice statements, always include both the choice and case nodes explicitly in the schema path to ensure correct trimming by the tool. For all other nodes, specifying the full raw schema path with appropriate prefixes is sufficient.

Using the show-loaded-schema tool is highly recommended to generate accurate and properly formatted schema paths for your schema trimming or filtering tasks.

8.2.4 Limitations

Schema trimming is an advanced process designed to handle complex YANG constructs. It has been tested with third-party YANG models from multiple vendors such as Cisco IOSXR, Juniper JunOS, Nokia SROS, Nokia SRLinux, Arista EOS, and OpenConfig.

However, due to the vast number of schema nodes and possible combinations, not all scenarios can be exhaustively tested, and the tool should be considered experimental.

Currently, the schema trimming tool does not support trimming of YANG unique statements. This limitation means that nodes or constraints defined using the unique statement in YANG models cannot be trimmed by the tool at this time.

8.3 Auto-config Filtering

Auto-config filtering in NSO is designed to address device configuration artifacts known as auto-config. These artifacts occur when a device automatically applies additional configuration related to the configuration explicitly deployed by NSO. For example, if NSO applies configuration A, the device will automatically also set configuration B.

NSO maintains its own Configuration Database (CDB) as the source of truth, so any auto-configured nodes not explicitly managed by NSO will immediately cause out-of-sync issues.

Devices exhibiting auto-config behavior are very common. There are basically three main strategies to handle this in NSO:

  1. Ignore the auto-config artifacts: Accept that out-of-sync states may occur if they are not critical for the use case.

  2. Adapt the services: Modify service logic to explicitly configure the auto-configured nodes s (e.g., A + B). This keeps NSO in sync but can be complex. It may also cause issues for example during rollback if the device does not handle explicit deletion of auto-config nodes well.

  3. Remove auto-configured nodes from the schema: This approach removes the auto-configured nodes from NSO's schema so that NSO is unaware of them, preventing out-of-sync issues caused by these nodes.

Auto-config filtering focuses on this third option to improve synchronization by filtering out device-generated configuration artifacts.

8.3.1 How it Works

The auto-config filtering in NSO works by identifying nodes that get auto-configured by the device after a service commits configuration. This process relies on two snapshots of the running configuration:

  • The before snapshot is taken immediately after the intended configuration has been committed on the device. It reflects the configuration that NSO intended to set.

  • The after snapshot is taken after a subsequent sync-from operation. It reflects both the intended configuration and any additional auto-configured nodes the device has applied.

By comparing these two snapshots, auto-config filter generates a diff that corresponds to the auto-configured configuration. The filter then uses this diff to generate an extra YANG deviation file. In this file, all auto-configured nodes are tagged with a not-supported statement, effectively removing them from the schema once loaded into NSO.

For example, the deviation file may look like this:

This deviation file is created in a pre-processor step and then compiled together with the remaining YANG files, ensuring that the auto-configured nodes are excluded from NSO's schema and thus preventing out-of-sync issues caused by device auto-configuration.

8.3.2 Usage

To ensure proper functionality, confirm that the NED is fully operational with its complete schema built-in. This can be achieved by following the initial setup steps outlined in chapters 1.2 - 1.4, possibly followed by installation of your service packages.

Before you can utilize the auto-config filter, it is essential to create two snapshots. Follow these steps:

  1. Perform an initial sync-from operation.

  2. Apply the desired configuration to the device (e.g., via a service).

  3. Execute show running-config and save the output in XML format to a file named before.xml. This specific file name is mandatory.

  4. Perform a new sync-from operation.

  5. Execute show running-config again and save the output in XML format to a file named after.xml. This specific file name is also mandatory.

Once these steps are completed, you are ready to use the auto-config filter.

Using the NED Built-in Rebuild Tool (RPC)

The recommended method for trimming schema nodes is by using the NED built-in rebuild tool. You can invoke this tool via any NSO northbound interface, specifying the auto-config filter.

Basic Command Structure:

Options for auto-config Filter:

  • dir: Specifies the directory containing the before.xml and after.xml files used for auto-config filtering.

  • file: An optional parameter for the name of the auto-generated deviation file.

Using a Unix Shell

Alternatively, you can rebuild the NED package directly from a Unix shell. This method is slightly more complex and does require multiple tests.

  1. Generate the deviation file:

  2. Rebuild the NED package

8.3.3 Examples

This simple example demonstrates how to effectively use the auto-config filter to remove automatically configured artifacts from a device. For this example, we assume a basic service named my-service has already been installed.

First, ensure the NED is fully operational with its complete schema by following the initial setup steps outlined in chapters 1.2 through 1.4.

Next, configure and commit a new instance of the my-service service. The commit is labeled '1' to facilitate restoring the device to its previous state if needed.

Now, save the current running configuration to the file: /tmp/auto-config/before.xml.

Optionally, you can perform a compare-config at this stage. This action should generate a diff, indicating that the device indeed has automatically configured certain elements..

Proceed by performing a sync-from operation. This action will populate the CDB with the auto-configured settings from the device.

After the sync-from, save the new running configuration to the file: /tmp/auto-config/after.xml.

Optionally, you may choose to restore the device to its previous state. To do this, first identify the commit ID associated with the label '1' by viewing the rollback files:

Then, you can rollback and commit the configuration:

Finally, rebuild the NED package by utilizing the auto-config filter.

After rebuilding the package, reload it to apply the changes.

8.3.4 Limitations

The auto-config filter employs a best-effort approach. It's important to note that if any automatically configured nodes overlap with the configurations being deployed through NSO, these overlapping nodes cannot be removed.

For instance, consider a scenario where you create a new entry in a list on the device, and the device subsequently adds another entry to the same list. In such a case, this list node cannot be made to disappear, as doing so would prevent the application of the initial configuration.

Since the auto-config filter leverages YANG deviations, it does not impact the resulting schema size. In other words, using an auto-config filter will not reduce the overall schema size.

9. Advanced: Issues Solvable with Schema Customization

This chapter addresses various issues and problems, all of which can be resolved using the schema customization techniques detailed in the preceding chapters. Each of these listed issues stems from real-world support cases, involving a range of different devices and third-party YANG NEDs.

The intention is for the described issues and their solutions to serve as an inspiration or a foundational knowledge base for other challenges that may arise when working with third-party YANG NEDs.

9.1 Excessive RPCs Leading to Unresponsive NSO CLI

Third-party YANG models can include a substantial number of Remote Procedure Calls (RPCs). For instance, a recent JunOS YANG distribution may contain over 6500 RPCs.

It has been observed that when all these RPCs are incorporated into the NED package, the NSO CLI can become unresponsive, especially affecting tab completion, when a user attempts to invoke them.

Should this unresponsiveness pose a problem for end-users, a simple workaround is to remove all unnecessary RPCs from the schema. In most scenarios, it is highly unlikely that all available RPCs would be needed.

Step-by-Step Guide: Trimming RPCs from the schema

First, ensure the NED is fully operational with its complete schema by following the initial setup steps outlined in chapters 1.2 through 1.4.

  1. Use the show-loaded-schema tool to list all RPCs currently installed in the NED package:

    This command will generate a file containing the schema paths for each defined RPC.

  2. Open and edit this generated file.

    Comment out (by adding a # at the beginning of the line) the RPCs you wish to keep, as shown in the example below:

  3. Rebuild the NED package using the trim-filter feature:

  4. Finally, after rebuilding the package, reload it to apply the changes:

9.2 Removing Deprecated Nodes from the Schema

The YANG modeling language supports annotating schema nodes with status information. Two status values, in particular, indicate that nodes are scheduled for removal in future model versions:

  • deprecated: The node is still supported but its use is no longer recommended.

  • obsolete: The node is no longer supported and should not be used.

If you want to reduce the size of a third-party YANG schema, a logical first step is to consider removing deprecated and/or obsolete nodes, since their use is already discouraged.

Currently, the NSO YANG compiler (yanger) does not provide a built-in method to automatically trim such nodes. However, you can achieve this using the schema trimming build filter, which removes specified nodes from the YANG modules before compilation.

Step-by-Step Guide: Trimming deprecated and obsolete nodes from the schema

  1. Check for deprecated/obsolete nodes:

    First, verify whether the schema contains any nodes with these statuses. The following example command counts all nodes with a status of deprecated or obsolete

    If the tool returns a number greater than zero, the schema contains nodes with the specified statuses.

  2. Rebuild the NED with the trim filter:

9.3 Identifying Problematic XPath Expressions Causing Performance Degradation in NSO

Many third-party YANG models are annotated with additional expressions to describe dependencies between different nodes in the schema. Typically, these dependencies are defined using xpath expressions in must or when statements, or by using the leafref type.

These kinds of dependency rules are always computationally intensive for NSO. Depending on how the xpath expressions are constructed, they can significantly impact overall NSO performance.

It can be very difficult for an end user to understand why a particular operation in NSO suddenly takes an unusually long time to complete. Identifying which specific xpath expression is causing the issue can be even more challenging.

Real Case Description:

This example is based on a support case involving the third-party YANG NED for Huawei VRP NETCONF. The VRP YANG models contain numerous dependency rules - about 4,000 must statements and 3,000 when statements in a recent distribution.

A delete operation of an interface instance led to unresponsiveness in the NSO CLI, as illustrated below:

When this kind of unresponsiveness occurs, it is often due to NSO having to evaluate poorly designed xpath expressions.

In this case, even the "no operation" during an open transaction took an unacceptably long time, suggesting that xpath calculations were involved-likely due to inefficient when statements. NSO verifies when expressions every time changes are made in an open transaction.

During the commit phase, NSO performs even more thorough verification of all dependencies, including all must, when, and leafref statements.

Step-by-Step Guide: Finding Problematic xpath Expressions

Here is a process to identify problematic xpath expressions when performance issues are suspected:

  1. Enable the NSO xpath tracer:

    Enabling the xpath tracer is essential for identifying xpath-related issues. Note that the tracer is disabled by default due to its significant impact on NSO performance. Operations like the simple delete above can take up to 10 times longer with the tracer enabled.

    To enable the xpath tracer, edit the ncs.conf configuration file located in <NSO RUNTIME DIR>/ncs.conf. Locate the <xpath-trace-log> section and ensure it is enabled:

    Restart NSO for the changes to take effect:

  2. Trigger the problematic operation:

    Reproduce the operation that causes performance issues. In our example, perform the delete operation again (skipping the commit for now to focus on identifying the initial bottleneck)

    This command will take considerable longer time to finish this time, due to the xpath tracing.

  3. Run the xpath trace analyzer tool:

    After enabling the xpath tracer and reproducing the problematic operation, an xpath trace file should now be available for analysis. This file is not intended to be read manually, as it is typically very large and in a raw format (for example, this simple case produced a 2 GB trace file).

    To simplify analysis, a new tool is included in the third-party YANG NED toolbox, the xpath-trace-analyzer:

    Command Options

    ​ • file: Path to the NSO xpath trace file to analyze (default: use the one written by the running NSO).

    ​ • number-of-entries: Sets the number of entries to display in the generated top list (default 10).

    Execute it like below:

  4. Analyze the output:

    The tool generates two top lists:

    ​ • The most frequently evaluated xpath expressions.

    ​ • The most time-consuming xpath expressions.

    Example output:

    When reviewing the top lists generated by the xpath trace analyzer, the first thing to look for is xpath expressions that use absolute paths. Absolute paths often indicate poorly designed expressions, which can significantly impact performance.

    In the example above, several absolute paths appear in the top lists. Notably, the first four entries in the "most time-consuming" list all use absolute paths, making them prime suspects for performance issues. Two of these entries share the same xpath expression defined at different locations in the schema.

  5. Identify the YANG statement using a specific xpath expression:

    The xpath tracer does not indicate exactly which YANG statement (such as when or must) is using a particular xpath expression. However, the top lists from the trace analyzer do include the schema path for each node associated with an xpath expression.

    To determine which YANG statement is using a specific xpath expression, you can use the show-loaded-schema tool.

    By referencing the schema path from the top list, it becomes straightforward to locate the relevant YANG statement:

    This will output the information we are interrested in:

    The output shows that all the problematic xpath expressions are used by when expressions.

  6. Create YANG recipes to remove problematic xpath expressions:

    You can trim the schema of problematic must and when statements by adding new YANG recipes and then rebuilding the NED.

    In this scenario, you need to add specific pragmas to the schypp YANG pre-processor. These pragmas will automatically modify the schema before the YANG files are compiled.

    Open the file $NED_ROOT_DIR/src/customize-schema.schypp and add the following lines to the file:

    The pragmas above should be self-explanatory.

    In some cases it might be preferred to correct the when expressions instead of removing them. Then use the replace pragma instead of remove. Check chapter 7.2.1 for further information about the schypp tool.

  7. Rebuild the NED package and reload it:

  8. Disable xpath tracing and restart NSO:

    Finally, verify that the performance issue is solved.

Why are Absolute Paths Problematic in XPath Expressions?

Absolute paths in xpath expressions can easily expand the scope of verification in unintended ways.

In the examples above, all the absolute paths reference the interfaces section of the schema-specifically, the node /ifm:ifm/ifm:interfaces/ifm:interface, which represents a list of interfaces.

Since these expressions do not specify a particular interface (for example, by using xpath predicates), NSO must evaluate the condition against every interface instance in the list. The more interfaces that are configured, the longer the evaluation takes. In this specific case, there were about 750 interfaces configured, resulting in significant performance degradation.

Important: There is no way for NSO to automatically protect itself against problematic xpath expressions. Such expressions should be regarded as bugs in the YANG model. They must be fixed - ideally by the third-party YANG vendor - or removed from the schema.

9.4 Solving Issues Related to the NSO Brownfield Feature

With the release of NSO 6.5, a new feature was introduced to better manage brownfield network setups. In such environments, agents other than NSO — including manual operators, automation scripts, or other orchestrators — can deploy configurations to network devices. A key challenge for NSO when orchestrating a brownfield network is that it is likely to be perpetually out of sync with the network's actual configuration.

Frequent "sync-from" operations are often ineffective in a brownfield network. To address this, NSO 6.5 introduced the new confirm-network-state commit feature, specifically designed for brownfield scenarios. A comprehensive description of this feature can be found in the NSO documentation. In essence, this feature ensures that NSO thoroughly verifies the network's current state as an initial step before committing new configurations. From a 3PY NED perspective, this typically involves one or more additional read operations towards the device, often performed as partial sync-from operations.

The confirm-network-state feature relies on the schema to determine which schema paths to validate during these read operations. Furthermore, it completely depends on the schema precisely matching the configuration tree on the target device for these read operations.

This dependency can lead to problems with third-party YANG models because there's no guarantee that these models perfectly correspond to the devices advertising them. In fact, it's common for third-party YANG models to be constructed as a superset, covering multiple device types.

Example:

To illustrate this problem, consider the simple YANG model below. This model acts as a superset, simultaneously supporting both device type A and device type B.

Now, imagine NSO needs to delete an entry from the /conf:/common-settings/master list on a device of type A. Since the network is brownfield and NSO is out-of-sync, the confirm-network-state feature will be engaged.

When deleting an entry from the /conf:/common-settings/master list using this commit feature, NSO must first verify that the entry is not referenced elsewhere. The schema includes two other lists that reference the master list. Consequently, NSO will query the device for all entries in both /conf:device-type-A-settings/used/used and /conf:device-type-B-settings/used/used.

However, the device itself is of type A and has no knowledge of the path /conf:device-type-B-settings/used/used. As a result, it will return an error for any read operations attempting to access that path.

How Common is This?

The use of superset third-party YANG models is quite common. A prominent example is the Nokia SROS models, which encompass all devices utilizing the SROS platform. Another instance can be found in vendor-neutral models like OpenConfig. Vendors that claim support for such models typically only implement a fraction of the full schema. While some vendors handle this appropriately by using YANG deviation modules to remove unsupported parts, others simply disregard this discrepancy.

It's also worth noting that most of the standard NEDs developed by the Cisco NSO NED team also employ superset YANG models.

How Severe is This?

The severity of this issue largely depends on the management protocol in use. For certain protocols, such as RESTCONF, it's often possible for the NED to ignore errors returned on specific read paths.

Unfortunately, the NETCONF protocol is particularly susceptible to this problem. This is because NETCONF can consolidate all paths to be read into a single request, which is usually very efficient as it minimizes round trips. However, if an invalid path is included among the valid ones, the device will return an error instead of any useful data.

For NETCONF, the partial-show operation in the previous example would typically appear as follows:

And a typical NETCONF device would respond with an error similar to this:

How to Solve the Problem?

Fortunately, a solution exists for this type of problem: utilizing the schema trimming feature available in every 3PY NED.

By first customizing the schema to precisely map to the device it will be used with, it will no longer function as a superset. This involves removing parts of the schema that are not relevant to the specific device — a task ideally suited for the schema trimmer feature.

Determining which nodes to trim can be quite challenging — often requiring consultation of device documentation — and can be a tedious process.

The 3PY NED toolbox can offer valuable hints on what should be trimmed, as will be demonstrated with the example below.

Real Case Description

This example is based on a real support case involving the third-party YANG NED for Nokia SROS NETCONF. It demonstrates how an issue encountered when using the confirm-network-state commit feature can be resolved by rebuilding the NED with the schema trimming feature.

The problem was triggered by a seemingly straightforward delete operation for a single list entry: association 123

The commit failed, and the device reported an error related to a seemingly unrelated node: service-activation-testhead.

Let's examine the NED trace to understand why. The additional read operation required by the confirm-network-state feature appears as follows:

Each XML element within the filter above represents a path that NSO attempts to read from the device. In this case, NSO needs to inspect ten different paths to successfully remove the association 123 list entry.

A relevant question here is, "Why?"

The built-in show-loaded-schema tool can help answer this. To inspect the schema corresponding to the association list, the details option is necessary.

The output will appear as follows:

The output reveals that 17 other nodes within the schema are defined as leafrefs pointing to the ma-admin-name key element in the association list. One of these nodes has a schema path beginning with /conf:configure/test-oam/service-activation-testhead.

Evidently, the device we are connected to does not support this specific schema node.

Therefore, it is necessary to remove this node from the schema embedded within the NED package. This is achieved by rebuilding the NED with a schema trim filter:

Next, reload the NED package:

To verify the removal of the /conf:configure/test-oam/service-activation-testhead node, execute the following command:

The output now appears as follows:

The ma-admin-name is no longer referenced from the path beginning with /conf:configure/test-oam/service-activation-testhead.

Finally, confirm that the delete operation is now successful:

In some cases, it might be necessary to repeat this procedure until the commit finally succeeds. In this specific example, there are potentially 16 additional nodes that might also require trimming.

10. Migrating From the Legacy IOSXR NETCONF NED

This chapter provides a step-by-step guide for migrating an existing NSO installation from the legacy IOSXR NETCONF NED to the new 3PY NETCONF NED for IOSXR.

The onboarding process includes:

  • Setting up the 3PY NED for different IOSXR versions.

  • Migrating each device instance to use the new 3PY NED

  • Adapting existing services to work with the new 3PY NED

  • Phasing out the old legacy NEDs for IOSXR

Scope

Overview

An IOSXR device typically supports three different families of YANG models:

  • Native classic models: YANG file names starting with Cisco-IOS-XR-

  • Native UM models: YANG file names starting with Cisco-IOS-XR-um-

  • Openconfig models: YANG files names starting with openconfig-

These three families largely overlap, meaning the same configuration can often be read or set using more than one model. For this reason, it is best to avoid mixing YANG models from different families when building a NED for this type of device. This is a crucial rule to remember.

Failing to follow this guideline can easily result in out-of-sync issues when working with NSO. For example, suppose you have two models, A and B, both included in the NED and both representing the same configuration element, x, on the XR device. If you use A:x to set the configuration and then perform a config compare, you may find that both A:x and B:x have been set on the device. This situation, which the NED team refers to as "config whac-a-mole" cannot be resolved simply by performing a sync-from operation. Eventually, when undeploying, NSO may attempt to delete both A:x and B:x in a single transaction, which the device will reject, resulting in an error.

There are additional benefits to minimizing the number of models included in NED packages. XR models are quite large and consume significant memory when loaded in NSO. Reducing the number of models not only decreases NSO's memory footprint but can also improve its responsiveness.

It is worth noting that the legacy IOSXR NED packages always included both classic and UM models. This is due to historical reasons.

Approach

The recommended approach is to replace all legacy XR NEDs with 3PY NEDs that include only the native UM models, as these are typically the most widely used for IOSXR.

However, UM models do not cover all possible configuration elements. Some IOSXR configuration can only be accessed through other model families.

If your services rely on configuration elements from multiple YANG families, you have two options:

  1. Include all required model families when downloading YANG files and rebuilding the NED. This is the quick-and-dirty approach and is prone to the problems described earlier.

  2. Rebuild the NED by selectively including (“cherry-picking”) models from the required families so that the NED covers your use cases while avoiding overlap. This process is described in Chapters 8.1 and 8.2, and an IOSXR example is provided in the optional step 15 below.

Step 1: Install the 3PY NED for IOSXR NETCONF

Download, extract, and install the NED package on your local NSO installation as described in Chapter 1 of the README.md.

Execute the following command in the NSO CLI:

Check that the package has been installed correctly by running:

Step 2: Identify the IOSXR Versions in Use

Determine which versions of the IOSXR legacy NEDs are currently used by the NSO device instances. These versions correspond to the IOSXR YANG bundles that will be needed when building the 3PY NEDs.

To check the versions, follow these steps in the NSO CLI to display the NED-IDs used by the legacy NED:

Example output:

The NED-ID of a legacy NED is identified by the prefix cisco-iosxr-nc-followed by a version number, which corresponds to the IOSXR version it supports.

In this guide the legacy NEDs for IOSXR version 7.10 and 24.2 will be used as examples, along with the corresponding device instances xrv-710 and xrv-242.

Step 3: Retrieve Connection Information for Devices

The next step is to gather the connection details for the device instances that will be migrated. For each device, record the relevant information such as address, port and authgroup.

Step 4: Create a Dummy Device Using the 3PY NED

This dummy device will serve as the 3PY NED factory when building customized packages for each IOSXR version.

For this step, configure the dummy device to point to the first device in your selection, for example: xrv-710.

Note: The device-type must be set to generic and ned-id to cisco-iosxr_nc-gen-1.1.

Sample NSO Configuration:

Steps:

  1. Commit the configuration.

  2. Fetch the SSH host keys for the dummy device.

    Expected result:

Step 5: Prepare the 3PY NED - Download, Rebuild, Export, and Clean

The following 3PY NED setup procedure must be performed separately for each IOSXR version in use. This ensures you generate customized 3PY NED packages tailored to each version.

Important Notes:

  • It is at this point assumed that the services utilize IOSXR UM YANG models only. Therefore, only the IOSXR UM models will be selected during the download step.

  • Use a unique NED ID representing the selected IOSXR version when rebuilding the 3PY NED.

  • Use a unique package suffix when exporting the rebuilt NED, so each customized 3PY NED package is clearly identifiable by version.

Procedure (Example for XR 7.10):

In the NSO CLI, execute:

Repeat this process for each additional IOSXR version (24.2):

  • Update the demo device's connection info to point to the corresponding device instance (i.e., change address, port and authgroup).

  • Download the appropriate YANG models for the new device.

  • Rebuild the NED with the correct major and minor version values.

  • Export the package using a suffix that matches the XR version (e.g., -um-24.2 etc).

  • IMPORTANT: Always run the clean step (rpc-clean-package) between each iteration to ensure a fresh environment for the next build.

Step 6: Restore the Original 3PY NED Package

After building and exporting the customized 3PY NED packages for each IOSXR version, restore the original 3PY NED package to its default state. This involves rebuilding it without any device models included. Doing so prevents warnings or errors during the next packages reload.

In the NSO CLI, execute:

Step 7: Install the Exported 3PY NED Packages

Now, install each of the 3PY NED packages you previously exported to /tmp/prebuilt-neds into NSO.

Follow the instructions described in chapter 1 the README.md.

Next, reload the packages in the NSO CLI:

This step might show warnings about some service packages failing to load. This is related to NED-ID conditionals defined in the service templates. For the moment this can be ignored.

Example:

Verify install

In the NSO CLI, execute:

Expected output:

Step 8: Prepare for NED Migration (First Iteration)

Begin by performing a dry-run NED migration for all configured device instances. This allows you to assess the migration impact and identify any potential issues before applying actual changes.

Dry-Run NED Migration

Run the following commands for each device, according to their respective IOSXR versions. The output will be saved for later analysis.

For the device using IOSXR 7.7:

In the NSO CLI, execute:

For devices using IOSXR 24.2:

In the NSO CLI, execute:

Note: The arguments no-networking and no-templates are optional. They were relevant for this example but may not be necessary in other cases.

Analyzing the Dry-Run Output

When reviewing the generated dry-run migration files, look for the following patterns, which indicate potential issues:

Pattern 1: Unused Config Nodes

Interpretation:

These entries mean the new schema does not contain the corresponding node. If this data is not used by any service (i.e., it is just unused config synced into NSO/CDB), it is generally safe to proceed with the NED migration.

Pattern 2: Service-Dependent Nodes

Interpretation:

These entries mean the new schema lacks a node that is referenced by a service. Migrating the NED may cause the service to malfunction.

In the example above a node that belongs to the native classic model family for XR is being referenced by a service. It is not available in the new schema based on UM models only.

To solve this it is necessary to either rebuild the NED package and include the models for the native classic as well, or by cherry picking models as described earlier.

Note: In some older NSO versions, you may see warnings like the one below. These warnings are harmless and can be safely ignored.

Step 9: Execute the NED Migration

Now it is time to perform the actual NED migration for each device. This step will update each device instance to use the models from the corresponding 3PY NED package instead of the legacy NED. The new configuration will be committed to the NSO CDB.

Procedure:

  • For each device, run the migration command with the appropriate new-ned-id matching the correct 3PY NED package.

  • Verify that the migration completes successfully.

Example:

In the NSO CLI, execute:

Verify:

All devices instance shall now be connected to a NED-ID starting with: cisco-iosxr_nc

In the NSO CLI, execute:

Expected output:

Do a compare-config to check if NSO is still in sync with the devices.

In the NSO CLI, execute:

Expected output, is no diff showing.

Step 10: Change device type on each device instance

Before completing the migration to the new 3PY NEDs, it is essential to update the device-type for each device instance in NSO. Currently, the device-type is set to netconf to match the legacy NED. It must now be changed to generic to ensure compatibility with the 3PY NED.

Important:

This step is critical. If you skip it, NSO will continue to use its internal NETCONF client instead of the customized NETCONF client provided by the 3PY NED package.

How to update the device-type:

For each device instance, update the configuration as follows:

Replace <device-name> and <corresponding-3PY-NED-package> with the appropriate values for your environment.

Example:

In the NSO CLI, execute:

After updating the device-type on each device instance, make sure to commit the changes to apply them in the NSO CLI:

Step 11: Phase out the legacy IOSXR NED packages

At this stage, there are no device instances remaining that use the legacy NEDs. Therefore, it is now safe to remove all legacy NED packages. While this step is not strictly required, it will reduce NSO's memory footprint and may also improve its responsiveness.

To remove the legacy packages, run the following commands in a bash shell:

Step 12: Adapt the Service

Some service packages will likely need updates to work with the new 3PY NED packages. This section provides an overview of the key changes that may be required:

  • Update the YANGPATH in each service package's Makefile to reflect dependencies on device YANG files.

  • Rebuild the service packages.

  • Adjust the XML templates, especially conditionals that depend on NED-IDs.

  • Review and update schema paths referenced by the service logic.

Update the YANGPATH Variable

Begin by updating the YANGPATH variable in each Makefile to point to the new 3PY NED packages. You can apply the change to all Makefiles at once using:

Rebuild All Service Packages

After updating the Makefiles, rebuild all service packages to ensure they are compiled against the updated dependencies.

Adjust the Schema Paths

This is an area where the legacy IOSXR NED differs significantly from the new 3PY NED.

The legacy IOSXR NED was built using the YANG compiler flag --prefix module-name. This flag instructs the NSO YANG compiler to use the module name as the prefix instead of the prefix defined inside the YANG file. This approach was necessary to avoid prefix collisions between YANG modules in NSO, especially since the legacy IOSXR NED did not have access to YANG pre-processor tools like YPP to resolve such conflicts differently.

In contrast, the 3PY NED uses the prefix defined in each YANG file by default, aligning with standard YANG module conventions and simplifying schema path references.

The YANG snippet below illustrates the difference.

  • Legacy NED prefix: Cisco-IOS-XR-um-interface-cfg

  • 3PY NED prefix: um-interface-cfg

This difference affects all service code that references schema nodes — including XPaths and Maagic paths. These will need to be updated accordingly.

XPaths

Legacy NED XPath example (module name as prefix):

3PY NED XPath example (YANG-defined prefix):

Maagic Python Paths

Legacy NED Maagic path (module name adapted to Python identifiers):

3PY NED Maagic path (YANG-defined prefix adapted to Python identifiers):

Recommended Approach

When migrating to the new 3PY NED for IOSXR, it is strongly recommended to update your services to use the YANG-defined prefixes. In many cases, this can be done using simple search/replace tools such as sed.

Alternative Option (Use With Caution)

If updating all prefixes would require excessive effort, you can rebuild the 3PY NED so that it uses module names as prefixes, matching the legacy behavior. However, this option should be used cautiously, as it may introduce unexpected side effects.

Additionally, you must explicitly configure the NSO device instances using the rebuilt NED to accept module-name-based prefixes. The schema-aware transform engine in the NED still defaults to the YANG-defined prefix unless configured otherwise.

Rebuild the NED package with module names as prefixes:

Configure a device instance to accept module names as prefixes:

Adjust the Service Templates

Many service templates include conditional checks based on the NED-ID. To ensure continued functionality after migration, these templates must be updated to recognize and use the new 3PY NED-IDs.

Step 13: Reload and Verify the Service Packages

At this stage, everything should be ready for onboarding the 3PY XR NEDs. The next step is to perform a final reload of the packages in NSO to ensure all changes are applied.

Since the legacy NEDs have been removed, it is necessary to use the force flag when reloading the packages.

In the NSO CLI, execute:

Carefully review the output of this command. Warnings such as the example below indicate that further adjustments may be needed as described in step 12:

Step 14: Test the Services

Once all packages have been successfully reloaded, the system is ready for testing the services.

Begin by loading some sample configuration for your service and perform a commit dry-run with the output format set to native.

In the NSO CLI, run:

Expected output:

The initial lock sequence shown above is a reliable indicator that the 3PY NED is now in use:

If you see this output, it confirms that the new 3PY NED has been successfully integrated and is operational.

Optional Step 15: Rebuild Scope Filtered 3PY NED Packages

As described earlier in this guide, including YANG models from different families within the same NED package can introduce risks. If some services depend not only on the native UM models but also on nodes defined in for instance the native classic models, the quick workaround has been to build 3PY NED packages that include both families.

A better approach is to select only the models actually used by the services and rebuild the 3PY NED based on this selection. This method is called scope filtering and can be enabled by providing additional arguments to the 3PY NED rebuild tool. For more detais on this, see chapter 8

The following example demonstrates this process using the device instance xrv-710 as the target device.

Collect Use Cases

The scope filter feature requires use cases to determine which YANG models to include. These use cases can be the device's existing day0 configuration, or configuration snippets that will be deployed through services. Store each config snippet as an XML file.

In this example, we'll collect both the day0 configuration and a day1 config generated by a service sample. Note:

In a shell:

Then do the following in the NSO CLI:

Setup the Demo Device

The demo device must point to the same target as xrv-710.

Download All Models

Now, prepare to rebuild a customized 3PY NED package using scope filtering. Start by downloading all models for both the UM and classic YANG families.

In the NSO CLI:

Address YANG Quirks

A glitch may occur when rebuilding XR models with a scope filter, related to certain system-level YANG files. As a temporary workaround, copy these files to your local 3PY NED YANG directory:

In a shell:

Rebuild and Export

In the NSO CLI:

Restore the 3PY NED Factory Package

To clean up and restore the original 3PY NED factory package, run:

Comparison

For reference, here's a comparison of the number of YANG models included in different NED packages, when using a simple example service package.

  • Legacy cisco-iosxr-nc-7.10: 1442

  • 3PY cisco-iosxr_nc-um-gen-7.10: 333

  • 3PY: cisco-iosxr_nc-customized-gen-7.10: 54

PreviousREADME-ned-settingsNextREADME v1.1.1 2025-10-21

Last updated

Was this helpful?