1. General
1.1 Extract the NED package
1.2 Install the NED package
1.2.1 Local install
1.2.2 System install
1.3 Configure the NED in NSO
2. Optional debug and trace setup
3. Dependencies
4. Sample device configuration
5. Built in RPC actions
5.1. rpc clean-package
5.2. rpc export-package
5.3. rpc get-modules
5.4. rpc list-modules
5.5. rpc list-profiles
5.6. rpc rebuild-package
5.7. rpc show-default-local-dir
5.8. rpc show-loaded-schema
5.7.1 any
5.7.2 gNOI
6. Built in live-status show
7. Limitations
8. How to report NED issues and feature requests
9. How to rebuild a NED
10. Using the NED feature load-native-config
1. General
This document describes the nokia-srlinux_gnmi NED.
This NED can be used together with Nokia SRLinux devices with gNMI support enabled.
It has been successfully tested with the following devices:
- Nokia SRLinux release v24.3.3
- Nokia SRLinux release v23.10.1
- Nokia SRLinux release v23.3.2
IMPORTANT:
This NED is delivered without any of the device YANG models bundled to the NED package.
It is required to download the YANG files separately and rebuild the NED package before the NED is
fully operational. See the README-rebuild.md for further information.
The recommended way to do this is by following the steps below:
Install and setup the NED. See chapter 1.1 to 1.3
Download the YANG models. See chapter 1.1 in README-rebuild.md for the recommended method (alternatives are described in
README-rebuild.md chapter 2 and 3).
Rebuild the NED. See chapter 1.3 in README-rebuild.md (an alternative with a custom NED-ID is described in README-rebuild.md chapter 4).
Reload the NED in NSO. See chapter 1.4 in README-rebuild.md
Additional README files bundled with this NED package
+---------------------------+------------------------------------------------------------------------------+
| Name | Info |
+---------------------------+------------------------------------------------------------------------------+
| README-ned-settings.md | Information about all run time settings supported by this NED. |
| | |
| README-rebuild.md | Detailed instructions on how to download the device YANG models and |
| | rebuilding the NED with them. |
+---------------------------+------------------------------------------------------------------------------+
Common NED Features
+---------------------------+-----------+------------------------------------------------------------------+
| Feature | Supported | Info |
+---------------------------+-----------+------------------------------------------------------------------+
| netsim | no | |
| | | |
| check-sync | yes | Disabled by default. Two alternatives available: 1. trans-id by |
| | | checking latest commit id on device, 2. trans-id by doing a hash |
| | | of the device config. See README-ned-settings.md |
| | | |
| partial-sync-from | yes | |
| | | |
| live-status actions | no | |
| | | |
| live-status show | yes | |
| | | |
| load-native-config | yes | Config snippet must be formatted as a gNMI SET request. See |
| | | chapter 9 for further info. |
+---------------------------+-----------+------------------------------------------------------------------+
Verified target systems
+---------------------------+-----------------+--------+---------------------------------------------------+
| Model | Version | OS | Info |
+---------------------------+-----------------+--------+---------------------------------------------------+
| Nokia SRLinux VM | v24.10.3 | SRLin | |
| | | | |
| Nokia SRLinux VM | v24.3.3 | SRLin | |
| | | | |
| Nokia SRLinux VM | v23.10.1 | SRLin | |
| | | | |
| Nokia SRLinux VM | v23.3.2 | SRLin | |
+---------------------------+-----------------+--------+---------------------------------------------------+
Verified YANG model bundles
+---------------------------+-----------------+------------------------------------------------------------+
| Bundle | Version | Info |
+---------------------------+-----------------+------------------------------------------------------------+
| Nokia SRLinux | 24.3.3 | |
| | | |
| Nokia SRLinux | 24.10.3 | |
| | | |
| Nokia SRLinux | 23.10.1 | |
| | | |
| Nokia SRLinux | 23.3.2 | |
+---------------------------+-----------------+------------------------------------------------------------+
1.1 Extract the NED package
It is assumed the NED package ncs-<NSO version>-nokia-srlinux_gnmi-<NED version>.signed.bin has already
been downloaded from software.cisco.com.
In this instruction the following example settings will be used:
NSO version: 6.0
NED version: 1.0.1
NED package downloaded to: /tmp/ned-package-store
Extract the NED package and verify its signature:
> cd /tmp/ned-package-store
> chmod u+x ncs-6.0-nokia-srlinux_gnmi-1.0.1.signed.bin
> ./ncs-6.0-nokia-srlinux_gnmi-1.0.1.signed.bin
In case the signature can not be verified (for instance if no internet connection),
do as below instead:
The result of the extraction shall be a tar.gz file with the same name as the .bin file:
> ls *.tar.gz
ncs-6.0-nokia-srlinux_gnmi-1.0.1.tar.gz
1.2 Install the NED package
There are two alternative ways to install this NED package.
Which one to use depends on how NSO itself is setup.
In the instructions below the following example settings will be used:
NSO version: 6.0
NED version: 1.0.1
NED download directory: /tmp/ned-package-store
NSO run time directory: ~/nso-lab-rundir
A prerequisite is to set the environment variable NSO_RUNDIR to point at the NSO run time directory:
> export NSO_RUNDIR=~/nso-lab-rundir
IMPORTANT:
This NED is delivered as an “empty” package, i.e without any device YANG models bundled.
It must be rebuilt with the device YANG models to become operational.
The procedure to rebuild the empty NED (described in the README-rebuild.md) shall typically
be done in a lab environment. For this step a “local install” of the NED shall be used.
It is not suitable to use “system install” here since it is intended for production systems only.
Once this NED has been rebuilt with the device YANG and exported to one or many
separate tar.gz customized NED packages, a “system installation” can be used on them.
1.2.1 Local install
This section describes how to install a NED package on a locally installed NSO
(see "NSO Local Install" in the NSO Installation guide).
It is assumed the NED package has been been unpacked to a tar.gz file as described in 1.1.
Untar the tar.gz file. This creates a new sub-directory named:nokia-srlinux_gnmi-<NED major digit>.<NED minor digit>:
> tar xfz ncs-6.0-nokia-srlinux_gnmi-1.0.1.tar.gz
> ls -d */
nokia-srlinux_gnmi-gen-1.0
Install the NED into NSO, using the ncs-setup tool:
admin@ncs(config)# devices device dev-1 sync-from
result true
If the sync-from was not successful, check the NED configuration again.
2. Optional debug and trace setup
It is often desirable to see details from when and how the NED interacts with the device(Example: troubleshooting)
This can be achieved by configuring NSO to generate a trace file for the NED. A trace file
contains information about all interactions with the device. Messages sent and received as well
as debug printouts, depending on the log level configured.
NSO creates one separate trace file for each device instance with tracing enabled.
Stored in the following location:
The log level 'info' is used by default and the 'debug' level is the most verbose.
IMPORTANT:
Tracing shall be used with caution. This feature does increase the number of IPC messages sent
between the NED and NSO. In some cases this can affect the performance in NSO. Hence, tracing should
normally be disabled in production systems.
An alternative method for generating printouts from the NED is to enable the Java logging mechanism.
This makes the NED print log messages to common NSO Java log file.
IMPORTANT:
Java logging does not use any IPC messages sent to NSO. Consequently, NSO performance is not
affected. However, all log printouts from all log enabled devices are saved in one single file.
This means that the usability is limited. Typically single device use cases etc.
3. Dependencies
This NED has the following host environment dependencies:
Java 1.8 (NSO version < 6.2)
Java 17 (NSO version >= 6.2)
Gnu Sed
Dependencies for NED recompile:
Apache Ant
Bash
Gnu Sort
Gnu awk
Grep
Python3 (with packages: re, sys, getopt, subprocess, argparse, os, glob)
4. Sample device configuration
The example below has been successfully verified using a Nokia SRLinux VM running version v22.6.4.
Note that it was necessary to expclicitly specify a TLS cipher to successfully connect to the device.
devices authgroups group dev-1
default-map remote-name <user name>
default-map remote-password <password>
!
devices device dev-1
address <address to device>
port <port used by gNMI service on device>
authgroup dev-1
device-type generic ned-id nokia-srlinux_gnmi-gen-1.0
ned-settings nokia-srlinux_gnmi connection tls enable true
ned-settings nokia-srlinux_gnmi connection tls accept-any true
ned-settings nokia-srlinux_gnmi connection tls ciphers [ TLS_RSA_WITH_AES_128_CBC_SHA ]
!
5. Built in RPC actions
5.1. rpc clean-package
Cleans the NED package from all downloaded third party YANG files.
Input arguments:
- verbose <empty>
Print the full clean output also for successful executions (otherwise only printed on errors).
5.2. rpc export-package
Export the customized and rebuilt NED. The exported archive file can then be used to install the
NED package in other NSO instances. The name of the file will by default have the following format
ncs-<NSO version>-<NED name>-<NED-version>-customized.tgz.
Input arguments:
- destination <string> (default /tmp)
Set destination directory for the exported archive file.
- suffix <string> (default -customized)
Configure a customized suffix to the name of the archive file.
5.3. rpc get-modules
Fetch the YANG modules advertised by the device, from device or given source.
Input arguments:
- module-include-regex <string>
Regular expression matching all YANG models to be included in the download. Example:
openconfig-.*.
- module-exclude-regex <string>
Regular expression matching all YANG models to be excluded from the download. Example:
tailf-.*.
- namespace-include-regex <string>
Regular expression matching all namespaces to be included in the download. Example: tailf-.*.
- namespace-exclude-regex <string>
Regular expression matching all namespaces to be excluded from the download. Example:
tailf-.*.
- module-additional-include-regex <string>
Regular expression matching additional YANG models that are not advertised by the device. For
instance vendor specific deviation models. Example: cisco-nx-openconfig-deviations.*.
- module-additional-exclude-regex <string>
Regular expression matching exceptions from the additional-include-regex.
- profile <union>
Use a download profile to match a predefined subset of matching YANG files.
- local-dir <string>
Path to the directory where the YANG files are to be copied (defaults to src/yang in package).
- ignore-errors <empty>
Ignore errors during download. For example missing files of failed revision checks.
Either of:
- remote device <empty>
The device itself.
OR:
- remote dir <string>
A directory on the local host holding all YANG files. For instance a local clone of a git
repository.
OR:
- remote archive <string>
A path to a zip/tgz archive file containing the YANG files.
OR:
- remote git repository <string>
The URL to the git repository. Example: https://github.com/YangModels/yang.git.
- remote git dir <string>
Path to a sub directory inside the git repo where the YANG files can be found. Example:
vendor/cisco/nx/10.1-2.
- remote git checkout <string>
Optionally, a name of a branch/tag in the git repo where the YANG files can be found.
Example: master.
- remote git include-dir <string>
Optional extra include paths to be used when searching for YANG files. Each include path
is relative to the git root directory.
5.4. rpc list-modules
List 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-additional-include-regex <string>
Regular expression matching additional YANG models that are not advertised by the device. For
instance vendor specific deviation models. Example: cisco-nx-openconfig-deviations.*.
- module-additional-exclude-regex <string>
Regular expression matching exceptions from the additional-include-regex.
- profile <union>
Use a download profile to match a predefined subset of matching YANG files.
5.5. rpc list-profiles
Fetch a list of all predefined download profiles supported by the NED.
No input arguments
5.6. rpc rebuild-package
Rebuild the NED package directly from within NSO. This invokes the gnu make internally.
Input arguments:
- verbose <empty>
Print the full build output also for successful executions (otherwise only printed on errors).
- profile <union>
Apply a certain build profile.
- filter scope dir <string>
Directory containing one or many xml file representing the wanted scope.
- filter trim-schema nodes <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).
- filter trim-schema file <string> (default /tmp/nedcom-trim-deviations.yang)
Name of auto generated deviation file with nodes to trim.
- filter auto-config dir <string>
Directory containing the files used for auto-config filtering. The following files must be
present: before.xml and after.xml.
- filter auto-config file <string> (default /tmp/nedcom-auto-deviations.yang)
Name of auto generated deviation file.
- ned-id major <string>
Set a custom major number in the generated ned-id.
- ned-id minor <string>
Set a custom minor number in the generated ned-id.
- ned-id suffix <string>
Set a custom suffix in the generated ned-id.
- local-dir <string>
Path to the directory where the YANG files are to be copied (defaults to src/yang in package).
5.7. rpc show-default-local-dir
Show the path to the default directory where the YANG files are to be copied. I.e <path to current
NED package>/src/yang.
No input arguments
5.8. rpc show-loaded-schema
Display the schema currently built into the NED package. Each node will by default be listed with
a schema path.
Input arguments:
- scope <enum> (default all)
Select the scope for the nodes that will be listed.
all - Display all nodes in the schema. This is the default.
used - Display only the config nodes in use, i.e currently populated in CDB.
unused - Display only the config nodes that are not in use.
- count <empty>
Count the nodes and return the sum instead of the full list of nodes.
- root-paths <string>
Specify root paths for which nodes shall be listed or counted. Only nodes with a schema path
starting any of the specified roots will then be processed.
- config <true|false> (default true)
Set to false to display non config nodes in the schema. Note: scope will in this case be
'all'.
5.7.1 any
exec any get
The NED supports a generic versatile get action which can be used for doing any type of read operation towards a Nokia SRLinux gNMI device.
exec any get origin <origin> encoding <encoding> path <path>
Mandatory arguments
path <string> - Specify the path to be used for the gNMI GET operation.
This can also be a EOS CLI command in case the optional origin argument is set to 'cli'
Optional arguments
origin <string> - Specify the gNMI origin to be used for the GET operation.
Nokia SRLinux supports the following predefined origins:
- openconfig : Used for accessing openconfig data, i.e the default config tree.
encoding <string> - Specify the gNMI encoding to be used.
The following predefined encodings are supported by SRLinux: JSON_IETF, JSON, ASCII
Example
admin@ncs# devices device nokia-srlinux-1 live-status exec any get encoding JSON_IETF path /srl_nokia-system:system/srl_nokia-system-name:name
response {
"srl_nokia-system:system":{
"srl_nokia-system-name:name":{
"host-name":"nokia-srlinux-1"
}
}
}
5.7.2 gNOI
The gRPC Network Operations Interface (gNOI) defines a set of gRPC-based services for executing operational commands on network devices. The gNOI command interface is supported on Nokia SRLInux version v23.3.2 and later. Currently limited to the categories system and file.
This NED supports a number of gNOI commands that can be executed on a SRLinux target.
exec gnoi system
This container contains all system gNOI commands.
time
Check time on the device
exec gnoi system time
Mandatory arguments
Optional arguments
ping
Execute ping on device
exec gnoi system ping <arguments>
Mandatory arguments
- destination <string> - Destination address.
Optional arguments
- source <string> - Source address.
- count <uint8> (default 1) - Number of packets.
- l3protocol <IPV4|IPV6> (default IPV4) - Layer3 protocol requested for the ping.
- interval <uint64> - Nanoseconds between requests.
- size <uint32> - Size of request packet. (excluding ICMP header)
- doNotFragment <boolean> - Set the do not fragment bit. (IPv4 destinations)
- doNotResolve <boolean> - Layer3 protocol requested for the ping.
traceroute
Execute traceroute on device.
exec gnoi system traceroute <arguments>
Mandatory arguments
- destination <string> - Destination address.
Optional arguments
- source <string> - Source address.
- initialTtl <uint8> (default 1) - Initial TTL.
- maxTtl <unit8> (default 30) - Maximum number of hops.
- l3protocol <IPV4|IPV6> (default IPV4) - Layer-3 protocol requested.
- l4protocol <ICMP|TCP|UDP> (default ICMP) - Layer-4 protocol requested
- doNotFragment <boolean> - Set the do not fragment bit. (IPv4 destinations)
- doNotResolve <boolean> - Layer3 protocol requested for the ping.
killProcess
Kill a process on the device. Either pid or process name must be specified
exec gnoi system killProcess <arguments>
Mandatory arguments
- pid <uint32> - The pid of the process to be killed.
- name <string> - The name of the process to be killed.
Optional arguments
- signal <SIGNAL_TERM|SIGNAL_KILL|SIGNAL_HUP> - Termination signal to be sent to the process
- restart <boolean>
reboot
Reboot the device
exec gnoi system reboot <arguments>
Mandatory arguments
Optional arguments
- delay <uint64> - Delay in nanoseconds before issuing reboot.
- message <string> - Informational reason for the reboot.
- force <boolean> - Force reboot if sanity checks fail. (ex. uncommited configuration)
- method <COLD|POWERDOWN|HALT|WARM|NSF|POWERUP> (default COLD) - Reboot method
cancelReboot
Cancel reboot of the device.
exec gnoi system cancelReboot <arguments>
Mandatory arguments
Optional arguments
- message <string> - Informational reason for the cancel
rebootStatus
Check reboot status on the device.
exec gnoi system rebootStatus
Mandatory arguments
Optional arguments
switchControlProcessor
Switch from the current route processor to the provided route processor.
exec gnoi system switchControlProcessor
Mandatory arguments
Optional arguments
6. Built in live-status show
The Nokia SRLinux NED has full support for fetching operational data via the NSO live-status API.
7. Limitations
Be aware that all XML namespaces were changed in SRLinux sometime between version 23 and 24.
Hence, if upgrading a NED that previously used SRLinux models for version 23 or older to version 24
will cause NSO to wipe most or all corresponding device data in CDB.
8. How to report NED issues and feature requests
Issues like bugs and errors shall always be reported to the Cisco NSO NED team through
the Cisco Support channel:
The following information is required for the Cisco NSO NED team to be able
to investigate an issue:
- A detailed recipe with steps to reproduce the issue.
- A raw trace file generated when the issue is reproduced.
- Access to a device where the issue can be reproduced by the Cisco NSO NED team.
This typically means both read and write permissions are required.
Pseudo access via tools like Webex, Zoom etc is not acceptable.
However, it is ok with device access through VPNs, jump servers etc though.
Do as follows to gather the necessary information needed for your device, here named 'dev-1':
Reproduce the found issue using ncs_cli or your NSO service.
Write down each necessary step in a reproduction report.
Gather the reproduction report and a copy of the raw trace file
containing data recorded when the issue happened.
Contact the Cisco support and request to open a case. Provide the gathered files
together with access details for a device that can be used by the
Cisco NSO NED when investigating the issue.
Requests for new features and extensions of the NED are handled by the Cisco NSO NED team when
applicable. Such requests shall also go through the Cisco support channel.
The following information is required for feature requests and extensions:
A detailed use case description, with details like:
Data of interest
The kind of operations to be used on the data. Like: 'read', 'create', 'update', 'delete'
and the order of the operation
Device APIs involved in the operations (For example: REST URLs and payloads)
Device documentation describing the operations involved
Run sync-from # devices device dev-1 sync-from (if relevant)
Attach the raw trace to the ticket (if relevant)
Access to a device that can be used by the Cisco NSO NED team for testing and verification
of the new feature. This usually means that both read and write permissions are required.
Pseudo access via tools like Webex, Zoom etc is not acceptable. However, it is ok with access
through VPNs, jump servers etc.
9. How to rebuild a NED
Check the README-rebuild.md file, chapter 1.3, for more information.
10. Using the NED feature load-native-config
This NED has support for the load-native-config feature, meaning that you can load config directly from a file formatted in native device format. Since it is a gNMI NED it is required that the file is formatted as a gNMI SetRequest message, as specified here: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md#341-the-setrequest-message
A gNMI SetRequest message is using a JSON structure containing three lists with the self explained names update, replace and delete. Each entry in the update and replace lists is a modify and/or create operation, represented by a gNMI path and a payload element. The latter is a JSON formatted string itself (in cleartext) describing the elements to be modified.
Each entry in the delete list is a delete operation represented by a gNMI path.
Optionally each gNMI SetRequest message can contain a prefix which is a gNMI path that will be prepended to all operations in the update, replace and delete lists.
Below is an example of a valid JSON structure that can be used for the load-native-commands feature.
