Cisco Crosswork NSO is a premier orchestration tool for hybrid networks. As a Linux-based application, it allows detailed control of network devices and can manage the configuration of both physical and virtual networks. It automates lifecycle services to help you create and deliver quality services more quickly.

Explore What's New in NSO

What's New | Cisco Crosswork NSO Documentation

Start Exploring NSO

NSO Basics

Learn the fundamentals of Cisco NSO.

Learning Paths

Explore various paths to learning NSO.

Quick Start

Get up and running with NSO quickly.

User Guides

Official NSO documentation guides.

Developer Reference

NSO APIs and interfaces reference.

NSO Resources

Platform tools, best practices, blogs, and more.

NSO for your Business Case

Integrate Cisco Crosswork NSO to boost network operations by automating services, reducing manual errors, and speeding up delivery. Discover more in:

• Common Use Cases for NSO

• FAQs on NSO

Welcome to the Cisco Crosswork NSO Documentation

On this page, you'll find a brief introduction to NSO to help you learn the basics of the product, its features, architecture, components, and how it helps you tackle network management challenges.

What is NSO?

Cisco Crosswork Network Services Orchestrator (NSO) enabled by Tail-f is an industry-leading orchestration platform for hybrid networks. As a Linux application, it allows fine-grained control of physical and virtual network devices and can powerfully orchestrate the configuration life cycle of networks they live in. It provides comprehensive lifecycle service automation to enable you to design and deliver high-quality services faster and easier.

Key Features

At its heart, NSO makes network orchestration possible by leveraging the following features:

• Multi-vendor device configuration management: Uses the native protocols of the network devices to manage a wide variety of network devices.

• Configuration Database (CDB): Manages synchronized configurations for all devices and services in the network domain.

• A rich set of northbound interfaces: Includes human interfaces like web UI and a CLI, programmable interfaces including RESTCONF, NETCONF, JSON-RPC, and language bindings including Java, Python, and Erlang.

• A central point of access to manage NSO: Manages entire networks for network engineers using the NSO CLI or web UI. Although this documentation illustrates the use cases using CLI examples, it is important to understand that any northbound interface can be used to achieve the same functionality.

• Network Element Drivers (NEDs): Used as software packages to facilitate telnet, SSH, or API interactions with the devices that it manages.

Background: The Orchestration Challenge

The industry is rapidly moving towards a service-oriented approach to network management, where multi-vendor devices, physical and virtual, support complex services. To manage these, operators are starting a transition from manually managing devices towards a situation where an operator is actively managing the various aspects of services.

Configuring the services and the affected devices is among the largest cost drivers in provider networks. Still, the common orchestration and configuration management practice involves pervasive manual work or ad hoc scripting. Why do we still apply these sorts of techniques to the configuration management problem? Two primary reasons are the variations of services and the constant change of devices. These two underlying characteristics are, to some degree, blocking automated solutions, since it takes too long to update the solution to cope with daily changes.

Time-to-market requirements are critical for a new service to be deployed quickly and the delay in configuring the corresponding tools has a significant impact on revenue. There is an unserved need in provider networks for tools that address these complex and sometimes contradictory challenges while constructing service configurations.

How NSO Addresses the Orchestration Challenge

Creating and configuring network services is a complex task that often requires multiple configuration changes to all devices participating in the service. Additionally, changes generally need to be made concurrently across all devices with the changes being either completely successful or rolled back to the starting configuration. And, configurations need to be kept in sync across the system and the network devices. NSO approaches these challenges by acting as an interface between people or software that want to configure the network and the devices in the network.

NSO enables service providers to dynamically adopt the orchestration solution according to changes in the offered service portfolio. This is enabled by using a model-driven architecture where service definitions can be changed on the fly. Rather than a hard-coded orchestrator, NSO learns from the service models. Service models are written in YANG (RFC 6020).

NSO delivers an automated orchestration solution toward a hybrid multi-vendor network. The network can be a mix of traditional equipment, virtual devices, and SDN Controllers. This flexibility is managed by a Network Element Driver, NED, layer that abstracts the device interfaces and the Device Manager which enables generic device configuration functions.

At the core of NSO is the configuration datastore, CDB, that is in sync with the actual device and service configuration. It also manages relationships between services and devices and can handle revisions of device interfaces.

All devices and services in the network can be accessed and configured using the NSO CLI, making it a powerful tool for network engineers. The CLI also provides an easy way to define roles and associated authorization policies limiting the engineer's view of the devices under NSO control. Policies and integrity constraints can also be defined to ensure the configuration adheres to operator standards.

The typical workflow when using the NSO CLI is as follows:

