Installation of NSO & DrNED Examiner

Running NSO in a Docker Container

An alternative to installing and running NSO and DrNED Examiner native on your Linux host is to run them in a Docker container. This simplifies the installation process, especially if you are already familiar with working with Docker containers.

Prerequisites

The NYAT container requires Docker or Podman or some other compatible container runtime to be available. On Windows or macOS, Docker Desktop works.

Download the nyat-container image here and add the image to Docker:

Copy$ docker image load -i <nyat-tar-ball-name>[nyat-1.4.tar.xz]

Launch the container

In the example below, we detach the container from the controlling terminal. This is so that we can run all commands from the host without having to switch back and forth between container and host. We also like to mount host directories for logs and drned-xmnr state as this makes it easier to view logs and dig into xmnr bugs but it's not necessary. Assuming you want to do that, you do it like this:

Copy$ mkdir -p mnt/{logs,states,xmnr,yangs}
$ docker run --detach \
             --rm \
             --init \
             --mount type=bind,source=$(pwd)/mnt/logs,target=/nyat/logs \
             --mount type=bind,source=$(pwd)/mnt/states,target=/nyat/states \
             --mount type=bind,source=$(pwd)/mnt/xmnr,target=/nyat/xmnr \
             --mount type=bind,source=$(pwd)/mnt/yangs,target=/nyat/yangs \
             --name nyat \
             --hostname nyat nyat:1.0

Getting Started

The container includes a couple of documentation commands to view ChangeLog (whats-new) and simple getting started documentation (about).

Copy$ docker exec nyat whats-new
## 1.0 (2022-04-29)
- drned-xmnr commit ca7e30f2
  Fix closing issue with python 3.8
  Bump NSO to 5.8.


$ docker exec nyat about
# NYAT Container

## Summary

This is the NYAT container.  The container packages NSO, drned-xmnr,
support scripts and its purpose is to verify NETCONF and YANG interfaces.

In order to do this we support device on-boarding, building NETCONF
NEDs, translate CLI test vectors to NETCONF, cappture tests and run
tests and summarize any errors we encounter.

## Tools

The container includes the following tools
* NSO
* drned-xmnr
* support scripts
* NETCONF NED
...

The above example also shows how to run commands inside the container from the host - just do docker exec .

Other Commands

If you need to access the NSO CLI to do something not supported by ned-test.py, just enter the CLI as usual:

Copydocker exec -it nyat ncs_cli -C -u admin

Note: The flags we pass to docker exec, i.e. -it (--interactive and --tty). We need these for interactive commands like ncs_cli or bash otherwise these commands will get EOF on stdin and exit immediately.

Bare-metal Installation

Overview

This document assumes the use of NSO 5.2 or later release. NSO software for non-production use can be downloaded via Cisco DevNet at: https://developer.cisco.com/site/nso/.

Note: The previous section Running NSO in a Docker Container is a simplified alternative to the bare-metal installation, using Docker Containers.

NSO Installation

NSO is delivered as a self-extracting archive which is OS/CPU specific. For NSO’s run time dependencies, please, refer to the Prerequisites section in Chapter 1 of the NSO Installation Guide that can be found under the doc folder in your installation directory after NSO has been installed on your system. To install NSO, just run the NSO installer with a single argument, that is the directory where you would like NSO to be installed. The installation directory you specify must either not yet exist or be empty. No files will be added or modified outside the directory you specify.

Copy$ sh nso-<VERSION>.<OS>.<ARCH>.installer.bin /path/to/install_dir

On a typical system, the installation process looks like this:

Copy$ sh download/nso-x.x.linux.x86_64.installer.bin ~/nso-x.x
INFO  Using temporary directory /var/folders/cs/7g8xdq0j1_b6k6p3pty3h3_w0000gp/T//ncs_installer.15936 to stage NCS installation bundle
INFO  Unpacked ncs-x.x in /home/tempuser/nso-x.x
INFO  Found and unpacked corresponding DOCUMENTATION_PACKAGE
INFO  Found and unpacked corresponding EXAMPLE_PACKAGE
INFO  Generating default SSH hostkey (this may take some time)
INFO  SSH hostkey generated
INFO  Environment set-up generated in /home/tempuser/nso-x.x/ncsrc
INFO  NCS installation script finished
INFO  Found and unpacked corresponding NETSIM_PACKAGE
INFO  NCS installation complete

