This NED is equipped with a number of runtime configuration options "NED settings" allowing for customization by the end user. All options are configurable using the NSO API for NED settings. Most NED settings can be configured globally, per device profile or per device instance in the following locations:
global /ncs:devices/global-settings/ned-settings/nokia-sros_nc/ profile /ncs:devices/ncs:profiles/profile:/ned-settings/nokia-sros_nc/ device /ncs:/device/devices/device:/ned-settings/nokia-sros_nc/
Profiles setting overrides global-settings and device settings override profile settings, hence the narrowest scope of the setting is used by the device.
If user changes a ned-setting, then user must reconnect to the device, i.e. disconnect and connect in order for the new setting to take effect.
From the NSO CLI the device instance NED settings for this NED are available under:
This file describes the ned-settings for nokia-sros_nc.
Settings affecting different aspects of NSO transactions towards device.
Configure additional device errors that shall be treated as warnings (i.e. to be ignored, not aborting transaction).
This list can be used to add extra filters when sending get-config RPC to the device. For example if there is a bug in the device which makes it not include all config under certain top-nodes. The key of the list is the path to add (non-unique nodes must be prefixed with 'global' prefix, i.e. prefix from module).
This list can be used to filter out certain namespaces from the configuration (i.e. all nodes belonging to namespaces given in this list will be dropped from the config before sent to NSO).
Inject tailf:meta-data extension into schema at given path, used for example to trigger xml transform methods (java methods annotated with XMLTransformMethod) before xml is sent to NSO, or when editing, to device. The meta-data can also be used for other purposes in custom java code in the NED. The path supplied can even be a key-path, i.e. containg list keys within curly braces.
NOTE: For more information about custom xml transforms, see section 'Custom XML transforms' in the README.md.
Control NED behaviour regarding 'bof' settings.The SROS devices regard 'bof' settings as a separate datastore, meaning that it is not permitted to deploy together with standard config.
Settings related to the initial connection to the device, including the initial hand-shake (hello).
Settings related the netconf capablities, and the discovery of supported yang modules.
List of regex patterns to use for excluding capabilities sent from device in hello, for example to exclude a capability which the device announces in hello, but which is not correctly implemented
List of regex patterns to use for including capabilities sent from device in hello. Note that when this list is non-empty, only capabilities matching any of the patterns in this list will be included
This list can be used to inject capabilities into the hello from the device, before processed and sent to NSO, for example if a capability sent from the device is invalid, it can be filtered out using 'regex-exclude', and replaced with an inject. Also if device leaves out a capability that should be present and is needed, it can be injected.
Settings related to the SSH client used by the NED to connect to the device.
Configure NED to access device via an ssh proxy (i.e. a ssh 'jump-host'). By default, when this options is used, the address, port, and credentials normally given for the device in NSO, is used as the address and credentials for the ssh proxy, in which case the ned-settings here are then used to access the actual device.
This 'reverse' logic is the effect of how the API historically worked, and can be changed by enabling the setting 'global-proxy'. When this setting is set to true, the device config is the address/port and credentials for the actual device (behind the proxy), and the proxy host is configured in this section. This means that the proxy can be configured globally, or in a profile, which is a convenient way to switch all or some devices to connect through a jump-host.
Configure NED settings related to live-status.
This list of regular expressions match the schema path of nodes to filter out from live-status (oper) data before sending it to NSO. The regex matches on either of the pure tag-path, 'global' path, or the key-path (i.e. possibly including keys within curly braces) of nodes in the data. I.e. if a path is unique, prefixes can be omitted, but not when used in a key-path, then a 'global' path is needed, i.e. prefixed as it would appear in NSO, including the prefix on each level where new namespace occurs.
Configuration of CLI interaction through 'exec any '.
Sometimes when entering commands in an interative shell, the device prompts for some specific input, in cases like this, this list can be configured with pairs of "questions" and "answers" to be used when interacting with the device. The "questions" are in the form of regular-expressions, which matches the prompt or "question" output from the device, and the "answers" are the string to send back to the device, when that specific "question" is found in the output from the device.
For example, to add the response "secret" for a password prompt, one can add the below ned-settings:
Settings for controlling logs generated.
Contains settings used by the NED developers.
# config
# devices device dev-1 ned-settings nokia-sros_nc
Press TAB to see all the NED settings.
1. ned-settings nokia-sros_nc
2. transaction
2.1. ignore-rpc-errors
2.2. extra-get-config-paths
2.3. exclude-namespaces
2.4. inject-meta-data
2.5. bof-settings
3. connection
3.1. capabilities
3.1.1. regex-exclude
3.1.2. regex-include
3.1.3. inject
3.2. ssh
4. proxy
5. live-status
5.1. regex-exclude
5.2. cli
5.2.1. auto-prompts
6. logger
7. developer- transaction confirmed-commit enable <true|false> (default true)
Enables confirmed-commit (if supported by device).
- transaction confirmed-commit confirm-timeout <uint16>
Timeout in seconds, if set, used as 'confirm-timeout' parameter to the confirmed-commit
(otherwise defaults to 600 seconds).
- transaction confirmed-commit persisted <true|false> (default false)
Enable this setting to use the 'persist-id' to let confirming commit be done in other session
(e.g. if closing session between commit and persist phases). NOTE: This can only be used with
devices which support netconf capability 'confirmed-commit:1.1'.
- transaction validate-before-commit <true|false> (default false)
If devices supports the validate1.1 capability, the NED will send a validate rpc before
sending the commit rpc.
- transaction persist-to-startup <true|false> (default true)
If enabled, 'running' datastore will be copied to 'startup' in NSO persist stage (if device
supports distinct startup datastore).
- transaction discard-changes-before-lock <true|false> (default false)
If enabled, and using the 'candidate' datastore, a 'discard-changes' operation will be issued
before trying to lock 'candidate'.
- transaction lock-running-before-candidate <true|false> (default false)
If enabled, and using the 'candidate' datastore, the 'running' datastore will also be locked
during transactions.
- transaction reconnect-on-commit <true|false> (default false)
If enabled, the NED will reconnect to the device after commit to ensure connectivity is not
broken (i.e. aborting the NSO commit stage if re-connect fails). This can for example be used
as an extra safeguard for early detection of invalid config being applied, which leaves the
device in an unreachable state. When used together with 'confirmed-commit' it will fail the
commit in NSO, while still leaving it up to the device to rollback the commit (since no
'confirming' commit will be sent from NSO). For devices that enforces the use of 'persist-id',
according to RFC, when using 'confirmed-commit' accross sessions, the ned-setting
'confirmed-commit/persisted' needs to be enabled aswell.
- transaction commit-in-persist <true|false> (default false)
If enabled, the NED will not send commit until in the persist phase in NSO (like a confirmed
commit, assuming config has been validated in the prepare or commit phase). Normally the
commit is sent in the NSO commit phase to be able to abort the transaction if the commit
fails, since errors reported by device in the persist phase will only lead to an alarm in NSO,
the transaction can no longer be aborted in the persist phase (i.e. the transaction must be
aborted in the prepare or commit phases for NSO to be able to rollback properly).
- transaction ignore-rpc-warnings <true|false> (default true)
By default rpc-error reply with severity 'warning' will not be treated as error, set to
'false' to treat warnings as errors (i.e. abort transaction on warnings).
- transaction report-full-rpc-error <true|false> (default false)
Enable this setting to get full rpc-error payload as message when error occurs (i.e. instead
of just error-message).
- transaction filter-invalid-values <true|false> (default false)
Filter out invalid leaf values from config before sending to NSO to avoid sync-from failure on
for example invalid range expression.
- transaction canonicalize-idrefs <true|false> (default false)
Canonicalize leaf values of type 'identityref' in config before sending to NSO, i.e.
add/change prefix to global prefix in NSO.
- transaction filter-config-by-version <union> (default disable)
Yang API version to allow (given meta-data annotations in yang models and/or injections).
- transaction get-config-no-filter <true|false> (default false)
Perform full get-config without specifying any filter at all. This applies to operations like
full sync-from and compare-config.
- transaction trans-id-method <enum> (default config-data)
Select the method for calculating transaction-id. Note that both 'config-hash' and
'config-data' will exclude config according to filtering which might be in effect,
i.e. the data used for calculating the transaction-id will be the config as it is sent
to NSO, with or without unmodeled nodes.
config-hash - Use a snapshot of the running config for calculation.
config-data - Use a snapshot of the data of only the modeled parts of running config for
calculation.
custom - Use trans-id provided by ned, e.g. a device provided time-stamp of last change
or something similar.
Either of:
- devices device ned-settings nokia-sros_nc transaction use-maapi-setvalues <true|false>
Use maapi setValues method instead of loadConfigStream to load data to NSO. This method is
very strict. Inacurracies in the loaded configuration will throw an error.
OR:
- devices device ned-settings nokia-sros_nc transaction use-maapi-load-config-cmds <true|false>
Use maapi loadConfigCmds method instead of loadConfigStream to load data to NSO. This
method is more relaxed. Inaccuracies in the loaded configuration will be silently ignored.
- transaction abort-on-diff <true|false> (default false)
Enable to detect diff immediately when config is applied (i.e. in commit/abort/revert).
If a diff is detected an exception is thrown, having the effect in commit that the transaction
is aborted (showing the diff). Note that this means some overhead in commit, where whole config
needs to be retrieved from device to do compare. The feature 'abort-on-diff' is used to detect
out-of-band changes, silently dropped config, and unknown side-effects to config (i.e. all
causing a diff compared to expected NSO state). In fact, it's the only method which guarantees
that the config was actually applied as desired. Due to the overhead, this setting should only
be used during development.
- transaction filter-side-effects <true|false> (default false)
Enable to automatically filter out side-effects when commiting config. With this feature enabled
the NED will accumulate 'exclude filter-paths' which are used to filter out config from device
to avoid diff when for example there are multiple nodes that represent the same data, i.e. in
overlapping models.
- transaction filter-paths-file <string>
File containing paths to filter out from data (config/oper/rpc-reply). Each line in the file
is of the format '<include|exclude> <schema-path>'. If no include lines are present, it implies
everything is included if not explicitly excluded. This can be combined with 'exclude-namespaces'.
- transaction delete-with-remove <true|false> (default false)
Enable this setting to always use netconf operation 'remove' instead of 'delete' when deleting
nodes with edit-config. This will have the effect that if trying to delete a node which is not
present the operation will be ignored.
- transaction set-default-to-delete <true|false> (default true)
Enable this setting to treat the operation 'set default' as a delete operation. By default, for
devices that has 'with-defaults' handling 'explicit' (or lacks this capability), the behaviour of
NSO is to send a 'set default' operation to the NED when a value which has a default value is to
be deleted, i.e. the value is explicitly set back to its default instead of being deleted.
- transaction delete-by-set-to-default <true|false> (default false)
Enable this setting to make the NED convert 'delete' operations to 'set to default' on nodes with
default values. Use this option to prevent NSO from emitting delete operations on nodes that were
not set in the from-transaction, which can happen if the configuration is deployed using the
'replace' feature.
- transaction enable-diff-dependencies <true|false> (default false)
Enable this setting to be able to use the 'diff-dependencies' annotations on nodes in the schema where device
has bugs imposing ordering dependencies for certain edit operations. For more information in the annotations
that can be used, see section 9.12 in the README.md.
- transaction force-revert-diff <true|false> (default false)
Enable this setting to force the use of an NSO calculated diff to apply when doing revert on device.
For example to be able to use the 'delayed-commit' feature, this is necessary.
- transaction nmda get-data enable <true|false> (default false)
Use get-data rpc for data retrieval, if device supports it.
- transaction nmda get-data with-origin <true|false> (default false)
Configure whether or not to include a </with-origin> tag in the get-data request. The
with-origin setting is usually only supported for operational datastores, like ds:operational.
- transaction nmda get-data datastore <union>
Configure datastore to be used by the get-data rpc. A value with prefix is mandatory.
- transaction nmda get-data origin-filter <union>
Configure an origin filter to be used by the get-data rpc. A value with prefix is mandatory.
Origin filter are usually only supported if an operational datastore like ds:operational has
been configured.
- transaction annotate-commit <enum> (default disabled)
Enable support for annotating the commit on SROS devices through NSO. When this option is
enabled, the NED uses the SROS specific non RFC compliant extension to the commit RPC.This
feature only works on NSO version 6.5 or later in combination with devices running SROS 23 or
newer.
with-label - The device commit annotation will use the NSO commit label.
with-comment - The device commit annotation will use the NSO commit comment.
disabled - disabled.- transaction ignore-rpc-errors <error>
- error <string>
Warning regular expression, e.g. '^.*interface.* does not exist.*$'. NOTE: please use
lowercase letters for device warnings, except for regex keywords.- transaction extra-get-config-paths <path>
- path <schema-path>
Schema path to explicitly add to filter for get-config.- transaction exclude-namespaces <ns>
- ns <namespace>
Namespace to exclude (i.e. as it appears in the yang module). For example, setting:
transaction inject-meta-data 0 path /interfaces/interface/Ethernet{0/0}/mtu meta-data filter-by-version meta-value "VERSION > 7.0"
Will be same as if the below yang statements would be present in the leaf mtu, but only for Ethernet0/0:
tailf:meta-data filter-by-version {
tailf:meta-value "VERSION > 7.0";
}- transaction inject-meta-data <id> <path> <meta-data> <meta-value>
- id <uint16>
Id in list, not used.
- path <schema-path|key-path>
Schema path, or key-path (i.e. with keys in curly braces), to node where to inject
the meta-data (non-unique nodes must be prefixed with 'global' prefix, i.e. prefix from module)
- meta-data <string>
Argument to tailf:meta-data as it would appear in yang.
- meta-value <string>
Argument to tailf:meta-value as it would appear in yang (can be left out if no meta-value
sub-statement needed).- bof-settings enable <true|false> (default false)
Enable NED support for handling of 'bof' settings through NSO.
- bof-settings use-config-region-ns <true|false> (default false)
SROS requires special non RFC compliant extensions to the messages used by the netconf
protocol to handle 'bof' settings. These extensions should actually be prefixed with their own
namespace. However, it seems that older versions of SROS cannot handle extra namespaces. This
applies to versions up to SROS 23. For SROS version 23 or newer it is required to set this
setting to true.- capabilities defaults-mode-override <enum>
Use this setting to override/force the 'with-defaults' handling reported to NSO,
regardless of what the device reports. When 'trim' is forced, the NED will trim
default values from data before sent to NSO, i.e. regardless of if the device support
it or not it will look like it's supported and in use.
report-all - report-all.
explicit - explicit.
trim - trim.
- capabilities use-netconf-state <true|false> (default false)
If this setting is enabled, and the device declares support for ietf-yang namespace
'ietf-netconf-monitoring', the list /netconf-state/schemas/schema will be fetched from the
device to discover available yang modules. Note, once fetched the contents will be cached in
persistent oper data until cleared with the built-in rpc clear-cached-capabilities.
- capabilities use-modules-state <true|false> (default true)
If this setting is enabled, and the device declares support for the netconf capability 'yang-library',
the node /modules-state from the ietf namespace 'ietf-yang-library' will be fetched from the device
to discover available yang modules. Note, once fetched the contents are cached in persistent oper
data and will only be refetched if the 'module-set-id' changes on the device, or the cache is cleared
with the built-in rpc clear-cached-capabilities.
- capabilities use-yang-library <true|false> (default true)
If this setting is enabled, and the device declares support for the netconf capability 'yang-library'
(version 1.1), the node /yang-library from the ietf namespace 'ietf-yang-library' will be fetched
from the device to discover available yang modules. Note, once fetched the contents are cached in
persistent oper data and will only be refetched if the 'content-id' changes on the device, or the
cache is cleared with the built-in rpc clear-cached-capabilities.
- capabilities use-all-local-modules <true|false> (default false)- capabilities regex-exclude <pattern>
- pattern <regex>
Regular expression to match contents of capabilities for exclusion.- capabilities regex-include <pattern>
- pattern <regex>
Regular expression to match contents of capabilities for inclusion.- capabilities inject <capa>
- capa <string>
Capability string to inject, as it would appear in the 'hello', that is the content which
appears inside the 'capability' xml-tag, e.g 'urn:ietf:params:netconf:capability:candidate:1.0'.- ssh host-key known-hosts-file <string>
Path to openssh formatted 'known_hosts' file containing valid host keys.
- ssh host-key public-key-file <string>
Path to openssh formatted public (.pub) host key file.
- ssh host-key auto-fetch <true|false> (default false)
Enable this setting to let the NED handle host-key validation internally (i.e. instead of using
NSO's 'ssh fetch-host-keys' action). The NED will store the host-key sent on the first
connection, after which it will verify that the host-key has not changed on subsequent connects
(it's stored in persistent operational data store in NSO, see below for how to view and edit
this list). This will work when connecting through a proxy as well. Please note that to enable
host-key validation for proxy connections, enable the ned-setting 'proxy host-key-validation'.
To view the stored known host-keys, you can for example do the below in ncs_cli:
admin@ncs# show devices device dev-1 ned-settings nokia-sros_nc-oper known-host-keys
HOST PORT FINGERPRINT
-----------------------------------------------------------------------
1.2.3.4 22 5c:aa:74:e0:4b:e2:a2:dd:67:0b:83:71:1b:24:42:fe
127.0.0.1 10883 a8:a7:39:a2:ed:7e:b8:80:1f:94:81:70:53:59:2f:bb
NOTE: When the host-key of a device changes and needs to be updated, it needs to be cleared in
the persistent store first, this can for example be done from the command line with the ncs_cmd
tool like this:
$ ncs_cmd -c "mdel /ncs:devices/device{dev-1}/ned-settings/nokia-sros_nc-oper/known-host-keys"
- ssh auth-key private-key-file <string>
Path to openssh formatted private key file for doing public key auth to device or proxy. Note
that if private-key authentication is needed to the device when connecting through a proxy,
that needs to be configured in 'proxy/auth-key/private-key-file.
- ssh keep-alive-interval <seconds> (default 0)
Configure SSH client keep alive interval in seconds, default 0 (i.e. no keep-alive). The
keep-alive is implemented in the client by sending an ssh 'ignore' message on the given
interval.- proxy global-proxy <true|false> (default false)
Enable this setting to 'reverse' the meaning of the settings in the proxy section into actually configuring the
proxy host instead of the device behind the proxy. Note that if enabling 'global-proxy' and host-key-validation is
preferred, the host-key of the proxy either needs to be added in the ned setting 'connection/ssh/host-key', or be
added to the .ssh/known_hosts of the user running NSO, or 'ssh host-key auto-fetch' needs to be enabled. The NSO
built-in standard fetch-host-keys can not be used of course since the configured device address is not to the proxy any more.
- proxy remote-address <ip-address|domain-name>
Internal address of device, i.e. when accessed from the proxy.
- proxy remote-port <uint16>
Port of device.
Either of:
- devices device ned-settings nokia-sros_nc proxy remote-name <string>
User name on the device behind the proxy.
- devices device ned-settings nokia-sros_nc proxy remote-password <string>
Password on the device behind the proxy.
OR:
- devices device ned-settings nokia-sros_nc proxy authgroup <string>
Authentication credentials for the device behind the proxy.
- proxy auth-key private-key-file <string>
Path to openssh formatted private key file for doing public key auth to device behind proxy.
Note that if private-key authentication is needed to the proxy itself, that needs to be
configured as it would be for the device, in 'connection/ssh/auth-key/private-key-file.
- proxy host-key-validation <true|false> (default false)
Determines if the host-key of the device or proxy should be validated or not. If validation is
preferred, the host-key must be configured in 'connection/ssh/host-key'.- live-status do-separate-get-calls <true|false> (default false)
By default this NED is passing a subtree filter with all requested paths to the device in one
get call. This is a fast method. Some devices do however not function properly with subtree
filters. In this case it is necessary to do one separate get call for each requested path. Set
to true if the NED shall do separate get calls.
- live-status show-stats-filter <true|false> (default true)
Use the filter API from NSO to do live-status requests (available in NSO 6.1 and later). This
API is much more flexible and will result in fewer round-trips to the device and possibly less
data transferred from the device.
- live-status time-to-live <int32> (default 50)
Define time-to-live for data fetched from the device via live-status.
- live-status filter-unmodeled <true|false> (default true)
Filters out operational data not present in yang-model before returning result to NSO.
- live-status filter-invalid-values <true|false> (default false)
Filter out invalid leaf values from config before sending to NSO to avoid sync-from failure on
for example invalid range expression.
- live-status canonicalize-idrefs <true|false> (default true)
Canonicalize leaf values of type 'identityref' in operational data before sending to NSO, i.e.
add/change prefix to global prefix in NSO.
- live-status nmda get-data enable <true|false> (default false)
Use get-data rpc for data retrieval, if device supports it.
- live-status nmda get-data with-origin <true|false> (default false)
Configure whether or not to include a </with-origin> tag in the get-data request. The
with-origin setting is usually only supported for operational datastores, like ds:operational.
- live-status nmda get-data datastore <union> (default operational)
Configure datastore to be used by the get-data rpc. A value with prefix is mandatory.
- live-status nmda get-data origin-filter <union>
Configure an origin filter to be used by the get-data rpc. A value with prefix is mandatory.
Origin filter are usually only supported if an operational datastore like ds:operational has
been configured.
- live-status nmda get-data skip-config <true|false> (default false)
Ask the device to not include 'config true' data in the response.
- live-status ignore-get-error-codes <string> (default unknown-element)
Some SROS devices do return an error instead of valid data on certain paths advertised by the
device when the NED is trying to get operational data. Such errors will typically result in
the NED throwing an exception towards NSO, which then will bail out. To avoid this, the NED
can be configurued to ignore the error returned by the device and instead return empty data to
NSO.
- live-status exec-any-mode <enum> (default md-cli-raw-command)
Configure how the NED can exceute CLI commands on the device. The default is to use the
md-cli-raw-command feature, which is a very efficient SROS specific method to tunnel CLI
commands over NETCONF. This feature is only available on SROS version 22 and newer. Older SROS
version require the NED to use CLI mode instead.
md-cli-raw-command - md-cli-raw-command.
cli - cli.- live-status regex-exclude <pattern>
- pattern <regex>
Regular expression matching path/key-path of node(s) to exclude.- cli port <uint16>
Alternatative port on device, if interactive CLI not availble on same port as 'netconf'
subsystem.
- cli prompt-pattern <string> (default ^.*# $)
Regex to match device prompt.
- cli no-pagination-cmd <string> (default environment more false)
Command line to send after login to turn off pagination on the device (i.e. to make output from commands not
stop to prompt user for 'more').live-status cli auto-prompts 10 question ".*assword: ?" answer secret
- cli auto-prompts <id> <question> <answer>
- id <WORD>
List id, any string (NOTE: list is matched in the order sorted on id).
- question <WORD>
Device question, as a regular expression.
- answer <WORD>
Answer to device question, i.e verbatim string to send as answer when 'question' is matched.- logger level <enum> (default info)
Sets the logger verbosity. Enable raw trace on the device instance in NSO to
get trace output. To trace the netconf raw RPCs, set level to verbose or debug.
error - Most restricitve level, only log errors.
info - Normal level, logs errors and important events.
verbose - Intermediate debug level, logs most events.
debug - Least restrictive level, logs everything, output might grow very large.
- logger java <true|false> (default true)
Toggle logs to be added to ncs-java-vm.log, Note, this file is shared between all NED
instances and might grow very large if level is increased.- developer trace-timestamp <true|false> (default false)
Add timestamp from NED instance in trace messages for debug purpose.
- developer sync-from-verbose <enum> (default brief)
Set info level for sync-from verbose output.
brief - brief.
full - full.
- developer strict-maapi-error-check <true|false> (default true)
When this setting is enabled, if maapi reports error when loading data to NSO, the error is
reported back to NSO, failing show operation.
- developer progress-verbosity <enum> (default debug)
Maximum NED verbosity level which will get written in devel.log file.
disabled - disabled.
normal - normal.
verbose - verbose.
very-verbose - very-verbose.
debug - debug.
- developer platform model <string>
Override device model name/number.
- developer platform name <string>
Override device name.
- developer platform version <string>
Override device version.This document describes the nokia-sros_nc NED.
IMPORTANT: This NED is delivered without any of the device YANG models bundled to the NED package.
It is required to download the YANG files separately and rebuild the NED package before the NED is fully operational. See the README-rebuild.md for further information.
In summary, the below steps are needed to have a fully functioning NED:
Additional README files bundled with this NED package
Common NED Features
Verified target systems
Verified YANG model bundles
It is assumed the NED package ncs-<NSO version>-nokia-sros_nc-<NED version>.signed.bin has already been downloaded from software.cisco.com.
In this instruction the following example settings will be used:
NSO version: 6.0
NED version: 1.0.1
NED package downloaded to: /tmp/ned-package-store
Extract the NED package and verify its signature:
In case the signature can not be verified (for instance if no internet connection), do as below instead:
The result of the extraction shall be a tar.gz file with the same name as the .bin file:
There are two alternative ways to install this NED package. Which one to use depends on how NSO itself is setup.
In the instructions below the following example settings will be used:
NSO version: 6.0
NED version: 1.0.1
NED download directory: /tmp/ned-package-store
NSO run time directory: ~/nso-lab-rundir
A prerequisite is to set the environment variable NSO_RUNDIR to point at the NSO run time directory:
IMPORTANT:
This NED is delivered as an “empty” package, i.e without any device YANG models bundled. It must be rebuilt with the device YANG models to become operational.
The procedure to rebuild the empty NED (described in the README-rebuild.md) shall typically be done in a lab environment. For this step a “local install” of the NED shall be used. It is not suitable to use “system install” here since it is intended for production systems only.
Once this NED has been rebuilt with the device YANG and exported to one or many separate tar.gz customized NED packages, a “system installation” can be used on them.
This section describes how to install a NED package on a locally installed NSO (see "NSO Local Install" in the NSO Installation guide).
It is assumed the NED package has been been unpacked to a tar.gz file as described in 1.1.
Untar the tar.gz file. This creates a new sub-directory named: nokia-sros_nc-<NED major digit>.<NED minor digit>:
Install the NED into NSO, using the ncs-setup tool:
Open a NSO CLI session and load the new NED package like below:
Alternatively the tar.gz file can be installed directly into NSO. Then skip steps 1 and 2 and do like below instead:
Set the environment variable NED_ROOT_DIR to point at the NSO NED package:
This section describes how to install a NED package on a system installed NSO (see "NSO System Install" in the NSO Installation Guide).
It is assumed the NED package has been been unpacked to a tar.gz file as described in 1.1.
Do a NSO backup before installing the new NED package:
Start a NSO CLI session and fetch the NED package:
Install the NED package (add the argument replace-existing if a previous version has been loaded):
Load the NED package
This section describes the steps for configuring a device instance using the newly installed NED package.
Start a NSO CLI session:
Enter configuration mode:
Configure a new authentication group (my-group) to be used for this device:
Configure a new device instance (example: dev-1):
IMPORTANT:
If the sync-from was not successful, check the NED configuration again.
It is often desirable to see details from when and how the NED interacts with the device(Example: troubleshooting)
This can be achieved by configuring NSO to generate a trace file for the NED. A trace file contains information about all interactions with the device. Messages sent and received as well as debug printouts, depending on the log level configured.
NSO creates one separate trace file for each device instance with tracing enabled. Stored in the following location:
$NSO_RUNDIR/logs/ned-nokia-sros_nc-gen-1.0-<device name>.trace
Do as follows to enable tracing in one specific device instance in NSO:
Start a NSO CLI session:
Enter configuration mode:
Enable trace raw:
Alternatively, tracing can be enabled globally affecting all configured device instances:
Configure the log level for printouts to the trace file:
The log level 'info' is used by default and the 'debug' level is the most verbose.
IMPORTANT: Tracing shall be used with caution. This feature does increase the number of IPC messages sent between the NED and NSO. In some cases this can affect the performance in NSO. Hence, tracing should normally be disabled in production systems.
An alternative method for generating printouts from the NED is to enable the Java logging mechanism. This makes the NED print log messages to common NSO Java log file.
$NSO_RUNDIR/logs/ncs-java-vm.log
Do as follows to enable Java logging in the NED
Start a NSO CLI session:
Enter configuration mode:
Enable Java logging with level all from the NED package:
Configure the NED to log to the Java logger
Alternatively Java logging can be enabled globally affecting all configured device instances using this NED package.
IMPORTANT: Java logging does not use any IPC messages sent to NSO. Consequently, NSO performance is not affected. However, all log printouts from all log enabled devices are saved in one single file. This means that the usability is limited. Typically single device use cases etc.
SSHJ DEBUG LOGGING For issues related to the ssh connection it is often useful to enable full logging in the SSHJ ssh client. This will make SSHJ print additional log entries in $NSO_RUNDIR/logs/ncs-java-vm.log:
This NED has the following host environment dependencies:
Java 1.8 (NSO version < 6.2)
Java 17 (NSO version >= 6.2)
Gnu Sed
Dependencies for NED recompile:
Apache Ant
Bash
Gnu Sort
Gnu awk
The nokia-sroc_nc NED has full support for fetching operational data via the NSO live-status API.
The SROS device must be properly configured in model driven mode and with netconf enabled for this NED to function properly. Any other mode such as 'mixed mode' makes SROS limited and will prevent the NED from using certain features. For instance the fast transaction id calculation nethod which has been customized for SROS.
Some issues has been observed when running towards SROS devices. These are briefly described here, please note that these are only what have been observed in specific use-cases, it might be related to device/SROS model/version, and also to specific configuration used in these use-cases. Hence, these issues might not be relevant for your use-case, and of course, there might be other issues which have not been observed.
As has been observed with many vendors yang-models, SROS seems to contain some leafrefs that are not enforced in the device, which might lead to NSO reporting "illegal reference" when doing sync-from. See file src/customize-schema.schypp for these, i.e. paths which have an 'inline_type' operation in this file. Also see the README-rebuild.md for more info on mitigating "illegal reference".
In some older versions of SROS, support for yang-library version 1.1 is announced, however, the implementation has bugs in it (this relates at least to SROS versions <= 20.10 which announce yang-library 1.1 support). In this case the NED needs to be configured to make it look like the device actually implements yang-library 1.0. This can be done by setting the below ned-settings:
NOTE: The "fake" module-set-id used here is not relevant, it can be anything
Another issue which has been observed is that while the device announces support for the yang-module ietf-interfaces, it can not be used for example inside the filter of a get-config request. Hence this module needs to be filtered out, which is done with the below ned-setting:
At least SROS version 22 has problems with properly returning valid data from the openconfig data tree when the NED is doing a get-config request. The device seems to have problems with the default filter used by the NED. If the NED is built with openconfig, this filter will contain namespaces of the openconfig models. This will result in the device returning an error instead of the valid config.
This issue can be solved by configuring the following NED setting:
All current versions of SROS have a special non rfc compliant behaviour for settings related to the configuration groups 'bof' and 'li'. These configuration trees are regarded as separate datastores by SROS. This means SROS does not allow editing standard config together with 'bof' or 'li' settings in the same transaction. Furthermore editing 'bof' and 'li' settings does require Nokia specific non rfc compliant extensions to the netconf messages.
Do as follows to enable support for managing 'bof' settings in the NED:
Make sure the Nokia 'bof' models are included when rebuilding the NED. For example, use the profile 'sros-combined-with-bof-from-device' when downloading the models.
Configure the following NED setting:
Set the following NED setting to true for devices running SROS version 23 or newer. Default is false.
The NED does currently not support managing 'li' settings. This is something that can be added upon request.
Issues like bugs and errors shall always be reported to the Cisco NSO NED team through the Cisco Support channel:
The following information is required for the Cisco NSO NED team to be able to investigate an issue:
Do as follows to gather the necessary information needed for your device, here named 'dev-1':
Enable full debug logging in the NED
Configure the NSO to generate a raw trace file from the NED
If the NED already had trace enabled, clear it in order to submit only relevant information
Do as follows for NSO 6.4 or newer:
Do as follows for older NSO versions:
Requests for new features and extensions of the NED are handled by the Cisco NSO NED team when applicable. Such requests shall also go through the Cisco support channel.
The following information is required for feature requests and extensions:
A detailed use case description, with details like:
Data of interest
The kind of operations to be used on the data. Like: 'read', 'create', 'update', 'delete' and the order of the operation
Device APIs involved in the operations (For example: REST URLs and payloads)
Check the README-rebuild.md file, chapter 1.3, for more information.
This NED supports multi factor authentication (MFA) using the ssh authentication method 'keyboard-interactive'.
Some additional steps are required to enable the MFA support:
Verify that your NSO version supports MFA. This is configurable as additional settings in the authentication group used by the device instance.
Enter a NSO CLI and enter the following and do tab completion:
If 'mfa' is displayed in the output like above, NSO has MFA support enabled. In case MFA is not supported it is necessary to upgrade NSO before proceeding.
Implement the authenticator executable. The MFA feature relies on an external executable to take care of the client part of the multi factor authentication. The NED will automatically call this executable for each challenge presented by the ssh server and expects to get a proper response in return.
The executable can be a simple shell script or a program implemented in any programming language.
The required behaviour is like this:
In case of connection problems the following steps can help for debugging:
Enable the NED trace in debug level:
Try connect again
Inspect the generated trace file.
Verify that the ssh client is using the external authenticator executable:
Verify that the executable is called with the challenges presented by the ssh server:
Check for any errors reported by the NED when calling the executable
Some commands that are available to a user logged in to an interactive CLI session on the device might not be available through NETCONF. For situations like this the NED provides the feature to run arbitrary commands on the device.
The NED feature to execute commands is connected in NSO to a live-status action called 'exec any'.
The NED does by default use the 'md-cli-raw-command' feature to tunnel commands to the device. This feature is supported by all newer versions of Nokia SROS.
It is also possible to configure the NED to use an interactive SSH login to the device. This extra SSH session is then handled internally in the NED. This option works also with older versions of SROS.
There are some ned-settings to control the behaviour of this feature, see the section 'ned-settings nokia-sros_nc live-status exec-any-mode and cli' in README-ned-settings.md for details on this.
Note that when using ncs_cli, the command-line given might need to be quoted if it contains characters that are interpreted by the ncs_cli itself.
1. General
1.1 Extract the NED package
1.2 Install the NED package
1.2.1 Local install
1.2.2 System install
1.3 Configure the NED in NSO
2. Optional debug and trace setup
3. Dependencies
4. Sample device configuration
5. Built in RPC actions
5.1. rpc add-filter-path
5.2. rpc clean-package
5.3. rpc clear-cached-capabilities
5.4. rpc clear-filter-paths
5.5. rpc compare-config
5.6. rpc compile-modules
5.7. rpc export-package
5.8. rpc get-modules
5.9. rpc import-filter-paths
5.10. rpc list-filter-paths
5.11. rpc list-module-sets
5.12. rpc list-modules
5.13. rpc list-profiles
5.14. rpc patch-modules
5.15. rpc rebuild-package
5.16. rpc remove-filter-path
5.17. rpc show-default-local-dir
5.18. rpc show-loaded-schema
5.19. rpc verify-get-config
5.20. rpc xpath-trace-analyzer
6. Built in live-status show
7. Limitations
8. How to report NED issues and feature requests
9. How to rebuild a NED
10. Configure the NED to use ssh multi factor authentication
11. Run arbitrary commands on deviceFinally commit the configuration
Verify configuration, using a sync-from.
Python3 (with packages: re, sys, getopt, subprocess, argparse, os, glob)
Reproduce the found issue using ncs_cli or your NSO service. Write down each necessary step in a reproduction report.
Gather the reproduction report and a copy of the raw trace file containing data recorded when the issue happened.
Contact the Cisco support and request to open a case. Provide the gathered files together with access details for a device that can be used by the Cisco NSO NED when investigating the issue.
Device documentation describing the operations involved
Run sync-from # devices device dev-1 sync-from (if relevant)
Attach the raw trace to the ticket (if relevant)
Access to a device that can be used by the Cisco NSO NED team for testing and verification of the new feature. This usually means that both read and write permissions are required. Pseudo access via tools like Webex, Zoom etc is not acceptable. However, it is ok with access through VPNs, jump servers etc.
read one line from stdin The line passed from the NED will be a semi colon separated string containing the following info:
The elements for device name, user, password and opaque corresponds to what has been configured in NSO. The ssh server name, instruction and prompt are given by the ssh server during the authentication step.
Each individual element in the semi colon separated list is Base64 encoded.
Extract the challenge based on the contents above.
Print a response matching the challenge to stdout and exit with code 0
In case a matching response can not be given do exit with code 2
Below is a simple example of an MFA authenticator implemented in Python3:
Configure the authentication group used by the device instance to enable MFA. There are two configurables available:
executable The path to the external multi factor authentication executable (mandatory).
opaque Opaque data that will passed as a cookie element to the executable (optional).
Try connecting to the device.
admin@ncs(config)# commitadmin@ncs(config)# devices device dev-1 sync-from
result true[<device name>;<user>;<password>;<opaque>;<ssh server name>;<ssh server instruction>;<ssh server prompt>;]> ncs_cli -C -u admin
admin@ncs# config
Entering configuration mode terminal
admin@ncs(config)# devices authgroups group <name> default-map mfa executable <path to the executable>
admin@ncs(config)# devices authgroups group <name> default-map mfa opaque <some opaque data>
admin@ncs(config)# commit1. Compile the empty package and load it into NSO
2a. Connect to device and fetch yang modules (if yang available on device or in git repository)
2b. Copy vendor yang directly into src/yang (if yang is available elsewhere)
3. Verify yang, potentially fixing any issues
4. Re-Compile package (i.e. in NSO), and do packages reload+---------------------------+------------------------------------------------------------------------------+
| Name | Info |
+---------------------------+------------------------------------------------------------------------------+
| README-ned-settings.md | Information about all run time settings supported by this NED. |
| | |
| README-rebuild.md | Detailed instructions on how to download the device YANG models and |
| | rebuilding the NED with them. |
+---------------------------+------------------------------------------------------------------------------++---------------------------+-----------+------------------------------------------------------------------+
| Feature | Supported | Info |
+---------------------------+-----------+------------------------------------------------------------------+
| netsim | yes | |
| | | |
| check-sync | yes | See the README-ned-settings.md, 'transaction trans-id-method' |
| | | for details. |
| | | |
| partial-sync-from | yes | |
| | | |
| live-status actions | yes | Can run CLI commands through 'exec any', see README.md |
| | | |
| live-status show | yes | All models are by default mounted under live-status |
| | | |
| load-native-config | no | Since config can be loaded in xml format in NSO, this can be |
| | | used instead. |
+---------------------------+-----------+------------------------------------------------------------------++---------------------------+-----------------+--------+---------------------------------------------------+
| Model | Version | OS | Info |
+---------------------------+-----------------+--------+---------------------------------------------------+
| 7950 | 22 | SROS | |
| | | | |
| 7950 | 23 | SROS | |
+---------------------------+-----------------+--------+---------------------------------------------------++---------------------------+-----------------+------------------------------------------------------------+
| Bundle | Version | Info |
+---------------------------+-----------------+------------------------------------------------------------+
| SROS Combined | rel22 | |
| | | |
| SROS Combined | rel23 | |
| | | |
| OpenConfig | 0.10.0 | |
+---------------------------+-----------------+------------------------------------------------------------+> cd /tmp/ned-package-store
> chmod u+x ncs-6.0-nokia-sros_nc-1.0.1.signed.bin
> ./ncs-6.0-nokia-sros_nc-1.0.1.signed.bin> ./ncs-6.0-nokia-sros_nc-1.0.1.signed.bin --skip-verification> ls *.tar.gz
ncs-6.0-nokia-sros_nc-1.0.1.tar.gz> export NSO_RUNDIR=~/nso-lab-rundir> tar xfz ncs-6.0-nokia-sros_nc-1.0.1.tar.gz
> ls -d */
nokia-sros_nc-gen-1.0> ncs-setup --package nokia-sros_nc-gen-1.0 --dest $NSO_RUNDIR> ncs_cli -C -u admin
admin@ncs# packages reload
reload-result {
package nokia-sros_nc-gen-1.0
result true
} > ncs-setup --package ncs-6.0-nokia-sros_nc-1.0.1.tar.gz --dest $NSO_RUNDIR
> ncs_cli -C -u admin
admin@ncs# packages reload
reload-result {
package nokia-sros_nc-gen-1.0
result true
}> export NED_ROOT_DIR=$NSO_RUNDIR/packages/nokia-sros_nc-gen-1.0> $NCS_DIR/bin/ncs-backup> ncs_cli -C -u admin
admin@ncs# software packages fetch package-from-file \
/tmp/ned-package-store/ncs-6.0-nokia-sros_nc-1.0.tar.gz
admin@ncs# software packages list
package {
name ncs-6.0-nokia-sros_nc-1.0.tar.gz
installable
}admin@ncs# software packages install nokia-sros_nc-1.0
admin@ncs# software packages list
package {
name ncs-6.0-nokia-sros_nc-1.0.tar.gz
installed
}admin@ncs# packages reload
admin@ncs# software packages list
package {
name ncs-6.0-nokia-sros_nc-gen-1.0
loaded
}> ncs_cli -C -u adminadmin@ncs# configure
Entering configuration mode terminal
admin@ncs(config)#admin@ncs(config)# devices authgroup group my-group default-map remote-name <user name on device> \
remote-password <password on device>admin@ncs(config)# devices device dev-1 address <ip address to device>
admin@ncs(config)# devices device dev-1 port <port on device>
admin@ncs(config)# devices device dev-1 device-type generic ned-id nokia-sros_nc-gen-1.0
admin@ncs(config)# devices device dev-1 state admin-state unlocked
admin@ncs(config)# devices device dev-1 authgroup my-group> ncs_cli -C -u adminadmin@ncs# configure
Entering configuration mode terminal
admin@ncs(config)#admin@ncs(config)# devices device dev-1 trace raw
admin@ncs(config)# commitadmin@ncs(config)# devices global-settings trace raw
admin@ncs(config)# commitadmin@ncs(config)# devices device dev-1 ned-settings nokia-sros_nc logger \
level [debug | verbose | info | error]
admin@ncs(config)# commit> ncs_cli -C -u adminadmin@ncs# configure
Entering configuration mode terminal
admin@ncs(config)#admin@ncs(config)# java-vm java-logging logger com.tailf.packages.ned.sros \
level level-all
admin@ncs(config)# commitadmin@ncs(config)# devices device dev-1 ned-settings nokia-sros_nc logger java true
admin@ncs(config)# commitadmin@ncs(config)# devices global-settings ned-settings nokia-sros_nc logger java true
admin@ncs(config)# commitadmin@ncs(config)# java-vm java-logging logger net.schmizz.sshj level level-all
admin@ncs(config)# commitdevices authgroups group nokia-auth-group
default-map remote-name <user>
default-map remote-password <password>
!
devices device dev-1
address <address>
port <port>
authgroup nokia-auth-group
device-type generic ned-id nokia-sros_nc-gen-1.0
trace raw
! Set get-config-no-filter true if openconfig models are being used
ned-settings nokia-sros_nc transaction get-config-no-filter true
ned-settings nokia-sros_nc transaction exclude-namespaces urn:ietf:params:xml:ns:yang:ietf-interfaces
ned-settings nokia-sros_nc live-status filter-invalid-values true
state admin-state unlocked
!Add a path to be filtered, possibly removing paths being made redundant.
Input arguments:
Either of:
- include <empty>
OR:
- exclude <empty>
- force <empty>
- path <string>Cleans the NED package from all downloaded third party YANG files.
Input arguments:
- verbose <empty>
Print the full clean output also for successful executions (otherwise only printed on errors).Clear all cached capabilities (module-set-id/content-id/yang-library/netconf-state).
No input argumentsClear all filter-paths, except content from ned-setting 'filter-paths-file'.
No input argumentsDo a NED-internal compare-config, with data either from device or file, optionally disabling
filtering.
Input arguments:
- config-file <string>
Optional file to load config from instead of fetching from device (NOTE, should be content of
rpc-reply, i.e. config wrapped in data-tag).
- strict <empty>
Match defaults strict, according to capabilities.
- unfiltered <empty>
Don't apply filter-paths.
- outformat <enum> (default tree)
tree - Standard NSO diff tree.
compact - Compact diff showing key-paths.
xml - Show diff as netconf edit-config XML.Compile YANG modules, showing all non-fatal warnings found.
Input arguments:
- local-dir <string>
Path to the directory where the YANG files are found (defaults to src/yang in package).
- no-deviations <empty>
Set to disable deviations.
- ignore-errors <empty>
Ignore errors while compiling, i.e. which would normally cause compilation to abort.Export the customized and rebuilt NED. The exported archive file can then be used to install the
NED package in other NSO instances. The name of the file will have the following format ncs-<NSO
version>-<NED name>-<NED-version>-customized.tgz.
Input arguments:
- destination <string> (default /tmp)
Set destination directory for the exported archive file.
- suffix <string> (default -customized)
Configure a customized suffix to the name of the archive file.Fetch the YANG modules from the device.
Input arguments:
- module-include-regex <string>
Regular expression matching all YANG models to be included in the download. Example:
'openconfig-.*'.
- module-exclude-regex <string>
Regular expression matching all YANG models to be excluded from the download. Example:
'tailf-.*'.
- namespace-include-regex <string>
Regular expression matching all namespaces to be included in the download. Example:
'tailf-.*'.
- namespace-exclude-regex <string>
Regular expression matching all namespaces to be excluded from the download. Example:
'tailf-.*'.
- module-set <string>
Only include modules from the given yang-library module-set (if device supports yang-library
1.1).
- only-present <empty>
- only-oper-filter <string>
- profile <union> (default sros-combined-from-device)
Use a download profile to match a predefined subset of matching YANG files.
- local-dir <string>
Path to the directory where the YANG files are to be copied (defaults to src/yang in package).
- ignore-errors <empty>
Ignore errors during download. For example missing files of failed revision checks.
Either of:
- remote device <empty>
The device itself.
OR:
- remote dir <string>
A directory on the local host holding all YANG files. For instance a local clone of a git
repository.
OR:
- remote archive <string>
A path to a zip/tgz archive file containing the YANG files.
OR:
- remote git repository <string>
The URL to the git repository. Example: https://github.com/YangModels/yang.git.
- remote git dir <string>
Path to a sub directory inside the git repo where the YANG files can be found. Example:
vendor/cisco/nx/10.1-2.
- remote git checkout <string>
Optionally, a name of a branch/tag in the git repo where the YANG files can be found.
Example: master.
- remote git include-dir <string>
Optional extra include paths to be used when searching for YANG files. Each include path
is relative to the git root directory.Import filter-paths from file, will be merged with currently loaded.
Input arguments:
- filter-file <string>
File containing filter-paths, one on each line: <include|exclude> <schema-path>.List currently loaded/generated filter-paths.
Input arguments:
- deviation-module <empty>
Generate a module which deviates all excluded paths as 'not-supported'.
- save-to-file <string>
Save result to given file. For deviation module, optionally just give name of module to
generate in src/yang.List the yang-library module-sets advertised by the device, if device supports it.
No input argumentsList the YANG modules advertised by the device. Including revision tag.
Input arguments:
- module-include-regex <string>
Regular expression matching all YANG models to be included in the download. Example:
'openconfig-.*'.
- module-exclude-regex <string>
Regular expression matching all YANG models to be excluded from the download. Example:
'tailf-.*'.
- namespace-include-regex <string>
Regular expression matching all namespaces to be included in the download. Example:
'tailf-.*'.
- namespace-exclude-regex <string>
Regular expression matching all namespaces to be excluded from the download. Example:
'tailf-.*'.
- module-set <string>
Only include modules from the given yang-library module-set (if device supports yang-library
1.1).
- only-present <empty>
- only-oper-filter <string>
- profile <union> (default sros-combined-from-device)
Use a download profile to match a predefined subset of matching YANG files.List all predefined download profiles bundled with the NED. Including a short description of each.
No input argumentsPatch YANG modules, to remove non-fatal warnings found.
Input arguments:
- local-dir <string>
Path to the directory where the YANG files are found (defaults to src/yang in package).
- no-deviations <empty>
Set to disable deviations.
- output-dir <string>
Path to the directory where the patched YANG files are written (defaults to src/yang in
package), existing files will be renamed to <name>.yang.orig.Rebuild the NED package directly from within NSO. This invokes the gnu make internally.
Input arguments:
- verbose <empty>
Print the full build output also for successful builds (otherwise only printed on errors).
- profile <string>
Apply a certain build profile.
- filter scope dir <string>
Directory containing one or many xml file representing the wanted scope.
- filter trim-schema method <enum> (default patch)
Select method to be used for trimming.
deviate - Trim by creating a YANG deviation file containing all selected nodes.
patch - Trim by patching the YANG models and remove all selected nodes from them before
they are being compiled.
Either of:
- filter trim-schema nodes <union>
List of nodes to trim. Use one of the pre-defined top node names. Alternatively, specify a
custom xpath to trim (prefix is mandatory on each element in the path).
OR:
- filter trim-schema all-unused <empty>
Trim all currently unused nodes in the schema. This means all config nodes that are
currently not populated in CDB.
OR:
- filter trim-schema all-with-status <enum>
Trim all nodes in the schema annotated with matching 'status' statements.
deprecated - Means node is still supported, but usage no longer recommended.
obsolete - Means node is not supported anymore, and should not be used.
OR:
- filter trim-schema nodes-from-file <string> (default /tmp/nedcom-trim-schema-nodes.txt)
Specify a path to a custom file to be used for trimming nodes. The file shall contain
schema paths, including relevant prefixes to all nodes to be trimmed. One schema path per
line.
OR:
- filter trim-schema custom-deviation-file <string>
Specify a path to a custom YANG deviation file to be used for trimming the schema. The
file shall comply to the standard for deviation files and contain paths to all nodes to be
trimmed from the schema.
OR:
- filter auto-config dir <string>
Directory containing the files used for auto-config filtering. The following files must be
present: before.xml and after.xml.
- filter auto-config file <string> (default /tmp/nedcom-auto-deviations.yang)
Name of auto generated deviation file.
- ned-id major <string>
Set a custom major number in the generated ned-id.
- ned-id minor <string>
Set a custom minor number in the generated ned-id.
- ned-id suffix <string>
Set a custom suffix in the generated ned-id.
- include-netsim <empty>
Do compile the YANG models for netsim as well, when rebuilding the NED package.
- additional-build-args <string>
Additional arguments to pass to build(make) commands.Remove a path from filter-paths.
Input arguments:
Either of:
- include <empty>
OR:
- exclude <empty>
- path <string>Show the path to the default directory where the YANG files are to be copied. I.e <path to current
NED package>/src/yang.
No input argumentsDisplay the schema currently built into the NED package. Each node will by default be listed with
a schema path.
Input arguments:
- scope <enum> (default all)
Select the scope for the nodes that will be listed.
all - Display all nodes in the schema. This is the default.
used - Display only the config nodes in use, i.e currently populated in CDB.
unused - Display only the config nodes that are not in use.
rpcs - Display the rpc nodes defined in the schema.
- with-status <enum>
Only select nodes annotated with matching 'status' statements.
deprecated - Means node is still supported, but usage no longer recommended.
obsolete - Means node is not supported anymore, and should not be used.
- count <empty>
Count the nodes and return the sum instead of the full list of nodes.
- details <empty>
Display schema details like must/when expression, leafrefs and leafref targets.
- root-paths <string>
Specify root paths for which nodes shall be listed or counted. Only nodes with a schema path
starting any of the specified roots will then be processed.
- config <true|false> (default true)
Set to false to display non config nodes in the schema. Note: scope will in this case be
'all'.
- output file <string>
- developer generate-schypp-pragmas pragma <enum> (default remove)
Set pragma type.
remove - remove.
replace - replace.
- developer generate-schypp-pragmas statement <enum>
Set the yang statement for the pragma.
must - must.
when - when.
unique - unique.
type - type.
- developer generate-schypp-pragmas pattern <string>
Configure the pattern to search for matching statements. Use ".*" to match any string.
- developer generate-schypp-pragmas replace-with <string>
For replace pragmas, set replacement for statements matching the pattern.
- developer generate-schypp-pragmas add-comment <empty>
Prepend extra comment containing info about the statement.Verify XML contents of config, either from device or file, to validate
data and look for unmodeled structures (the yang-modules are compiled on
the fly making this a convenient way to verify yang-updates).
Input arguments:
Either of:
- local-dir <string>
Path to the directory where the YANG files are found (defaults to src/yang in package).
- no-deviations <empty>
Set to disable deviations.
- patch <empty>
Auto-patch yang when possible (e.g. missing leafref targets will expand referrer type).
- config-file <string>
Optional file to load config from instead of fetching from device (NOTE, should be content
of rpc-reply, i.e. config wrapped in data-tag).
OR:
- no-compile <empty>
- verbose <empty>
Show verbose output, like 'sync-from verbose'.A tool for analyzing NSO XPath traces, designed to identify inefficient or problematic XPath
expressions in third-party YANG files that may negatively impact NSO performance.
Input arguments:
- file <string> (default logs/xpath.trace)
Path to the NSO xpath trace file to use. The xpath trace file used by the current NSO will be
used by default.
- number-of-entries <uint8> (default 10)
Set the number of entries to display in the generated top list. ned-settings nokia-sros_nc connection capabilities use-yang-library false
ned-settings nokia-sros_nc connection capabilities regex-exclude .*yang-library:1.1.*
ned-settings nokia-sros_nc connection capabilities inject urn:ietf:params:netconf:capability:yang-library:1.0revision=2019-01-04&module-set-id=20.10.R4 ned-settings nokia-sros_nc transaction exclude-namespaces urn:ietf:params:xml:ns:yang:ietf-interfaces ned-settings nokia-sros_nc transaction get-config-no-filter true ned-settings nokia-sros_nc transaction bof-settings enable true; ned-setinngs nokia-sros_nc transaction bof-settings use-config-region-ns true- A detailed recipe with steps to reproduce the issue.
- A raw trace file generated when the issue is reproduced.
- Access to a device where the issue can be reproduced by the Cisco NSO NED team.
This typically means both read and write permissions are required.
Pseudo access via tools like Webex, Zoom etc is not acceptable.
However, it is ok with device access through VPNs, jump servers etc though.ncs_cli -C -u admin
admin@ncs# configure
admin@ncs(config)# devices device dev-1 ned-settings nokia-sros_nc logging level debug
admin@ncs(config)# commitadmin@ncs(config)# devices device dev-1 trace raw
admin@ncs(config)# commitadmin@ncs(config)# devices device dev-1 clear-traceadmin@ncs(config)# devices clear-trace> ncs_cli -C -u admin
admin@ncs# show running-config devices authgroups group default default-map <tab>
Possible completions:
action-name The action to call when a notification is received.
callback-node Invoke a standalone action to retrieve login credentials for managed devices on the 'callback-node' instance.
mfa Settings for handling multi-factor authentication towards the device
public-key Use public-key authentication
remote-name Specify device user name
remote-password Specify the remote password
remote-secondary-password Second password for configuration
same-pass Use the local NCS password as the remote password
same-secondary-password Use the local NCS password as the remote secondary password
same-user Use the local NCS user name as the remote user name> devices device dev-1 trace raw
> devices device dev-1 ned-settings nokia-sros_nc logger level debug
> commitusing ssh external mfa executable: <configured path to executable>calling external mfa executable with ssh server given name: '<name>', instruction: '<instruction>', prompt '<challenge>'ERROR: external mfa executable failed <....>admin@ncs# devices device dev-1 live-status exec any admin display-configadmin@ncs(config)# devices device global-settings ned-settings nokia-sros_nc logger \
level [debug | verbose | info | error]
admin@ncs(config)# commitadmin@ncs(config)# devices device dev-1 compare-config#!/usr/bin/env python3
import sys
import base64
# This is an example on how to implement an external multi factor authentication handler
# that will be called by the NED upon a ssh 'keyboard-interactive' authentication
# The handler is reading a line from stdin with the following expected format:
# [<device name>;<user>;<password>;<opaque>;<ssh server name>;<ssh server instruction>;<ssh server prompt>;]
# All elements are base64 encoded.
def decode(arg):
return str(base64.b64decode(arg))[2:-1]
if __name__ == '__main__':
query_challenges = {
"admin@localhost's password: ":'admin',
'Enter SMS passcode:':'secretSMScode',
'Press secret key: ':'2'
}
# read line from stdin and trim brackets
line = sys.stdin.readline().strip()[1:-1]
args = line.split(';')
prompt = decode(args[6])
if prompt in query_challenges.keys():
print(query_challenges[prompt])
exit(0)
else:
exit(2)The nokia-sros_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 before proceeding.
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, YANG models can typically be downloaded directly from the device. This is also true for Nokia SROS devices, as long as the models have been properly loaded onto the device.
Important: Ensure that the device is configured to advertise the correct models. You should enable one or both of the following:
nokia-combined-modules
openconfig-modules
Note: The use of nokia-submodules should be avoided. The corresponding YANG files are known to cause compilation problems with some NSO versions.
The downloader tool comes pre-configured with the following profiles:
sros-combined-from-device: Downloads the Nokia SROS combined YANG models from the device, including dependencies. This is the default profile.
sros-combined-with-bof-from-device: Downloads the Nokia SROS combined YANG models from the device, including the bof models. Managing bof settings through NSO requires additional NED configuration and has certain limitations. Refer to README-ned-settings.md and the "Limitations" section in README.md for more information.
To download files using the sros-combined-from-device profile, run the following command in the NSO CLI:
Or simply:
(since this is the default profile)
To download files using the openconfig-from-device profile, use:
Do as follows in the NSO CLI to download the files using the openconfig-from-device profiles.
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 provides more details about the downloader tool, including a complete list of available command line arguments.
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.
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.
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 ).
To rebuild the NED, follow these steps:
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:
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.
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.
Remove the downloaded YANG files:
Rebuild NED package without any additional arguments. This will reset the NED-ID to its original initial state:
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.
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 .
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 beforehand. It is also recommended to follow the steps in Chapters 1.2 and 1.3 for best results.
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 .
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.
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: nokia-sros_nc-gen-1.0
Do as follows to build each flavour of the nokia-sros_nc NED. Do it in iterations, one at the time:
Follow the instructions in chapter 1.1 to 1.3 in 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.
Follow the instructions in chapter 1.2 to download the YANG models matching the configured device.
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: nokia-sros_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.
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 for more information.
Below is a description of the YANG recipes currently used by the nokia-sros_nc NED.
The YANG recipes used by this NED are divided into one group for Nokia SROS specific fixes and one for OpenConfig fixes
Not applicable
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 . 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 .
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.
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.
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
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.
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
Adds YANG statements to the schema.
Syntax:
Example:
Removes a YANG statement from the schema.
Syntax:
Example:
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:
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:
Identify the file containing the declaration of the node you wish to modify.
Open the file and locate the node.
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
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.
Open $NED_ROOT_DIR/src/ned-custom.mk.
Locate the do-profile-default make target.
Add your jypp rules to this section.
Example:
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:
Open $NED_ROOT_DIR/src/ned-custom.mk.
Locate the do-profile-default make target.
Add your ypp rules to this section.
Example:
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.
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:
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.
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.
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.
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:
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.
Make the NED fully operational with the full schema by following the initial setup steps (chapters 1.2 - 1.4).
Connect to the device:
Optionally, list the modules currently supported by the NED:
This lists all YANG modules with revisions built into the NED package.
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.
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.
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.
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.
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:
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:
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.
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.
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:
Ignore the auto-config artifacts: Accept that out-of-sync states may occur if they are not critical for the use case.
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.
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.
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.
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:
Perform an initial sync-from operation.
Apply the desired configuration to the device (e.g., via a service).
Execute show running-config and save the output in XML format to a file named before.xml. This specific file name is mandatory.
Perform a new sync-from operation.
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.
Generate the deviation file:
Rebuild the NED package
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.
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.
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.
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.
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.
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:
Rebuild the NED package using the trim-filter feature
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
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.
Rebuild the NED with the trim filter:
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.
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:
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:
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.
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.
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.
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.
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:
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.
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.
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 FeatureAlternative 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: nokia-sros_nc-r21.6-gen-1.'
This will generate a NED-ID like: nokia-sros_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: nokia-sros_nc-r21.6-gen-1.0
This will generate a NED-ID like: nokia-sros_nc-gen-21.6
Follow the instructions in chapter 1.4 to reload the NED package. The rebuilt NED package will now have the NED-ID: nokia-sros_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.
Reconfigure the device instance from step #1 in this list. Now use the new NED-ID
Verify functionality by executing a sync-from on the configured device instance.
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
Save the running configuration into an XML file:
Execute a dry-run commit using the installed service package configuration (stored in /tmp/my-service-test-config.xml):
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:
Reload the NED package:
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.
nodes-from-file: Specify a file containing a list of schema paths to trim.
To list unused nodes under a specific subtree:
To list all deprecated nodes:
To list all RPCs in the schema:
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.
Finally, after rebuilding the package, reload it to apply the changes:
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.
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:
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.
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.
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.
Rebuild the NED package and reload it:
Disable xpath tracing and restart NSO:
Finally, verify that the performance issue is solved.
admin@ncs# show running-config devices device dev-1 config | display xml | save overwrite /tmp/use-cases/day0.xmladmin@ncs# config
admin@ncs(config)# load merge /tmp/my-service-test-config.xml
admin@ncs(config)# commit dry-run outformat xml | save overwrite /tmp/use-cases/day1.xml
admin@ncs(config)# abortadmin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { scope { dir /tmp/use-cases } }admin@ncs# packages reload forceadmin@ncs# show devices device dev-1 moduledevices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema scope unused root-paths [ /conf:top/sublist ] output { file /tmp/all-unused-in-sublist }devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema with-status [ deprecated ] output { file /tmp/all-deprecated }devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema scope rpcs output { file /tmp/all-rpcs }admin@ncs# packages reload devices device dev-0 rpc rpc-xpath-trace-analyzer xpath-trace-analyzeradmin@ncs# devices device dev-0 rpc rpc-xpath-trace-analyzer xpath-trace-analyzer number-of-entries 5Top 5 most frequently occurring evaluated expressions:
Schema path: /ifm:ifm/interfaces/interface/ethernet:ethernet/l3-sub-interface
Expression: ../../ifm:class='sub-interface'
Occurrences: 1012418
Total time: 133.039000 s
Average time: 0.000131 s
Schema path: /ifm:ifm/interfaces/interface
Expression: ifm:type='Eth-Trunk' or ifm:type='Ip-Trunk'
Occurrences: 982920
Total time: 149.002000 s
Average time: 0.000152 s
Schema path: /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-group6s/nd-send-simple
Expression: /ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-termination
Occurrences: 711
Total time: 192.415000 s
Average time: 0.270626 s
Schema path: /ifm:ifm/interfaces/interface/arp:arp-entry
Expression: not(/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member[ifm-trunk:name=current()/../ifm:name])
Occurrences: 711
Total time: 218.064000 s
Average time: 0.306700 s
Schema path: /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-groups/arpsend-simple
Expression: /ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-termination
Occurrences: 711
Total time: 191.862000 s
Average time: 0.269848 s
Top 5 most time-consuming evaluate operations:
Schema path: /ifm:ifm/interfaces/interface/arp:arp-entry
Expression: not(/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member[ifm-trunk:name=current()/../ifm:name])
Occurrences: 711
Total time: 218.064000 s
Average time: 0.306700 s
Schema path: /ifm:ifm/interfaces/interface/ethernet:ethernet/main-interface/fim-ethernet:fim-main
Expression: not((../../../ifm:name) = (/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member/ifm-trunk:name)) and ../../../ifm:type!='FlexE-200GE' and ../../../ifm:type!='FlexE-50G' and ../../../ifm:type!='FlexE-100G' and ../../../ifm:type!='FlexE-10G' and ../../../ifm:type!='FlexE-400G' and ../../../ifm:type!='FlexE-50|100G' and ../../../ifm:type!='Virtual-Ethernet' and ../../../ifm:type!='Tunnel' and ../../../ifm:type!='NULL' and ../../../ifm:type!='LoopBack' and ../../../ifm:type!='Global-VE' and ../../../ifm:type!='Nve' and ../../../ifm:type!='Vbdif' and ../../../ifm:type!='Vlanif' and ../../../ifm:type!='PW-VE'
Occurrences: 711
Total time: 194.174000 s
Average time: 0.273100 s
Schema path: /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-group6s/nd-send-simple
Expression: /ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-termination
Occurrences: 711
Total time: 192.415000 s
Average time: 0.270626 s
Schema path: /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-groups/arpsend-simple
Expression: /ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-termination
Occurrences: 711
Total time: 191.862000 s
Average time: 0.269848 s
Schema path: /bd:bd/instances/instance/ims:igmp-snooping/static-router-ports
Expression: /mc:multicast/ims:igmp-snooping/ims:global-enable or /ni:network-instance/ni:instances/ni:instance/igmp-mld:igmp/igmp-mld:interfaces/igmp-mld:interface[igmp-mld:enable='true'][igmp-mld:name=/ifm:ifm/ifm:interfaces/ifm:interface[ifm:type='Vbdif'][ifm:number=string(current()/../../bd:id)]/ifm:name]
Occurrences: 1
Total time: 0.122000 s
Average time: 0.122000 snot(/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member[ifm-trunk:name=current()/../ifm:name])
not((../../../ifm:name) = (/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member/ifm-trunk:name)) and ../../../ifm:type!='FlexE-200GE' and ../../../ifm:type!='FlexE-50G' and ../../../ifm:type!='FlexE-100G' and ../../../ifm:type!='FlexE-10G' and ../../../ifm:type!='FlexE-400G' and ../../../ifm:type!='FlexE-50|100G' and ../../../ifm:type!='Virtual-Ethernet' and ../../../ifm:type!='Tunnel' and ../../../ifm:type!='NULL' and ../../../ifm:type!='LoopBack' and ../../../ifm:type!='Global-VE' and ../../../ifm:type!='Nve' and ../../../ifm:type!='Vbdif' and ../../../ifm:type!='Vlanif' and ../../../ifm:type!='PW-VE'
/ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-terminationadmin@ncs# devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema root-paths [ /ifm:ifm/interfaces/interface/arp:arp-entry /ifm:ifm/interfaces/interface/ethernet:ethernet/main-interface/fim-ethernet:fim-main /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-group6s/nd-send-simple /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-groups/arpsend-simple ] details/ifm:ifm/interfaces/interface/vrrp:vrrp/backup-groups/arpsend-simple
when "/ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-termination"
/ifm:ifm/interfaces/interface/vrrp:vrrp/backup-group6s/nd-send-simple
when "/ifm:ifm/ifm:interfaces/ifm:interface/ethernet:ethernet/ethernet:l3-sub-interface/ethernet:qinq-termination"
/ifm:ifm/interfaces/interface/ethernet:ethernet/main-interface/fim-ethernet:fim-main
when "not((../../../ifm:name) = (/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member/ifm-trunk:name)) and ../../../ifm:type!='FlexE-200GE' and ../../../ifm:type!='FlexE-50G' and ../../../ifm:type!='FlexE-100G' and ../../../ifm:type!='FlexE-10G' and ../../../ifm:type!='FlexE-400G' and ../../../ifm:type!='FlexE-50|100G' and ../../../ifm:type!='Virtual-Ethernet' and ../../../ifm:type!='Tunnel' and ../../../ifm:type!='NULL' and ../../../ifm:type!='LoopBack' and ../../../ifm:type!='Global-VE' and ../../../ifm:type!='Nve' and ../../../ifm:type!='Vbdif' and ../../../ifm:type!='Vlanif' and ../../../ifm:type!='PW-VE'"
/ifm:ifm/interfaces/interface/ethernet:ethernet/main-interface/fim-ethernet:fim-main/outer-vlan-enable
/ifm:ifm/interfaces/interface/arp:arp-entry
when "not(/ifm:ifm/ifm:interfaces/ifm:interface/ifm-trunk:trunk/ifm-trunk:members/ifm-trunk:member[ifm-trunk:name=current()/../ifm:name])"
..
..remove /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-groups/arpsend-simple::when
remove /ifm:ifm/interfaces/interface/vrrp:vrrp/backup-group6s/nd-send-simple::when
remove /ifm:ifm/interfaces/interface/ethernet:ethernet/main-interface/fim-ethernet:fim-main::when
remove /ifm:ifm/ifm:interfaces/ifm:interface/arp-entry::whenadmin@ncs# devices device dev-0 rpc rpc-rebuild-package rebuild-package
admin@ncs# packages reload# devices device dev-1 rpc rpc-get-modules get-modules profile sros-combined-from-device# devices device dev-1 rpc rpc-get-modules get-modules# devices device dev-1 rpc rpc-get-modules get-modules profile openconfig-from-deviceadmin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package> cd $NED_ROOT_DIR/src
> make clean alladmin@ncs# packages reloadadmin@ncs# packages reload forceadmin@ncs# devices device dev-1 rpc rpc-clean-package clean-package> cd $NED_ROOT_DIR/src
> make distcleanadmin@ncs# devices device dev-1 rpc rpc-clean-package clean-packageadmin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package> cd $NED_ROOT_DIR/src
> make distclean clean all# devices device dev-1 rpc rpc-list-modules list-modules# devices device dev-1 rpc rpc-list-modules list-modules module-include-regex "(nokia-.+)"# devices device dev-1 rpc rpc-list-modules list-modules module-exclude-regex "(nokia-sr-openconfig-.+)"# devices device dev-1 rpc rpc-get-modules get-modules module-include-regex "(nokia-.+)" module-exclude-regex "(nokia-sr-openconfig-.+)" <additional arguments>> cp <path to directory with the YANG files>/*.yang $NED_ROOT_DIR/src/yangtailf-internal-rpcs.yang
tailf-internal-rpcs-custom.yang
tailf-ned-nokia-sros_nc-dev-meta.yang
tailf-ned-nokia-sros_nc-meta.yang
tailf-ned-nokia-sros_nc-meta-custom.yang
tailf-ned-nokia-sros_nc-oper.yang
tailf-ned-nokia-sros_nc-stats.yangadmin@ncs# devices device dev-1 rpc rpc-export-package export-package
result ok
exported to: /tmp/ncs-6.2.2-nokia-sros_nc-1.0.2-customized.tar.gzPath: /conf:configure/filter/ip-filter/entry/log
Fix: type inlinedPath: /conf:configure/qos/sap-egress/fc/queue
Fix: type inlinedPath: /conf:configure/qos/sap-ingress/fc/multicast-queue
Fix: type inlinedPath: /conf:configure/qos/sap-ingress/fc/queue
Fix: type inlinedPath: /conf:configure/qos/queue-group-templates/egress/queue-group/fc/queue/queue-id
Fix: type inlinedPath: /conf:configure/service/epipe/customer
Fix: type inlinedPath: /conf:configure/service/vprn/customer
Fix: type inlinedPath: /conf:configure/service/vpls/customer
Fix: type inlinedPath: /conf:configure/service/ies/customer
Fix: type inlinedPath: /conf:configure/system/security/cpm-filter/ip-filter/entry/log
Fix: type inlinedPath: /#sr-igp-config/#srgb
Fix: RemovedPath: /#sr-igp-config/#srlb
Fix: RemovedPath: /#.oc-platform:components.oc-platform:component.oc-platform:properties.oc-platform:property.oc-platform:name/deviate/type
Fix: Replaced with type stringPath: /#.oc-platform:components.oc-platform:component.oc-platform:subcomponents.oc-platform:subcomponent.oc-platform:name/deviate/type
Fix: Replaced with type stringPath: /#.oc-netinst:network-instances.oc-netinst:network-instance.oc-netinst:inter-instance-policies
Fix: RemovedPath: /#.oc-platform:components.oc-platform:component.oc-transceiver:transceiver.oc-transceiver:physical-channels.oc-transceiver:channel.oc-transceiver:index/deviate/type
Fix: Replaced with type uint16AUTOPATCH_YANG_NED ?= yes> cd $NED_ROOT_DIR/src
> make clean all
augmented/[email protected]:2876: error: the node 'protocol' from module 'openconfig-network-instance' (in node 'config' in module 'openconfig-network-instance' from 'openconfig-network-instance') is not found
augmented/openconfig-rib-bgp-attributes.yang:2284: error: the node 'endpoint' from module 'openconfig-network-instance' (in node 'state' in module 'openconfig-network-instance' from 'openconfig-network-instance') is not found
augmented/openconfig-rib-bgp-attributes.yang:2309: error: the node 'instance-id' from module 'openconfig-network-instance' (in node 'state' in module 'openconfig-network-instance' from 'openconfig-network-instance') is not found leaf forwarding-action {
type identityref {
base FORWARDING_ACTION;
}
/* AUTO-PATCHED: Removed stmt: /oc-acl:acl/acl-sets/acl-set/acl-entries/acl-entry/actions/config/forwarding-action::mandatory
mandatory false;
*/
description "Specifies the forwarding action. One forwarding action
must be specified for each ACL entry";
} leaf interface {
/* AUTO-PATCHED: Inlined leafref target type from (type string, openconfig-interfaces.yang:793)
type leafref {
path /oc-if:interfaces/oc-if:interface/oc-if:name;
}
*/
type string;
description "Reference to a base interface. If a reference to a
subinterface is required, this leaf must be specified
to indicate the base interface.";
}
add <schema-path>::<YANG-stmt(s)|@filename>add /configuration/protocols/l2circuit/neighbor::uses apply-advanced;
add /configuration/protocols/l2circuit/neighbor/interface::{ min-elements 1; max-elements 10; }
add /configuration/protocols/l2circuit/neighbor::@file-with-YANG-snippetremove <schema-path>::<stmt-match>remove /configuration/routing-instances/instance/protocols/vpls/mesh-group/neighbor/vpls-id-list::ordered-by
remove /oc-acl:acl/acl-sets/acl-set/acl-entries/acl-entry/actions/config/forwarding-action::mandatoryreplace <schema-path>::<stmt-match>::<YANG-stmt(s)>replace /configuration/chassis/fpc/pic/name::type::type string;cd $NED_ROOT_DIR/src
./tools/jypp --print-path=<line number> tmp-yang/<model file>.yangtypedef mpls-label {
type union {
type uint32 {
range 13..1048575;
}
..
..> ./tools/jypp --print-path=280 tmp-yang/openconfig-mpls-types.yang
openconfig-mpls-types.yang:280 /#mpls-label/type/#uint32/rangedo-profile-default:
./tools/jypp --replace-stmt=/#mpls-label/type/#uint32/range::"range 13..1048575;" \
'tmp-yang/openconfig-mpls-types.yang' &> /dev/null || true
.PHONY: do-profile-default./tools/ypp --from=<regular expression> --to=<replacement containing text and/or matched groups> <file>./tools/ypp --from="(list\s+route\s+[^;]+)(route-type)([^;]+;)" --to="\g<1>\g<3>" 'tmp-yang/srl-ip-route-tables.yang'
./tools/ypp --from="(leaf\s+(dot1p-policy)\s+{[^}]+)(type\s+leafref[^}]+})" --to="\g<1>type string;" 'tmp-yang/srl-qos.yang'do-profile-default:
./tools/ypp --from="(list\s+route\s+[^;]+)(route-type)([^;]+;)" --to="\g<1>\g<3>" 'tmp-yang/srl-ip-route-tables.yang'
.PHONY: do-profile-default> cd $NED_ROOT_DIR/src
> make clean prepare-yangadmin@ncs# devices device dev-1 sync-from
result false
info illegal reference devices device dev-1 config components component 0/0 subcomponents subcomponent 0/0-Virtual-Motherboard nameinline-type /components/component/subcomponents/subcomponent/namemodule openconfig-interfaces {
yang-version "1";
// namespace
namespace "http://openconfig.net/yang/interfaces";
prefix "oc-if";
// import some basic types
import ietf-interfaces { prefix ietf-if; }
import openconfig-yang-types { prefix oc-yang; }
import openconfig-types { prefix oc-types; }
import openconfig-extensions { prefix oc-ext; }
import openconfig-transport-types { prefix oc-opt-types; }
..
..$ ncs_cli -C -u admin
admin@ncs# config
Entering configuration mode terminal
admin@ncs(config)# devices device xrv9k-gnmi-1 config oc-if:interfaces interface GigabitEthernet0/0/0/0 config description TEST
admin@ncs(config-interface-GigabitEthernet0/0/0/0)# commit dry-run outformat xml
result-xml {
local-node {
data <devices xmlns="http://tail-f.com/ns/ncs">
<device>
<name>xrv9k-gnmi-1</name>
<config>
<interfaces xmlns="http://openconfig.net/yang/interfaces">
<interface>
<name>GigabitEthernet0/0/0/0</name>
<config>
<description>TEST</description>
</config>
</interface>
</interfaces>
</config>
</device>
</devices>
}
}admin@ncs# config
admin@ncs(config)# load merge /tmp/my-first-service-use-case.xml
admin@ncs(config)# commit dry-run outformat xml | save overwrite /tmp/use-cases/use-case-1.xml
admin@ncs(config)# abort
admin@ncs# config
admin@ncs(config)# load merge /tmp/my-second-service-use-case.xml
admin@ncs(config)# commit dry-run outformat xml | save overwrite /tmp/use-cases/use-case-2.xml
admin@ncs(config)# abortadmin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { scope { dir /tmp/use-cases } }admin@ncs# packages reloadadmin@ncs# packages reload force$ make -C $NED_ROOT_DIR/src clean all YANG_SCOPE_FILTER_DIR=/tmp/use-casesadmin@ncs# devices device dev-1 connectadmin@ncs# show devices device dev-1 modulemodule trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
leaf a {
type string;
}
leaf b {
type string;
}
}
container top {
uses ab;
leaf c {
type string;
}
}
}module trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
/* AUTO-PATCHED: Trimmed /conf:top/a
leaf a { ... }
*/
leaf b {
type string;
}
}
container top {
uses ab;
/* AUTO-PATCHED: Trimmed /conf:top/c
leaf c { ... }
*/
}
}module trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
leaf a {
type string;
}
leaf b {
type string;
}
}
container top {
uses ab;
leaf c {
type string;
}
container subtree1 {
uses ab;
}
container subtree2 {
uses ab;
}
}
}module trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
leaf a {
type string;
}
leaf b {
type string;
}
}
container top {
/* AUTO-PATCHED: Expanded grouping ab
uses ab;
*/
/* AUTO-PATCHED: Trimmed /conf:top/a
leaf a { ... }
*/
leaf b {
type string;
}
leaf c {
type string;
}
container subtree1 {
/* AUTO-PATCHED: Expanded grouping ab
uses ab;
*/
leaf a {
type string;
}
/* AUTO-PATCHED: Trimmed /conf:top/subtree1/b
leaf b { ... }
*/
}
container subtree2 {
uses ab;
}
}
}module trim-schema-aug {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-aug;
prefix conf-aug;
import trim-schema {
prefix conf;
}
augment /conf:top/conf:subtree1 {
container extra {
leaf x {
type string;
}
leaf y {
type string;
}
}
}
}module trim-schema-aug {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-aug;
prefix conf-aug;
import trim-schema {
prefix conf;
}
augment /conf:top/conf:subtree1 {
container extra {
leaf x {
type string;
}
/* AUTO-PATCHED: Trimmed /conf:top/subtree1/extra/y
leaf y { ... }
*/
}
}
}module trim-schema-aug {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-aug;
prefix conf-aug;
import trim-schema {
prefix conf;
}
grouping extra {
container extra {
leaf x {
type string;
}
leaf y {
type string;
}
}
}
augment /conf:top/conf:subtree1 {
uses extra;
}
augment /conf:top/conf:subtree2 {
uses extra;
}
}module trim-schema-aug {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-aug;
prefix conf-aug;
import trim-schema {
prefix conf;
}
grouping extra {
container extra {
leaf x {
type string;
}
leaf y {
type string;
}
}
}
// AUTO-CLONE: Cloned from grouping extra used by node /conf:top/subtree1
grouping extra-AUTO-CLONED-7ccb8305 {
container extra {
leaf x {
type string;
}
/* AUTO-PATCHED: Trimmed /conf:top/subtree1/extra/y
leaf y { ... }
*/
}
}
augment /conf:top/conf:subtree1 {
/* AUTO-PATCHED: AUTO-CLONE: Using cloned grouping extra-AUTO-CLONED-7ccb8305
uses extra;
*/
uses extra-AUTO-CLONED-7ccb8305;
}
augment /conf:top/conf:subtree2 {
uses extra;
}
}module trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
leaf a {
type string;
}
leaf b {
type string;
}
}
container top {
uses ab;
list sublist {
key a;
uses ab;
}
leaf active {
type leafref {
path "../sublist/a";
}
}
}
}module trim-schema-aug {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-aug;
prefix conf-aug;
import trim-schema-test {
prefix conf;
}
grouping extra {
container extra {
leaf x {
type string;
}
leaf y {
type string;
}
}
}
augment /conf:top/conf:sublist {
uses extra;
}
}module trim-schema-dev {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-dev;
prefix conf-dev;
import trim-schema-test {
prefix conf;
}
deviation /conf:top/conf:sublist/conf:b {
deviate replace {
type uint32;
}
}
}module trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
leaf a {
type string;
}
leaf b {
type string;
}
}
container top {
uses ab;
/* AUTO-PATCHED: Trimmed /conf:top/sublist
list sublist { ... }
*/
leaf active {
/* AUTO-PATCHED: Inlined leafref target type from (type string, trim-schema-test.yang:10)
type leafref {
path "../subtree1/a";
}
*/
type string;
}
}
}module trim-schema-aug {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-aug;
prefix conf-aug;
import trim-schema {
prefix conf;
}
grouping extra {
container extra {
leaf x {
type string;
}
leaf y {
type string;
}
}
}
/* AUTO-PATCHED: Trimmed /conf:top/conf:sublist
augment /conf:top/conf:sublist { ... }
*/
}module trim-schema-dev {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf-dev;
prefix conf-dev;
import trim-schema {
prefix conf;
}
/* AUTO-PATCHED: Trimmed /conf:E/conf:sublist
deviation /conf:top/conf:sublist/conf:b { ... }
*/
}devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { ... } }devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { nodes [ /conf:top/conf:sublist /conf:top/conf:c] } }#This is a comment
/conf:top/conf:sublist
/conf:top/conf:cdevices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { nodes-from-file <path to file> } }devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { all-with-status [ deprecated obsolete ] } }devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { all-unused } }devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema scope used output { file /tmp/all-used }show running-config devices device dev-1 config | display xpathdevices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema scope unused output { file /tmp/all-unused }devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { nodes-from-file /tmp/all-nodes-to-trim }$ make -C $NED_ROOT_DIR/src clean all YANG_TRIM_FILTER_FILE=/tmp/all-nodes-to-trimmodule trim-schema {
yang-version 1.1;
namespace urn:cisco.com:trim:test:conf;
prefix conf;
grouping ab {
leaf a {
type string;
}
leaf b {
type string;
}
choice my-choice {
case first {
leaf x {
type string;
}
leaf y {
type string;
}
}
leaf z {
type string;
}
}
container top {
uses ab;
list sublist {
key a;
uses ab;
}
}
}module nedcom-auto-deviations {
yang-version 1.1;
namespace urn:tail-f.com:nedcom-auto-deviations;
prefix nedcom-auto-deviations;
import Cisco-IOS-XR-um-key-chain-cfg {
prefix um-key-chain-cfg;
}
revision 2025-01-10 {
description "Automatic deviations generated from exclude filter";
}
deviation /um-key-chain-cfg:key/um-key-chain-cfg:chains/um-key-chain-cfg:chain/um-key-chain-cfg:accept-tolerance/um-key-chain-cfg:infinite {
deviate not-supported;
}
deviation /um-key-chain-cfg:key/um-key-chain-cfg:chains/um-key-chain-cfg:chain/um-key-chain-cfg:timezone/um-key-chain-cfg:gmt {
deviate not-supported;
}
}devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { auto-config { ... } }$NED_INSTALL_DIR/tools/turboy --silent --plugin=cdb-data --compare-config --read=<snabshot directory>/before.xml --read=<snapshot directory>/after.xml $NED_INSTALL_DIR/src/yang/../tmp-yang --yang-path=$NED_INSTALL_DIR/src/yang/.. --outformat=deviations --write=<path to deviation file>.yangmake -C $NED_INSTALL_DIR/src clean all YANG_EXTRA_DEVIATION_FILE="<path to deviation file"admin@ncs# config
admin@ncs(config)# load merge /tmp/my-service-test-config.xml
admin@ncs(config)# commit label 1
admin@ncs(config)# abortadmin@ncs# show running-config devices device dev-1 config | outformat xml | save overwrite /tmp/auto-config/before.xmladmin@ncs# devices device dev-1 compare-configadmin@ncs# devices device dev-1 sync-fromadmin@ncs# show running-config devices device dev-1 config | outformat xml | save overwrite /tmp/auto-config/after.xmladmin@ncs# show rollback-filesconfig
rollback-files apply-rollback-file id <the commit id for '1'>
commit
abortadmin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { auto-config { dir /tmp/auto-config } }admin@ncs# packages reloadadmin@ncs# devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema scope rpcs output { file /tmp/rpcs-to-trim }#/ethernet-switching:get-ethernet-switching-flood-information
/ethernet-switching:get-satellite-control-flood-ethernet
/ethernet-switching:get-satellite-control-composite-next-hop-eth
#/ethernet-switching:get-ethernet-switching-table-interface-information
#/ethernet-switching:get-ethernet-switching-table-persistent-learning
/ethernet-switching:get-persistent-learning-interface
#/ethernet-switching:get-persistent-learning-mac
/ethernet-switching:get-satellite-eth-switch-device-db
..
..admin@ncs# devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema with-status [ deprecated obsolete ] countdevices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { all-with-status [ deprecated obsolete ] } }admin@ncs# devtools true
admin@ncs# config
admin@ncs(config-config)# timecmd no devices device dev-1 config ifm interfaces interface Eth-Trunk44.123456 Command executed in 238.26 sec
admin@ncs(config-config)# timecmd commit
Commit complete.
Command executed in 2545.09 sec<xpath-trace-log>
<filename>./logs/xpath.trace</filename>
<enabled>true</enabled>
</xpath-trace-log>$ (cd <NSO_RUNTIME_DIR>; ncs --stop; ncs)module demo-schema {
yang-version 1.1;
namespace urn:cisco.com:demo:test:conf;
prefix conf;
container common-settings {
list master {
key name;
leaf name {
type string;
}
}
}
// Settings only relevant for device type A
container device-type-A-settings {
container used {
list used {
key name;
leaf name {
type leafref {
path "../../../common-settings/master/name"
}
}
}
}
}
// Settings only relevant for device type B
container device-type-B-settings {
container used {
list used {
key name;
leaf name {
type leafref {
path "../../../common-settings/master/name"
}
}
}
}
}
}<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="5">
<get-config>
<source>
<running/>
</source>
<filter>
<configure xmlns="urn:cisco.com:demo:test:conf">
<device-type-A-settings>
<used>
<used>
</used>>
</used>>
</device-type-A-settings>
<device-type-B-settings>
<used>
<used>
</used>>
</used>>
</device-type-B-settings>
</configure>
</filter>
</get-config>
</rpc><rpc-reply message-id="5" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>unknown-element</error-tag>
<error-severity>error</error-severity>
<error-path xmlns:a="urn:cisco.com:demo:test:conf">
/a:device-type-B-settings/a:used/a:used
</error-path>
<error-message>
MINOR: Unknown element
</error-message>
<error-info>
<bad-element>device-type-B-settings</bad-element>
</error-info>
</rpc-error>
</rpc-reply>admin@ncs# config
admin@ncs(config)# no devices device dev-1 config configure eth-cfm domain 12355 association 123
admin@ncs(config)# commit confirm-network-state
Aborted: External error in the NED implementation for device nokia-sros-1: RPC error: error unknown-element: MINOR: MGMT_CORE #2201: Unknown element (error-path: /a:configure/a:service/a:test-oam/a:service-activation-testhead)<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config><source><running/></source><filter>
<configure xmlns="urn:nokia.com:sros:ns:yang:sr:conf">
<test-oam>
<service-activation-testhead>
<service-test>
</service-test>
</service-activation-testhead>
</test-oam>
<service>
<vprn>
</vprn>
<vpls>
</vpls>
<ies>
</ies>
<epipe>
</epipe>
</service>
<router>
</router>
<port>
</port>
<lag>
</lag>
<eth-ring>
</eth-ring>
<eth-cfm>
<domain>
<md-admin-name>12355</md-admin-name>
<association>
<ma-admin-name>123</ma-admin-name>
</association>
</domain>
</eth-cfm>
</configure></filter></get-config></rpc>admin@ncs# devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema root-paths [ /conf:configure/eth-cfm/domain/association ] details/conf:configure/eth-cfm/domain/association
/conf:configure/eth-cfm/domain/association/ma-admin-name
referred by : /conf:configure/service/ies/interface/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/router/interface/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/eth-ring/path/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/port/ethernet/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/ies/interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/ies/subscriber-interface/group-interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/epipe/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vprn/interface/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/epipe/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/lag/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vprn/interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vprn/subscriber-interface/group-interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/mesh-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/test-oam/service-activation-testhead/service-test/service-stream/frame-payload/ethernet/eth-cfm/source/ma-admin-name
..
..admin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { nodes [ /conf:configure/test-oam/service-activation-testhead ] } }admin@ncs# packages reloadadmin@ncs# devices device dev-1 rpc rpc-show-loaded-schema show-loaded-schema root-paths [ /conf:configure/eth-cfm/domain/association ] details/conf:configure/eth-cfm/domain/association
/conf:configure/eth-cfm/domain/association/ma-admin-name
referred by : /conf:configure/service/vpls/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vprn/subscriber-interface/group-interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/eth-ring/path/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/lag/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/epipe/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vprn/interface/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vprn/interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/router/interface/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/ies/interface/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/port/ethernet/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/mesh-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/epipe/sap/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/ies/interface/spoke-sdp/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/vpls/eth-cfm/mep/ma-admin-name
referred by : /conf:configure/service/ies/subscriber-interface/group-interface/sap/eth-cfm/mep/ma-admin-nameadmin@ncs# config
admin@ncs(config)# no devices device dev-1 config configure eth-cfm domain 12355 association 123
admin@ncs(config)# commit confirm-network-state
Commit complete.
admin@ncs(config)#admin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package ned-id suffix -21.6admin@ncs# devices device dev-1 rpc rpc-rebuild-package rebuild-package ned-id major 21 minor 6> make NED_ID_SUFFIX=-r21.6 clean all> make NED_ID_MAJOR=21 NED_ID_MINOR=6 clean alladmin@ncs# devices device dev-1 sync-fromdevices device dev-1 rpc rpc-rebuild-package rebuild-package filter { trim-schema { nodes-from-file /tmp/rpcs-to-trim } }admin@ncs# config
admin@ncs(config-config)# no devices device dev-1 config ifm interfaces interface Eth-Trunk44.123456
admin@ncs(config-config)# abort
admin@ncs#