1. The user logs in to the CLI and thereby starts a new session. The session provides a (logical) copy of the running configuration of CDB as a scratch pad for edits.

2. Changes made to the scratch pad are optionally validated at any time against policies and schemas using the "validate" command. Changes can always be viewed and verified before committing them.

3. The changes are committed, meaning that the changes are copied to the NSO database and deltas are pushed out to the network devices that are affected by the change. Changes that violate integrity constraints or network policies will not be committed but produce validation errors. The changes to the devices are done in a distributed and atomic transaction across all devices in parallel.

4. Changes either succeed and remain committed to device configuration or fail and are rolled back as a whole returning the entire network to the prior state.

NSO Architecture

Related Learning: Building Blocks of NSO

NSO has two main layers, the Device Manager and the Service Manager. They serve different purposes but are tightly integrated with a transactional engine and database.

NSO uses a dedicated built-in storage Configuration Database (CDB) for all configuration data. NSO keeps the CDB in sync with the real network device configurations. Audit, to ensure configuration consistency, and reconciliation, to synchronize configuration with the devices, functions are supported. It also maintains the runtime relationships between service instances and the corresponding device configurations.

NSO uses Network Element Drivers, NEDs, to communicate with devices. NEDs are not closed hard-coded adapters. Rather, the device interface is modeled in a data model using the YANG data modeling language. NSO can render the required commands or operations directly from this model. This includes support for legacy configuration interfaces like device CLIs. This means that the NEDs can easily be updated to support new commands just by extending the data models with the appropriate model constructs which avoid any programming tasks as part of the change cycle.

NSO also comes with tooling for simulating the configuration aspects of a network. The netsim tool is used to simulate management interfaces like Cisco CLI and NETCONF for NSO examples and service development.

The main components of NSO are described below.

Service Manager

The Service Manager makes it possible for an operator to manage high-level aspects of the network that are not supported by the devices directly or are supported in a cumbersome way. With the appropriate service definition running in the Service Manager, an operator could for example configure the VLANs that should exist in the network in a single place, and the Service Manager compute the specific configuration changes required for each device in the network and push them out. This covers the whole life cycle for a service: creation, modification, and deletion. NSO has an intelligent and easy way to use a mapping layer so that network engineers can define how a service should be deployed in the network.

The Service Manager addresses the following challenges:

• Transaction-safe activation of services across different multi-vendor devices.

• What-if scenarios, (dry-run), showing the effects on the network for a service creation/change.

• Maintaining relationships between services and corresponding device configurations and vice versa.

• Modeling of services

• Short development and turn-around time for new services.

• Mapping the service model to device models.

Device Manager

The purpose of the Device Manager is to manage device configurations in a transactional manner. It supports features like fine-grained configuration commands, bidirectional device configuration synchronization, device groups and templates, and compliance reporting.

The Device Manager supports the following overall features:

• Deploy configuration changes to multiple devices in a fail-safe way using distributed transactions.

• Validate the integrity of configurations before deploying to the network.

• Apply configuration changes to named device groups.

• Apply templates (with variables) to named device groups.

• Easily roll back changes, if needed.

• Configuration audits: Check if device configurations are in sync with the NSO database. If they are not, what is the diff?

• Synchronize the NSO database and the configurations on devices, in case they are not in sync. This can be done in either direction (import the diff to the NSO database or deploy the diff on devices).

Network Element Drivers (NEDs)

NED, or Network Element Driver, represents a key NSO component that makes it possible for the NSO's core system to communicate southbound with the network devices in most deployments. NSO has a built-in client that can be used to communicate southbound with NETCONF-enabled devices. The vast majority of existing network devices are, however, not NETCONF-enabled. There are two main categories of NEDs: the CLI NEDs, and the Generic NEDs. Both categories have the same basic components in common. A Cisco-provided NED is an NSO package containing a bundle of YANG models together with a driver element implemented in Java.

UI and APIs

NSO provides user interfaces as well as northbound APIs for integration into other systems. The main user interface is the NSO network-wide CLI which gives a unified CLI towards the complete network including the network services. This documentation illustrates most of the functions using the CLI. NSO also provides a Web UI.

The northbound APIs are available in different language bindings (Java, Python), and as protocols, like NETCONF and REST.

To support dynamic updates of functionality as added or modified service models, support for a new device type, etc, NSO manages extensions as well-defined packages. Every NED is its own package with its own release life cycle. Every service model with the corresponding mapping is also a package of its own. These can be upgraded without upgrading NSO itself.

When running NSO against real devices, (not just the NSO network simulator for educational purposes), make sure you have the correct NED package version from the delivery repository.

To learn how to use NSO and also to simplify development using NSO, NSO comes with a network simulator, ncs-netsim. Many of the examples will use netsim as the network.