As you can see, in addition to unpacking the installation files, the installer will create a default SSH hostkey and a file called ‘ncsrc’ with handy environment settings for using this installation.

Refer to the NSO Installation Guide that can be found under the doc folder of your NSO installation for more information on how to install and start NSO on your system.

Run NSO

Source the shell script that was created during the installation as follows:

Copy$ source $HOME/nso-version/ncsrc

Create a runtime directory for NSO to keep its database, state files, logs and other files. In these instructions we assume that this directory is $HOME/ncs-run.

Copy$ ncs-setup --no-netsim --dest $HOME/ncs-run

You will find the following folders getting created:

Copy$ ls $HOME/ncs-run
README.ncs     logs        ncs-cdb        ncs.conf
packages    scripts    state

Start the NSO daemon ncs:

Copy$ cd $HOME/ncs-run
ncs-run$ ncs

When you start NSO, make sure that you are situated in the deployment directory since by default NSO reads its config files from its current working directory.

Install the DrNED Examiner Package

The DrNED Examiner package is a toolkit that helps with testing both CLI and NETCONF NEDs. It can perform automated interoperability testing with your device. Its full capabilities for testing NETCONF NEDs will be described in this document. Refer to the Readme file in the GitHub site for the latest version requirements on the required packages,

DrNED Examiner is written in Python and depends on the following Python packages:

• pytest
• pexpect
• lxml

On Ubuntu, you can issue the following commands to install them:

Copyncs-run$ sudo apt-get install python-pytest python-pexpect python-lxml

You can get the latest DrNED Examiner package from https://github.com/NSO-developer/drned-xmnr and place it in the packages subdirectory under your ncs-run directory.

Copyncs-run$ cd packages
packages$ git clone https://github.com/NSO-developer/drned-xmnr.git

Execute the following command to build it:

Copypackages$ cd ..
ncs-run$ make –C packages/drned-xmnr/src clean all

Run NSO CLI and Load the DrNED Examiner Package

Launch the NSO CLI in Cisco style:

Copyncs-run$ ncs_cli –C –u admin

The default login and password for NSO are admin and admin.

Copyadmin@ncs# packages reload
reload-result {
    package drned-xmnr
    result true
}
admin@ncs#
System message at 2019-10-07 14:29:41...
    Subsystem stopped: ncs-dp-19163-drned-xmnr:drned_xmnr
admin@ncs#
System message at 2019-10-07 14:29:42...
    Subsystem started: ncs-dp-19222-drned-xmnr:drned_xmnr
admin@ncs# show packages
packages package drned-xmnr
 package-version 0.1.0
 description     "DrNED Examiner is a tool for examining/diagnosing your NEDs"
 ncs-min-version [ 4.1 ]
 python-package vm-name drned-xmnr
 directory       ./state/packages-in-use/1/drned-xmnr
 component drned_xmnr
  application python-class-name drned_xmnr.action.Xmnr
  application start-phase phase2
 oper-status up

Configure the DrNED Examiner Package

DrNED Examiner has two configuration parameters: /drned-xmnr/xmnr-directory and /drned-xmnr/drned-directory. The former sets the location where the tool stores its data and defaults to /tmp/xmnr; the latter defaults to the built-in DrNED package that comes with this DrNED Examiner package.

We will just set the first parameter to a directory called xmnr in the ncs-run folder and leave the second one to its default value. It is also a good idea to configure logging in the Examiner CLI to not be too verbose and also make sure that logging is enabled for the python-vm as these logs contain a lot of useful troubleshooting information:

Copyncs-run$ mkdir xmnr
ncs-run$ ncs_cli -C -u admin
admin@ncs# config
admin@ncs(config)# drned-xmnr log-detail cli overview
admin@ncs(config)# drned-xmnr xmnr-directory ./xmnr
admin@ncs(config)# python-vm logging level level-debug
admin@ncs(config)# commit
Commit complete.