HA and Clustering

NSO supports a 1:N high-availability mode. One NSO system can be primary and can have any number of secondaries. Any configuration write has to go through the primary node. The configuration changes are replicated to the read-only secondaries. The replication can be done in asynchronous or synchronous mode. In the synchronous mode, the transaction returns when the secondaries are in sync.

For large networks, the network devices can be clustered across NSO systems. Say you have 100,000 devices split into two continents. You may choose to have 50,000 devices in one NSO and 50,000 in another. There are several options on how to configure clusters to see the whole network. The most common is a top NSO where services are provisioned, and the top NSO sees the whole network.

Core Concepts

These are some of the core concepts that make NSO special. The following picture gives a high-level view of the components involved.

NETCONF/YANG

As network programmability was starting to grow in importance it was realized that configuration of network elements needed a modern model-driven interface to enable that programmability. This led to the development of YANG, a modeling language for configuration.

NSO uses YANG as the overall modeling language to manage devices and services. YANG models describe all NSO configurations, including device configuration and service configuration. This means that everything that is done in NSO is model-driven, this allows all interfaces to be automatically rendered.

YANG was originally paired with NETCONF, but as REST became a more popular interface RESTCONF was standardized as well. Both of the protocols let you define your API using YANG, giving you a model-driven interface; this means that the basic working of the protocol is defined by the standards and the application-specific details can be derived from the loaded YANG models. The RESTCONF protocol provides a compatible subset of the functionality of the NETCONF protocol but does not provide the full transactional interface of the latter.

Configuration Database (CDB)

At the core of NSO is the Configuration Database (CDB). This is a tree-structured database that is defined by a YANG schema. This means that all of the information stored inside of NSO is validated against the schema.

Every transaction towards CDB exhibits ACID properties, which among other things means either the transaction as a whole ends up on all participating devices (as well as in the NSO CDB), or otherwise, the whole transaction is aborted and all changes are automatically rolled back.

The CDB always contains NSO's view of the complete network configuration. To handle out-of-band changes operations are available to check if a device is in sync, write NSO's view to the device, or read the device configuration into NSO.

Service Algorithm - FastMap

As a Service Developer, you need to express the mapping from a YANG service model to the corresponding device YANG models. This is a declarative mapping in the sense that no sequencing is defined. Observe that irrespective of the underlying device type and corresponding native device interface, the mapping is towards a YANG device model, not the native CLI for example. This means that as you write the service mapping, you do not have to worry about the syntax of different devices' CLI commands or in which order these commands are sent to the devices. This is all taken care of by the NSO device manager.

NSO reduces this problem to a single data-mapping definition for the "create" scenario. At run-time NSO will render the minimum change for any possible change like all the ones mentioned below. This is managed by the FASTMAP algorithm.

FASTMAP covers the complete service life-cycle: creating, changing, and deleting the service. The solution requires a minimum amount of code for mapping from a service model to a device model.

FASTMAP is based on generating changes from an initial 'create'. When the service instance is created the reverse of the resulting device configuration is stored together with the service instance. If an NSO user later changes the service instance, NSO first applies (in a transaction) the reverse diff of the service, effectively undoing the previous results of the service creation code. Then it runs the logic to create the service again and finally executes a diff to the current configuration. This diff is then sent to the devices.

Accessing the Network (NEDs)

The NSO device manager is the center of NSO. The device manager maintains a flat list of all managed devices. NSO serves as a "source of truth" and keeps a copy of the configuration for each managed device in the CDB. Whenever a change is done to the device configuration copies in the CDB, the device manager will partition this "network configuration change" into the corresponding changes for the actually managed devices. The device manager passes on the required changes to the NEDs, Network Element Drivers. A NED needs to be installed for every type of device OS, like Cisco IOS NED, Cisco XR NED, Juniper JUNOS NED, etc. The NEDs communicate through the native device protocol southbound. The NEDs fall into the following categories:

• NETCONF capable device. The Device Manager will produce NETCONF edit-configuration RPC operations for each participating device.

• SNMP device. The Device Manager translates the changes made to the configuration into the corresponding SNMP SET PDUs

• A device with Cisco CLI. The device has a CLI with the same structure as Cisco IOS or XR routers. The Device Manager and a CLI NED are used to produce the correct sequence of CLI commands which reflects the changes made to the configuration.

• For other devices that do not fit into any of the above-mentioned categories, a corresponding Generic NED is invoked. Generic NEDs are used for proprietary protocols like REST and for CLI flavors that are not resembling IOS or XR. The Device Manager will inform the Generic NED about the made changes and the NED will translate these to the appropriate operations toward the device.

NSO for Device Turnup

Simplify the deployment of a new device (e.g., a router). Construct and deliver the initial (day 1) config for the device, reducing the manual effort required and reducing the risk of errors.

NSO has configuration templates for the different device types and roles, and it takes the device-specific parameters for that device and applies them to the appropriate template. The engineer can choose to preview the configuration before it is sent to the device if desired. NSO then sends the configuration to the device and has the ability to save the config, reboot the device, etc. NSO can manage multiple devices in one operation and retry any failures.

NSO for NFV Orchestration

Orchestrate the lifecycle of a virtual service. Create, modify, repair, and delete virtualized services on customer demand within minutes or seconds.

NSO has a Network Service Descriptor (NSD) for each virtualized service that describes each Virtual Network Function (VNF) that makes up the virtual service and how the VNFs are chained together. NSO uses the NFV Orchestrator (NFVO) NSO Package to control a VNF Manager such as Cisco's Elastic Services Controller (ESC) and Virtual Infrastructure Managers (VIMs) such as OpenStack and vSphere.

NSO for SD-WAN Orchestration

Orchestrate the lifecycle of SD-WAN services, including Cisco iWAN (Intelligent WAN). Create, modify, repair, and delete SD-WAN services on customer demand within minutes or seconds.

NSO creates, modifies, repairs, and deletes SD-WAN hubs and branches for Service Provider customers.

For Cisco iWAN services, NSO uses the IWAN and vBranch Function Packs. These have built-in service definitions to match the Cisco Validated Design (CVD) for iWAN. Both physical and virtual branch sites are supported.

For other SD-WAN services, NSO has NEDs for solutions from Versa, Silverpeak, ODL, and others.

NSO for ACL Management

Simplify the management of Access Control Lists (ACLs) across network devices. Update ACLs on multiple devices on demand, ensuring security policies are applied consistently across the entire infrastructure.

NSO has service models corresponding to the desired security policies and generates ACLs matching the desired policy. Policies are translated into the exact syntax needed for the specific vendors and devices and delivered to the device using the appropriate NED.

NSO for QoS Management

Simplify the management of QoS shaping and policing rules on network devices. Update policy maps on demand, ensuring that QoS policies are applied correctly and consistently across the entire infrastructure.

Only the QoS parameters (bandwidth, etc.) have to be entered, and NSO has service models that generate the exact syntax needed for the specific vendors and devices. These are delivered to the device using the appropriate NED.

NSO as a Power Tool for Network Engineers

Use NSO's higher-level CLI to control network devices. Network Engineers interact with NSO's service models instead of directly with the device CLI. This greatly reduces the amount of CLI that must be entered and enables all devices in a multi-vendor network to be controlled using the same CLI syntax. Engineers can choose their preferred CLI syntax (e.g., Cisco or Juniper), and the NSO NEDs ensure that the right CLI is used for each device.

NSO for Config Audit

With NSO, you can ensure that device configurations conform to network-wide rules, ensuring that the entire network is correctly configured. NSO has configuration templates matching "golden configs" for the various device types and roles. NSO gets the latest running-config from each device and performs a config audit, comparing the config to the templates. Any deviations are flagged for correction.

NSO for OS Upgrade

Perform bulk upgrades of devices from a central location. The new OS (e.g., IOS, StarOS) is delivered to a set of devices in bulk, e.g., within a maintenance window.

NSO sends the update to the device and can save the config, reboot the device, etc. NSO can manage multiple devices in one operation and retry any failures.

Problems Solved

General NSO Configuration Management Principles

Vendor-Specific Device Management

Transactions and roll-backs

Usability

The Cisco NSO Difference

Integration, Support, and Hardware requirements

NFV and SDN

There are many different ways of learning NSO. This site has many resources available that can help you along the way.

With NSO, we often talk about an automation journey. Similarly, there is a journey for a Service Developer as well. Several skills come together when using NSO:

• NSO skills: You must understand how NSO works and how to implement your services in NSO.

• Networking: You have to have an understanding of the service that is being configured.

• Software development skills: Depending on your language of choice, a bit of Java or Python knowledge is desirable. Java or Python multiprocessing skills for faster service deployment are helpful.

• DevOps skills: Understanding the processes around automating the network, setting up delivery pipelines, and continuous integration systems.

The focus of the material we are collecting here is on the NSO skills, but as you dive deeper into NSO, additional skills will also be needed in the other areas.

Your Learning Journey with NSO

Download Your NSO Free Trial Installer and Cisco NEDs

This evaluation copy has been provided under the terms of the Cisco NSO Evaluation License. There are two versions of the NSO installer for macOS and Linux systems, respectively:

• NSO for Linux and MacOS (Darwin), including NED examples

Requirements

For development purposes, choose between the following:

• Linux for x86_64 or arm64.

• macOS Darwin for x86_64 or arm64.

A detailed list of NSO installation requirements can be found in the NSO Installation and Deployment guide.

Installation

Operating System

Cisco NSO can run on macOS or Linux systems. If you are a Windows user (or do not wish to install it natively on your laptop), you can install NSO on a Linux virtual machine or in a container.

If you use Docker, there are pre-built system install images available. See the Containerized NSO guide.

There are NSO Playgrounds available to dive right in and try out examples in a user-friendly browser-based integrated development environment (IDE).

Performing a Local Install

Once you've installed the prereqs and downloaded the NSO installation file for your operating system, you are ready to do your installation:

cd ~/Downloads
ls -l nso*.bin
-rw-r--r--@ 1 user  staff   199M Dec 15 11:45 nso-6.0.darwin.x86_64.installer.bin
-rw-r--r--@ 1 user  staff   199M Dec 15 11:45 nso-6.0.darwin.x86_64.signed.bin

sh nso-6.0.darwin.x86_64.signed.bin 

# Output
Unpacking...
Verifying signature...
Downloading CA certificate from http://www.cisco.com/security/pki/certs/crcam2.cer ...
Successfully downloaded and verified crcam2.cer.
Downloading SubCA certificate from http://www.cisco.com/security/pki/certs/innerspace.cer ...
Successfully downloaded and verified innerspace.cer.
Successfully verified root, subca and end-entity certificate chain.
Successfully fetched a public key from tailf.cer.
Successfully verified the signature of nso-6.0.darwin.x86_64.installer.bin using tailf.cer

ls -l

# Output
-rw-r--r--  1 user  staff   1.8K Nov 29 06:05 README.signature
-rw-r--r--  1 user  staff    12K Nov 29 06:05 cisco_x509_verify_release.py
-rwxr-xr-x  1 user  staff   199M Nov 29 05:55 nso-6.0.darwin.x86_64.installer.bin
-rw-r--r--  1 user  staff   256B Nov 29 06:05 nso-6.0.darwin.x86_64.installer.bin.signature
-rwxr-xr-x@ 1 user  staff   199M Dec 15 11:45 nso-6.0.darwin.x86_64.signed.bin
-rw-r--r--  1 user  staff   1.4K Nov 29 06:05 tailf.cer

sh nso-6.0.darwin.x86_64.installer.bin --help

# Output
This is the NCS installation script.

Usage: ./nso-6.0.darwin.x86_64.installer.bin [--local-install] LocalInstallDir

Installs NCS in the LocalInstallDir directory only.
This is convenient for test and development purposes.

Usage: ./nso-6.0.darwin.x86_64.installer.bin --system-install [--install-dir InstallDir]
    [--config-dir ConfigDir] [--run-dir RunDir] [--log-dir LogDir]
    [--run-as-user User] [--keep-ncs-setup] [--non-interactive]

Does a system install of NCS, suitable for deployment.
Static files are installed in InstallDir/ncs-<vsn>.
The first time --system-install is used, the ConfigDir,
RunDir, and LogDir directories are also created and
populated for config files, run-time state files, and log files,
respectively, and an init script for start of NCS at system boot
and user profile scripts are installed. Defaults are:

InstallDir - /opt/ncs
ConfigDir  - /etc/ncs
RunDir     - /var/opt/ncs
LogDir     - /var/log/ncs

By default, the system install will run NCS as the root user.
If the --run-as-user option is given, the system install will
instead run NCS as the given user. The user will be created if
it does not already exist.

If the --non-interactive option is given, the installer will
proceed with potentially disruptive changes (e.g. modifying or
removing existing files) without asking for confirmation.

sh nso-6.0.darwin.x86_64.installer.bin --local-install ~/nso-6.0

# Output
INFO  Using temporary directory /var/folders/90/n5sbctr922336_0jrzhb54400000gn/T//ncs_installer.93831 to stage NCS installation bundle
INFO  Unpacked ncs-6.0 in /Users/user/nso-6.0
INFO  Found and unpacked corresponding DOCUMENTATION_PACKAGE
INFO  Found and unpacked corresponding EXAMPLE_PACKAGE
INFO  Found and unpacked corresponding JAVA_PACKAGE
INFO  Generating default SSH hostkey (this may take some time)
INFO  SSH hostkey generated
INFO  Environment set-up generated in /Users/user/nso-6.0/ncsrc
INFO  NSO installation script finished
INFO  Found and unpacked corresponding NETSIM_PACKAGE
INFO  NCS installation complete

Exploring the Installation

Before we start up NSO, let's just look at what we have.

Go ahead and cd into the new installation directory.

cd ~/nso-6.0

Documentation

Note: Links to the online version of the NSO Guides and NSO Extension API Reference documentation.

Along with the binaries, NSO installs a full set of documentation available in the doc/ folder in ~/nso-6.0.

ls -l doc/
drwxr-xr-x   5 user  staff   160B Nov 29 05:19 api/
drwxr-xr-x  14 user  staff   448B Nov 29 05:19 html/
-rw-r--r--   1 user  staff   202B Nov 29 05:19 index.html
drwxr-xr-x  17 user  staff   544B Nov 29 05:19 pdf/

Feel free to open up the index.html file in your favorite browser and poke around (you can use the open command in the terminal to open the file). You'll find installation, admin, user, development, and more guides available for you to jump right into.

Examples

An NSO Local Install also comes with A LOT of examples of a variety of different types of ways you can use NSO. Many of these touch on advanced topics, but there are plenty of basic ones as well. Here are the high-level directories of examples in ~/nso-6.0/examples.ncs

ls -l examples.ncs/

# Output
-rw-r--r--   1 user  staff   1.0K Nov 29 05:17 README
drwxr-xr-x   4 user  staff   128B Nov 29 04:50 datacenter/
drwxr-xr-x   3 user  staff    96B Nov 29 04:50 generic-ned/
drwxr-xr-x   4 user  staff   128B Nov 29 04:50 getting-started/
drwxr-xr-x   7 user  staff   224B Nov 29 04:50 service-provider/
drwxr-xr-x   3 user  staff    96B Nov 29 04:50 snmp-ned/
drwxr-xr-x  11 user  staff   352B Nov 29 05:17 snmp-notification-receiver/
drwxr-xr-x   5 user  staff   160B Nov 29 04:50 web-server-farm/

NEDs or Network Element Drivers

In order to "talk to" the network, NSO uses NEDs as device drivers for different device types. Cisco has NEDs for hundreds of different devices available for customers, and several are included in the installer in the ~/nso-6.0/packages/neds directory.

ls -l

# Output
drwxr-xr-x  13 user  staff   416B Nov 29 05:17 a10-acos-cli-3.0/
drwxr-xr-x  12 user  staff   384B Nov 29 05:17 alu-sr-cli-3.4/
drwxr-xr-x  13 user  staff   416B Nov 29 05:17 cisco-asa-cli-6.6/
drwxr-xr-x  12 user  staff   384B Nov 29 05:17 cisco-ios-cli-3.0/
drwxr-xr-x  12 user  staff   384B Nov 29 05:17 cisco-ios-cli-3.8/
drwxr-xr-x  13 user  staff   416B Nov 29 05:17 cisco-iosxr-cli-3.0/
drwxr-xr-x  13 user  staff   416B Nov 29 05:17 cisco-iosxr-cli-3.5/
drwxr-xr-x  13 user  staff   416B Nov 29 05:17 cisco-nx-cli-3.0/
drwxr-xr-x  13 user  staff   416B Nov 29 05:17 dell-ftos-cli-3.0/
drwxr-xr-x  10 user  staff   320B Nov 29 05:17 juniper-junos-nc-3.0/

Here you can see there are NEDs for Cisco ASA, IOS, IOS XR, and NX-OS. Also included are NEDs for other vendors including Juniper JunOS, A10, ALU, and Dell.

Note: The NEDs included in the installer are intended for evaluation, demonstration, and use with the examples.ncs that are also included. These are not the latest versions available, and often don't have all the features available in production NEDs.

Installing New NED Versions

Cisco also makes additional versions of some NEDs available on DevNet for evaluation and non-production use. You can find them with the NSO downloads (scroll up!).

Note: The specific file names and versions you download maybe different from this guide. Update the paths appropriately.

1. Like the NSO installer, the NEDs are signed.bin files that need to be run to validate the download and extract the new code.

2. First, find the downloaded files - change to the working directory where your downloads are:

Note: The filenames indicate which version of NSO the NEDs are pre-compiled for (in this case NSO 6.0), and the version of the NED.

cd ~/Downloads/
ls -l ncs*.bin

# Output
-rw-r--r--@ 1 user  staff   9708091 Dec 18 12:05 ncs-6.0-cisco-asa-6.16-freetrial.signed.bin
-rw-r--r--@ 1 user  staff  51233042 Dec 18 12:06 ncs-6.0-cisco-ios-6.88-freetrial.signed.bin
-rw-r--r--@ 1 user  staff  39292052 Dec 18 12:06 ncs-6.0-cisco-iosxr-7.43-freetrial.signed.bin
-rw-r--r--@ 1 user  staff   8400190 Dec 18 12:05 ncs-6.0-cisco-nx-5.23.6-freetrial.signed.bin

1. Use the sh command to "run" the signed.bin to verify the certificate and extract the NED tar.gz and other files. Repeat for all files.

sh ncs-6.0-cisco-nx-5.23.6.signed.bin

Output:

Unpacking...
Verifying signature...
Downloading CA certificate from http://www.cisco.com/security/pki/certs/crcam2.cer ...
Successfully downloaded and verified crcam2.cer.
Downloading SubCA certificate from http://www.cisco.com/security/pki/certs/innerspace.cer ...
Successfully downloaded and verified innerspace.cer.
Successfully verified root, subca and end-entity certificate chain.
Successfully fetched a public key from tailf.cer.
Successfully verified the signature of ncs-6.0-cisco-nx-5.23.6.tar.gz using tailf.cer

1. You now have three tarballs (.tar.gz) files. These are compressed versions of the NEDs.

ls -l ncs*.tar.gz

Output:

-rw-r--r--  1 user  staff   9704896 Dec 12 21:11 ncs-6.0-cisco-asa-6.16.tar.gz
-rw-r--r--  1 user  staff  51260488 Dec 13 22:58 ncs-6.0-cisco-ios-6.88.tar.gz
-rw-r--r--  1 user  staff  39305257 Oct  7 17:47 ncs-6.0-cisco-iosxr-7.43.tar.gz
-rw-r--r--  1 user  staff   8409288 Dec 18 09:09 ncs-6.0-cisco-nx-5.23.6.tar.gz

1. Navigate to the packages/neds directory for your local install.

cd ~/nso-6.0/packages/neds

1. While in ~/nso-6.0/packages/neds directory, extract the tarballs into this directory using the tar command with the path to where the compressed NED is located:

Update the path and file name for the NED versions you downloaded

tar -zxvf ~/Downloads/ncs-6.0-cisco-nx-5.23.6.tar.g
tar -zxvf ~/Downloads/ncs-6.0-cisco-ios-6.88.tar.gz
tar -zxvf ~/Downloads/ncs-6.0-cisco-iosxr-7.43.tar.gz
tar -zxvf ~/Downloads/ncs-6.0-17:47-6.16.tar.gz

Here is a sample list of the newer NEDs extracted along with the ones bundled with the installation:

drwxr-xr-x  13 user  staff   416 Nov 29 05:17 a10-acos-cli-3.0
drwxr-xr-x  12 user  staff   384 Nov 29 05:17 alu-sr-cli-3.4
drwxr-xr-x  13 user  staff   416 Nov 29 05:17 cisco-asa-cli-6.6
drwxr-xr-x  13 user  staff   416 Dec 12 21:11 cisco-asa-cli-6.7
drwxr-xr-x  12 user  staff   384 Nov 29 05:17 cisco-ios-cli-3.0
drwxr-xr-x  12 user  staff   384 Nov 29 05:17 cisco-ios-cli-3.8
drwxr-xr-x  13 user  staff   416 Dec 13 22:58 cisco-ios-cli-6.42
drwxr-xr-x  13 user  staff   416 Nov 29 05:17 cisco-iosxr-cli-3.0
drwxr-xr-x  13 user  staff   416 Nov 29 05:17 cisco-iosxr-cli-3.5
drwxr-xr-x  13 user  staff   448 Oct  7 14:46 cisco-iosxr-cli-7.4
drwxr-xr-x  13 user  staff   416 Nov 29 05:17 cisco-nx-cli-3.0
drwxr-xr-x  14 user  staff   448 Dec 18 09:09 cisco-nx-cli-5.13
drwxr-xr-x  13 user  staff   416 Nov 29 05:17 dell-ftos-cli-3.0
drwxr-xr-x  10 user  staff   320 Nov 29 05:17 juniper-junos-nc-3.0

1. And now you have the newer NED versions available, as well as the demo/evaluation versions included with NSO itself!

ncsrc

The last thing to note is the files ncsrc and ncsrc.tsch. These are shell scripts for bash and tsch that set up your PATH and other environment variables for NSO. Depending on your shell, you will need source this file before starting your NSO work.

# NOTE your path may be different, double check!
 $ source $HOME/nso-6.0/ncsrc

Most users add source ~/nso-6.0/ncsrc to their ~/.bash_profile, but you can just do it manually when you want it. Once it has been "sourced" you have access to all the NSO executable commands - which start with ncs.

ncs {TAB} {TAB}

# Output
ncs                      ncs-maapi                ncs-project              ncs-start-python-vm      ncs_cmd                  ncs_load                 
ncs-backup               ncs-make-package         ncs-setup                ncs-uninstall            ncs_conf_tool            ncsc                     
ncs-collect-tech-report  ncs-netsim               ncs-start-java-vm        ncs_cli                  ncs_crypto_keys 

Creating an Instance of NSO

A NSO Local Install unpacks and prepares your system to run NSO, but doesn't actually start it up. A Local Install allows the engineer to create an NSO "instance" tied to a project, which you have not done yet.

If you are familiar with Python, you can think of this like creating a Python virtual environment after installing Python. Within this NSO instance, you will have different inventory, configuration, and code.

Using ncs-setup to Create an NSO Instance

One of the included scripts with an NSO installation is ncs-setup, which makes it very easy to create instances of NSO from a Local Install. You can look at the --help for full details, but the two options we need to know are: * --dest defines the directory where you want to set up NSO (if the directory does not exist, it will be created) * --package defines the NEDs you want to this NSO instance to have installed. You can specify this option multiple times.

Note: NCS is the original name of the NSO product, so many the commands and application features will be prefaced with ncs. Think of ncs as another name for NSO.

1. Go ahead and run this command to setup an NSO instance in the current directory with the IOS, NX-OS, IOS-XR, and ASA NEDs, you only need one NED per platform that you want NSO to manage (even though you may have multiple versions in your installer neds directory).

   You will want to use the name of the NED folder in ${NCS_DIR}/packages/neds for the latest NED version you've got installed for the target platform. You can use tab complete after you start typing a path (or just copy and paste, though double check the NED version numbers below match what is currently on the sandbox to avoid a syntax error):

   Copy

   ncs-setup --package ~/nso-6.0/packages/neds/cisco-ios-cli-6.44 \
     --package ~/nso-6.0/packages/neds/cisco-nx-cli-5.15 \
     --package ~/nso-6.0/packages/neds/cisco-iosxr-cli-7.20 \
     --package ~/nso-6.0/packages/neds/cisco-asa-cli-6.8 \
     --dest nso-instance

2. If you check out the nso-instance directory now, you'll find several new files and folders have been created. This guide won't go through them all in detail now, but a couple are handy to know about.

   • ncs.conf is the NSO application configuration file. Used to customize aspects of the NSO instance (change ports, enable/disable features, etc.). The defaults are often perfect for projects like this.

   • packages/ is the directory that has symlinks to the NEDs that we referenced in the --package arguments at setup.

   • logs/ is the directory that contains all the logs from NSO. This directory is useful when troubleshooting.

   Copy

   $ ls nso-instance/
   logs  ncs-cdb  ncs.conf  packages  README.ncs  scripts  state
   $ ls -l nso-instance/packages/
   total 0
   lrwxrwxrwx 1 user docker 51 Mar 19 12:44 cisco-asa-cli-6.8 -> /home/user/nso-6.0/packages/neds/cisco-asa-cli-6.8
   lrwxrwxrwx 1 user docker 52 Mar 19 12:44 cisco-ios-cli-6.44 -> /home/user/nso-6.0/packages/neds/cisco-ios-cli-6.44
   lrwxrwxrwx 1 user docker 54 Mar 19 12:44 cisco-iosxr-cli-7.20 -> /home/user/nso-6.0/packages/neds/cisco-iosxr-cli-7.20
   lrwxrwxrwx 1 user docker 51 Mar 19 12:44 cisco-nx-cli-5.15 -> /home/user/nso-6.0/packages/neds/cisco-nx-cli-5.15
   $

3. Now you need to "start" your NSO instance. Navigate to the nso-instance directory and type the command ncs. It will take a few seconds to run, and you won't get any explicit output unless there is a problem.

Note: You need to be in the nso-instance directory each time you want to start or stop NSO. If you have multiple instances, you need to navigate to each one to use the ncs command to start or stop each one.

ncs

1. You can verify that NSO is running by using the ncs --status | grep status command, which has a large amount of information, so we use grep to just search for the status:

$ ncs --status | grep status
status: started
        db=running id=31 priority=1 path=/ncs:devices/device/live-status-protocol/device-type

1. Now you should add either some netsim devices (ncs-netsim -h) or lab devices to NSO and get automating!

Get Started

We recommend that you start with the online version or in the doc directory $HOME/nso-VERSION/doc/pdf/.

There are a lot of examples in the $HOME/nso-VERSION/examples.ncs directory. The examples have a short description in the $HOME/nso-VERSION/examples.ncs/READMEfile. Each example has a README file that explains how to run it.

Sandboxes

If you do not want to download and install Cisco NSO, please check out the NSO Reservable Sandbox on DevNet. There is also an associated tutorial called Learn NSO the Easy Way.

Still Need Help?

There is a lot of material on the NSO Developer Hub, where you also can ask questions about anything NSO-related.